RAG/docs/04-project-todo.md

# 项目全生命周期 TODO 与进度看板

| 项目 | 当前值 |
|---|---|
| 基线日期 | 2026-07-13 |
| 当前阶段 | 核心 synthetic 产品链已 Docker E2E；Stage 1 真实三模型验收 `BLOCKED`，Stage 2–5/7 按剩余项推进 |
| 已完成阶段 | Stage 0：仓库、安全和设计基线 |
| 整体完成度 | 任务级挣值约 50%，合理区间 45%–55%；核心 synthetic 产品工程链约 70% |
| 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
| 业务代码完成度 | 上传→解析→manifest 审核→向量化→原子激活→正式检索已两次 Docker E2E；文档/检索/问答页面可运行 |
| 当前预计剩余工期 | 约 6–10 周；主要取决于百炼授权、PDF/OCR、300 题双审盲测、论文和答辩排期 |
| 进度权威来源 | 本文的阶段状态、验收证据和已推送提交 |

本文把 [总体设计](00-overall-design.md)、[数据与评测设计](01-data-and-evaluation.md)、[部署与安全设计](02-deployment-and-security.md) 和 [实施计划](03-implementation-plan.md) 转换为从当前状态到最终答辩、归档的可执行清单。它只表示计划和已验证事实，不因文档完整就声称系统代码已经完成。

## 1. 状态与完成度规则

### 1.1 状态定义

| 状态 | 含义 | 进入条件 | 退出条件 |
|---|---|---|---|
| `DONE` | 阶段已形成可验证闭环 | 功能、测试、文档、提交均完成 | 验收证据齐全且提交已推送 |
| `IN_PROGRESS` | 当前正在实施 | 依赖满足并已有明确执行任务 | 达到 `DONE`，或因硬门禁转为 `BLOCKED` |
| `TODO` | 尚未开始 | 前置阶段或资源未满足 | 依赖满足并正式启动 |
| `BLOCKED` | 硬门禁阻止继续 | 缺授权、密钥、外部服务或必要决策 | 阻断证据消除并记录恢复原因 |
| `OPTIONAL` | 不影响首版答辩主链路 | 核心目标已满足且仍有时间 | 完成或明确延期 |

阶段只有在以下四项同时成立时才能标记 `DONE`：

1. 范围内功能及失败路径已经实现。
2. 适用的自动测试、静态检查和安全检查通过。
3. 验收证据可复查，设计与运行文档已同步。
4. 符合 Lore 协议的提交已经推送，远端提交可见。

### 1.2 进度口径

当前进度采用固定阶段权重下的**任务级挣值**，不采用“文件数量”或“代码行数”，也不再使用
“整阶段只要缺一项就记 0”的陈旧口径。`已计入进度` 只统计已有自动测试、Docker/HTTP 证据和
文档契约的交付；设计稿、尚未验证的代码和外部计划不计入。阶段只有全部 Definition of Done
满足时才标记 `DONE`，所以部分挣值不等于阶段完成。

| 阶段 | 权重 | 当前状态 | 已计入进度 |
|---|---:|---|---:|
| Stage 0 设计与安全基线 | 12% | `DONE` | 12% |
| Stage 1 模型与数据库 PoC | 8% | 离线 `DONE`，真实模型 `BLOCKED` | 6% |
| Stage 2 完整工程骨架 | 10% | `IN_PROGRESS` | 9% |
| Stage 3 数字文档入库 | 14% | `IN_PROGRESS` | 9% |
| Stage 4 检索与重排 | 12% | `IN_PROGRESS` | 7% |
| Stage 5 生成、引用和 UI | 12% | `IN_PROGRESS` | 5% |
| Stage 6 OCR、表格与质量 | 10% | `TODO` | 0% |
| Stage 7 正式评测与消融 | 12% | `IN_PROGRESS` | 2% |
| Stage 8 安全、恢复、性能和论文 | 7% | `TODO` | 0% |
| Stage 9 答辩、发布与归档 | 3% | `TODO` | 0% |
| **合计** | **100%** | — | **50%** |

Stage 1 已完成数据库、适配器契约、synthetic seed 和模型出口隔离，但真实三模型请求当前均返回
401，因此真实模型子门禁保持 `BLOCKED`。不依赖该外部鉴权的产品链已经继续推进：文档上传、
本地解析、manifest 审核、向量化、版本激活、正式 Retrieval、Grounded Chat 和 React 页面在
Docker 中连续两次通过，重复运行保持相同身份，version/chunk/assignment/jobs/invocations 为
`1/1/1/2/1`；当前全量门禁记录为 296 项后端测试、53 项前端测试。按上述任务级证据计入约
50% 是比旧 12% 更合理的实现进度，但**不是毕业验收进度已完成一半的承诺**：PDF/OCR、真实
认证与多租户、正式 300 题盲测、备份恢复/压测、论文和答辩仍在关键路径上。

## 2. 阶段依赖与关键路径

```text
Stage 0 DONE
  -> Stage 1 模型/数据库 PoC
  -> Stage 2 完整工程骨架
  -> Stage 3 数字文档入库
       -> Stage 4 检索与重排
       -> Stage 6 OCR/表格（可与 Stage 4、5 部分并行）
  -> Stage 5 生成/引用/UI
  -> Stage 7 正式评测（标注可在 Stage 3 后提前启动）
  -> Stage 8 安全/恢复/性能/论文
  -> Stage 9 答辩/发布/归档
```

