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

Implementation Plan: External API & Internal Management

Overview

本实现计划将对外API接口和内部管理功能分为多个阶段实现：

1. 数据库扩展和基础设施
2. 对外API接口实现
3. 内部管理功能扩展
4. 前端界面实现

Tasks

• [x] 1. 数据库扩展和基础设施

  • 1.1 扩展projects表结构
  • 添加 status 字段（VARCHAR(20) DEFAULT 'draft'）
  • 添加 source 字段（VARCHAR(20) DEFAULT 'internal'）
  • 添加 task_type 字段（VARCHAR(50)）
  • 添加 updated_at 字段（TIMESTAMP）
  • 添加 external_id 字段（VARCHAR(100)）

  • Requirements: 6.1, 10.1

  • [x] 1.2 创建对外API的Schema定义

  • 创建 backend/schemas/external.py

  • 定义 TaskType 枚举

  • 定义 ProjectInitRequest/Response

  • 定义 ProgressResponse 和 AnnotatorProgress

  • 定义 ExternalExportFormat 枚举

  • 定义 ExternalExportRequest/Response

  • 定义 ExportCallbackPayload

  • Requirements: 1.2, 1.4, 2.2, 3.1

  • [x] 1.3 扩展项目Schema定义

  • 更新 backend/schemas/project.py

  • 添加 ProjectStatus 枚举

  • 添加 ProjectSource 枚举

  • 添加 ProjectStatusUpdate 模型

  • 添加 ProjectConfigUpdate 模型

  • 添加 LabelConfig 模型

  • 添加 ProjectResponseExtended 模型

  • Requirements: 6.2, 6.3, 7.1, 10.1

  • [x] 1.4 创建任务分发相关Schema

  • 添加 DispatchRequest 模型

  • 添加 AssignmentPreviewRequest 模型

  • 添加 AnnotatorAssignment 模型

  • 添加 AssignmentPreviewResponse 模型

  • 添加 DispatchResponse 模型

  • Requirements: 8.1, 9.1, 9.2

• [x] 2. Checkpoint - 确保数据库迁移和Schema定义完成

  • 运行数据库迁移脚本
  • 验证新字段已添加
  • 确保所有Schema定义无语法错误

• [x] 3. 对外API服务层实现

  • 3.1 创建External Service
  • 创建 backend/services/external_service.py
  • 实现 init_project 方法（创建项目和任务）
  • 实现默认XML配置模板生成

  • Requirements: 1.2, 1.3, 5.5

  • [ ]* 3.2 编写项目创建完整性属性测试

  • Property 2: 项目创建完整性

  • 验证创建的任务数量等于输入数据项数量

  • Validates: Requirements 1.2, 1.3, 1.4

  • [x] 3.3 实现进度查询服务

  • 实现 get_project_progress 方法

  • 计算总任务数、已完成、进行中、待处理

  • 计算完成百分比

  • 获取每个标注人员的统计信息

  • Requirements: 2.1, 2.2, 2.3, 2.4

  • [ ]* 3.4 编写进度计算正确性属性测试

  • Property 3: 进度计算正确性

  • 验证完成百分比 = 已完成任务数 / 总任务数

  • Validates: Requirements 2.2, 2.3

  • [x] 3.5 实现数据导出服务

  • 实现 export_project_data 方法

  • 支持多种导出格式（JSON, CSV, ShareGPT, YOLO, COCO, Alpaca）

  • 实现文件生成和存储

  • 实现回调通知功能

  • Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.13, 3.14

  • [ ]* 3.6 编写导出过滤正确性属性测试

  • Property 5: 导出过滤正确性

  • 验证 completed_only=true 时只导出已完成任务

  • Validates: Requirements 3.9, 3.10

• [x] 4. 对外API路由实现

  • 4.1 创建External API Router
  • 创建 backend/routers/external.py
  • 实现 POST /api/external/projects/init 端点
  • 实现 GET /api/external/projects/{id}/progress 端点
  • 实现 POST /api/external/projects/{id}/export 端点
  • 添加管理员权限验证

  • Requirements: 1.1, 1.5, 2.1, 3.1, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6

  • [ ]* 4.2 编写Token验证一致性属性测试

  • Property 1: Token验证一致性

  • 验证无效Token返回401，非管理员返回403

  • Validates: Requirements 1.5, 4.2, 4.4, 4.5, 4.6

  • [x] 4.3 注册External Router到主应用

  • 更新 backend/main.py

  • 导入并注册 external router

  • Requirements: 1.1

• [x] 5. Checkpoint - 确保对外API功能完成

  • 测试项目初始化接口
  • 测试进度查询接口
  • 测试数据导出接口
  • 验证Token认证正常工作

