Make deployment truth and remaining graduation gates explicit

Document the runnable Docker workflow, expected one-shot container exits, server-controlled Bailian namespace switch, current earned progress, and the security and evaluation work that still blocks private-data or graduation release claims. Constraint: Current local Bailian credentials are rejected by the configured workspace Rejected: Mark the project complete from synthetic metrics | would overstate provider, OCR, authorization, and blind-evaluation readiness Confidence: high Scope-risk: narrow Directive: Keep progress evidence task-based and distinguish synthetic engineering validation from real geological efficacy Tested: make verify-design; Markdown links; secret scan; diff checks Not-tested: Final thesis review and live provider authorization
2026-07-13 05:58:39 +08:00
parent ecdb10c37a
commit 63279cf213
7 changed files with 214 additions and 109 deletions
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@

 本仓库用于“基于 RAG 的地质找矿知识问答系统构建与应用”毕业设计。系统计划采用 Python/FastAPI 后端、React/TypeScript 前端、PostgreSQL + pgvector 向量存储，以及阿里云百炼的 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash`。

-当前处于 Stage 1“模型与数据库 PoC”：设计基线、离线 pgvector/适配器/seed、FastAPI 和 React/Nginx 可视化检索演示均可运行；真实百炼 smoke 仍待轮换后的新 Key，正式知识库、文档入库和生成问答尚未实现。完整方案、状态和评测方法见 [docs/README.md](docs/README.md)，仓库不会把离线演示伪装成已经完成的产品。
+核心 synthetic 产品链现已在 Docker 中多次端到端通过：文档上传、本地解析、manifest 人工审核、向量写库、原子激活、正式检索和带引用问答均可运行，React 已提供 `/documents`、`/retrieval` 和 `/chat` 页面。固定 fixture 的两次入库使用相同身份，version/chunk/assignment/jobs/invocations 计数稳定为 `1/1/1/2/1`；最新 fresh + replay smoke 还证明当前 Worker 执行与幂等重放均有效。当前质量门禁记录为 296 项后端测试、53 项前端测试。真实百炼的 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash` 仍全部返回 401，PDF/OCR、正式认证与多租户、300 题盲测、备份恢复/压测、论文和答辩仍未完成，因此本仓库不会把 synthetic 闭环描述为毕业验收完成。

 ## 目录

@@ -45,6 +45,9 @@
 - [全生命周期 TODO 与进度](docs/04-project-todo.md)
 - [Stage 1 PoC 运行手册](docs/05-stage1-runbook.md)
 - [React 离线检索演示运行手册](docs/06-frontend-demo-runbook.md)
+- [正式检索、Worker 与评测运行手册](docs/07-retrieval-worker-evaluation-runbook.md)
+- [Grounded Chat 运行与引用验证手册](docs/08-grounded-chat-runbook.md)
+- [文档上传、审核、向量化与检索运行手册](docs/09-document-ingestion-indexing-runbook.md)
 - [架构决策记录](docs/adr/README.md)

 ## 当前可运行入口
@@ -52,11 +55,11 @@
 ```bash
 make setup-hooks
 bash scripts/init-local-secrets.sh
-docker compose up -d --build web
-docker compose --profile tools run --rm seed-demo-offline
+make up
+make seed-offline
+make smoke-document
 curl http://127.0.0.1:8000/health/ready
-curl http://127.0.0.1:8000/api/v1/demo/status
 make verify
 ```

-这组命令不需要百炼 Key，只使用 20 条虚构数据验证 pgvector 写入、检索、重排、引用编号和同源 Web 交互。`web` 会依次启动数据库、迁移、内部 API 和 gateway；启动后访问 <http://127.0.0.1:8000/> 使用 React 演示，或访问 <http://127.0.0.1:8000/docs> 查看 FastAPI Swagger。真实模型运行必须先轮换聊天中已暴露的旧 Key，再按 [Stage 1 运行手册](docs/05-stage1-runbook.md) 操作。
+这组命令不需要有效百炼 Key，只使用公开虚构数据验证上传、解析、审批、向量化、pgvector 写入和正式检索/重排；Chat 引用与同源 Web 交互由测试套件及对应页面单独验证。`migrate` 与 `upload-init` 是成功后正常显示 `Exited (0)` 的一次性任务，不是服务暂停。启动后访问 <http://127.0.0.1:8000/documents> 完成文档入库与审核，访问 <http://127.0.0.1:8000/retrieval> 查看正式检索页，访问 <http://127.0.0.1:8000/chat> 查看 Grounded Chat，或访问 <http://127.0.0.1:8000/docs> 查看 Swagger。详细操作见 [文档入库运行手册](docs/09-document-ingestion-indexing-runbook.md)。真实模型运行必须先轮换聊天中已暴露的旧 Key，再按 [Stage 1 运行手册](docs/05-stage1-runbook.md) 操作；真实 Key 永远不得提交到 Git。
--- a/docs/00-overall-design.md
+++ b/docs/00-overall-design.md
@@ -5,7 +5,7 @@
 | 课题 | 基于 RAG 的地质找矿知识问答系统构建与应用 |
 | 学科方向 | 大数据分析 |
 | 文档版本 | v1.1-implementation-sync |