| 阶段 | 必须依赖 | 可提前并行的工作 | 不得提前做的工作 |
|---|---|---|---|
| Stage 1 | Stage 0、已轮换 Secret、受控联网 | 虚构数据和 fake server 契约测试 | 使用真实地质资料，或使用已暴露密钥 |
| Stage 2 | Stage 1 三模型和迁移 PoC | React 离线演示、OpenAPI 类型生成、Nginx 单入口和网络隔离前置 | 绕过任务租约直接做不可恢复长任务 |
| Stage 3 | Stage 2 服务骨架 | 合法语料清单、标注规范准备 | 未通过 `CLOUD_APPROVED` 的内容出域 |
| Stage 4 | Stage 3 可追溯切片与向量 | 100 组三元组完善 | 用测试集调相似度、Top K 或阈值 |
| Stage 5 | Stage 4 稳定候选和引用 ID | UI 组件、Prompt fake 测试 | 让前端直接接触模型 Key |
| Stage 6 | Stage 3 数据状态机 | 与 Stage 4、5 并行开发 | 把图例 OCR 宣称为完整图件理解 |
| Stage 7 | Stage 4、5；正式总评需 Stage 6 | Stage 3 后开始问题编写和双审 | 开发者查看盲测答案，或把 Gold 入库 |
| Stage 8 | Stage 2–7 主链路稳定 | 论文各章随阶段持续写作 | 未恢复验证就声称备份可用 |
| Stage 9 | Stage 8 发布候选通过 | 演讲稿和演示素材提前准备 | 在最终演示前临时升级依赖或模型配置 |

## 3. Stage 0：仓库、安全和设计基线

- **状态：** `DONE`
- **工期：** 已完成
- **依赖：** 无

### 已完成任务

- [x] 建立仓库说明、贡献约定、安全说明和 AGENTS 约束。
- [x] 建立 `backend/`、`frontend/`、`data/`、`ops/`、`scripts/` 和 `docs/` 结构。
- [x] 完成 00–03 总体、数据评测、部署安全和实施计划设计基线。
- [x] 建立 ADR 入口和首批关键架构决策。
- [x] 建立 `.gitignore`、本地 Secret 扫描钩子和 Gitea 工作流基线。
- [x] 建立 `make verify-design`、Markdown 相对链接和 diff 检查。
- [x] 将 Stage 0 基线提交推送到 `origin/main`。

### 验收证据

- `git status --short --branch` 显示 `main...origin/main`，Stage 0 基线提交远端可见。
- `make verify-design` 可检查 Secret、设计文档、相对链接和 diff。
- [00-overall-design.md](00-overall-design.md) 现已同步“设计基线；安全运行骨架部分实现，产品主链路未完成”。
- Stage 0 完成时尚无可运行应用；后续运行骨架不改变“Stage 0 只代表设计和工程防线”的历史验收口径。

### 已完成提交/推送节点

- [x] `S0-A`：建立安全、架构、数据、部署和实施设计基线。
- [x] 推送 `main` 并确认 `origin/main` 指向 Stage 0 基线提交。

### 后续仍持续生效的门禁

- 真实 Key、真实工作空间地址、受限数据和私有 benchmark 永不进入 Git。
- 新实现若改变边界、数据状态或模型契约，必须先更新 ADR/设计再验收。
- Stage 0 完成不能被用于宣称模型、数据库、后端或前端已经可运行。

## 4. Stage 1：模型与数据库 PoC

- **状态：** 离线 PoC `DONE`；真实百炼三模型 `BLOCKED`（401）
- **预计工期：** 1–2 个工作日；外部密钥或网络未就绪时暂停计时
- **依赖：** Stage 0；已轮换百炼 Key；允许的工作空间端点；本机 Docker

### 具体实现任务

#### 4.1 安全与供应商前置

- [ ] 在百炼控制台撤销聊天中曾暴露的旧 Key，创建新 Key。
- [ ] 通过 Docker Secret 或未提交的本地 Secret 文件注入新 Key；禁止写入 `.env.example`。
- [ ] 分别确认 Embedding、Rerank 和 Chat 的实际路径、请求协议、模型返回名和能力指纹。
- [ ] 记录脱敏的 endpoint identity hash、region、resolved revision 或受控 cache epoch。
- [x] 建立 live provider 测试的手动开关；默认 CI 只使用 fake server。

#### 4.2 最小后端和 Compose

- [x] 创建 `backend/pyproject.toml` 和依赖锁文件，不引入未说明依赖。
- [x] 创建最小 `backend/Dockerfile`，使用非 root 用户和固定基础镜像 digest。
- [x] 创建 Compose，包含 `db + migrate + model-gateway + api + gateway + web + provider-smoke + seed-demo/offline`；Worker 仍待实现。
- [x] 启动最小 FastAPI `api + gateway`，内部 API 无 egress，gateway 无 Secret 并仅发布回环端口；提供真实数据库 readiness、Swagger 和只读 synthetic demo 检索。
- [x] 创建 PostgreSQL bootstrap、migrator 和 app 分权角色初始化脚本；备份只读角色在备份功能落地时单独创建。
- [x] 创建 Alembic 基线迁移，启用 pgvector 并建立 1024 维向量表/HNSW 基线。
- [x] 确保运行期服务不挂载 bootstrap 或 migrator Secret。
- [x] 将百炼 Key 和公网出口隔离到独立 `model-gateway`；API/seed/smoke 只持对应内部 token，不直持 Key。
- [x] 以 `Authorization: Bearer` + `X-RAG-Caller: api|worker` 建立内部身份，常量时间比较并限制 API 身份不得执行文档向量化。

#### 4.3 三模型适配器

