# Implementation Plan: Annotation Platform

## Overview

本实现计划将标注平台分解为可执行的开发任务。任务按照从基础设施到核心功能再到集成的顺序组织,确保每一步都可以独立测试和验证。

## Tasks

- [x] 1. 初始化前端应用和项目结构
  - 使用 Nx 生成 React 应用: `cd web && nx generate @nx/react:application lq_label --style=scss --bundler=webpack`
  - 创建目录结构: components/, views/, atoms/, services/, utils/
  - 安装依赖: react-router-dom, jotai, axios
  - 配置 TypeScript 和 ESLint
  - 创建基础的 App.tsx 和 main.tsx
  - _Requirements: 4.1, 4.2, 4.8_

- [x] 2. 初始化后端应用和数据库
  - 创建 backend/ 目录结构
  - 创建 requirements.txt 并安装依赖 (fastapi, uvicorn, pydantic)
  - 创建 main.py 和 FastAPI 应用实例
  - 配置 CORS 中间件
  - 创建 database.py 和 SQLite 连接管理
  - 创建数据库表结构 (projects, tasks, annotations)
  - 实现数据库初始化逻辑
  - _Requirements: 5.1, 5.2, 5.8, 6.1, 6.2, 6.3, 9.1, 9.2_

- [x] 2.1 编写后端数据库初始化的单元测试

  - 在 backend/test/ 目录创建测试文件
  - 测试数据库表创建
  - 测试连接管理
  - _Requirements: 9.1, 9.2_

- [x] 3. 实现后端 Project API
  - [x] 3.1 创建 Project 数据模型和 Pydantic schemas
    - 定义 ProjectCreate, ProjectUpdate, ProjectResponse schemas
    - 创建数据库模型
    - _Requirements: 6.1_

  - [x] 3.2 实现 Project CRUD 端点
    - GET /api/projects (列表)
    - POST /api/projects (创建)
    - GET /api/projects/{id} (详情)
    - PUT /api/projects/{id} (更新)
    - DELETE /api/projects/{id} (删除,级联删除任务)
    - _Requirements: 5.3, 1.3, 1.6, 1.7_

  - [x] 3.3 编写 Property 1 的属性测试

    - 在 backend/test/ 目录创建测试文件
    - **Property 1: Project creation adds to list**
    - **Validates: Requirements 1.3**
    - 使用 Hypothesis 生成随机项目数据
    - 验证创建后项目出现在列表中且有唯一 ID
    - _Requirements: 1.3_

  - [ ]* 3.4 编写 Property 3 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 3: Project deletion cascades**
    - **Validates: Requirements 1.7**
    - 创建项目和关联任务,删除项目后验证任务也被删除
    - _Requirements: 1.7_

  - [ ]* 3.5 编写 Property 12 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 12: Project ID validation on task creation**
    - **Validates: Requirements 6.4**
    - 使用无效的 project_id 创建任务,验证返回 404
    - _Requirements: 6.4_

- [ ] 4. 实现后端 Task API
  - [x] 4.1 创建 Task 数据模型和 Pydantic schemas
    - 定义 TaskCreate, TaskUpdate, TaskResponse schemas
    - 创建数据库模型
    - _Requirements: 6.2_

  - [x] 4.2 实现 Task CRUD 端点
    - GET /api/tasks (列表,支持筛选)
    - POST /api/tasks (创建)
    - GET /api/tasks/{id} (详情)
    - PUT /api/tasks/{id} (更新)
    - DELETE /api/tasks/{id} (删除)
    - GET /api/projects/{id}/tasks (按项目查询)
    - _Requirements: 5.4, 2.2, 2.5, 2.6_

  - [ ]* 4.3 编写 Property 4 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 4: Task creation associates with project**
    - **Validates: Requirements 2.2**
    - 创建任务并验证它关联到正确的项目
    - _Requirements: 2.2_

  - [ ]* 4.4 编写 Property 6 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 6: Task completion updates status**
    - **Validates: Requirements 2.7**
    - 标注所有数据后验证任务状态更新为 completed
    - _Requirements: 2.7_

