LabelingSystem/.kiro/specs/annotation-platform/requirements.md

Requirements Document

Introduction

本文档定义了一个完整的标注平台系统的需求规范。该平台支持从项目创建、任务分配到人员标注的完整工作流程。系统采用前后端分离架构,前端使用 React + TypeScript + Nx 单体仓库,后端使用 Python FastAPI + SQLite。

Glossary

• Annotation_Platform: 标注平台系统,提供项目管理、任务管理和标注功能的完整解决方案
• Project: 标注项目,包含多个标注任务的容器
• Task: 标注任务,属于某个项目,包含待标注的数据和标注配置
• Annotation: 标注结果,用户对任务数据的标注输出
• User: 系统用户,可以是管理员或标注人员
• Frontend_App: 前端应用,位于 web/apps/lq_label 目录
• Backend_API: 后端 API 服务,位于 backend 目录
• Layout: 后台管理平台样式的布局组件
• View: 独立的页面视图组件,可被其他平台复用

Requirements

Requirement 1: 项目管理

User Story: 作为管理员,我想要创建和管理标注项目,以便组织不同的标注工作。

Acceptance Criteria

1. WHEN 用户访问项目列表页面 THEN THE Frontend_App SHALL 显示所有项目的列表,包括项目名称、描述、创建时间和任务数量
2. WHEN 用户点击创建项目按钮 THEN THE Frontend_App SHALL 显示项目创建表单,包含项目名称、描述和标注配置字段
3. WHEN 用户提交有效的项目信息 THEN THE Backend_API SHALL 创建新项目并返回项目 ID
4. WHEN 用户提交空的项目名称 THEN THE Frontend_App SHALL 阻止提交并显示验证错误
5. WHEN 用户点击项目详情 THEN THE Frontend_App SHALL 导航到项目详情页面,显示项目信息和关联的任务列表
6. WHEN 用户编辑项目信息 THEN THE Backend_API SHALL 更新项目数据并返回更新后的项目
7. WHEN 用户删除项目 THEN THE Backend_API SHALL 删除项目及其所有关联任务

Requirement 2: 任务管理

User Story: 作为管理员,我想要在项目中创建和管理标注任务,以便分配具体的标注工作。

Acceptance Criteria

1. WHEN 用户在项目详情页点击创建任务 THEN THE Frontend_App SHALL 显示任务创建表单,包含任务名称、数据源和分配人员字段
2. WHEN 用户提交有效的任务信息 THEN THE Backend_API SHALL 创建新任务并关联到当前项目
3. WHEN 用户查看任务列表 THEN THE Frontend_App SHALL 显示任务名称、状态、分配人员和完成进度
4. WHEN 用户筛选任务状态 THEN THE Frontend_App SHALL 只显示匹配状态的任务
5. WHEN 用户编辑任务信息 THEN THE Backend_API SHALL 更新任务数据
6. WHEN 用户删除任务 THEN THE Backend_API SHALL 删除任务及其所有标注结果
7. WHEN 任务的所有数据都被标注 THEN THE Backend_API SHALL 自动更新任务状态为已完成

Requirement 3: 人员标注

User Story: 作为标注人员,我想要对分配给我的任务进行标注,以便完成标注工作。

Acceptance Criteria

1. WHEN 标注人员访问任务列表 THEN THE Frontend_App SHALL 只显示分配给该用户的任务
2. WHEN 标注人员点击任务 THEN THE Frontend_App SHALL 打开标注界面,显示待标注数据和标注工具
3. WHEN 标注人员完成标注 THEN THE Backend_API SHALL 保存标注结果并更新任务进度
4. WHEN 标注人员提交空的标注结果 THEN THE Frontend_App SHALL 阻止提交并提示必须完成标注
5. WHEN 标注人员查看已标注数据 THEN THE Frontend_App SHALL 显示之前的标注结果并允许修改
6. WHEN 标注人员跳过当前数据 THEN THE Frontend_App SHALL 保存跳过状态并显示下一条数据
7. WHEN 标注界面加载 THEN THE Frontend_App SHALL 使用项目的标注配置初始化 LabelStudio 编辑器

Requirement 4: 前端应用架构

User Story: 作为开发者,我想要前端应用遵循组件化和模块化设计,以便代码可维护和可复用。

Acceptance Criteria

1. THE Frontend_App SHALL 使用 Nx 工作空间结构,位于 web/apps/lq_label 目录
2. THE Frontend_App SHALL 使用 React 函数组件和 TypeScript
3. THE Frontend_App SHALL 使用 Jotai 进行状态管理
4. THE Frontend_App SHALL 从 @humansignal/ui 导入 UI 组件而非自行创建
5. THE Frontend_App SHALL 使用后台管理平台样式的 Layout 组件
6. WHEN 定义页面视图 THEN THE Frontend_App SHALL 将每个视图作为独立组件,以便其他平台复用
7. THE Frontend_App SHALL 遵循 .cursor/rules 中定义的 React、TypeScript 和 Tailwind 规范
8. THE Frontend_App SHALL 使用 SCSS 模块进行组件样式定义

