# V2 AI 知识库上传任务与配置执行时间线闭环

日期：2026-06-23

## 本轮目标

按照《AI 合同平台 V2 重构版开发方案》，继续把知识库上传、文档解析、OCR、失败重试这类长流程能力收敛到 `yuqei-ai-platform`，合同 Web 只做管理展示和触发动作。

## 已完成

1. AI Platform 新增 `KnowledgeIngestionJob`
   - 记录知识库上传任务状态：`queued / running / succeeded / failed`
   - 记录解析状态：`pending / parsed / failed / ocr_required / ocr_skipped`
   - 记录 OCR 状态：`not_required / pending / skipped / succeeded / failed`
   - 记录失败原因、重试次数、关联导入批次、关联文档、worker 名称。

2. 上传接口升级为可追踪任务
   - `POST /api/v1/knowledge-bases/{knowledge_base_id}/documents`
   - 成功上传会返回 `ingestion_job`
   - 解析失败或扫描件无可读文本时，也会落一条失败任务，并在错误响应中返回任务信息。

3. 失败重试入口
   - `GET /api/v1/knowledge-ingestion-jobs`
   - `POST /api/v1/knowledge-ingestion-jobs/{job_id}/retry`
   - 当前 MVP 对已有关联导入批次的任务执行重建索引。
   - 对解析前失败且原始文件未暂存的任务，明确返回需要重新上传，避免伪造“已重试成功”。

4. 数据库迁移
   - 新增迁移：`20260623_0011_add_knowledge_ingestion_jobs.py`
   - 新增表：`knowledge_ingestion_jobs`
   - 增加状态、批次、文档、时间字段索引。

5. OpenAPI 与 Python SDK
   - OpenAPI 增加 `KnowledgeIngestionJob` schema 和任务查询/重试接口。
   - `KnowledgeDocumentUploadResult` 增加 `ingestion_job`。
   - `AiQualityImprovementExecutionBundle` 增加 `knowledge_ingestion_jobs`。
   - SDK 增加 `list_knowledge_ingestion_jobs`、`retry_knowledge_ingestion_job`。

6. 管理区前端
   - `/admin/ai-knowledge` 增加 Ingestion jobs 任务状态区。
   - 支持查看上传任务状态、解析状态、OCR 状态、失败原因、重试次数。
   - 失败任务支持从页面触发 retry。
   - 质量改进项详情页新增统一配置执行时间线：
     - 模型参数发布/回滚
     - Prompt 发布/回滚
     - 知识库上传任务
     - 知识库重建索引

## 与 V2 方案的一致性

- 新能力位于 `yuqei-ai-platform`，没有写入合同业务后端。
- 合同 Web 只通过 AI Platform API 代理展示和触发动作。
- SDK 与 OpenAPI 同步更新，保持 AI 中台调用边界清晰。
- OCR 目前是任务状态和扩展点，不假装已有完整 OCR 引擎。
- 真正 worker 队列后续可以直接消费 `knowledge_ingestion_jobs`，不需要推翻管理页和 SDK。

## 验证

- `python -m pytest yuqei-ai-platform\services\ai-platform-api\tests\test_platform_data.py -q`
- `python -m pytest yuqei-ai-sdk-python\tests\test_ai_platform.py -q`
- `npm --prefix yuqei-contract-platform/apps/contract-web run build`
- OpenAPI YAML 解析通过
- `git diff --check` 通过

## 后续建议

下一步可继续进入真实 worker 执行循环：把当前 API 同步解析逻辑拆成任务创建 + worker 消费，并接入对象存储暂存原始上传文件、真实 OCR provider、任务日志和幂等键。