-| 状态 | 设计基线；安全运行骨架已部分实现，产品主链路未完成 |
+| 状态 | 核心 synthetic 产品链已实现；真实百炼与毕业验收范围未完成 |
 | 更新日期 | 2026-07-13 |
 | 后端 | Python + FastAPI |
 | 前端 | React + TypeScript |
@@ -37,9 +37,10 @@ React/Nginx
    -> FastAPI API
        -> PostgreSQL + pgvector
        -> 内部 model-gateway client
-    -> Python Worker（与 API 共用同一 Python 代码镜像）
-        -> 文档解析、分块、向量化和持久化任务
-        -> 内部 model-gateway client
+    -> worker-local（有上传卷，无模型网络/Token）
+        -> 文档验证、解析、分块和审核工件
+    -> worker-model（无上传卷，有内部模型网络/Token）
+        -> 已审批文本的向量化、完整性校验和激活
 model-gateway（唯一持有百炼 Key 和公网出口）
    -> 阿里云百炼 Embedding / Rerank / Chat
 ```
@@ -144,10 +145,12 @@ flowchart LR
    M --> E["text-embedding-v4"]
    M --> R["qwen3-rerank"]
    M --> L["deepseek-v4-flash"]
-    J["DB 持久化任务"] --> K["Python Worker"]
-    K --> D
-    K --> F
-    K -->|"Bearer + X-RAG-Caller: worker"| M
+    J["DB 持久化任务"] --> KL["worker-local"]
+    J --> KM["worker-model"]
+    KL --> D
+    KL --> F
+    KM --> D
+    KM -->|"Bearer + X-RAG-Caller: worker"| M
    A --> J
 ```

@@ -158,7 +161,8 @@ flowchart LR
 | `web` | React 静态页面、Nginx 代理、SSE 透传 | 模型凭证、业务权限判断 |
 | `gateway` | 固定 API 上游、请求大小/头边界、脱敏错误和流式转发 | 数据库凭证、模型凭证、业务权限判断 |
 | `api` | 认证、知识库、检索、问答、评测 API | 长时间 OCR/批量入库 |
-| `worker` | 解析、OCR、分块、向量化、索引、评测批任务 | 对外开放端口 |
+| `worker-local` | 读取上传卷，执行本地验证、解析与确定性切分 | 模型网络、模型 Token、对外端口 |
+| `worker-model` | 读取数据库中已审批文本，执行向量化、完整性校验与激活 | 原始上传卷、百炼 Key、对外端口 |
 | `model-gateway` | 唯一读取百炼 Key、统一模型协议/限流/脱敏错误；校验 API/Worker 内部身份 | 数据库、上传卷、外部端口、业务授权 |
 | `db` | 元数据、向量、任务、会话、评测事实来源 | 原始大文件长期存储 |
 | `storage` | 开发期 Docker volume，生产可切换 OSS | 访问控制的最终判定 |
@@ -166,7 +170,12 @@ flowchart LR

 ### 4.3 为什么不先拆微服务

-解析、检索、生成和评测共享同一领域模型、配置和数据库。拆分业务微服务会提前引入服务发现、分布式追踪、数据一致性和接口版本问题，却没有对应吞吐收益。第一版使用一个 Python 包，由 `api`、`worker` 和 `model-gateway` 三种进程加载；其中 `model-gateway` 不是独立业务服务，而是最小权限的凭证/出口隔离边界。详细决策见 [ADR-0005](adr/0005-isolate-model-egress.md)。
+解析、检索、生成和评测共享同一领域模型、配置和数据库。拆分业务微服务会提前引入服务发现、
+分布式追踪、数据一致性和接口版本问题，却没有对应吞吐收益。第一版使用一个 Python 包，由
+`api`、两个互斥 capability 的 Worker 和 `model-gateway` 进程加载；其中 `model-gateway` 不是
+独立业务服务，而是最小权限的凭证/出口隔离边界。模型出口见
+[ADR-0005](adr/0005-isolate-model-egress.md)，本地/模型 Worker 拆分见
+[ADR-0007](adr/0007-split-local-and-model-workers.md)。

 ## 5. 技术选型

@@ -730,7 +739,13 @@ pgvector 官方给出的单精度 `vector` 存储约为 `4 * dimensions + 8` 字

 ### 15.1 2026-07-13 实现边界

