# LabelStudio 编辑器集成完整总结

## 项目背景

在标注平台项目中集成 LabelStudio 编辑器，用于实现数据标注功能。

## 遇到的问题

### 问题 1：橙色到粉色的渐变遮罩
**症状**：整个标注界面被一个橙色渐变覆盖，无法交互

**根本原因**：
- `relations-overlay` 是 LabelStudio 的关系标注覆盖层（SVG 元素）
- 默认有一个背景色，导致遮挡了整个界面

**解决方案**：
在组件样式中添加透明背景：
```scss
:global(.relations-overlay) {
  background: transparent !important;
  fill: none !important;
}

:global(.lsf-container) {
  background: transparent !important;
}
```

**修改的文件**：
- `web/apps/lq_label/src/views/editor-test/editor-test.module.scss`
- `web/apps/lq_label/src/views/annotation-view/annotation-view.module.scss`

### 问题 2：编辑器样式完全不显示（核心问题）
**症状**：
- 标签按钮没有颜色
- 按钮没有边框和背景
- 面板和侧边栏样式缺失
- 整体看起来像是没有加载 CSS

**根本原因**：
LabelStudio 使用 CSS 模块和 BEM 命名约定，所有 CSS 类名需要添加 `lsf-` 前缀：
- HTML 元素：`<div class="lsf-label">...</div>`
- CSS 文件：`.label { ... }` → 需要转换为 `.lsf-label { ... }`
- 我们的 webpack 配置缺少这个转换逻辑

**技术细节**：
1. 根目录的 `web/webpack.config.js` 有特殊的 CSS 模块配置
2. 它会给所有非 `.module.scss` 的 SCSS 文件添加 `lsf-` 前缀
3. 配置代码：
```javascript
cssLoader.options.modules = {
  localIdentName: `${css_prefix}[local]`, // css_prefix = "lsf-"
  getLocalIdent(_ctx, _ident, className) {
    if (className.includes("ant")) return className;
  },
};
```

**解决方案**：
在 `web/apps/lq_label/webpack.config.js` 中添加相同的配置：

```javascript
const css_prefix = 'lsf-';

// 1. 定义 CSS_PREFIX 环境变量
config.plugins = [
  ...config.plugins,
  new webpack.DefinePlugin({
    'process.env.CSS_PREFIX': JSON.stringify(css_prefix),
  }),
];

// 2. 配置 CSS 模块添加 lsf- 前缀
config.module.rules.forEach((rule) => {
  const testString = rule.test?.toString() || '';
  
  if (rule.test?.toString().match(/scss|sass/) && !testString.includes('.module')) {
    const r = rule.oneOf?.filter((r) => {
      if (!r.use) return false;
      const testString = r.test?.toString() || '';
      if (testString.match(/module|raw|antd/)) return false;
      return testString.match(/scss|sass/) && 
             r.use.some((u) => u.loader && u.loader.includes('css-loader'));
    });

    r?.forEach((_r) => {
      const cssLoader = _r.use.find((use) => 
        use.loader && use.loader.includes('css-loader')
      );
      
      if (!cssLoader) return;

      const isSASS = _r.use.some((use) => 
        use.loader && use.loader.match(/sass|scss/)
      );
      
      if (isSASS) _r.exclude = /node_modules/;

      if (cssLoader.options) {
        cssLoader.options.modules = {
          localIdentName: `${css_prefix}[local]`,
          getLocalIdent(_ctx, _ident, className) {
            if (className.includes('ant')) return className;
          },
        };
      }
    });
  }
});
```

**修改的文件**：
- `web/apps/lq_label/webpack.config.js`

**重要提示**：
- 修改 webpack 配置后必须重启开发服务器
- 浏览器需要硬刷新（Ctrl+Shift+R）

## 调试过程

### 1. 初步探索
- 参考了 `playground` 和 `labelstudio` 应用的实现
- 发现它们只导入 UI 库样式，不静态导入 editor 样式
- 修改了 `main.tsx` 的样式导入顺序