- [x] 实现 `EmbeddingProvider.embed_documents` 和 `embed_query` 契约。
- [x] 通过 MockTransport 验证 `text-embedding-v4` 的 1024 维、批次下标和有限浮点数；真实响应待 smoke。
- [ ] 对原生 Embedding 模式区分 `document/query`；兼容模式能力必须显式记录。
- [x] 实现 `qwen3-rerank` 候选索引回填、Token 预检、Top 10 保存。
- [x] 实现 `deepseek-v4-flash` 最小流式 Chat，默认关闭搜索和思考。
- [x] 为三个适配器实现 timeout、429/5xx 有界重试和脱敏错误映射。

#### 4.4 虚构数据和测试

- [x] 创建 `provider_smoke`，只输出状态、模型、耗时、request ID 和脱敏错误码。
- [x] 创建 `seed-demo`，使用 20 条明确标记的虚构文本完成写入、检索和重排。
- [x] 重复运行 seed，证明行数和任务不增长。
- [x] 建立 fake server 契约测试，覆盖成功、乱序、无效响应、401、429、5xx 和超时。
- [x] 建立并执行迁移空 volume、角色权限和 Docker 重启持久化测试。
- [x] 明确文档族 split、盲测保管人和“盲测用于调参即退役”规则。
- [x] 扩展 `make verify`，纳入 Stage 1 后端格式、类型和测试门禁。
- [x] 实现并实跑 `0002_model_profiles`：profile、embedding cache、chunk assignment、model invocation 与稳定 `citation_id`；空卷和已有数据均完成 upgrade/downgrade/upgrade。

### 验收证据

- [x] `docker compose up db migrate` 在空 volume 成功建立扩展、角色和表。
- [ ] `docker compose run --rm provider-smoke` 三模型探测成功，日志无 Secret。
- [x] `docker compose run --rm seed-demo-offline` 完成 20 条虚构数据写入、检索和重排；真实模式待新 Key。
- [x] `api + gateway` 镜像构建并达到 healthy；live/ready/meta/demo status/demo search 均通过真实 HTTP 验收。
- [x] 第二次运行 seed 后数据库计数与第一次相同，均为 chunks/vectors/searchable = 20/20/20。
- [x] 已验证测试集证明模型契约、健康检查、固定上游 gateway、SSE 代理分块与早断连释放契约、离线 demo、数据治理和失败路径正确；本轮新增 model-gateway/0002 契约须随阶段提交重新运行全量门禁。
- [x] `make verify`、Secret 扫描、固定镜像构建和 `git diff --check` 通过。

### 2026-07-12 已验证运行证据