-当前已实现安全运行骨架、内部 `model-gateway` 及 token 身份、模型内部客户端、应用工厂/Problem/trace 契约和 `0002_model_profiles` 迁移代码；`provider-smoke`、真实 `seed-demo` 和 API 进程不再直接持有百炼 Key。当前工作空间对 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash` 的实际请求仍返回 401，因此三能力真实可用性尚未验收。数字文档上传/解析/审核、正式检索 API、grounded chat、Worker 租约恢复、评测运行器和完整产品 UI 仍是后续实现项；不得把本节理解为“整个项目完成”。
+当前已实现安全运行骨架、内部 `model-gateway` 及 token 身份、应用工厂/Problem/trace 契约、
+profile/cache/invocation 与文档入库/审核迁移。公开 synthetic 文档可经上传、解析、manifest
+审核、双 Worker 向量化、原子激活进入正式 Retrieval，并可在 Grounded Chat 中带引用回答；
+Docker 主链已连续两次得到相同身份和稳定计数。当前工作空间对 `text-embedding-v4`、
+`qwen3-rerank`、`deepseek-v4-flash` 的实际请求仍返回 401，因此三能力真实可用性尚未验收。
+PDF/OCR、真实认证与多租户、300 题正式盲测、备份恢复/压测、论文和答辩仍是后续实现项；
+不得把 synthetic 产品链理解为“整个项目完成”。

 ## 16. 参考资料

--- a/docs/02-deployment-and-security.md
+++ b/docs/02-deployment-and-security.md
@@ -3,8 +3,8 @@
 | 项目 | 设计值 |
 |---|---|
 | 部署方式 | Docker Compose 单机 |
-| 长期服务 | 当前 `web`、`gateway`、`api`、`model-gateway`、`db`；后续加入 `worker` |
-| 一次性服务 | `migrate` |
+| 长期服务 | `web`、`gateway`、`api`、`model-gateway`、`worker-local`、`worker-model`、`db` |
+| 一次性服务 | `migrate`、`upload-init`；成功后正常 `Exited (0)` |
 | 对外端口 | 仅 Nginx/Web |
 | 密钥 | Docker Secret / Secret Manager |
 | 数据库 | PostgreSQL 17 + pgvector 0.8.x（实现时固定 digest） |
@@ -17,7 +17,10 @@
 docker compose up -d --build
 ```

-这条命令当前完成数据库健康等待、一次性迁移、`model-gateway`、API、入口 Gateway 和 Web 启动；Worker 落地后也遵循同一依赖链。它不等于“所有数据和模型凭证自动生成”，首次部署仍必须完成密钥轮换、Secret 创建和三模型能力探测。
+这条命令当前完成数据库健康等待、一次性迁移、上传卷初始化、两个最小权限 Worker、
+`model-gateway`、API、入口 Gateway 和 Web 启动。`migrate` 与 `upload-init` 成功后显示
+`Exited (0)` 是预期终态，不是服务暂停。它不等于“所有数据和模型凭证自动生成”，首次部署
+仍必须创建本地 Secret；真实模式还必须完成密钥轮换和三模型能力探测。

 架构定位是适合毕设、演示和单机内部使用的生产式单节点，不宣称跨主机高可用。互联网生产环境应替换托管数据库、对象存储和集中密钥管理。

@@ -29,10 +32,12 @@ docker compose up -d --build
 |---|---|---|---|
 | `db` | 固定版本 pgvector 镜像 | 元数据、向量、任务、会话、评测 | 仅内部网络 |
 | `migrate` | 与后端同镜像 | 运行 Alembic，一次成功退出 | 无 |
+| `upload-init` | 与后端同镜像 | 无网络初始化上传卷属主，一次成功退出 | 无网络 |
 | `api` | `backend/Dockerfile` | FastAPI、检索、问答、管理 API | 仅 internal data/model 网络 |
 | `gateway` | 与后端同镜像 | 固定上游、请求边界、脱敏错误和流式转发 | 仅 internal ingress/data 网络 |
 | `model-gateway` | 与后端同镜像 | 唯一读取百炼 Key，代理 Embedding/Rerank/Chat | 仅 internal model + egress 网络，无宿主机端口 |
-| `worker` | 同一后端镜像 | 解析、向量化、评测后台任务 | 无 |
+| `worker-local` | 同一后端镜像 | 本地文件验证、解析、切分；有上传卷，无模型网络/Token | 仅 internal data 网络 |
+| `worker-model` | 同一后端镜像 | 只处理已审批文本的向量化；无上传卷 | 仅 internal data/model 网络 |
 | `web` | `frontend/Dockerfile` | React 静态资源、Nginx 同源入口和 SSE 代理 | `127.0.0.1:8000`；生产部署 HTTPS |
 | `ocr-worker` | 可选 profile | PaddleOCR 重型任务 | 无 |
 | `prometheus/grafana` | 可选 profile | 本地观测 | 默认不对公网 |
@@ -121,6 +126,20 @@ services:
    networks: [data]
    restart: "no"

