# Label Studio Web 前端项目结构分析

## 项目概述

这是 Label Studio 的纯前端 Web 项目，基于 **NX Monorepo** 架构，使用 **React + TypeScript** 技术栈。项目已移除后端、Docker 等配置，专注于前端开发。

## 技术栈

- **构建工具**: NX (Monorepo 管理)
- **前端框架**: React 18.3.1
- **语言**: TypeScript 5.8.3
- **状态管理**: 
  - MobX + mobx-state-tree (编辑器核心)
  - Jotai (应用层状态管理)
- **UI 组件库**: 
  - Ant Design 4.x
  - Radix UI (现代化组件)
  - Shadcn/ui (基于 Radix UI)
- **样式方案**: 
  - Tailwind CSS 3.4.3
  - SCSS Modules
- **打包工具**: Webpack 5
- **测试框架**: 
  - Jest (单元测试)
  - Cypress (E2E 测试)
- **代码质量**: 
  - Biome (代码检查和格式化)
  - Stylelint (样式检查)

## 项目结构

```
web/
├── apps/                    # 应用层
│   ├── labelstudio/        # 主应用
│   ├── labelstudio-e2e/    # E2E 测试
│   └── playground/         # 独立演示应用
├── libs/                    # 共享库
│   ├── editor/             # 标注编辑器核心
│   ├── datamanager/        # 数据管理器
│   ├── ui/                 # UI 组件库
│   ├── core/               # 核心工具库
│   ├── app-common/         # 应用通用模块
│   ├── frontend-test/      # 测试工具库
│   └── storybook/          # Storybook 配置
├── tools/                   # 构建工具
├── dist/                    # 构建输出
└── 配置文件
```

## 核心应用 (Apps)

### 1. `apps/labelstudio` - 主应用

**用途**: Label Studio 的完整前端应用

**特点**:
- 集成所有功能库和组件
- 包含完整的用户界面、路由、页面管理
- 需要配合后端 API 使用（通过环境变量配置）
- 构建输出: `dist/apps/labelstudio/`

**启动命令**:
```bash
yarn ls:dev          # 开发模式（支持 HMR）
yarn ls:watch        # 监听模式
yarn ls:build        # 生产构建
```

### 2. `apps/playground` - 独立演示应用

**用途**: 标注编辑器的独立测试和演示环境

**特点**:
- 完全独立运行（standalone 模式）
- 无需后端支持
- 主要用于测试和演示标注编辑器功能
- 可通过 URL 参数加载配置

**启动命令**:
```bash
yarn playground:serve    # 开发服务器
yarn playground:build    # 生产构建
```

### 3. `apps/labelstudio-e2e` - E2E 测试

**用途**: 端到端测试套件

**特点**:
- 基于 Cypress
- 测试主应用的完整工作流

**运行命令**:
```bash
yarn ls:e2e    # 运行 E2E 测试
```

## 共享库 (Libs)

### 1. `libs/editor` - 标注编辑器核心 ⭐

**功能**: 数据标注的核心功能库

**技术栈**: 
- React + mobx-state-tree
- Konva (画布渲染)
- Ant Design (UI 组件)

**特点**:
- 可独立使用和嵌入到其他应用
- 支持多种数据类型标注：
  - 图像（矩形、多边形、关键点、分割等）
  - 音频（区域标注、分类）
  - 文本（NER、分类、关系抽取）
  - 视频（时间轴标注）
  - 时间序列数据
- 包含标注工具、画布、控件等完整功能
- 可通过 XML 配置定义标注界面

**开发命令**:
```bash
yarn lsf:watch          # 监听构建
yarn lsf:serve          # 独立运行
yarn lsf:unit           # 单元测试
yarn lsf:integration    # 集成测试
yarn lsf:e2e            # E2E 测试
```

### 2. `libs/datamanager` - 数据管理器

**功能**: 数据探索和管理工具

**特点**:
- 数据列表展示（虚拟滚动优化）
- 高级过滤和排序
- 批量操作支持
- 数据可视化
- 与编辑器深度集成