- [ ] 5. 实现后端 Annotation API
  - [x] 5.1 创建 Annotation 数据模型和 Pydantic schemas
    - 定义 AnnotationCreate, AnnotationUpdate, AnnotationResponse schemas
    - 创建数据库模型
    - _Requirements: 6.3_

  - [x] 5.2 实现 Annotation CRUD 端点
    - GET /api/annotations (列表,支持筛选)
    - POST /api/annotations (创建)
    - GET /api/annotations/{id} (详情)
    - PUT /api/annotations/{id} (更新)
    - GET /api/tasks/{id}/annotations (按任务查询)
    - _Requirements: 5.5, 3.3, 3.5_

  - [ ]* 5.3 编写 Property 8 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 8: Annotation saves update progress**
    - **Validates: Requirements 3.3**
    - 保存标注后验证任务进度更新
    - _Requirements: 3.3_

  - [ ]* 5.4 编写 Property 13 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 13: Task ID validation on annotation creation**
    - **Validates: Requirements 6.5**
    - 使用无效的 task_id 创建标注,验证返回 404
    - _Requirements: 6.5_

  - [ ]* 5.5 编写 Property 14 的属性测试
    - 在 backend/test/ 目录创建测试文件
    - **Property 14: JSON serialization round-trip**
    - **Validates: Requirements 6.7**
    - 验证标注结果的 JSON 序列化和反序列化
    - _Requirements: 6.7_

- [ ]* 5.6 编写 Property 11 的属性测试
  - 在 backend/test/ 目录创建测试文件
  - **Property 11: API error responses**
  - **Validates: Requirements 5.6**
  - 测试各种无效请求返回正确的 4xx 状态码和错误消息
  - _Requirements: 5.6_

- [ ] 6. Checkpoint - 后端 API 完成
  - 确保所有 API 端点正常工作
  - 确保所有测试通过
  - 询问用户是否有问题

- [x] 7. 实现前端状态管理 (Jotai Atoms)
  - 创建 atoms/projectAtoms.ts (projectsAtom, currentProjectAtom, loading, error)
  - 创建 atoms/taskAtoms.ts (tasksAtom, currentTaskAtom, taskFilterAtom, loading, error)
  - 创建 atoms/annotationAtoms.ts (currentAnnotationAtom, lsfInstanceAtom, loading, error)
  - _Requirements: 4.3_

- [x] 8. 实现前端 API 服务层
  - 创建 services/api.ts
  - 实现 axios 实例配置
  - 实现 Project API 调用函数 (listProjects, createProject, getProject, updateProject, deleteProject)
  - 实现 Task API 调用函数 (listTasks, createTask, getTask, updateTask, deleteTask)
  - 实现 Annotation API 调用函数 (listAnnotations, createAnnotation, getAnnotation, updateAnnotation)
  - 实现错误处理和响应拦截器
  - _Requirements: 10.1_

- [ ] 9. 实现 Layout 组件
  - [x] 9.1 创建 Layout 组件
    - 使用 Tailwind CSS 创建后台管理布局
    - 包含 Sidebar 和主内容区域
    - 使用 @humansignal/ui 的组件
    - _Requirements: 4.5, 7.1, 7.4, 7.7_

  - [x] 9.2 创建 Sidebar 组件
    - 定义菜单项 (Projects, Tasks, Annotations)
    - 实现导航功能
    - 实现响应式设计
    - _Requirements: 7.2, 7.5_

  - [ ]* 9.3 编写 Property 15 的属性测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 15: Navigation menu highlighting**
    - **Validates: Requirements 7.3**
    - 验证当前路由对应的菜单项高亮显示
    - _Requirements: 7.3_