Requirement 5: 后端 API 架构

User Story: 作为开发者,我想要后端 API 提供 RESTful 接口,以便前端应用调用。

Acceptance Criteria

1. THE Backend_API SHALL 使用 Python FastAPI 框架
2. THE Backend_API SHALL 使用 SQLite 作为数据存储
3. THE Backend_API SHALL 提供项目的 CRUD 接口
4. THE Backend_API SHALL 提供任务的 CRUD 接口
5. THE Backend_API SHALL 提供标注结果的创建和查询接口
6. WHEN 接收到无效请求 THEN THE Backend_API SHALL 返回 4xx 状态码和错误信息
7. WHEN 发生服务器错误 THEN THE Backend_API SHALL 返回 5xx 状态码和错误信息
8. THE Backend_API SHALL 支持 CORS 以允许前端跨域请求

Requirement 6: 数据模型

User Story: 作为开发者,我想要定义清晰的数据模型,以便前后端数据交互一致。

Acceptance Criteria

1. THE Backend_API SHALL 定义 Project 模型,包含 id、name、description、config、created_at 字段
2. THE Backend_API SHALL 定义 Task 模型,包含 id、project_id、name、data、status、assigned_to、created_at 字段
3. THE Backend_API SHALL 定义 Annotation 模型,包含 id、task_id、user_id、result、created_at、updated_at 字段
4. WHEN 创建任务 THEN THE Backend_API SHALL 验证 project_id 存在
5. WHEN 创建标注 THEN THE Backend_API SHALL 验证 task_id 存在
6. THE Backend_API SHALL 在删除项目时级联删除关联的任务和标注
7. THE Backend_API SHALL 使用 JSON 格式存储标注配置和标注结果

Requirement 7: 用户界面布局

User Story: 作为用户,我想要使用清晰的后台管理界面,以便快速访问各个功能模块。

Acceptance Criteria

1. THE Frontend_App SHALL 使用侧边栏导航布局
2. WHEN 用户访问应用 THEN THE Frontend_App SHALL 显示包含项目、任务、标注三个主菜单项的侧边栏
3. WHEN 用户点击菜单项 THEN THE Frontend_App SHALL 导航到对应的视图组件
4. THE Frontend_App SHALL 在顶部显示应用标题和用户信息
5. THE Frontend_App SHALL 使用响应式设计,支持不同屏幕尺寸
6. WHEN 视图组件渲染 THEN THE Frontend_App SHALL 在主内容区域显示视图内容
7. THE Frontend_App SHALL 使用 Tailwind CSS 语义化类名进行样式定义

Requirement 8: 标注编辑器集成

User Story: 作为标注人员,我想要使用功能完整的标注编辑器,以便高效完成标注工作。

Acceptance Criteria

1. THE Frontend_App SHALL 集成 @humansignal/editor 作为标注编辑器
2. WHEN 打开标注界面 THEN THE Frontend_App SHALL 使用项目的标注配置初始化编辑器
3. WHEN 编辑器初始化完成 THEN THE Frontend_App SHALL 加载任务数据到编辑器
4. WHEN 用户完成标注 THEN THE Frontend_App SHALL 从编辑器获取标注结果
5. THE Frontend_App SHALL 处理编辑器的加载状态和错误状态
6. WHEN 用户保存标注 THEN THE Frontend_App SHALL 序列化标注结果为 JSON 格式
7. THE Frontend_App SHALL 在编辑器卸载时正确清理资源

Requirement 9: 数据持久化

User Story: 作为系统,我想要可靠地存储和检索数据,以便保证数据完整性。

Acceptance Criteria

1. THE Backend_API SHALL 在应用启动时初始化 SQLite 数据库
2. THE Backend_API SHALL 创建必要的数据表结构
3. WHEN 接收到创建请求 THEN THE Backend_API SHALL 验证数据并插入数据库
4. WHEN 接收到查询请求 THEN THE Backend_API SHALL 从数据库检索数据并返回
5. WHEN 接收到更新请求 THEN THE Backend_API SHALL 验证数据并更新数据库记录
6. WHEN 接收到删除请求 THEN THE Backend_API SHALL 从数据库删除记录
7. THE Backend_API SHALL 使用事务确保数据一致性

Requirement 10: 错误处理和用户反馈

User Story: 作为用户,我想要在操作失败时看到清晰的错误信息,以便了解问题并采取行动。

Acceptance Criteria

1. WHEN API 请求失败 THEN THE Frontend_App SHALL 显示用户友好的错误消息
2. WHEN 表单验证失败 THEN THE Frontend_App SHALL 在相应字段旁显示验证错误
3. WHEN 操作成功 THEN THE Frontend_App SHALL 显示成功提示消息
4. WHEN 加载数据 THEN THE Frontend_App SHALL 显示加载指示器
5. THE Frontend_App SHALL 实现错误边界以捕获组件错误
6. WHEN 后端返回错误 THEN THE Backend_API SHALL 包含错误代码和描述性消息
7. THE Frontend_App SHALL 记录错误到控制台以便调试