• [x] 6. 内部管理功能 - 项目状态管理

  • 6.1 扩展Project Router
  • 更新 backend/routers/project.py
  • 添加 PUT /api/projects/{id}/status 端点
  • 添加 PUT /api/projects/{id}/config 端点
  • 实现状态流转验证逻辑

  • Requirements: 7.9, 10.2, 10.3, 10.4, 10.5, 10.7

  • [ ]* 6.2 编写项目状态流转正确性属性测试

  • Property 9: 项目状态流转正确性

  • 验证只允许合法的状态转换

  • Validates: Requirements 10.2, 10.3, 10.4, 10.5, 10.7

  • [x] 6.3 更新项目列表接口

  • 返回扩展的项目信息（状态、来源、任务类型）

  • 支持按状态筛选

  • 支持按来源筛选

  • Requirements: 6.2, 6.3, 6.4

• [x] 7. 内部管理功能 - 任务分发

  • 7.1 创建Assignment Service
  • 创建 backend/services/assignment_service.py
  • 实现 preview_assignment 方法
  • 实现 dispatch_tasks 方法
  • 实现 get_annotator_workload 方法

  • Requirements: 8.6, 8.7, 9.1, 9.2, 9.3

  • [ ]* 7.2 编写一键分发任务数量一致性属性测试

  • Property 10: 一键分发任务数量一致性

  • 验证分配的任务总数等于项目总任务数

  • Validates: Requirements 8.6, 8.7

  • [x] 7.3 扩展Task Router

  • 更新 backend/routers/task.py

  • 添加 POST /api/tasks/preview-assignment 端点

  • 添加 POST /api/projects/{id}/dispatch 端点

  • Requirements: 8.1, 8.2, 9.1, 9.5

  • [ ]* 7.4 编写分配预览与实际分配一致性属性测试

  • Property 11: 分配预览与实际分配一致性

  • 验证预览结果与实际分配结果一致

  • **Validates: Requirements 9.1, 9.2, 9.5_

• [x] 8. Checkpoint - 确保内部管理API功能完成

  • 测试项目状态更新接口
  • 测试项目配置更新接口
  • 测试任务分配预览接口
  • 测试一键分发接口

• [x] 9. 前端 - 项目列表扩展

  • 9.1 更新项目列表组件
  • 显示项目状态标签
  • 显示项目来源标签（内部/外部）
  • 添加状态筛选器
  • 添加来源筛选器

  • Requirements: 6.2, 6.3, 6.4

  • [x] 9.2 添加项目状态操作按钮

  • 根据状态显示不同操作按钮

  • draft状态显示"配置项目"按钮

  • ready状态显示"一键分发"按钮

  • Requirements: 6.5, 8.1

• [x] 10. 前端 - 项目配置页面

  • 10.1 创建标签编辑组件
  • 支持添加/删除/编辑标签
  • 支持设置标签颜色
  • 支持设置快捷键

  • Requirements: 7.2, 7.3, 7.4, 7.5

  • [x] 10.2 创建XML配置预览组件

  • 显示当前XML配置

  • 支持手动编辑XML

  • 实时预览配置效果

  • Requirements: 7.1, 7.6

  • [x] 10.3 实现配置保存和状态更新

  • 保存配置时验证XML有效性

  • 显示验证错误提示

  • 更新项目状态

  • Requirements: 7.7, 7.8, 7.9, 7.10

• [x] 11. 前端 - 一键分发对话框

  • 11.1 创建标注人员选择组件
  • 显示所有可用标注人员
  • 显示每个人员当前工作负载
  • 支持多选

  • Requirements: 8.2, 8.3, 8.4, 8.5

  • [x] 11.2 创建分配预览组件

  • 显示每个人员将分配的任务数

  • 显示分配百分比

  • Requirements: 9.1, 9.2, 9.3

  • [x] 11.3 实现分发确认和结果展示

  • 确认分发后执行分配

  • 显示分配结果摘要

  • 更新项目状态

  • Requirements: 8.8, 8.9, 9.5

• [x] 12. Checkpoint - 确保前端功能完成

  • 测试项目列表筛选功能
  • 测试项目配置页面
  • 测试一键分发流程
  • 验证状态流转正确

• [x] 13. 集成测试和文档

  • 13.1 编写集成测试
  • 测试完整流程：创建项目 → 配置 → 分发 → 标注 → 导出
  • 测试外部API认证流程
  • 测试各种错误场景

  • Requirements: 全部

  • [x] 13.2 更新API文档

  • 确保 EXTERNAL_API_DOCUMENTATION.md 与实现一致

  • 添加内部API文档（如需要）

  • Requirements: 全部

• [x] 14. Final Checkpoint - 确保所有功能完成

  • 运行所有测试 ✅ (15/15 passed)
  • 验证对外API文档准确性 ✅
  • 确认所有需求已实现 ✅

Test Results

最终测试结果 (2026-02-03):

• 15 个集成测试全部通过
• 测试覆盖：认证、项目初始化、进度查询、数据导出、状态转换、配置更新、任务分发

Notes

• Tasks marked with * are optional and can be skipped for faster MVP
• Each task references specific requirements for traceability
• Checkpoints ensure incremental validation
• Property tests validate universal correctness properties
• Unit tests validate specific examples and edge cases