### 2. 发现橙色遮罩
- 使用浏览器开发者工具检查元素
- 找到了 `relations-overlay` 和 `lsf-container` 类名
- 搜索源代码找到对应的组件
- 添加透明背景修复

### 3. 样式不显示的深入调查
- 检查 Network 标签，确认 CSS 文件已加载
- 检查 CSS 文件内容，发现没有 `lsf-` 前缀的类名
- 检查 HTML 元素，发现有 `lsf-` 前缀的类名
- 意识到是 CSS 模块转换的问题

### 4. 找到根本原因
- 阅读根目录的 `webpack.config.js`
- 发现 CSS 模块的 `localIdentName` 配置
- 理解了 `lsf-` 前缀的转换逻辑
- 在我们的应用中复制了这个配置

### 5. 验证修复
- 重启开发服务器
- 硬刷新浏览器
- 检查 HTML 和 CSS 的类名匹配
- 确认样式正确显示

## 创建的文件

### 测试页面
- `web/apps/lq_label/src/views/editor-test/editor-test.tsx` - 测试页面组件
- `web/apps/lq_label/src/views/editor-test/editor-test.module.scss` - 样式文件
- `web/apps/lq_label/src/views/editor-test/index.ts` - 导出文件

### 文档
- `web/apps/lq_label/EDITOR_TEST.md` - 测试页面说明
- `web/apps/lq_label/RELATIONS_OVERLAY_FIX.md` - 橙色遮罩修复文档
- `web/apps/lq_label/CSS_PREFIX_FIX.md` - CSS 前缀问题修复文档
- `web/apps/lq_label/LABELSTUDIO_INTEGRATION_SUMMARY.md` - 本文档

### 规范
- `.kiro/steering/labelstudio-集成规范.md` - 完整的集成规范
- `.kiro/steering/README.md` - 规范索引

## 关键经验

### 1. 参考成功案例
- 不要从零开始，先看看其他应用是怎么做的
- `playground` 应用是最好的参考
- 根目录的 `webpack.config.js` 包含关键配置

### 2. 使用浏览器开发者工具
- Elements 标签：检查 HTML 元素和类名
- Network 标签：检查 CSS 文件是否加载
- Console 标签：查看错误和日志
- Styles 面板：检查样式是否被应用

### 3. 理解 CSS 模块
- CSS 模块会转换类名
- `localIdentName` 配置决定转换规则
- LabelStudio 依赖特定的前缀

### 4. 搜索源代码
- 使用类名搜索找到对应的组件
- 理解组件的用途和实现
- 找到样式文件和配置

### 5. 创建测试页面
- 隔离问题，简化调试
- 添加调试面板显示状态
- 使用简单的配置和数据

## 最终效果

✅ 橙色遮罩消失
✅ 所有样式正确显示
✅ 标签按钮有颜色和边框
✅ 悬停和选中效果正常
✅ 侧边栏和面板样式正确
✅ 编辑器完全可用

## 访问测试页面

1. 启动开发服务器：
```bash
cd web
yarn nx serve lq_label
```

2. 访问测试页面：
- 首页：http://localhost:4200/
- 点击 "🧪 编辑器测试" 按钮
- 或直接访问：http://localhost:4200/editor-test

3. 访问标注页面：
- 创建项目和任务
- 访问：http://localhost:4200/tasks/:id/annotate

## 后续工作

- [ ] 完善标注保存功能
- [ ] 添加更多的编辑器配置选项
- [ ] 实现标注历史记录
- [ ] 添加标注质量检查
- [ ] 优化编辑器性能

## 致谢

感谢 LabelStudio 团队提供的优秀编辑器！
感谢 playground 和 labelstudio 应用提供的参考实现！

---

**文档创建时间**：2026-01-13
**最后更新时间**：2026-01-13
**维护者**：项目开发团队