# Implementation Plan: External API & Internal Management

## Overview

本实现计划将对外API接口和内部管理功能分为多个阶段实现：
1. 数据库扩展和基础设施
2. 对外API接口实现
3. 内部管理功能扩展
4. 前端界面实现

## Tasks

- [x] 1. 数据库扩展和基础设施
  - [x] 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服务层实现
  - [x] 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路由实现
  - [x] 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. 内部管理功能 - 项目状态管理
  - [x] 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. 内部管理功能 - 任务分发
  - [x] 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. 前端 - 项目列表扩展
  - [x] 9.1 更新项目列表组件
    - 显示项目状态标签
    - 显示项目来源标签（内部/外部）
    - 添加状态筛选器
    - 添加来源筛选器
    - _Requirements: 6.2, 6.3, 6.4_

  - [x] 9.2 添加项目状态操作按钮
    - 根据状态显示不同操作按钮
    - draft状态显示"配置项目"按钮
    - ready状态显示"一键分发"按钮
    - _Requirements: 6.5, 8.1_

- [x] 10. 前端 - 项目配置页面
  - [x] 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. 前端 - 一键分发对话框
  - [x] 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. 集成测试和文档
  - [x] 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