- [x] 10. 实现 ProjectListView
  - [x] 10.1 创建 ProjectListView 组件
    - 使用 @humansignal/ui 的 DataTable 显示项目列表
    - 实现创建项目按钮
    - 实现项目操作 (查看详情、编辑、删除)
    - 集成 Jotai atoms 获取和更新项目数据
    - _Requirements: 1.1, 1.2, 1.5_

  - [ ]* 10.2 编写单元测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - 测试项目列表渲染
    - 测试创建按钮点击
    - 测试项目操作
    - _Requirements: 1.1, 1.2_

- [x] 11. 实现 ProjectForm 组件
  - [x] 11.1 创建 ProjectForm 组件
    - 使用 @humansignal/ui 的表单组件
    - 实现表单验证 (name, description, config 必填)
    - 实现提交和取消功能
    - _Requirements: 1.2, 1.4_

  - [ ]* 11.2 编写 Property 2 的属性测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 2: Empty project name rejection**
    - **Validates: Requirements 1.4**
    - 使用 fast-check 生成空白字符串,验证表单阻止提交
    - _Requirements: 1.4_

- [x] 12. 实现 ProjectDetailView
  - 创建 ProjectDetailView 组件
  - 显示项目基本信息
  - 显示关联任务列表
  - 实现编辑项目功能
  - 实现创建任务按钮
  - _Requirements: 1.5, 1.6_

- [ ]* 12.1 编写单元测试
  - 在 web/apps/lq_label/test/ 目录创建测试文件
  - 测试项目详情渲染
  - 测试任务列表显示
  - _Requirements: 1.5_

- [x] 13. 实现 TaskListView
  - [x] 13.1 创建 TaskListView 组件
    - 使用 @humansignal/ui 的 DataTable 显示任务列表
    - 实现状态筛选功能
    - 实现任务操作 (开始标注、查看详情、删除)
    - 集成 Jotai atoms 获取和更新任务数据
    - _Requirements: 2.3, 2.4_

  - [ ]* 13.2 编写 Property 5 的属性测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 5: Task status filtering**
    - **Validates: Requirements 2.4**
    - 验证筛选后只显示匹配状态的任务
    - _Requirements: 2.4_

  - [ ]* 13.3 编写 Property 7 的属性测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 7: User task assignment filtering**
    - **Validates: Requirements 3.1**
    - 验证用户只看到分配给自己的任务
    - _Requirements: 3.1_

- [x] 14. 实现 TaskForm 组件
  - [x] 14.1 创建 TaskForm 组件
    - 使用 @humansignal/ui 的表单组件
    - 实现表单验证 (name, project_id, data 必填)
    - 实现 JSON 格式验证
    - 实现提交和取消功能
    - 在 ProjectDetailView 中集成 TaskForm
    - _Requirements: 2.1, 2.2_

- [ ]* 14.1 编写单元测试
  - 在 web/apps/lq_label/test/ 目录创建测试文件
  - 测试表单验证
  - 测试提交功能
  - _Requirements: 2.1, 2.2_

- [x] 15. Checkpoint - 项目和任务管理完成
  - 确保项目和任务的 CRUD 功能正常
  - 确保所有测试通过
  - 询问用户是否有问题