**技术栈**:
- React + MobX
- react-window (虚拟滚动)
- @tanstack/react-table (表格)

**开发命令**:
```bash
yarn dm:watch    # 监听构建
yarn dm:unit     # 单元测试
```

### 3. `libs/ui` - UI 组件库 ⭐

**功能**: 共享的 UI 组件库

**特点**:
- 基于 Radix UI 和 Tailwind CSS
- 包含 Shadcn/ui 组件
- 设计令牌系统（从 Figma 自动生成）
- 完整的 Storybook 文档
- 支持深色模式

**组件类型**:
- 基础组件（Button, Input, Select 等）
- 布局组件（Dialog, Popover, Tabs 等）
- 数据展示组件（Table, Toast 等）

**开发命令**:
```bash
yarn ui:serve              # 启动 Storybook
yarn design-tokens         # 重新生成设计令牌
```

### 4. `libs/core` - 核心工具库

**功能**: 跨应用的通用工具和类型定义

**特点**:
- 工具函数集合
- TypeScript 类型定义
- 常量和配置
- 无 UI 依赖

### 5. `libs/app-common` - 应用通用模块

**功能**: 应用级别的共享代码

**特点**:
- 跨应用的页面级组件
- 共享的业务逻辑
- 可以依赖其他 libs，但不能被其他 libs 依赖

### 6. `libs/frontend-test` - 测试工具库

**功能**: 测试辅助工具和 Helpers

**特点**:
- Cypress 测试 Helpers
- 测试工具函数
- Mock 数据生成

### 7. `libs/storybook` - Storybook 配置

**功能**: Storybook 的全局配置和插件

**特点**:
- 统一的 Storybook 配置
- 自定义插件和装饰器
- 主题配置

## 依赖关系图

```
apps/labelstudio
├── libs/editor          (标注编辑器)
├── libs/datamanager     (数据管理)
├── libs/ui              (UI 组件)
├── libs/core            (核心工具)
└── libs/app-common      (应用通用)

apps/playground
├── libs/editor          (标注编辑器)
├── libs/ui              (UI 组件)
└── libs/core            (核心工具)

libs/app-common
├── libs/ui
├── libs/core
└── libs/editor

libs/datamanager
├── libs/ui
└── libs/core

libs/editor
├── libs/ui
└── libs/core

libs/ui
└── libs/core
```

**依赖规则**:
- `apps/` 可以导入任何 `libs/`
- `libs/` 不能导入 `apps/`
- `libs/app-common` 可以导入其他 `libs/`
- 其他 `libs/` 不能导入 `libs/app-common`
- 避免循环依赖

## 开发工作流

### 启动开发环境

```bash
# 1. 安装依赖
yarn install --frozen-lockfile

# 2. 启动主应用（开发模式）
yarn dev
# 或
yarn ls:dev

# 3. 启动 Storybook（UI 组件开发）
yarn ui:serve

# 4. 启动 Playground（编辑器测试）
yarn playground:serve
```

### 构建生产版本

```bash
# 构建主应用
yarn build
# 或
yarn ls:build

# 构建 Playground
yarn playground:build

# 构建 Storybook
yarn storybook:build
```

### 测试

```bash
# 运行所有单元测试
yarn test:unit

# 运行特定模块测试
yarn ls:unit          # 主应用
yarn lsf:unit         # 编辑器
yarn dm:unit          # 数据管理器

# 运行集成测试
yarn lsf:integration

# 运行 E2E 测试
yarn test:e2e
yarn ls:e2e           # 主应用 E2E
yarn lsf:e2e          # 编辑器 E2E

# 测试覆盖率
yarn test:unit:coverage
```

### 代码质量检查

```bash
# 代码检查和自动修复
yarn lint

# SCSS 检查和自动修复
yarn lint-scss

# 生成文档
yarn docs
```

## 配置文件说明

### 核心配置

