LabelingSystem/.kiro/specs/external-api/requirements.md

Requirements Document

Introduction

本文档定义了标注平台对外开放API及内部配套管理功能的需求规范。这些功能主要用于：

1. 与"样本中心"等外部系统集成，支持项目初始化、进度查询和数据导出
2. 管理员对预派发项目进行配置和任务分发
3. 自动化的任务分配流程

外部系统使用管理员长期有效的Token进行身份验证。

Glossary

• External_API: 对外开放的API接口，供样本中心等外部系统调用
• Sample_Center: 样本中心，外部系统，负责发布初始标注任务
• Project: 标注项目，包含配置信息和任务列表
• Task: 标注任务，包含待标注的数据项
• Annotation: 标注结果，用户对任务数据的标注
• Admin_Token: 管理员长期有效的访问令牌
• Task_Item: 任务中的单个数据项（如单张图片、单条文本）
• Progress: 项目或任务的完成进度
• Pre_Dispatch_Project: 预派发项目，由外部系统创建但尚未配置完成的项目
• Project_Status: 项目状态（draft草稿/configuring配置中/ready就绪/in_progress进行中/completed已完成）
• Auto_Assignment: 自动任务分配，系统自动将任务平均分配给选定的标注人员

Requirements

Requirement 1: 对外项目初始化接口

User Story: As a 样本中心系统, I want to 通过API创建标注项目并导入初始任务数据, so that 标注平台管理员可以对项目进行配置和任务分发。

Acceptance Criteria

1. WHEN 样本中心调用项目初始化接口并提供有效的管理员Token THEN THE External_API SHALL 验证Token有效性并允许创建项目
2. WHEN 样本中心提供项目名称、描述和任务类型 THEN THE External_API SHALL 创建一个新的标注项目并返回项目ID
3. WHEN 样本中心提供任务数据列表（文本或图像URL列表） THEN THE External_API SHALL 为每个数据项创建对应的任务记录
4. WHEN 项目创建成功 THEN THE External_API SHALL 返回项目ID、创建的任务数量和项目状态
5. IF 提供的Token无效或过期 THEN THE External_API SHALL 返回401未授权错误
6. IF 请求参数缺失或格式错误 THEN THE External_API SHALL 返回400错误并说明具体问题
7. WHEN 任务类型为文本标注 THEN THE External_API SHALL 接受文本内容数组作为任务数据
8. WHEN 任务类型为图像标注 THEN THE External_API SHALL 接受图像URL数组作为任务数据

Requirement 2: 对外项目进度查询接口

User Story: As a 样本中心系统, I want to 查询标注项目的进度信息, so that 我可以监控标注工作的完成情况。

Acceptance Criteria

1. WHEN 样本中心调用进度查询接口并提供项目ID THEN THE External_API SHALL 返回该项目的详细进度信息
2. THE External_API SHALL 返回以下进度指标：总任务数、已完成任务数、进行中任务数、待处理任务数
3. THE External_API SHALL 返回项目整体完成百分比
4. WHEN 查询进度时 THEN THE External_API SHALL 返回每个标注人员的任务分配和完成情况
5. IF 项目ID不存在 THEN THE External_API SHALL 返回404错误
6. IF Token无效 THEN THE External_API SHALL 返回401未授权错误
7. THE External_API SHALL 返回项目的最后更新时间

Requirement 3: 对外数据导出接口

User Story: As a 样本中心系统, I want to 导出标注完成的数据, so that 我可以获取标注结果用于后续处理。

Acceptance Criteria

1. WHEN 样本中心调用数据导出接口并提供项目ID THEN THE External_API SHALL 返回该项目的标注数据文件
2. THE External_API SHALL 支持JSON格式导出
3. THE External_API SHALL 支持CSV格式导出
4. THE External_API SHALL 支持ShareGPT对话格式导出
5. THE External_API SHALL 支持YOLO目标检测格式导出
6. THE External_API SHALL 支持COCO数据集格式导出
7. THE External_API SHALL 支持Alpaca指令微调格式导出
8. WHEN 导出数据时 THEN THE External_API SHALL 以文件形式返回数据
9. WHERE 用户指定只导出已完成任务 THEN THE External_API SHALL 仅返回状态为completed的任务数据
10. WHERE 用户指定导出所有任务 THEN THE External_API SHALL 返回所有任务数据（包括未完成的）
11. IF 项目ID不存在 THEN THE External_API SHALL 返回404错误
12. IF Token无效 THEN THE External_API SHALL 返回401未授权错误
13. WHEN 导出成功 THEN THE External_API SHALL 返回文件下载链接
14. WHERE 用户提供回调URL THEN THE External_API SHALL 在导出完成后向该URL发送通知

Requirement 4: API安全认证

User Story: As a 系统管理员, I want to 使用长期有效的管理员Token进行API认证, so that 外部系统可以安全地调用对外接口。

Acceptance Criteria

1. THE External_API SHALL 使用Bearer Token方式进行身份验证
2. WHEN 请求头中包含有效的Authorization Bearer Token THEN THE External_API SHALL 允许访问
3. IF 请求头中缺少Authorization THEN THE External_API SHALL 返回401错误
4. IF Token格式不正确 THEN THE External_API SHALL 返回401错误
5. THE External_API SHALL 验证Token对应的用户具有管理员权限
6. IF Token对应的用户不是管理员 THEN THE External_API SHALL 返回403禁止访问错误