- 全新 volume 上 `db` 达到 healthy，`migrate` 以非超级用户退出码 0，版本为 `0001_initial_schema`。
- `0002_model_profiles` 已在独立全新 volume 完成 `空库 -> 0001 -> 0002 -> 0001 -> 0002`，并在已有 20 条合成数据的 volume 完成 downgrade/upgrade；重复 seed 后 profile/active KB=1/1、cache/READY assignment/citation=20/20/20，citation 无重复。
- `vector` 扩展与 HNSW 基线存在；app/migrator 均非超级用户，app 无 `rag` schema DDL 权限但具有所需 DML。
- 两次离线 seed 均输出 20/20/20，9 个可回答虚构问题 Hit@3 = 9/9。
- FastAPI 容器使用 app 最小权限角色，根文件系统只读且无 egress；无 Secret gateway 仅提供回环入口；Swagger 可见，demo search 返回合成片段与不透明 citation ID。
- API 容器对公网 TCP 探测返回 `ENETUNREACH (101)`；gateway 的 mounts 为空且不含数据库或百炼业务环境变量。
- PostgreSQL 重启后计数仍为 20/20/20。
- app 尝试修改已 `CLOUD_APPROVED` 的 `cloud_text` 被审批不可变触发器拒绝；尝试建表被权限拒绝。
- React + TypeScript strict 离线演示已实现工作台与系统状态页；14 项前端测试、ESLint、类型检查和生产构建通过。
- Nginx 成为唯一回环入口，Compose 仅发布 `127.0.0.1:8000`；`web -> gateway -> api` 同源链路、Swagger、OpenAPI、健康检查和 synthetic search 均通过真实 HTTP 验收。
- `edge / ingress / data / model / egress` 五网络边界已落地；API、seed、smoke 不挂载百炼 Key，只有不连数据库/上传卷的 `model-gateway` 同时连接 internal model 与 egress。
- gateway 与 Nginx 已关闭代理缓冲；Grounded Chat 现已实跑 synthetic `meta -> retrieval -> delta -> citations -> usage -> done`，并具备终态错误与客户端取消路径。真实 `deepseek-v4-flash` 仍受供应商鉴权阻断，持久会话/断线重放尚未实现。
- 当前真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` 请求均到达供应商但返回 401；三能力与真实模式 seed 未验收。上传、正式检索、Grounded Chat、Worker 和 synthetic 评测已作为后续阶段能力落地，但不能反向替代 Stage 1 的真实供应商验收。

### 提交/推送节点

- [x] `S1-A`：数据库初始化、分权角色、迁移和最小 Compose 已随 `f4ba5d5` 验证并推送。
- [ ] `S1-B`：三模型适配器和 fake 契约测试已随 `f4ba5d5` 推送；新 Key 下的 live smoke 未完成，因此节点保持未完成。
- [x] `S1-C`：20 条虚构 seed、幂等验证、运行证据和文档已随 `f4ba5d5` 推送。
- [x] `S1-D`：内部 API、无 Secret gateway、只读 demo 检索和真实 HTTP/Docker 运行证据已随 `cfd6d4c` 验证并推送。

`f4ba5d5` 是 Stage 1 离线可执行闭环提交，不代表 Stage 1 已完成；阶段完成仍以真实三模型 smoke 和真实模式 seed 通过为准。

建议最终阶段提交意图：`Prove the selected model chain before building product workflows`。

### 风险门禁

- **停止条件：** 新 Key 未轮换、Secret 出现在日志/镜像、真实端点能力不明、迁移使用超级用户运行。
- **禁止数据：** Stage 1 只使用虚构文本，不上传任何真实地质报告。
- **降级策略：** 供应商暂不可用时完成 fake 契约和数据库工作，但 Stage 1 不得标记 `DONE`。
- **进入 Stage 2 的门槛：** 三模型真实 smoke、迁移和 seed 幂等全部通过。

## 5. Stage 2：扩展为完整工程骨架

- **状态：** `IN_PROGRESS`（核心 Compose、业务 Worker 和恢复契约已落地；正式认证/RBAC 与进程级故障矩阵待补）
- **预计工期：** 3–4 个工作日
- **依赖：** Stage 1 `DONE`
- **已完成前置：** React、OpenAPI 离线生成、Nginx 单入口、数据库迁移、上传卷初始化及本地/模型 Worker 拆分均已进入默认 Compose。

### 具体实现任务

- [x] 建立 FastAPI 应用工厂、配置加载、稳定 Problem JSON、trace middleware 和 OpenAPI；导入阶段不连库、不读模型凭证。
- [x] 正式 Retrieval、Grounded Chat、文档上传/审核、评测、任务队列和解析/索引 handler 已按 `api/workers -> services -> adapters/persistence` 分层；认证和持久会话仍需沿用该边界。
- [x] 建立核心业务的 PostgreSQL 仓储和短事务边界；Alembic 已推进文档入库/审核 schema，空卷和升级路径已验证。
- [x] 建立 PostgreSQL `background_jobs`、短事务 claim、租约、lease token、过期时间 fencing 和重试状态机。
- [x] 建立 Worker maintenance loop、心跳不超过租约 1/3、advisory-lock reaper、优雅停止和真实 PostgreSQL 并发/过期租约 smoke；解析与向量化业务 handler 已接入，SIGKILL/耗尽重试矩阵仍待补。
- [ ] `/health/live`、数据库 `/health/ready` 及 model-gateway 本地 readiness 已有；管理员模型能力探测 API 仍待实现。
- [x] 建立 React + TypeScript strict、路由、TanStack Query 和 OpenAPI 客户端生成。
- [x] 建立 Nginx，仅发布 Web 端口；API、DB、两个 Worker 均不发布宿主机端口。
- [x] 建立默认 Compose：`web/gateway/api/model-gateway/worker-local/worker-model/db/migrate/upload-init`；OCR profile 仍未实现。
- [x] 建立当前范围的 Ruff、类型、pytest、ESLint、TypeScript、Vitest 和镜像检查；Stage 2 新模块必须继续纳入门禁。
- [x] 建立 Gitea CI 的 fake provider 测试；外部 PR 不运行真实 Key 测试。

### 验收证据

- [x] 新环境按 README 初始化本地 Secret 后可用 `make up` 启动完整 synthetic 骨架。
- [x] `migrate` 与 `upload-init` 均为一次性任务，成功 `Exited (0)`；依赖失败会阻止 API 启动。
- [x] 当前 `docker compose ps` 只暴露 Nginx/Web 回环端口；Worker 无端口。
- [x] Docker 重启后数据库数据和上传卷保留。
- [x] 真实 PostgreSQL smoke 已验证并发仅一个 winner、错误 token/过期租约拒绝、过期任务换 token 重领并完成；进程级 SIGKILL 与耗尽 `FAILED` 场景仍待持续 Worker 服务接入后补验。
- [x] 当前全量门禁记录为 296 项后端测试、53 项前端测试，并覆盖 OpenAPI、Compose 和 Secret 契约。

### 提交/推送节点

- [x] `S2-PREP`：React 离线演示、Nginx 单入口、当时的四网络隔离、SSE 代理安全修复与质量门禁已随 `c3bad0f` 验证并推送；当前拓扑进一步拆分本地/模型 Worker，详见 ADR-0007。
- [x] `S2-A` 功能范围：FastAPI、持久化、健康端点和错误契约已实现；阶段提交记录随当前交付统一落地。
- [x] `S2-B` 功能范围：任务租约、reaper、fencing 和恢复 smoke 已实现；进程级 SIGKILL 矩阵仍作为加固项。
- [x] `S2-C` 功能范围：React、Nginx、双 Worker Compose、CI 门禁和文档已实现；正式认证仍阻止整个 Stage 2 标记 `DONE`。
- [ ] 每个节点验证后独立提交并推送；Stage 2 完成时在本文更新状态。

### 风险门禁

- 不为单机毕设提前引入 Redis、Celery、微服务或独立向量数据库。
- readiness 不把百炼短时故障等同于 API 容器不可用；模型健康单独展示。
- 前端构建产物、OpenAPI 示例和测试日志不得包含 Key 或真实受限数据。

## 6. Stage 3：数字文档入库主链路

- **状态：** `IN_PROGRESS`（TXT/Markdown/DOCX synthetic 主链已 E2E；PDF/OCR、删除/版本演进与真实语料待补）
- **预计工期：** 1 周
- **依赖：** Stage 2 `DONE`；合法数字资料样本和审核人可用

### 具体实现任务

- [x] 实现大小、扩展名、MIME、签名、编码、DOCX 加密/zip bomb/路径穿越/active content 检查，以及声明→流式写入→摘要确认的两阶段上传 API。
- [x] 实现 `QUARANTINED_LOCAL_REVIEW -> LOCAL_PARSED_PENDING_CLOUD_REVIEW -> CLOUD_APPROVED/REJECTED` 状态机、乐观 revision 和审核事件。
- [x] TXT/Markdown/DOCX 的安全本地解析、逻辑页/行/字符/章节锚点已完成；PDF 当前 fail closed 为 `OCR_REQUIRED`，可靠 PDF parser/OCR Worker 尚未接入。
- [x] 生成分离的 `display_text/cloud_text/embedding_text`、独立 hash 和确定性 outbound manifest，并要求数据库审批绑定 exact manifest。
- [x] 实现确定性 512 Token 基线、800 上限、64 重叠、章节边界和 embedding 元数据前缀；地质标识符保持为单 token。
- [ ] 已实现相同上传/任务幂等和确定性 chunk ID；近重复文档族与完整版本关系仍待实现。
- [x] 实现 Embedding 批次、内容缓存、chunk assignment、调用记录、租约 fencing 和有界重试。
- [x] 实现 READY 完整性对账，以及 `documents.active_version_id` 与 `chunks.searchable` 单事务切换。
- [ ] 实现删除立即退出检索、后台物理清理和最小审计记录。
- [x] 实现 `/documents` 文档列表、上传/任务进度、复核、批准/拒绝和安全错误 UI。
- [ ] 冻结 corpus manifest 与文档族 60/20/20 split；盲测标签由独立保管人控制。
- [ ] 用允许使用的小规模数字 PDF 语料完成端到端入库演练。

### 验收证据

- [x] 当前 synthetic 主链的 searchable 切片可追溯版本、来源锚点和 outbound manifest；真实多页语料仍待抽样验收。
- [x] synthetic E2E 验证 `approved chunks == READY vector assignments`，维度和文本/profile 哈希一致。
- [x] 同一 fixture 连续两次 E2E 使用相同身份，version/chunk/assignment/jobs/invocations 稳定为 `1/1/1/2/1`。
- [ ] 新版本未完整 READY 前旧版本继续可检索；切换没有空窗。
- [ ] 删除后在线查询立即不可命中，物理清理可审计。
- [x] 未获 manifest 审批的版本不会创建 embedding assignment/job；本地解析 Worker 无模型网络与 Token。

### 提交/推送节点

- [ ] `S3-A`：上传、数据治理状态机和本地解析。
- [ ] `S3-B`：结构切分、去重、向量任务和版本激活。
- [ ] `S3-C`：文档 UI、删除/恢复测试、corpus manifest 和证据。
- [ ] 每个节点通过安全与回归门禁后提交、推送。

### 风险门禁

- 权利、涉密等级、云处理权限任一不明确即停止外发。
- `cloud_text`、处理器或 manifest 任一变化自动撤销原审批。
- 解析失败页、跨页表和低置信内容必须显式失败或进入复核，不静默丢弃。

## 7. Stage 4：检索与重排

- **状态：** `IN_PROGRESS`（synthetic 正式检索切片已运行，真实语料/百炼与质量规模验收未完成）
- **预计工期：** 1 周
- **依赖：** Stage 3 `DONE`；开发集 qrels/100 组三元组可用

### 具体实现任务

- [x] 实现 profile-aware query embedding；当前兼容模式走内部 model-gateway，原生模式能力指纹仍待真实供应商验证。
- [ ] 实现同权限过滤条件下的 exact Cosine Top K 基线。
- [ ] 实现 HNSW、iterative scan、`ef_search`、over-fetch 和 ANN 对账。
- [x] 在候选生成 SQL 的 `LIMIT` 前应用知识库、服务端授权 scope、active version、审批、READY assignment、profile 和 searchable 过滤。
- [ ] Dense Top 50 与 `qwen3-rerank` Top 10 已完成；独立 Context Top 8 builder、邻接合并和硬 token budget 尚未完成。
- [x] 实现 Rerank UTF-8 请求预算、响应 index/分数校验、裁剪和显式 degraded 回退。
- [ ] 已实现 citation 去重；邻接补全、同文档抑制和上下文 Token 预算仍待完成。
- [x] React 检索实验室已展示请求/生效配置、初召回/重排 rank/score、profile、来源、trace 和分阶段耗时。
- [ ] 完善 100 组三元组，覆盖同义词、实体冲突、数字、单位、OCR 和难负例。
- [ ] 校准 Top K 和阈值；所有参数只使用开发集。

### 验收证据

- [ ] 三元组 `sim(query, positive) > sim(query, hard_negative)` 达到预设目标或形成完整错误报告。
- [ ] 至少 200 个查询的 ANN Recall@10 相对 exact 基线达到目标，过滤条件完全相同。
- [ ] 未授权文档从候选生成阶段即被排除。
- [ ] Rerank 前后 MRR/nDCG、延迟和 Token 可复查。
- [ ] 相同运行配置可由 `config.yaml` 和 provider profile 重现。

### 提交/推送节点

- [ ] `S4-A`：exact/HNSW、权限过滤和 ANN 质量测试。
- [ ] `S4-B`：Rerank、上下文构建和错误处理。
- [ ] `S4-C`：检索实验室、三元组报告和参数冻结。

### 风险门禁

- 不使用一个固定余弦或 Rerank 分数跨所有问题通用。
- Rerank 不能恢复初召回未命中的证据，错误归因必须分层。
- 不得查看盲测答案后调整维度、Top K、阈值或 instruct。

## 8. Stage 5：生成、引用和问答 UI

- **状态：** `IN_PROGRESS`（single-turn synthetic Grounded Chat 已运行，持久会话与真实百炼未验收）
- **预计工期：** 1 周
- **依赖：** Stage 4 `DONE`

### 具体实现任务

- [ ] 建立版本化 Grounded Answer Prompt，要求仅依据编号证据回答。
- [x] 实现 `deepseek-v4-flash` 经 model-gateway 的 SSE 契约、超时/错误终态和客户端中止传播路径；真实供应商鉴权成功仍待验证。
- [x] 后端只接受本轮 source map 的 `[S1..Sn]`，映射稳定 citation/document/section/page，并过滤越界或畸形引用。
- [ ] 已实现证据不足拒答、无合法引用时 retrieval-only 和 provider error 保留 retrieval 事件；资料冲突分来源陈述仍待专门策略。
- [ ] 实现会话与消息持久化、来源卡片、页码定位和用户反馈。
- [x] 实现文档管理、聊天、检索实验室和系统状态页面导航。
- [ ] 增加正式评测运行/工件页面；当前评测仅提供可复现 CLI/JSON 工件。
- [x] 首版只渲染安全纯文本；后端转义 SSE 中 HTML 敏感字符，测试覆盖 XSS 片段、Prompt Injection 和非法引用。
- [ ] 测试用户取消后 Embedding/Rerank/Chat 下游请求停止。
- [x] 单轮流记录 trace、检索阶段耗时、usage、模型 request ID 和供应商中性错误；持久审计记录仍待会话表接入。

### 验收证据

- [ ] 回答中的每个引用均可打开到授权文档和正确页码。
- [ ] 模型伪造、越界或不存在的引用被后端拦截。
- [ ] 无答案题正确拒答；系统错误与“证据不足”状态不同。
- [ ] 模型不可用时仍展示检索来源和可理解错误。
- [ ] Playwright 覆盖上传、问答、引用、取消、失败重试和 XSS。

### 提交/推送节点

- [ ] `S5-A`：生成服务、证据 Prompt、引用验证和拒答。
- [ ] `S5-B`：聊天/来源 UI、SSE 取消和错误状态。
- [ ] `S5-C`：端到端、安全回归、可观测性和文档。

### 风险门禁

- 模型输出永远视为不可信数据；引用和 Markdown 必须后端/前端双层校验。
- 前端不得获得模型 Key、工作空间凭证或未授权文档正文。
- 不把问答系统输出表述为勘查结论、储量评估或投资建议。

## 9. Stage 6：OCR、表格和数据质量挑战集

- **状态：** `TODO`
- **预计工期：** 1–2 周
- **依赖：** Stage 3 `DONE`；可与 Stage 4、5 部分并行

### 具体实现任务

- [ ] 建立页级数字/扫描/混合 PDF 检测。
- [ ] 建立隔离的 OCR worker profile、资源限制和临时文件清理。
- [ ] 实现 300 DPI 渲染、旋转/倾斜校正、PaddleOCR/PP-Structure 输出。
- [ ] 保留 `raw_text`、修订文本、bbox、置信度、修订人和处理器 profile。
- [ ] 建立低置信页、数值密集页、表格页人工复核队列。
- [ ] 提取表格 JSON、Markdown、截图引用和逐行语义文本。
- [ ] 处理跨页表、合并单元格、表头、单位和脚注；无法确认时显式失败。
- [ ] 建立 OCR 金标准页、术语/数字/单位和表格行列对齐评测。
- [ ] 建立图件挑战集和 UI 边界提示，不宣称已理解空间几何。

### 验收证据

- [ ] 金标准页 CER ≤ 3%，地质术语准确率 ≥ 95%，数字/符号/单位准确率 ≥ 98%。
- [ ] 表格行列对齐 ≥ 97%，数值及单位准确率 ≥ 99%。
- [ ] OCR 原文和人工修订文本均可追溯且不会互相覆盖。
- [ ] 跨页表/合并单元格失败可见，不产生静默错位。
- [ ] 只依赖图件空间关系的问题被标记为挑战集或拒答。

### 提交/推送节点

- [ ] `S6-A`：扫描检测、OCR worker 和复核队列。
- [ ] `S6-B`：表格结构、语义行和数值校验。
- [ ] `S6-C`：金标准质量报告、图件边界和文档。

### 风险门禁

- OCR/表格完整处理必须在出域审批前于隔离环境完成。
- 低置信结果不得自动变为 `searchable`。
- OCR 模型、预处理或修订变化后，outbound manifest 和向量审批必须失效重做。

## 10. Stage 7：正式验证集、盲测与消融

- **状态：** `IN_PROGRESS`（指标核心与 synthetic runner 已完成，正式数据/盲测尚未开始）
- **预计工期：** 3–4 周；语料标注可在 Stage 3 后提前并行
- **依赖：** 问题编写依赖 Stage 3；最终评测依赖 Stage 4–6 `DONE`

### 具体实现任务

- [ ] 建立至少 300 题：构建、开发、盲测各 100；500 题仅作为资源充足时扩展。
- [ ] 按文档族、来源、矿种、题型、模态、难度和多跳分层。
- [ ] 为 Gold 和全部 0–3 judgment 建立不可变源锚点。
- [ ] 双人独立审核答案、证据和可回答性；第三名地质评审裁决。
- [ ] 建立 `anchored_judgments.jsonl`、manifest、版本和 SHA-256。
- [ ] 使用 Dense/词法/Hybrid/Rerank union pooling；未判定结果先补标再计分。
- [ ] 每个 run 生成独立 qrels、anchor resolution、预测、指标和错误报告。
- [ ] 已实现严格 Hit、Recall、CompleteHit、EvidenceGroupRecall、MRR、nDCG、引用 precision/recall/F1 与拒答指标；专家答案/忠实度裁决尚未完成。
- [x] synthetic runner 使用固定 seed 的 2000 次 bootstrap，输出 95% 区间；正式分层结果尚待数据集。
- [ ] 在开发集完成维度、切片、重叠、前缀、Rerank、上下文、Query 改写等消融。
- [ ] 冻结最终配置、corpus、judgment set 和盲测哈希，再执行一次正式盲测。
- [ ] 补标或裁决变化后生成新 judgment 版本，并对比较表中全部系统重新计分。
- [ ] 生成论文图表、成本/延迟对比和错误分类案例。

### 验收证据

- [ ] Gold、参考答案、qrels、`eval/` 和 `runs/` 永不被知识库导入器扫描。
- [ ] 正式盲测标签在参数冻结前对开发者不可见。
- [ ] 检索、重排、生成、引用、拒答和端到端指标均有版本化输入与配置。
- [ ] 所有比较系统使用相同 judgment snapshot、resolver 和 corpus manifest。
- [ ] 所有论文实验图表可由冻结运行产物重新生成。
- [ ] 若盲测结果用于调参，该集合立即退役，最终结论改用新盲测集。

### 提交/推送节点

- [ ] `S7-A`：问题 schema、源锚点、标注工具和构建/开发集。
- [ ] `S7-B`：盲测托管、union pooling、评测 runner 和评分规约。
- [ ] `S7-C`：消融、配置冻结和最终盲测。
- [ ] `S7-D`：图表、错误分析、成本和论文实验章节。

### 风险门禁

- 盲测问题、答案和标签必须由独立保管人/受控凭据管理。
- 公开 benchmark 只能包含允许再分发或充分脱敏的内容。
- LLM 可以辅助出题或评分，但不能同时成为唯一出题者、唯一裁判和最终评分者。
- 工期不足时缩减到 300 题，不降低盲测隔离、双审和可复现要求。

## 11. Stage 8：安全加固、恢复、性能和论文定稿

- **状态：** `TODO`
- **预计工期：** 1 周，论文写作应贯穿前序阶段
- **依赖：** Stage 2–7 主链路和评测结果稳定

### 具体实现任务

- [ ] 完成管理员、资料员、评测人员和普通用户 RBAC。
- [ ] 完成对象级知识库/文档权限、审计日志和越权回归。
- [ ] 完成上传限制、路径穿越、压缩炸弹、XSS、Prompt Injection 和限流测试。
- [ ] 完成结构化日志脱敏、trace、模型 Token/耗时、任务和索引监控。
- [ ] 固定镜像 digest、依赖锁和数据库迁移版本。
- [ ] 建立数据库、允许备份文件和独立 Secret 的备份策略。
- [ ] 在全新 Compose project 恢复数据库与文件，重建或校验索引。
- [ ] 恢复后运行固定 20 题冒烟并记录 RTO、缺口和哈希。
- [ ] 测量入库吞吐、查询 p50/p95、并发、错误率和每 1000 查询费用。
- [ ] 完成论文各章、系统截图、实验图表、失败案例和局限性。
- [ ] 完成部署手册、管理员手册、演示故障降级和恢复手册。

### 验收证据

- [ ] `make verify`、Secret 扫描、镜像检查、单元/集成/契约/E2E/安全测试通过。
- [ ] 空白环境恢复成功，并通过固定 20 题冒烟。
- [ ] 端到端 p95、稳态错误率、并发和成本均为实测结果。
- [ ] 论文中的每张实验图表可追溯到 run manifest。
- [ ] 论文明确系统边界，不夸大图件理解、找矿预测或专业决策能力。

### 提交/推送节点

- [ ] `S8-A`：RBAC、审计、安全和限流。
- [ ] `S8-B`：备份、恢复、性能和费用报告。
- [ ] `S8-C`：论文定稿、运维手册和 release candidate。

### 风险门禁

- 只有备份文件、没有空环境恢复证据，不得通过验收。
- 性能数字必须注明硬件、网络、数据规模、模型配置和采样窗口。
- release candidate 后不再做非必要依赖升级或架构替换。

## 12. Stage 9：答辩、发布与归档

- **状态：** `TODO`
- **预计工期：** 2–3 个工作日，另预留答辩排期缓冲
- **依赖：** Stage 8 release candidate `DONE`

### 具体实现任务

- [ ] 冻结答辩 release candidate、镜像 digest、迁移、模型配置和演示数据。
- [ ] 在干净机器完整执行 `docker compose up -d --build` 和健康检查。
- [ ] 按 [实施计划的答辩脚本](03-implementation-plan.md#8-最终答辩演示脚本) 连续彩排至少两次。
- [ ] 准备模型临时不可用时的降级演示、预录视频和静态证据。
- [ ] 检查答辩 PPT、论文、截图、日志和视频中没有 Secret 或受限原文。
- [ ] 准备演示问题：正常问答、无答案、版本冲突、表格数值和局限性。
- [ ] 生成公开归档包与内部受控归档包；两者使用不同 manifest。
- [ ] 归档源代码、迁移、锁文件、镜像 digest、公开样例、运行配置、论文和演示材料。
- [ ] 归档数据库/文件恢复说明、校验和、保留周期和销毁策略。
- [ ] 删除临时 Secret、临时文件和未授权数据；按策略轮换或撤销演示 Key。
- [ ] 创建最终 Git tag/release，推送远端并记录 commit、tag 和归档 SHA-256。
- [ ] 记录已知限制、未完成 OPTIONAL 项、后续维护人和恢复入口。

### 验收证据

- [ ] 干净环境演示全流程成功，或按预定降级方案完成而不泄漏数据。
- [ ] 答辩十步脚本中的每一步都有实时或冻结证据。
- [ ] 公开包通过 Secret、版权、坐标和商业秘密复核。
- [ ] 内部包访问控制、保留期、销毁责任人和恢复步骤明确。
- [ ] 最终 tag/release、论文版本、镜像 digest、run manifest 和归档哈希相互可追踪。

### 提交/推送节点

- [ ] `S9-A`：答辩 release candidate、演示脚本和故障降级证据。
- [ ] `S9-B`：论文/材料最终修订、公开与内部归档 manifest。
- [ ] `S9-C`：最终 tag/release、远端推送和归档校验记录。

### 风险门禁

- 答辩当天不临时升级模型、依赖、数据库或重新生成整套索引。
- 公开 release 不包含真实 Key、工作空间地址、受限语料、私有 benchmark 或可逆脱敏内容。
- 未验证恢复的备份、未固定哈希的实验和未推送提交不能作为最终归档证据。

## 13. 跨阶段风险登记与停止条件

| 风险 | 等级 | 触发信号 | 必须动作 | 解除门槛 |
|---|---|---|---|---|
| 已暴露或疑似暴露 Key | 严重 | Key 出现在聊天、日志、Git、镜像 | 立即停止真实调用并轮换；运行 Secret 扫描 | 新 Key 仅由 Secret 注入，旧 Key 已撤销 |
| 未授权/涉密资料出域 | 严重 | 许可、坐标、保密等级或云处理权不清 | 保持隔离，不调用任何云模型 | 审核 exact outbound manifest 并进入 `CLOUD_APPROVED` |
| Gold/盲测泄漏 | 严重 | `eval/` 被入库、开发者看到盲测标签 | 停止评测，作废受污染集合 | 新盲测集、独立保管和导入 allowlist 测试通过 |
| 模型别名漂移 | 高 | 能力指纹或响应模型变化 | 提升 cache epoch，冻结新 profile，重跑受影响实验 | 新旧运行明确分版，比较不混用 |
| 向量/版本不一致 | 高 | 文本哈希、profile、维度或 active 投影不一致 | 阻止激活并运行 reconciliation | 新版本全部 READY，原子切换验证通过 |
| OCR/表格静默错误 | 高 | 数值、单位、行列错位或低置信未处理 | 降级为复核/失败，不进入检索 | 金标准和人工复核门槛通过 |
| 供应商不可用/限流 | 中 | 429、5xx、超时或区域故障 | 有界重试、熔断、展示检索降级 | smoke 恢复且错误率正常 |
| 标注工期失控 | 高 | 3–4 周内无法完成 500 题 | 缩减到 300 题，保持双审与盲测 | 300 题各 split/题型覆盖满足规范 |
| 范围蔓延 | 中 | 提前引入微服务、多模态预测或新数据库 | 回到首版非目标，记录 ADR | 核心主链路和论文证据完成后再评估 |
| 答辩环境不稳定 | 高 | 干净机器失败、模型网络不稳 | 冻结 RC、准备预录和离线证据 | 连续两次彩排通过且有降级路径 |

## 14. 每阶段统一收尾清单

每个阶段完成前复制并勾选以下清单：

- [ ] 实现范围与本阶段 TODO 一致，未静默扩展权限、依赖或服务。
- [ ] 正常路径、失败路径和恢复路径均有验证。
- [ ] Ruff/类型/pytest、ESLint/TypeScript/Vitest/Playwright 等适用检查通过。
- [ ] `make verify`、Secret 扫描、Markdown 链接和 diff 检查通过。
- [ ] 数据库迁移可在空环境向前应用，必要时有回滚/恢复说明。
- [ ] API、配置、数据格式、ADR 和本文状态已同步。
- [ ] 验收证据记录命令、时间、commit、数据/配置哈希和已知缺口。
- [ ] 使用 Lore 协议提交；`Tested` 和 `Not-tested` 如实填写。
- [ ] 推送远端并确认提交、CI 和证据可见。
- [ ] 只有全部必选项完成后，才把阶段状态改为 `DONE` 并更新整体进度。

## 15. 下一步执行顺序

当前主线是保留已通过的 synthetic 产品链作为回归基线，并行关闭真实供应商、数据能力和毕业
验收三类缺口。建议按以下顺序继续：

1. 在百炼控制台确认旧 Key 已撤销，并核对当前本地 Secret 对应的工作空间、北京地域、端点、计费方案和模型权限；Key 只保存在未提交 Secret 中。
2. 通过独立 `model-gateway` 重跑三能力 smoke；当前三项 401 未消除前保持 S1-B 未完成。
3. 三能力成功后，用现有公开 synthetic 数据运行真实 Embedding/Rerank/Chat 链路和幂等 seed；
   在权利、涉密和云处理审批前，真实地质资料仍不得出域。
4. 保持 `make smoke-document` 作为每次入库/Worker/Compose 改动的回归门禁，并补充 SIGKILL、
   重试耗尽、删除、旧版本持续可检索和多版本原子切换场景。
5. Stage 6 引入可靠 PDF/OCR/表格 adapter、独立 OCR Worker 和人工质量复核，不把 OCR 文字识别
   宣称为地质图空间理解。
6. 并行建立真实认证、RBAC/多租户和允许使用的 corpus manifest；随后冻结至少 300 题的构建、
   开发、盲测三分集，完成双审、第三方裁决和消融实验。
7. 完成备份恢复、性能/并发/成本压测、论文图表与局限性章节，再冻结答辩 RC 并连续彩排。

在 Stage 1 真实模型验收和资料出域审批之前，不展开真实语料云端入库；synthetic 产品链可继续
用于工程回归，但不得据此发布真实地质效果结论或调正式盲测。