+  upload-init:
+    build: ./backend
+    command: ["python", "-m", "app.tools.init_upload_storage"]
+    environment:
+      UPLOAD_ROOT: /data/uploads
+    user: "0:0"
+    network_mode: none
+    volumes:
+      - uploads_data:/data/uploads
+    read_only: true
+    cap_drop: [ALL]
+    cap_add: [CHOWN, FOWNER, DAC_OVERRIDE]
+    restart: "no"
+
  model-gateway:
    build: ./backend
    command: ["uvicorn", "app.model_gateway:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -143,6 +162,8 @@ services:
    depends_on:
      migrate:
        condition: service_completed_successfully
+      upload-init:
+        condition: service_completed_successfully
      model-gateway:
        condition: service_healthy
    environment:
@@ -151,7 +172,7 @@ services:
      - postgres_app_password
      - model_gateway_api_token
    volumes:
-      - uploads:/data/uploads
+      - uploads_data:/data/uploads
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health/ready', timeout=2)"]
      interval: 10s
@@ -170,22 +191,40 @@ services:
    networks: [ingress, data]
    restart: unless-stopped

-  worker:
+  worker-local:
    build: ./backend
-    command: ["python", "-m", "app.workers.main"]
+    command: ["python", "-m", "app.worker"]
    depends_on:
      migrate:
        condition: service_completed_successfully
+      upload-init:
+        condition: service_completed_successfully
+    environment:
+      <<: *runtime-config
+      WORKER_CAPABILITIES: document_parse
+    secrets:
+      - postgres_app_password
+    volumes:
+      - uploads_data:/data/uploads
+    networks: [data]
+    restart: unless-stopped
+
+  worker-model:
+    build: ./backend
+    command: ["python", "-m", "app.worker"]
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+      model-gateway:
+        condition: service_healthy
    environment:
      <<: [*runtime-config, *model-client-config]
      MODEL_GATEWAY_TOKEN_FILE: /run/secrets/model_gateway_worker_token
      MODEL_GATEWAY_CALLER: worker
-      WORKER_CAPABILITIES: ${WORKER_CAPABILITIES:-document_parse,embedding,rerank,evaluation}
+      WORKER_CAPABILITIES: embedding
    secrets:
      - postgres_app_password
      - model_gateway_worker_token
-    volumes:
-      - uploads:/data/uploads
    networks: [data, model]
    restart: unless-stopped

@@ -231,7 +270,7 @@ services:

 volumes:
  postgres_data:
-  uploads:
+  uploads_data:

 networks:
  edge:
@@ -265,7 +304,17 @@ secrets:

 实际实现固定数据库镜像 digest。`migrate` 只有一个实例执行；成功应用到 head 后退出码为 0，随后在 `docker compose ps -a` 显示 `Exited (0)` 是一次性任务的正常终态，不是服务暂停。API 和 Worker 不在启动时并发自动迁移。首次初始化脚本只在 `db` 容器内使用 bootstrap 凭据创建 `vector` 扩展、无超级用户权限的 migrator/app 登录角色和专属 schema；migrator 拥有 schema/DDL，app 仅获运行期所需的 DML/sequence 权限及默认权限，API/Worker 永远不挂载 bootstrap 或 migrator Secret。最后一个初始化脚本只有在全部 SQL 事务和授权成功后，才在 `PGDATA` 内用同文件系统 rename 原子写入 `.rag-bootstrap-complete`；healthcheck 同时检查 `pg_isready` 与该哨兵，防止临时初始化 server 提前放行迁移。Compose 的 `.env` 仅做变量插值，不会自动注入容器；后端从 `*_FILE` 读取 Secret，不把明文密码放进 `.env` 或 `DATABASE_URL`。

-网络分为五层：`web` 位于普通 `edge` 和 internal `ingress`；入口 `gateway` 位于 `ingress + data`；API 位于 internal `data + model`；数据库/迁移位于 internal `data`；只有 `model-gateway` 位于 internal `model + egress`。`provider-smoke` 只持 API 内部 token，真实 `seed-demo` 只持数据库 Secret 和 Worker 内部 token；二者都不挂载百炼 Key、不加入 `egress`。未来 Worker 沿用相同边界。`model-gateway` 不连接数据库、不挂载上传卷、不发布端口。入口隔离见 [ADR-0004](adr/0004-secretless-web-ingress.md)，模型出口隔离见 [ADR-0005](adr/0005-isolate-model-egress.md)。必须注意：普通 `edge` bridge 为 Web 提供宿主机端口发布时，也给 Web 留有技术上的默认公网出口；生产仍需主机防火墙或出口代理只允许 `model-gateway` 到百炼域名。
+网络分为五类：`web` 位于普通 `edge` 和 internal `ingress`；入口 `gateway` 位于
+`ingress + data`；API 位于 internal `data + model`；数据库、迁移和 `worker-local` 位于
+internal `data`；`worker-model` 位于 internal `data + model`；只有 `model-gateway` 位于
+internal `model + egress`。`worker-local` 挂载上传卷但没有模型 Token/网络，`worker-model` 持
+内部 Worker Token 但不挂载上传卷；两者的信任边界见
+[ADR-0007](adr/0007-split-local-and-model-workers.md)。`provider-smoke` 和真实 `seed-demo` 都不
+挂载百炼 Key、不加入 `egress`。`model-gateway` 不连接数据库、不挂载上传卷、不发布端口。
+入口隔离见 [ADR-0004](adr/0004-secretless-web-ingress.md)，模型出口隔离见
+[ADR-0005](adr/0005-isolate-model-egress.md)。必须注意：普通 `edge` bridge 为 Web 提供宿主机
+端口发布时，也给 Web 留有技术上的默认公网出口；生产仍需主机防火墙或出口代理只允许
+`model-gateway` 到百炼域名。

 ### 2.3 后台任务为何不用 Redis

@@ -331,7 +380,11 @@ def read_secret(file_env: str, value_env: str) -> str:

 生产只允许文件/Secret Manager；本地值环境变量仅作为临时兼容。`bailian_api_key` 只挂载到 `model-gateway`。API 与 Worker 分别挂载 `model_gateway_api_token`、`model_gateway_worker_token`；调用同时使用 Bearer token 和 `X-RAG-Caller`，服务端以常量时间比较并拒绝 token/身份不匹配。应用启动后不打印 Settings 的 Secret 字段，异常对象不得包含请求头。

-Secret 或模型端点配置在运行中发生变化时，`model-gateway` 会原子清空旧 provider 与内部 token，并进入 `restart_required`；旧、新 token 都不能在旧进程继续调用。Docker 的 `restart: unless-stopped` 不会仅因 unhealthy 自动重启，因此轮换操作必须协调执行 `docker compose restart model-gateway api`（Worker 落地后同时重启 Worker），待 readiness 恢复后再运行 provider smoke。禁止只替换文件而让旧进程长期携带旧凭据。
+Secret 或模型端点配置在运行中发生变化时，`model-gateway` 会原子清空旧 provider 与内部
+token，并进入 `restart_required`；旧、新 token 都不能在旧进程继续调用。Docker 的
+`restart: unless-stopped` 不会仅因 unhealthy 自动重启，因此轮换操作必须协调执行
+`docker compose restart model-gateway api worker-model`，待 readiness 恢复后再运行 provider
+smoke。禁止只替换文件而让旧进程长期携带旧凭据。

 ### 3.3 Git 防泄漏

--- a/docs/03-implementation-plan.md
+++ b/docs/03-implementation-plan.md
@@ -165,7 +165,12 @@ features/chat/

 每个阶段都必须形成“功能 + 测试 + 文档 + 提交 + 推送”的闭环。

-### 阶段 0：仓库、安全和设计基线（当前阶段）
+截至 2026-07-13，核心 synthetic 上传→解析→审核→向量化→检索链已在 Docker 中连续两次
+通过，当前门禁记录为 296 项后端测试和 53 项前端测试。以下阶段描述仍是最终 Definition of
+Done，不因部分能力提前落地而降低验收标准；实时完成度和剩余项以
+[04-project-todo.md](04-project-todo.md) 为准。
+
+### 阶段 0：仓库、安全和设计基线

 交付：

--- a/docs/04-project-todo.md
+++ b/docs/04-project-todo.md
@@ -3,12 +3,12 @@
 | 项目 | 当前值 |
 |---|---|
 | 基线日期 | 2026-07-13 |
-| 当前阶段 | Stage 1：模型与数据库 PoC，`IN_PROGRESS` |
+| 当前阶段 | 核心 synthetic 产品链已 Docker E2E；Stage 1 真实三模型验收 `BLOCKED`，Stage 2–5/7 按剩余项推进 |
 | 已完成阶段 | Stage 0：仓库、安全和设计基线 |
-| 整体完成度 | 约 12%，合理区间 10%–15% |
+| 整体完成度 | 任务级挣值约 50%，合理区间 45%–55%；核心 synthetic 产品工程链约 70% |
 | 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
-| 业务代码完成度 | 不以新增文件提前抬高里程碑；已增加独立 `model-gateway`、内部 token 身份、应用工厂/Problem/trace 和 `0002` profile/cache 迁移，完整产品主链路仍未完成 |
-| 当前预计剩余工期 | 约 9–13 周，含 300 题正式标注、盲测、论文和答辩缓冲 |
+| 业务代码完成度 | 上传→解析→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) 转换为从当前状态到最终答辩、归档的可执行清单。它只表示计划和已验证事实，不因文档完整就声称系统代码已经完成。
@@ -34,23 +34,32 @@

 ### 1.2 进度口径

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

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

