tasks.md 14 KB
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
- 使用 Nx 生成 React 应用:
[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
- 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
- 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
- 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 组件
- 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
- 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 组件
- 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
- 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 组件
- 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 功能正常
- 确保所有测试通过
- 询问用户是否有问题
[x] 16. 实现 AnnotationView (LabelStudio 集成)
- 16.1 创建 AnnotationView 组件基础结构
- 创建组件框架
- 实现加载状态和错误状态显示
- 添加保存和跳过按钮
Requirements: 3.2, 10.4
[x] 16.2 集成 LabelStudio 编辑器
动态导入 @humansignal/editor
获取项目配置和任务数据
初始化 LabelStudio 实例
配置编辑器选项
Requirements: 8.1, 8.2, 8.3
[x] 16.3 实现标注保存功能
使用 MST onSnapshot 监听标注变化
序列化标注结果为 JSON
调用 API 保存标注
更新任务进度
Requirements: 3.3, 8.4, 8.6
[x] 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
[x] 18. 实现错误处理和用户反馈
- 18.1 实现 Toast 通知系统
- 使用 @humansignal/ui 的 Toast 组件
- 实现成功、错误、警告消息显示
Requirements: 10.1, 10.3
[x] 18.2 实现 Error Boundary
创建 ErrorBoundary 组件
实现错误捕获和显示
实现错误日志记录
Requirements: 10.5, 10.7
[x] 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
[x] 19. 实现表单验证
- 在 ProjectForm 中实现验证逻辑
- 在 TaskForm 中实现验证逻辑
- 显示内联验证错误
- Requirements: 10.2
[ ]* 19.1 编写单元测试
- 在 web/apps/lq_label/test/ 目录创建测试文件
- 测试表单验证规则
- 测试验证错误显示
- Requirements: 10.2
[x] 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 任务确保增量验证
- 属性测试验证通用正确性属性
- 单元测试验证具体示例和边缘情况
- 前端和后端任务可以并行开发