- **`nx.json`**: NX 工作区配置
- **`package.json`**: 项目依赖和脚本
- **`tsconfig.base.json`**: TypeScript 基础配置
- **`webpack.config.js`**: Webpack 构建配置
- **`tailwind.config.js`**: Tailwind CSS 配置
- **`biome.json`**: Biome 代码检查配置
- **`.stylelintrc.json`**: Stylelint 样式检查配置

### 设计令牌

- **`design-tokens.json`**: 从 Figma 导出的设计令牌
- **`components.json`**: Shadcn/ui 组件配置

### 测试配置

- **`jest.config.ts`**: Jest 测试配置
- **`jest.preset.js`**: Jest 预设配置
- **`cypress.config.ts`**: Cypress E2E 测试配置

## 独立性分析

### ✅ 可以独立运行的部分

1. **Playground 应用** (完全独立)
   - 无需后端支持
   - 可通过 URL 参数加载配置
   - 适合演示和测试标注功能

2. **Editor 库** (可嵌入)
   - 可作为独立库嵌入到其他项目
   - 支持 standalone 模式
   - 可通过 npm 包方式使用

3. **UI 组件库** (完全独立)
   - 通过 Storybook 独立开发和预览
   - 可作为独立组件库使用


## 扩展和定制

### 创建新应用

```bash
# 使用 NX 生成器创建新应用
nx generate @nx/react:application my-app --style=scss --bundler=webpack
```

### 创建新库

```bash
# 创建新的共享库
nx generate @nx/react:library my-lib --style=scss --unitTestRunner=jest
```

### 添加新组件

```bash
# 在 UI 库中添加新组件
nx generate @nx/react:component my-component --project=ui --style=scss
```

## 环境变量配置

### 开发环境 HMR 配置

创建 `.env` 文件（可选）:

```env
# 启用热模块替换
FRONTEND_HMR=true

# HMR 服务器地址（默认: http://localhost:8010）
FRONTEND_HOSTNAME=http://localhost:8010

# Django 后端地址（默认: http://localhost:8080）
DJANGO_HOSTNAME=http://localhost:8080
```

### DataManager 自定义配置

参考 `libs/datamanager/.env.example`:

```env
# API 网关地址
NX_API_GATEWAY=http://localhost:8080/api/dm

# Label Studio 访问令牌
LS_ACCESS_TOKEN=your_access_token
```

## 性能优化

### 构建优化

- 使用 NX 缓存加速构建
- Webpack 代码分割
- Tree-shaking 移除未使用代码
- CSS 压缩和优化

### 运行时优化

- React.memo 减少重渲染
- 虚拟滚动处理大数据集
- 懒加载路由和组件
- 图片和资源优化

## 常见问题

### 1. 如何连接后端 API？

主应用需要配置后端 API 地址，通常通过环境变量或构建时配置。

### 2. 如何独立使用编辑器？

使用 Playground 应用或将 `@humansignal/editor` 作为 npm 包引入你的项目。

### 3. 如何添加新的标注类型？

在 `libs/editor` 中扩展标注工具和控件，参考现有实现。

### 4. 如何自定义 UI 主题？

修改 `design-tokens.json` 和 Tailwind 配置，重新生成设计令牌。

### 5. 如何运行测试？

```bash
yarn test:unit           # 所有单元测试
yarn test:integration    # 集成测试
yarn test:e2e            # E2E 测试
```

## 总结

这是一个现代化的前端 Monorepo 项目，具有以下特点：

- ✅ **模块化架构**: 清晰的应用和库分离
- ✅ **可复用性**: 核心功能可独立使用
- ✅ **类型安全**: 完整的 TypeScript 支持
- ✅ **现代工具链**: NX + Webpack + Biome
- ✅ **完善的测试**: 单元测试 + 集成测试 + E2E 测试
- ✅ **组件文档**: Storybook 支持
- ✅ **设计系统**: 基于 Figma 的设计令牌

项目专注于前端开发，可以独立开发和测试，也可以与后端 API 集成使用。