- [-] 16. 实现 AnnotationView (LabelStudio 集成)
  - [x] 16.1 创建 AnnotationView 组件基础结构
    - 创建组件框架
    - 实现加载状态和错误状态显示
    - 添加保存和跳过按钮
    - _Requirements: 3.2, 10.4_

  - [-] 16.2 集成 LabelStudio 编辑器
    - 动态导入 @humansignal/editor
    - 获取项目配置和任务数据
    - 初始化 LabelStudio 实例
    - 配置编辑器选项
    - _Requirements: 8.1, 8.2, 8.3_

  - [ ] 16.3 实现标注保存功能
    - 使用 MST onSnapshot 监听标注变化
    - 序列化标注结果为 JSON
    - 调用 API 保存标注
    - 更新任务进度
    - _Requirements: 3.3, 8.4, 8.6_

  - [ ] 16.4 实现编辑器清理逻辑
    - 在组件卸载时销毁 LabelStudio 实例
    - 清理 MST 订阅
    - 清理 DOM 引用和事件监听器
    - _Requirements: 8.8_

  - [ ]* 16.5 编写 Property 9 的属性测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 9: Empty annotation rejection**
    - **Validates: Requirements 3.4**
    - 验证空标注结果被阻止提交
    - _Requirements: 3.4_

  - [ ]* 16.6 编写 Property 10 的集成测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 10: LabelStudio config initialization**
    - **Validates: Requirements 3.7**
    - 验证编辑器使用项目配置正确初始化
    - _Requirements: 3.7, 8.2_

  - [ ]* 16.7 编写 Property 16 的集成测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - **Property 16: Editor cleanup on unmount**
    - **Validates: Requirements 8.8**
    - 验证编辑器卸载时资源被正确清理
    - _Requirements: 8.8_

- [x] 17. 实现路由配置
  - 安装并配置 react-router-dom
  - 定义路由: /, /projects, /projects/:id, /tasks, /tasks/:id/annotate
  - 在 App.tsx 中集成路由
  - 实现 404 页面
  - _Requirements: 7.3, 7.6_

- [ ] 18. 实现错误处理和用户反馈
  - [ ] 18.1 实现 Toast 通知系统
    - 使用 @humansignal/ui 的 Toast 组件
    - 实现成功、错误、警告消息显示
    - _Requirements: 10.1, 10.3_

  - [ ] 18.2 实现 Error Boundary
    - 创建 ErrorBoundary 组件
    - 实现错误捕获和显示
    - 实现错误日志记录
    - _Requirements: 10.5, 10.7_

  - [ ] 18.3 实现加载状态指示器
    - 使用 @humansignal/ui 的 Spinner 组件
    - 在数据加载时显示加载指示器
    - _Requirements: 10.4_

  - [ ]* 18.4 编写单元测试
    - 在 web/apps/lq_label/test/ 目录创建测试文件
    - 测试 Toast 通知显示
    - 测试 Error Boundary 捕获错误
    - 测试加载状态显示
    - _Requirements: 10.1, 10.3, 10.4, 10.5_

- [ ] 19. 实现表单验证
  - 在 ProjectForm 中实现验证逻辑
  - 在 TaskForm 中实现验证逻辑
  - 显示内联验证错误
  - _Requirements: 10.2_

- [ ]* 19.1 编写单元测试
  - 在 web/apps/lq_label/test/ 目录创建测试文件
  - 测试表单验证规则
  - 测试验证错误显示
  - _Requirements: 10.2_

- [ ] 20. 样式优化和响应式设计
  - 使用 Tailwind CSS 优化所有组件样式
  - 确保响应式设计在不同屏幕尺寸下正常工作
  - 使用语义化 token 类名
  - 遵循设计规范
  - _Requirements: 4.7, 7.5, 7.7_

- [ ] 21. 最终集成测试
  - 测试完整的用户流程: 创建项目 → 创建任务 → 标注
  - 测试错误场景
  - 测试边缘情况
  - _Requirements: All_

- [ ] 22. 文档和部署准备
  - 编写 README.md (前端和后端)
  - 添加环境变量配置说明
  - 添加开发和部署指南
  - 创建 .env.example 文件
  - _Requirements: All_

- [ ] 23. Final Checkpoint - 完整功能验证
  - 确保所有功能正常工作
  - 确保所有测试通过
  - 进行代码审查
  - 询问用户是否满意

## Notes

- 标记 `*` 的任务为可选测试任务,可以跳过以加快 MVP 开发
- 每个任务都引用了具体的需求编号以便追溯
- Checkpoint 任务确保增量验证
- 属性测试验证通用正确性属性
- 单元测试验证具体示例和边缘情况
- 前端和后端任务可以并行开发