From e3b5b4d50fd2b88b9bb3c05bce92f14ff2c6d43c Mon Sep 17 00:00:00 2001 From: d-robotics Date: Wed, 2 Sep 2026 16:00:42 +0800 Subject: [PATCH] docs: plan async ingestion and prioritize MCP --- docs/api/API_CONTRACT.md | 35 ++++++++ docs/api/MCP_CONTRACT.md | 24 ++++++ docs/architecture/ARCHITECTURE.md | 33 ++++++++ docs/demo/DEMO_SCOPE.md | 48 +++++++++-- docs/development/DEFINITION_OF_DONE.md | 9 ++ docs/plans/ASYNC_INGESTION_MCP_PLAN.md | 109 +++++++++++++++++++++++++ docs/plans/PROGRESS.md | 18 ++++ docs/plans/TASKS.md | 17 ++++ docs/plans/V1_EXECUTION_PLAN.md | 12 +++ docs/product/PRD.md | 14 ++++ 10 files changed, 311 insertions(+), 8 deletions(-) create mode 100644 docs/plans/ASYNC_INGESTION_MCP_PLAN.md diff --git a/docs/api/API_CONTRACT.md b/docs/api/API_CONTRACT.md index 704a167..743d756 100644 --- a/docs/api/API_CONTRACT.md +++ b/docs/api/API_CONTRACT.md @@ -11,6 +11,8 @@ Use OpenAPI as executable source of truth once implementation starts. Provider-s DEMO-009 公开以下最小接口。`docs/demo/DEMO_SCOPE.md` 中的 `/api/*` 逻辑路径按本契约统一 版本化为 `/api/v1/*`。 +下表描述当前已实现的同步 Demo 契约;它将在 `DEMO-015` 完成时由后文的异步契约替代。 + | Method | Path | 行为 | |---|---|---| | `POST` | `/api/v1/documents` | multipart 单文件上传并同步执行完整入库流水线 | @@ -60,3 +62,36 @@ Search 响应: DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个客户端路由, `/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST 契约;所有业务操作仍调用 `/api/v1`。 + +## Planned async ingestion contract(DEMO-015/016,尚未实现) + +| Method | Path | 行为 | +|---|---|---| +| `POST` | `/api/v1/documents` | 单文件接收;持久化 Source、Document、Job 后返回 `202` | +| `POST` | `/api/v1/ingestion-batches` | multipart 多文件接收,返回批次及逐文件 Document/Job 标识 | +| `GET` | `/api/v1/ingestion-batches/{batch_id}` | 返回批次汇总和逐文件最新状态 | +| `GET` | `/api/v1/jobs/{job_id}` | 返回阶段、状态、attempt、最大尝试次数和安全错误信息 | + +单文件与批量上传都不等待解析、Chunk、Embedding 或索引完成。批量响应示意: + +```json +{ + "batch_id": "d21f8012-4c4e-4bb4-89af-e11c0f9f470e", + "items": [ + { + "filename": "退款政策.md", + "document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752", + "job_id": "7adc4278-1157-4c3d-95a4-6926ad77a04e", + "status": "queued" + } + ] +} +``` + +Job 公开状态为 `queued | running | retrying | succeeded | failed | cancelled`,并通过 `stage` +表示 `parsing | cleaning | chunking | embedding | indexing`。错误字段只返回有界、安全摘要。 +批次允许逐文件部分接收/失败,不以一个文件的处理结果回滚其他文件。文件数量、单文件大小和 +请求总大小均由服务端配置限制。 + +自动重试是服务端 Job 行为,不要求客户端再次上传,也不新增公开手动重试接口。每次重试前 +清理派生数据但保留原始文件和稳定的 Document ID;达到次数上限或清理失败后进入 `failed`。 diff --git a/docs/api/MCP_CONTRACT.md b/docs/api/MCP_CONTRACT.md index 05a42d3..59549b0 100644 --- a/docs/api/MCP_CONTRACT.md +++ b/docs/api/MCP_CONTRACT.md @@ -9,3 +9,27 @@ P0 business tools: - `list_knowledge_bases` Every request maps to a user/service identity and uses the same authorization/application services as REST. Do not expose OceanBase Vector, BOS, model names, parsers or other infrastructure choices. + +## Demo priority slice(DEMO-012,尚未实现) + +`DEMO-012` 已提升为当前最高实现优先级。首个可运行 Gateway 只注册 +`search_knowledge`,其输入与 `/api/v1/search` 对齐: + +```json +{ + "query": "产品A退款周期是多少?", + "top_k": 5 +} +``` + +输出保留业务来源字段:`document_id`、`filename`、`page`、`section`、`chunk_id`、`content` +和排序分数。Gateway 必须复用现有 Search Service 或正式 REST API,不得复制检索、来源补全 +或排序逻辑。 + +Demo 验证也必须建立 user/service identity 映射边界,禁止使用共享超级管理员 Token。由于 +Document ACL 尚未进入 Demo Scope,`DEMO-012` 只能证明身份传递、认证拒绝和业务服务复用, +不能声称完成 V1 ACL 授权闭环。错误响应和日志不得包含 Provider Endpoint、凭据、数据库表名 +或模型名。 + +验收至少覆盖:MCP 工具发现、参数校验、成功检索、无结果、认证失败、安全错误收敛,以及 +WorkBuddy Enterprise 的一次端到端调用。其余 P0 tools 继续留在完整 V1 `EKP-071`。 diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 236f6aa..8dbdecc 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -174,6 +174,34 @@ Queued / Parsing / Cleaning / Chunking / Embedding / Indexing / Completed / Fail - 软删除; - 来源页码和章节追踪。 +### 4.2.1 批量异步提交与失败恢复 + +API 只负责校验并持久化不可变源文件、Document 和 Ingestion Job,然后返回 `202`。批次是 +提交与聚合查询边界,不是跨文件数据库事务;每个文件独立排队、执行和失败。 + +```text +Batch Request + ├─ Source A + Document A + Job A ─→ Worker + ├─ Source B + Document B + Job B ─→ Worker + └─ Source C + Document C + Job C ─→ Worker +``` + +Worker 对可重试错误执行有界退避。重新执行前必须通过独立的派生数据清理服务按以下顺序 +恢复干净状态: + +```text +Vector/Sparse rows +→ ChunkIndexState +→ Chunks +→ Parsed artifact + parsed_storage_key +→ reset processing state +→ next attempt from immutable source +``` + +清理服务与 Document 删除语义分离:重试清理保留原始 BOS 对象、Document 和 Job/Attempt +历史。清理失败时 Job 终止,不能在未知状态继续执行。Job 通过数据库状态、唯一有效 Attempt +和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。 + --- ### 4.3 文档结构与 Chunk @@ -604,6 +632,11 @@ ReindexJob EvaluationJob ``` +当前增量实现先提供单个 `IngestionJob` 编排既有 Parse/Clean/Chunk/Embedding/Indexing 阶段, +保留阶段级状态和 Attempt 历史;以后拆分为独立阶段 Job 时不得改变公开批次/Job 查询契约。 +Demo 默认最多 3 次总尝试,只有瞬时 Provider、网络、存储或数据库错误进入自动重试;输入 +校验和确定性内容错误直接终止。 + GPU 节点优先承担: - MinerU / OCR; diff --git a/docs/demo/DEMO_SCOPE.md b/docs/demo/DEMO_SCOPE.md index bd9822d..4788f4e 100644 --- a/docs/demo/DEMO_SCOPE.md +++ b/docs/demo/DEMO_SCOPE.md @@ -305,7 +305,7 @@ Search Response 示例: --- -## 8. P1 可选增强 +## 8. Demo 后续增强 ### DEMO-011 Hybrid Search @@ -323,12 +323,25 @@ Reranker ### DEMO-012 MCP -只实现一个最小 MCP Tool:`search_knowledge`,内部调用 `/api/search`,用于验证 WorkBuddy 接入。 +**已批准并提升为下一优先级。** 只实现一个最小 MCP Tool:`search_knowledge`,复用现有 +Search Service 或 `/api/v1/search`,用于验证标准 MCP、identity 边界和 WorkBuddy 接入。 +不在本 Task 扩展其他 P0 tools 或声称完成尚未实施的 Document ACL。 ### DEMO-013 OCR / MinerU 增加扫描 PDF、图片、OCR 和复杂中文 PDF 处理能力。 +### DEMO-015 异步入库 Job 与自动重试清理 + +将现有同步入库流水线放入持久化 Ingestion Job。可重试失败自动执行有界重试;每次重试前 +删除旧解析产物、Chunk、索引状态和向量数据,但保留不可变原始文件、Document 和 Attempt +历史。清理失败时终止,不在未知脏状态继续执行。 + +### DEMO-016 批量异步上传 + +在 DEMO-015 基础上支持一次提交多个文件、逐文件 Document/Job 状态、批次聚合查询和 +Admin Console 状态展示。批次内文件相互隔离,不包含目录上传、压缩包解包或断点续传。 + --- ## 9. 明确后置能力 @@ -369,22 +382,36 @@ DEMO-007 Dense Retrieval DEMO-008 Reranker + Source Result DEMO-009 Document/Search REST API DEMO-010 简单 Admin Console +DEMO-012 MCP search_knowledge(已提升优先级) DEMO-014 地瓜机器人品牌化前端优化(用户新增) +DEMO-015 异步入库 Job + 自动重试前清理(用户新增) +DEMO-016 批量异步上传 + 状态展示(用户新增) ARCH-001~006 Provider 架构迁移与真实验收 ``` 实施状态(2026-09-02):`DEMO-001~DEMO-010`、用户新增的 `DEMO-014` 与 -`ARCH-001~ARCH-006` 均已完成并通过当前 Scope 的闭环验收。`DEMO-011~DEMO-013` 仍为 -可选项,不因本状态记录自动进入范围。 +`ARCH-001~ARCH-006` 均已完成并通过当前 Scope 的闭环验收。`PLAN-001` 已完成现状审计和 +任务拆分;`DEMO-012`、`DEMO-015`、`DEMO-016` 已批准,按该顺序实施。`DEMO-011` 和 +`DEMO-013` 仍为可选项,不因本状态记录自动进入范围。 可选: ```text DEMO-011 Hybrid Search -DEMO-012 MCP search_knowledge DEMO-013 OCR / MinerU ``` +已批准顺序: + +```text +DEMO-012 MCP search_knowledge + → DEMO-015 Async Job + Retry Cleanup + → DEMO-016 Batch Async Upload + UI +``` + +详细 Task 映射、依赖与验收边界见 +[`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`](../plans/ASYNC_INGESTION_MCP_PLAN.md)。 + --- ## 11. Demo 测试数据 @@ -473,7 +500,8 @@ Demo 阶段不设严格生产指标。 ## 14. Codex 开发约束 -Codex 当前只能实现 `DEMO-001 ~ DEMO-010` 和已批准的 `ARCH-001 ~ ARCH-006`。 +Codex 当前只能实现 `DEMO-001 ~ DEMO-010`、`DEMO-012`、`DEMO-014 ~ DEMO-016` 和已批准的 +`ARCH-001 ~ ARCH-006`。 ARCH 迁移任务不授权实现下列被排除的完整 V1 能力。 除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、微服务、Kubernetes 和企业级 Job Queue。 @@ -551,10 +579,14 @@ Upload ```text Demo ↓ -Hybrid Search - ↓ MCP ↓ +Async Job + Retry Cleanup + ↓ +Batch Async Upload + ↓ +Hybrid Search + ↓ OCR / Complex Parsing ↓ Document Version diff --git a/docs/development/DEFINITION_OF_DONE.md b/docs/development/DEFINITION_OF_DONE.md index 5f3f431..cecf152 100644 --- a/docs/development/DEFINITION_OF_DONE.md +++ b/docs/development/DEFINITION_OF_DONE.md @@ -1,3 +1,12 @@ # Definition of Done A task is done only when scope is implemented, architecture invariants hold, format/lint/typecheck pass, relevant tests pass, migrations/contracts/docs are updated as needed, no secrets are committed, retrieval changes include RAG regression results, and known limitations are documented. + +For asynchronous ingestion or retry tasks, relevant tests must also prove durable Job/Attempt state, +bounded retry classification, idempotent duplicate delivery, cleanup-before-retry, preservation of the +immutable source, and terminal behavior when cleanup fails. Batch ingestion must cover per-file partial +failure and configured limits. + +For MCP tasks, contract tests must cover tool discovery, identity propagation, authorization/error +boundaries, REST/application-service parity, infrastructure redaction, and the explicitly targeted MCP +client compatibility check. diff --git a/docs/plans/ASYNC_INGESTION_MCP_PLAN.md b/docs/plans/ASYNC_INGESTION_MCP_PLAN.md new file mode 100644 index 0000000..1923515 --- /dev/null +++ b/docs/plans/ASYNC_INGESTION_MCP_PLAN.md @@ -0,0 +1,109 @@ +# MCP 与异步批量入库优先级方案 + +**Task:** PLAN-001 +**Status:** Accepted planning baseline +**Date:** 2026-09-02 + +## 1. 现状判断 + +| 能力 | 当前实现 | 结论 | +|---|---|---| +| 单文件上传 | `POST /api/v1/documents` 接收一个 `file`,并在请求线程内同步完成解析、Chunk、Embedding 和索引 | 已实现,但不满足 V1 异步要求 | +| 批量上传 | API 与 Admin Console 都只支持一个文件 | 未实现 | +| 失败补偿 | 上传元数据失败会删除源对象;解析元数据失败会删除本次解析产物;索引失败会删除当前 Document/Profile 的可能残留向量 | 已有局部补偿,不是自动重试 | +| 自动重试 | 没有持久化 Job、Attempt、调度器、退避策略或自动重新执行入口 | 未实现 | +| 重试前清理 | 影子索引重建能清理目标 Profile 的部分写入;正常上传流水线没有统一清理解析产物、Chunk、索引状态和向量的能力 | 未实现 | +| MCP | 已有 MCP 业务契约和可复用 Search Service/REST API,没有可运行 MCP Gateway 或 WorkBuddy 验证 | 未实现 | + +因此,现有失败补偿只能降低一次执行留下半成品的概率,不能满足“失败后自动重新执行,并在重新执行前清理旧数据”。 + +## 2. Task 归并结论 + +### DEMO-012:MCP `search_knowledge`(提升为最高优先级) + +保留既有 Task ID,不新建重复任务。范围限定为: + +- 提供可运行的标准 MCP Gateway; +- 只暴露 `search_knowledge`; +- 复用现有 Search Service 或正式 `/api/v1/search`,不复制检索逻辑; +- 建立 WorkBuddy 所需的 user/service identity 边界,不使用共享超级管理员凭据; +- 完成协议契约、错误收敛、凭据脱敏和 WorkBuddy 兼容性验证。 + +该 Task 是 `EKP-070`、`EKP-071`、`EKP-072` 的最小垂直切片,不能据此把三个完整 V1 Task 标记为完成。 + +### DEMO-015:异步入库 Job 与自动重试清理(新增) + +从 `EKP-017` 和 `EKP-023` 抽取 Demo 所需的最小基础能力,并复用 DEMO-003~006 的处理服务: + +- 新增持久化 Ingestion Job/Attempt,记录阶段、状态、尝试次数、安全错误和时间戳; +- 源文件成功写入 BOS 且 Document 已持久化后立即排队,API 不等待解析和索引; +- 同一 Document 同时最多一个有效执行,任务投递和消费具备幂等保护; +- 对可重试的瞬时错误自动执行有界重试和退避;Demo 默认最多 3 次总尝试,允许通过非敏感配置调整; +- 格式不支持、文件为空、无可提取内容等确定性错误直接失败,不进行无意义重试; +- 每次重新执行前,按顺序清理该 Document 的向量行、`ChunkIndexState`、Chunk 和解析产物,再从不可变原始文件重新处理; +- 原始文件、Document 标识和审计所需的 Job/Attempt 历史不得被重试清理删除; +- 任一清理步骤失败时禁止启动下一次尝试,并记录为终止失败,避免在未知脏状态上重复执行。 + +该 Task 只完成 Demo 入库所需的 Job/Retry 基线,不扩展到完整审计系统、Compilation、OCR、分布式高可用或通用企业级 Job 平台。 + +### DEMO-016:批量异步上传与状态展示(新增) + +建立在 DEMO-015 之上,不与 Job 基础合并: + +- 新增批量上传 API,一次接收多个 Demo 支持类型文件; +- 每个文件独立生成 Document 和 Ingestion Job,单个文件失败不回滚已成功接收的其他文件; +- 返回批次 ID、逐文件 Document ID、Job ID 和接收状态,不等待后台处理完成; +- 提供批次/Job 查询能力,并在 Admin Console 展示逐文件阶段、重试次数和最终结果; +- 文件数量、单文件大小和请求总大小均受可配置限制; +- 不在本 Task 引入目录上传、压缩包解包、断点续传或跨批次去重。 + +该 Task 对应 `EKP-021` 的批量异步扩展及 `EKP-080`/`EKP-081` 的最小状态 UI 切片,不能据此把完整 V1 Task 标记为完成。 + +## 3. 实施顺序与依赖 + +```text +DEMO-009 + ARCH-006 + └──→ DEMO-012 MCP search_knowledge + +DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006 + └──→ DEMO-015 Async Job + Retry Cleanup + └──→ DEMO-016 Batch Async Upload + UI +``` + +推荐严格按以下顺序执行并逐项闭环: + +1. `DEMO-012` +2. `DEMO-015` +3. `DEMO-016` + +MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不会阻塞后续批量上传。`DEMO-016` 必须等待 `DEMO-015`,否则会把同步流水线简单并发放大,缺少可靠的状态、隔离和恢复边界。 + +## 4. 验收边界 + +### DEMO-012 + +- MCP Inspector/标准客户端能发现并调用 `search_knowledge`; +- WorkBuddy 使用已映射的 user/service identity 完成一次端到端检索; +- REST 与 MCP 对同一查询复用同一业务逻辑并返回一致的来源字段; +- 响应与日志不泄露 OceanBase、BOS、模型名、Endpoint 或凭据。 + +### DEMO-015 + +- 上传接口在源文件和 Job 持久化后返回 `202`,后台完成现有全流水线; +- 注入一次可重试故障后可观察到自动重试,并最终成功; +- 第二次尝试开始前,旧解析产物、Chunk、索引状态和向量均已清理,原始源文件仍存在; +- 永久错误不重试,达到次数上限后稳定进入 `failed`; +- 并发或重复投递不会产生双重有效执行和重复派生数据。 + +### DEMO-016 + +- 一次提交多个文件后立即得到逐文件 Document/Job 标识; +- 批次内成功、处理中、重试中和失败状态互不影响且可查询; +- Admin Console 无需刷新即可轮询展示逐文件进度和最终状态; +- 批次边界、大小限制、部分失败和重试清理均有集成测试。 + +## 5. 非目标与 ADR 影响 + +- 不把 RabbitMQ/Celery、Kubernetes、高可用或完整 Observability 纳入上述 Demo Task;具体执行器继续通过接口隔离,后续 V1 可替换。 +- 不改变 OceanBase/BOS canonical、向量索引可重建、原始文档不可变、Provider 抽象和 MCP 隐藏基础设施等 Accepted ADR。 +- 本次只是任务拆分、优先级和契约澄清,不需要新增或重开 Accepted ADR。 diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index b49e3b2..ab4dafe 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -267,3 +267,21 @@ Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → AR - 完整验证结果:Ruff Format/Lint、Mypy、JavaScript 语法与 Git diff 通过;Unit、Integration 和 RAG Evaluation 合计 `155 passed`;Alembic Head 与离线升级通过。本任务不修改 API、 检索算法、Provider 或数据库,不重复调用真实资源验收。 + +### PLAN-001(已完成) + +- 审计确认当前 `/api/v1/documents` 仅接受一个文件,并在请求线程同步执行解析、Chunk、 + Embedding 和索引;API 与 Admin Console 均没有批量提交、Job 查询或后台状态轮询。 +- 当前上传、解析和向量索引具备阶段内失败补偿,影子索引重建具备目标 Profile 的重试安全 + 清理,但正常上传流水线没有持久化 Job/Attempt、自动调度退避或统一的重试前派生数据清理, + 因而不能视为已实现自动重试。 +- 保留既有 `DEMO-012` 并提升为最高优先级;新增 `DEMO-015` 承担 Async Job、自动重试和 + 重试前清理,新增 `DEMO-016` 承担批量异步上传和逐文件状态 UI。严格执行顺序为 + `DEMO-012 → DEMO-015 → DEMO-016`。 +- 已更新 PRD、Architecture、API/MCP Contract、Execution Plan、Task List、Demo Scope 与 DoD; + 本任务只形成规划和待实现契约,没有修改业务代码、数据库 Migration 或 Accepted ADR。 +- 验证结果:Ruff Format/Lint、Mypy、Git diff 与 Alembic Head/离线升级通过;Unit + Integration + `150 passed`,RAG Evaluation `5 passed`。首次受限网络运行因无法解析 PyPI 失败,获准联网 + 获取已锁定的构建依赖后全套复验通过。 +- 下一任务:`DEMO-012`。详细依赖、范围和验收标准见 + `docs/plans/ASYNC_INGESTION_MCP_PLAN.md`。 diff --git a/docs/plans/TASKS.md b/docs/plans/TASKS.md index a2bbfa3..67e8880 100644 --- a/docs/plans/TASKS.md +++ b/docs/plans/TASKS.md @@ -23,6 +23,23 @@ ARCH-001 Each architecture task uses an independent branch and is merged into `main` only after its own validation. Provider credentials and internal endpoints are runtime inputs and never task artifacts. +## Post-Demo priority plan + +- [x] PLAN-001 MCP 与异步批量入库现状审计、任务拆分和契约基线 +- [ ] DEMO-012 MCP `search_knowledge` Gateway + identity + WorkBuddy verification +- [ ] DEMO-015 Async ingestion Job + bounded automatic retry + pre-retry cleanup +- [ ] DEMO-016 Batch async upload API + per-file Job status + Admin Console + +Dependencies and acceptance boundaries are defined in +[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md). These Demo tasks are vertical slices of +the V1 backlog below; completing a slice does not automatically complete its corresponding `EKP-*` +task. + +```text +DEMO-009 + ARCH-006 → DEMO-012 +DEMO-003~006 → DEMO-015 → DEMO-016 +``` + ## Phase 0 - [ ] EKP-001 Repository bootstrap - [ ] EKP-002 Backend Python toolchain diff --git a/docs/plans/V1_EXECUTION_PLAN.md b/docs/plans/V1_EXECUTION_PLAN.md index 203907a..87f1bda 100644 --- a/docs/plans/V1_EXECUTION_PLAN.md +++ b/docs/plans/V1_EXECUTION_PLAN.md @@ -9,3 +9,15 @@ 7. Admin Console 8. Knowledge Compilation 9. Evaluation, security and release hardening + +## 当前增量实施顺序(2026-09-02) + +在不扩大 V1 范围的前提下,当前先按 Demo 垂直切片补齐已确认的高优先级能力: + +1. `DEMO-012`:MCP `search_knowledge`、identity 边界和 WorkBuddy 验证; +2. `DEMO-015`:异步入库 Job、自动重试和重试前派生数据清理; +3. `DEMO-016`:批量异步上传、批次/Job 查询和 Admin Console 状态展示。 + +`DEMO-012` 复用已经完成的 Search Service,可独立先行。`DEMO-016` 依赖 `DEMO-015`,不得在 +缺少持久化状态、幂等执行和恢复边界时直接并发调用当前同步流水线。详细范围和验收标准见 +[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md)。 diff --git a/docs/product/PRD.md b/docs/product/PRD.md index 595cde7..25c3436 100644 --- a/docs/product/PRD.md +++ b/docs/product/PRD.md @@ -447,6 +447,9 @@ V1 必须支持: Document processing 必须异步执行。 +源文件与 Document/Job 成功持久化后返回 `202 Accepted`。批量上传中的每个文件拥有独立的 +Document ID 和 Ingestion Job;单个文件处理失败不得阻塞或回滚批次内其他已接收文件。 + **REQ-INGEST-004** 展示处理阶段: @@ -468,10 +471,18 @@ Failed 失败必须展示: - Failed Stage; +- Attempt Count; +- 是否仍会自动重试; - Error Code; - Error Message; - Retry。 +**REQ-INGEST-006** + +可重试的瞬时执行失败必须自动进行有界重试。每次重新执行前必须清理该 Document 的旧解析 +产物、Chunk、Chunk Index State 和向量/稀疏索引数据,再从不可变原始文件开始处理。清理不得 +删除原始文件、Document 标识或 Job/Attempt 历史;清理失败时不得继续重试。 + --- # 11. 文件版本和去重 @@ -1814,6 +1825,9 @@ Cancelled Retry ``` +Retry 必须记录 Attempt 历史并区分可重试的瞬时错误与确定性永久错误;重试执行前遵循 +`REQ-INGEST-006` 的派生数据清理规则。 + --- # 57. 删除语义