Requirement 5: 任务类型支持

User Story: As a 样本中心系统, I want to 创建不同类型的标注任务, so that 我可以支持文本标注和图像标注等多种场景。

Acceptance Criteria

1. THE External_API SHALL 支持文本分类标注任务类型
2. THE External_API SHALL 支持图像分类标注任务类型
3. THE External_API SHALL 支持图像目标检测标注任务类型
4. THE External_API SHALL 支持命名实体识别（NER）标注任务类型
5. WHEN 创建项目时指定任务类型 THEN THE External_API SHALL 生成对应的默认XML配置模板（不含标签）
6. THE System SHALL 由管理员在项目配置阶段设置标签

Requirement 6: 预派发项目管理

User Story: As a 管理员, I want to 管理由外部系统创建的预派发项目, so that 我可以对项目进行配置和准备工作。

Acceptance Criteria

1. WHEN 外部系统创建项目后 THEN THE System SHALL 将项目状态设置为"draft"（草稿）
2. THE System SHALL 在项目列表中显示项目来源（内部创建/外部创建）
3. WHEN 管理员查看预派发项目列表 THEN THE System SHALL 显示项目名称、任务数量、创建时间和当前状态
4. THE System SHALL 支持按项目状态筛选项目列表
5. WHEN 管理员点击配置项目 THEN THE System SHALL 进入项目配置页面
6. THE System SHALL 显示项目的任务类型和默认配置模板

Requirement 7: 项目配置功能

User Story: As a 管理员, I want to 配置预派发项目的标注词条和标签, so that 标注人员可以使用正确的标签进行标注。

Acceptance Criteria

1. WHEN 管理员进入项目配置页面 THEN THE System SHALL 显示当前的XML配置
2. THE System SHALL 提供可视化的标签编辑界面
3. WHEN 管理员添加新标签 THEN THE System SHALL 更新XML配置中的标签列表
4. WHEN 管理员删除标签 THEN THE System SHALL 从XML配置中移除该标签
5. WHEN 管理员修改标签名称或颜色 THEN THE System SHALL 更新XML配置中的对应属性
6. THE System SHALL 提供XML配置的预览功能
7. THE System SHALL 验证XML配置的有效性
8. IF XML配置无效 THEN THE System SHALL 显示错误提示并阻止保存
9. WHEN 管理员保存配置 THEN THE System SHALL 将项目状态更新为"configuring"（配置中）
10. WHEN 管理员确认配置完成 THEN THE System SHALL 将项目状态更新为"ready"（就绪）

Requirement 8: 一键任务分发

User Story: As a 管理员, I want to 一键将任务分发给多个标注人员, so that 我可以快速启动标注工作。

Acceptance Criteria

1. WHEN 项目状态为"ready" THEN THE System SHALL 显示"一键分发"按钮
2. WHEN 管理员点击一键分发 THEN THE System SHALL 显示标注人员选择界面
3. THE System SHALL 显示所有可用的标注人员列表
4. THE System SHALL 支持多选标注人员
5. THE System SHALL 显示每个标注人员当前的任务负载
6. WHEN 管理员选择标注人员并确认分发 THEN THE System SHALL 自动平均分配任务
7. THE System SHALL 使用"equal"模式进行任务分配，确保每个人分配的任务数量尽量相等
8. WHEN 任务分配完成 THEN THE System SHALL 将项目状态更新为"in_progress"（进行中）
9. WHEN 任务分配完成 THEN THE System SHALL 显示分配结果摘要
10. THE System SHALL 记录任务分配的历史记录

Requirement 9: 任务分配预览

User Story: As a 管理员, I want to 在分发前预览任务分配结果, so that 我可以确认分配方案是否合理。

Acceptance Criteria

1. WHEN 管理员选择标注人员后 THEN THE System SHALL 显示分配预览
2. THE System SHALL 显示每个标注人员将分配到的任务数量
3. THE System SHALL 显示任务分配的百分比分布
4. THE System SHALL 支持调整分配比例（可选）
5. WHEN 管理员确认分配方案 THEN THE System SHALL 执行实际分配

Requirement 10: 项目状态流转

User Story: As a 系统, I want to 管理项目的状态流转, so that 项目可以按照正确的流程进行。

Acceptance Criteria

1. THE System SHALL 支持以下项目状态：draft（草稿）、configuring（配置中）、ready（就绪）、in_progress（进行中）、completed（已完成）
2. WHEN 外部系统创建项目 THEN THE System SHALL 设置状态为"draft"
3. WHEN 管理员开始配置项目 THEN THE System SHALL 允许状态从"draft"转为"configuring"
4. WHEN 管理员完成配置 THEN THE System SHALL 允许状态从"configuring"转为"ready"
5. WHEN 管理员分发任务 THEN THE System SHALL 允许状态从"ready"转为"in_progress"
6. WHEN 所有任务完成 THEN THE System SHALL 自动将状态更新为"completed"
7. IF 状态转换不符合规则 THEN THE System SHALL 拒绝操作并提示错误