-Stage 1 已完成可离线验收的数据库、适配器契约、synthetic seed、只读 API 和 Web 演示子闭环，并已把百炼 Key/公网出口收敛到独立 `model-gateway`；但真实三模型请求当前均返回 401，因此 Stage 1 不提前计入整体里程碑。Stage 2 中应用工厂、Problem/trace、React、Nginx、网络隔离和质量门禁已作为前置落地，`0002_model_profiles` 迁移代码也已建立；Worker 租约、上传入库、正式检索/聊天和评测等必选项尚未完成，Stage 2 仍为 `TODO`。本文复选框表示“已通过对应层级的验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑仍约 12%，安全离线链路可运行，真实百炼验证和产品主链路尚未完成。**
+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. 阶段依赖与关键路径

@@ -115,7 +124,7 @@ Stage 0 DONE

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

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

@@ -184,8 +193,8 @@ Stage 0 DONE
 - 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 已关闭代理缓冲，自动测试证明两个 SSE 事件保持为独立下游分块，且响应头阶段断连也会释放上游流；真实聊天生成与取消传播仍属于 Stage 5，尚未实现。
- 当前真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` 请求均到达供应商但返回 401；三能力与真实模式 seed 未验收。上传、正式检索、grounded chat、Worker 和评测仍属于后续阶段，不能称为“唯一剩余项”。
+- 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 的真实供应商验收。

 ### 提交/推送节点

@@ -207,40 +216,40 @@ Stage 0 DONE

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

- **状态：** `TODO`
+- **状态：** `IN_PROGRESS`（核心 Compose、业务 Worker 和恢复契约已落地；正式认证/RBAC 与进程级故障矩阵待补）
 - **预计工期：** 3–4 个工作日
 - **依赖：** Stage 1 `DONE`
- **已完成前置：** 不依赖云密钥的 React 离线演示、OpenAPI 类型、Nginx 单入口和质量门禁已验收；模型隔离网络加入后当前为五层网络。这不代表 Stage 2 已启动或完成。
+- **已完成前置：** React、OpenAPI 离线生成、Nginx 单入口、数据库迁移、上传卷初始化及本地/模型 Worker 拆分均已进入默认 Compose。

 ### 具体实现任务

 - [x] 建立 FastAPI 应用工厂、配置加载、稳定 Problem JSON、trace middleware 和 OpenAPI；导入阶段不连库、不读模型凭证。
- [ ] 按 `domain -> ports -> services -> adapters/persistence` 落实后端依赖边界。
- [ ] 建立完整 SQLAlchemy 仓储和业务事务边界；Alembic 已推进到 `0002_model_profiles`，且空卷/已有数据升降级已验证。
- [ ] 建立 PostgreSQL `background_jobs`、租约、lease token、fencing 和重试状态机。
- [ ] 建立 Worker maintenance loop、advisory-lock reaper 和强杀恢复测试。
+- [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 落地后必须沿用同一边界。
- [ ] 建立完整 Compose：`web/api/worker/db/migrate`，OCR profile 默认关闭。
+- [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 测试。

 ### 验收证据

- [ ] 空白机器仅按 README 执行即可启动完整骨架。
- [ ] migration 只执行一次，失败时 API readiness 不通过。
- [x] 当前 `docker compose ps` 只暴露 Nginx/Web 回环端口；加入 Worker 后须重新验收。
- [ ] Docker 重启后数据库数据保留。
- [ ] 强杀 Worker 后验证可重领、耗尽进入 `FAILED`、旧 token 不能提交。
- [x] 已提交基线的两端 lint、类型、测试和构建门禁通过；本轮新增 model-gateway、应用工厂和 `0002` 仍须在提交前以 `make verify` 重新确认。
+- [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` 验证并推送；后续 `model` 网络把当前拓扑扩为五层，该前置提交不代表 Stage 2 已启动或完成。
- [ ] `S2-A`：FastAPI、持久化、健康端点和错误契约。
- [ ] `S2-B`：任务租约、reaper、fencing 和恢复测试。
- [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档；其中 React/Nginx/CI 前置已完成，缺 Worker 与完整 Compose 验收，节点不得提前关闭。
+- [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 完成时在本文更新状态。

 ### 风险门禁
@@ -251,33 +260,33 @@ Stage 0 DONE

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

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

 ### 具体实现任务

- [ ] 实现上传流式大小、扩展名、MIME、页数、加密和恶意文件检查。
- [ ] 实现 `QUARANTINED_LOCAL_REVIEW -> LOCAL_PARSED_PENDING_CLOUD_REVIEW -> CLOUD_APPROVED/REJECTED` 状态机。
- [ ] 在隔离本地完成数字 PDF/DOCX/TXT/Markdown 解析、页码和章节恢复。
- [ ] 生成 `raw_text`、脱敏 `cloud_text` 和 outbound manifest；所有外发调用前核对哈希。
- [ ] 实现 512 Token 基线切分、64 Token 重叠、表头上下文和元数据前缀开关。
- [ ] 实现精确去重、近重复族、版本关系和确定性 chunk ID。
- [ ] 实现 Embedding 批次、内容缓存、chunk assignment、检查点和有界重试。
- [ ] 实现 `documents.active_version_id` 与 `chunks.searchable` 单事务切换和持续对账。
+- [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` 单事务切换。
 - [ ] 实现删除立即退出检索、后台物理清理和最小审计记录。
- [ ] 实现知识库、文档列表、上传进度、复核状态和错误详情 UI。
+- [x] 实现 `/documents` 文档列表、上传/任务进度、复核、批准/拒绝和安全错误 UI。
 - [ ] 冻结 corpus manifest 与文档族 60/20/20 split；盲测标签由独立保管人控制。
 - [ ] 用允许使用的小规模数字 PDF 语料完成端到端入库演练。

 ### 验收证据

- [ ] 100% `searchable` 切片可追溯当前文档版本、页码和 outbound manifest。
- [ ] `approved chunks == READY vector assignments`，维度和文本/profile 哈希一致。
- [ ] 同一文件重复上传、任务重跑和中断恢复不产生重复记录或重复费用。
+- [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 前旧版本继续可检索；切换没有空窗。
 - [ ] 删除后在线查询立即不可命中，物理清理可审计。
- [ ] 未获云审批的文档不会触发 Embedding、Rerank 或 LLM 请求。
+- [x] 未获 manifest 审批的版本不会创建 embedding assignment/job；本地解析 Worker 无模型网络与 Token。

 ### 提交/推送节点

@@ -294,20 +303,20 @@ Stage 0 DONE

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

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

 ### 具体实现任务

- [ ] 实现 query embedding，并在原生模式使用 `text_type=query`。
+- [x] 实现 profile-aware query embedding；当前兼容模式走内部 model-gateway，原生模式能力指纹仍待真实供应商验证。
 - [ ] 实现同权限过滤条件下的 exact Cosine Top K 基线。
 - [ ] 实现 HNSW、iterative scan、`ef_search`、over-fetch 和 ANN 对账。
- [ ] 在候选生成 SQL 内应用知识库、角色、文档状态和可见范围过滤。
- [ ] 实现 Dense Top 50、`qwen3-rerank` Top 10、生成上下文 Top 8。
- [ ] 实现 Rerank 总 Token 预检、响应 index 回填、裁剪和错误分类。
- [ ] 实现候选去重、邻接补全和上下文 Token 预算。
- [ ] 实现检索实验室：展示查询配置、初召回、重排、来源和耗时。
+- [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 和阈值；所有参数只使用开发集。

@@ -333,21 +342,22 @@ Stage 0 DONE

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

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

 ### 具体实现任务

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

 ### 验收证据

@@ -409,7 +419,7 @@ Stage 0 DONE

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

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

@@ -422,8 +432,8 @@ Stage 0 DONE
 - [ ] 建立 `anchored_judgments.jsonl`、manifest、版本和 SHA-256。
 - [ ] 使用 Dense/词法/Hybrid/Rerank union pooling；未判定结果先补标再计分。
 - [ ] 每个 run 生成独立 qrels、anchor resolution、预测、指标和错误报告。
- [ ] 实现 Hit、CompleteHit、EvidenceGroupRecall、MRR、nDCG、专家答案、忠实度、引用和拒答指标。
- [ ] 对查询做 1000 次 bootstrap，输出 95% 置信区间和分层结果。
+- [ ] 已实现严格 Hit、Recall、CompleteHit、EvidenceGroupRecall、MRR、nDCG、引用 precision/recall/F1 与拒答指标；专家答案/忠实度裁决尚未完成。
+- [x] synthetic runner 使用固定 seed 的 2000 次 bootstrap，输出 95% 区间；正式分层结果尚待数据集。
 - [ ] 在开发集完成维度、切片、重叠、前缀、Rerank、上下文、Query 改写等消融。
 - [ ] 冻结最终配置、corpus、judgment set 和盲测哈希，再执行一次正式盲测。
 - [ ] 补标或裁决变化后生成新 judgment 版本，并对比较表中全部系统重新计分。
@@ -565,13 +575,20 @@ Stage 0 DONE

 ## 15. 下一步执行顺序

-当前主线仍是关闭 Stage 1 的真实供应商门禁，同时继续不依赖云授权的安全骨架。建议按以下顺序继续：
+当前主线是保留已通过的 synthetic 产品链作为回归基线，并行关闭真实供应商、数据能力和毕业
+验收三类缺口。建议按以下顺序继续：

 1. 在百炼控制台确认旧 Key 已撤销，并核对当前本地 Secret 对应的工作空间、北京地域、端点、计费方案和模型权限；Key 只保存在未提交 Secret 中。
 2. 通过独立 `model-gateway` 重跑三能力 smoke；当前三项 401 未消除前保持 S1-B 未完成。
-3. 三能力成功后，用现有 20 条 synthetic 数据运行真实 Embedding/Rerank/Chat 链路和幂等 seed；真实地质资料仍不得出域。
-4. 继续实现 Stage 2 的 Worker 租约、fencing、reaper、恢复测试和完整 Compose，不让外部 401 阻塞可离线验证的工程工作。
-5. Stage 3 实现数字 PDF/DOCX/TXT/Markdown 的隔离解析、页码/章节恢复、审批状态机、切分、向量化写库和可追溯版本激活。
-6. Stage 4 完成真实向量召回、重排与验证集评测；Stage 5 再实现 grounded chat SSE、取消传播、引用解析和聊天 UI，不把当前代理分块测试误称为聊天功能完成。
+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 验收之前，不展开真实语料云端入库或正式验证集调参；前端可继续做不接触 Secret、不会绕过阶段门禁的离线可用性修正。
+在 Stage 1 真实模型验收和资料出域审批之前，不展开真实语料云端入库；synthetic 产品链可继续
+用于工程回归，但不得据此发布真实地质效果结论或调正式盲测。
--- a/docs/05-stage1-runbook.md
+++ b/docs/05-stage1-runbook.md
@@ -97,7 +97,10 @@ docker compose --profile tools run --rm seed-demo
 docker compose --profile tools run --rm seed-demo
 ```

-真实模式使用 Worker 内部身份，仍只允许本仓库的虚构样例；任何真实地质报告必须等 Stage 3 的许可、涉密和 outbound manifest 审核链完成。
+真实模式使用 Worker 内部身份，仍只允许本仓库的虚构样例。三能力和真实 seed 均成功后，可按
+[文档入库运行手册](09-document-ingestion-indexing-runbook.md#7-切换到真实阿里云百炼) 将服务端
+`DOCUMENT_NAMESPACE_MODE` 切到 `bailian`，用上传/审核链验证真实向量写库。正式认证、RBAC、
+资料许可、涉密和云处理审批未完成前，不得把私有或真实地质报告送入这条链路。

 截至 2026-07-13，已通过独立 `model-gateway` 重跑三项真实调用：三项都到达供应商，但均返回安全脱敏的 `authentication` 类别（内部非流式调用由 Gateway 以 502 封装，Chat SSE 以终态错误事件返回；根因仍是供应商鉴权失败）。此时应核对 Key 所属工作空间、北京地域、专属端点、计费方案和模型权限，不要反复自动重试。在三项成功前不得声明百炼接入验收通过。

@@ -130,4 +133,8 @@ docker compose down

 ## 5. 当前完成边界

-可在没有可用百炼权限时验收：配置/Secret 安全、内部 token 身份、MockTransport 契约、离线向量/重排、Compose 渲染、迁移、20 条写入和幂等。当前代码还包含 FastAPI 应用工厂、稳定 Problem/trace 契约，以及 `0002_model_profiles` 的 profile/cache/assignment/invocation/citation 迁移；这些不代表上传、正式检索、grounded chat、Worker 和评测已完成。只有有效 Key 完成三模型真实 smoke 与真实 seed 后，Stage 1 才能从 `IN_PROGRESS` 改为 `DONE`。
+可在没有可用百炼权限时验收：配置/Secret 安全、内部 token 身份、MockTransport 契约、离线
+向量/重排、Compose 渲染、迁移、20 条写入和幂等。后续阶段现已实现上传、本地解析、manifest
+审核、向量化、正式检索、Grounded Chat、双 Worker 和 synthetic 评测；这些能力不能反向证明
+真实供应商可用。只有有效 Key 完成三模型真实 smoke 与真实 seed 后，Stage 1 的真实模型子门禁
+才能从 `BLOCKED` 改为 `DONE`。
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,13 +3,15 @@
 ## 当前进度

 - Stage 0“仓库、安全和设计基线”已完成并推送。
- Stage 1“模型与数据库 PoC”正在进行。
- 当前整体里程碑仍约 12%，合理区间为 10%–15%；新增代码不在阶段验收前提前计入完成度。
+- Stage 1“模型与数据库 PoC”的离线部分已完成，真实百炼验收仍受三能力 401 阻断。
+- 按任务级挣值而非“整阶段全有或全无”重新估算，当前完整毕业交付约 50%（合理区间 45%–55%）；核心 synthetic 产品工程链约 70%。详细口径见 [项目全生命周期 TODO](04-project-todo.md)。
 - 00–03 的设计基线已完成；后端离线链路、20 条 synthetic 数据、React 离线演示和 Nginx 单入口已验收。
 - 五层网络与独立 `model-gateway` 已实现：只有该服务持百炼 Key/egress，API、seed、smoke 使用区分 API/Worker 身份的内部 token。
- FastAPI 应用工厂、稳定 Problem/trace 契约，以及 `0002_model_profiles` 的 profile/cache/assignment/invocation/citation 迁移代码已落地。
+- FastAPI 应用工厂、稳定 Problem/trace 契约，以及 profile/cache/assignment/invocation/citation、文档入库和审核迁移已落地。
 - 真实 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash` 当前仍全部返回 401，真实百炼能力尚未验收。
- Stage 2 仍为 `TODO`：Worker 租约/fencing/reaper、上传入库、正式检索、grounded chat、评测和完整产品 UI 尚未完成。
+- 文档上传、本地解析、manifest 审核、异步向量化、原子激活和正式检索已经在 Docker 中连续两次端到端通过；相同身份及 version/chunk/assignment/jobs/invocations 计数均为 `1/1/1/2/1`。
+- 质量门禁当前记录为 296 项后端测试、53 项前端测试。React 已提供文档、正式检索和 Grounded Chat 页面。
+- PDF/OCR、真实认证和多租户、正式 300 题双审盲测、备份恢复/压测、论文与答辩仍未完成，所以全项目仍不能标记 `DONE`。
 - 后续状态、依赖、验收证据、工期和提交节点以 [项目全生命周期 TODO](04-project-todo.md) 为准。

 ## 文档列表
@@ -20,11 +22,14 @@
 | [01-data-and-evaluation.md](01-data-and-evaluation.md) | 语料治理、解析、验证集生成、向量入库测试和论文评测 | 设计基线完成 |
 | [02-deployment-and-security.md](02-deployment-and-security.md) | Docker Compose、配置、密钥、监控、备份和安全 | 设计基线完成 |
 | [03-implementation-plan.md](03-implementation-plan.md) | 阶段计划、完成定义、测试与验收清单 | 设计基线完成 |
-| [04-project-todo.md](04-project-todo.md) | 从当前状态到最终答辩、发布和归档的任务看板 | Stage 1 进行中 |
+| [04-project-todo.md](04-project-todo.md) | 从当前状态到最终答辩、发布和归档的任务看板 | 持续更新 |
 | [05-stage1-runbook.md](05-stage1-runbook.md) | Secret 初始化、离线数据库/seed、真实三模型 smoke 和排障命令 | Stage 1 运行手册 |
 | [06-frontend-demo-runbook.md](06-frontend-demo-runbook.md) | React/Nginx 离线检索演示、同源 API、开发与验收命令 | 离线前端运行手册 |
+| [07-retrieval-worker-evaluation-runbook.md](07-retrieval-worker-evaluation-runbook.md) | 正式 Retrieval API、Worker fencing 和冻结评测工件 | 可运行切片手册 |
+| [08-grounded-chat-runbook.md](08-grounded-chat-runbook.md) | Grounded Chat SSE、引用校验、拒答、降级和真实模型边界 | 可运行切片手册 |
+| [09-document-ingestion-indexing-runbook.md](09-document-ingestion-indexing-runbook.md) | 文档上传、本地解析、人工审核、向量化、激活和检索 Docker E2E | 核心 synthetic 产品链手册 |
 | [adr/](adr/) | 不易逆转的架构决策记录 | 持续维护 |

 文档中的工作空间地址统一使用 `<workspace-id>` 占位符；真实地址和凭证均属于部署配置，不写入仓库。

-建议首次阅读按 00 → 01 → 02 → 03 → 04 的顺序；日常执行查看 04，数据库/模型 PoC 查看 05，React 演示查看 06。
+建议首次阅读按 00 → 01 → 02 → 03 → 04 的顺序；日常执行查看 04，数据库/模型 PoC 查看 05，文档产品链验证直接查看 09。