Make the first RAG slice executable without risking production data

The Stage 1 foundation now proves provider contracts with mocks and validates PostgreSQL/pgvector ingestion, approval binding, retrieval, reranking, and idempotency using only synthetic data. Live Bailian validation remains gated on rotating the exposed key.

Constraint: The key shown in chat is compromised and cannot be used or committed

Rejected: Mark Stage 1 complete from mock and offline results | real three-model smoke is still required

Confidence: high

Scope-risk: moderate

Reversibility: clean

Directive: Do not enable real-data ingestion until Stage 3 cloud approval and outbound manifest controls are enforced end to end

Tested: make verify; 41 pytest tests; strict mypy; Ruff; Compose config; pinned image build; empty-volume migration; role denial; two idempotent 20-vector seeds; database restart persistence

Not-tested: Live Bailian calls require a newly rotated key; React product UI is not implemented

docs/04-project-todo.md

@@ -0,0 +1,560 @@
+# 项目全生命周期 TODO 与进度看板
+
+| 项目 | 当前值 |
+|---|---|
+| 基线日期 | 2026-07-12 |
+| 当前阶段 | Stage 1：模型与数据库 PoC，`IN_PROGRESS` |
+| 已完成阶段 | Stage 0：仓库、安全和设计基线 |
+| 整体完成度 | 约 12%，合理区间 10%–15% |
+| 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
+| 业务代码完成度 | 约 8%；Stage 1 的离线/数据库 PoC 已验收，真实百炼 smoke 仍待新 Key，前端产品功能尚未实现 |
+| 当前预计剩余工期 | 约 9–13 周，含 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 进度口径
+
+当前进度采用里程碑权重，不采用“文件数量”或“代码行数”：
+
+| 阶段 | 权重 | 当前状态 | 已计入进度 |
+|---|---:|---|---:|
+| 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 6 OCR、表格与质量 | 10% | `TODO` | 0% |
+| Stage 7 正式评测与消融 | 12% | `TODO` | 0% |
+| Stage 8 安全、恢复、性能和论文 | 7% | `TODO` | 0% |
+| Stage 9 答辩、发布与归档 | 3% | `TODO` | 0% |
+| **合计** | **100%** | — | **12%** |
+
+Stage 1 已完成可离线验收的数据库、适配器契约和 synthetic seed 子闭环，阶段内部约完成 85%；但真实三模型 smoke 仍依赖轮换后的新 Key，因此 Stage 1 不提前计入整体里程碑。本文复选框表示“已通过验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑约 12%，Stage 1 离线部分可运行，真实百炼验证尚未完成。**
+
+## 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 | 前端静态布局、OpenAPI 生成脚本 | 绕过任务租约直接做不可恢复长任务 |
+| 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 的完成只代表设计和工程防线完成。
+
+### 已完成提交/推送节点
+
+- [x] `S0-A`：建立安全、架构、数据、部署和实施设计基线。
+- [x] 推送 `main` 并确认 `origin/main` 指向 Stage 0 基线提交。
+
+### 后续仍持续生效的门禁
+
+- 真实 Key、真实工作空间地址、受限数据和私有 benchmark 永不进入 Git。
+- 新实现若改变边界、数据状态或模型契约，必须先更新 ADR/设计再验收。
+- Stage 0 完成不能被用于宣称模型、数据库、后端或前端已经可运行。
+
+## 4. Stage 1：模型与数据库 PoC
+
+- **状态：** `IN_PROGRESS`
+- **预计工期：** 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.yaml`，包含 `db + migrate + provider-smoke + seed-demo/offline`。
+- [x] 创建 PostgreSQL bootstrap、migrator 和 app 分权角色初始化脚本；备份只读角色在备份功能落地时单独创建。
+- [x] 创建 Alembic 基线迁移，启用 pgvector 并建立 1024 维向量表/HNSW 基线。
+- [x] 确保运行期服务不挂载 bootstrap 或 migrator Secret。
+
+#### 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] `docker compose up db migrate` 在空 volume 成功建立扩展、角色和表。
+- [ ] `docker compose run --rm provider-smoke` 三模型探测成功，日志无 Secret。
+- [x] `docker compose run --rm seed-demo-offline` 完成 20 条虚构数据写入、检索和重排；真实模式待新 Key。
+- [x] 第二次运行 seed 后数据库计数与第一次相同，均为 chunks/vectors/searchable = 20/20/20。
+- [x] 41 项测试证明 Embedding 维度/下标、Rerank 下标、Chat 流式响应和失败路径正确。
+- [x] `make verify`、Secret 扫描、固定镜像构建和 `git diff --check` 通过。
+
+### 2026-07-12 已验证运行证据
+
+- 全新 volume 上 `db` 达到 healthy，`migrate` 以非超级用户退出码 0，版本为 `0001_initial_schema`。
+- `vector` 扩展与 HNSW 基线存在；app/migrator 均非超级用户，app 无 `rag` schema DDL 权限但具有所需 DML。
+- 两次离线 seed 均输出 20/20/20，9 个可回答虚构问题 Hit@3 = 9/9。
+- PostgreSQL 重启后计数仍为 20/20/20。
+- app 尝试修改已 `CLOUD_APPROVED` 的 `cloud_text` 被审批不可变触发器拒绝；尝试建表被权限拒绝。
+- 唯一未验收项是真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` smoke 与真实模式 seed。
+
+### 提交/推送节点
+
+- [ ] `S1-A`：数据库初始化、分权角色、迁移和最小 Compose；验证后提交并推送。
+- [ ] `S1-B`：三模型适配器、fake 契约测试和 live smoke；验证后提交并推送。
+- [ ] `S1-C`：20 条虚构 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：扩展为完整工程骨架
+
+- **状态：** `TODO`
+- **预计工期：** 3–4 个工作日
+- **依赖：** Stage 1 `DONE`
+
+### 具体实现任务
+
+- [ ] 建立 FastAPI 应用工厂、配置加载、稳定错误码和 OpenAPI。
+- [ ] 按 `domain -> ports -> services -> adapters/persistence` 落实后端依赖边界。
+- [ ] 建立 SQLAlchemy 仓储、Alembic 迁移运行器和事务边界。
+- [ ] 建立 PostgreSQL `background_jobs`、租约、lease token、fencing 和重试状态机。
+- [ ] 建立 Worker maintenance loop、advisory-lock reaper 和强杀恢复测试。
+- [ ] 建立 `/health/live`、`/health/ready` 和管理员模型能力探测端点。
+- [ ] 建立 React + TypeScript strict、路由、TanStack Query 和 OpenAPI 客户端生成。
+- [ ] 建立 Nginx，仅发布 Web 端口；API、Worker、DB 只在内部网络。
+- [ ] 建立完整 Compose：`web/api/worker/db/migrate`，OCR profile 默认关闭。
+- [ ] 建立 Ruff、类型、pytest、ESLint、TypeScript、Vitest 和镜像检查。
+- [ ] 建立 Gitea CI 的 fake provider 测试；外部 PR 不运行真实 Key 测试。
+
+### 验收证据
+
+- [ ] 空白机器仅按 README 执行即可启动完整骨架。
+- [ ] migration 只执行一次，失败时 API readiness 不通过。
+- [ ] `docker compose ps` 只暴露 Nginx/Web 端口。
+- [ ] Docker 重启后数据库数据保留。
+- [ ] 强杀 Worker 后验证可重领、耗尽进入 `FAILED`、旧 token 不能提交。
+- [ ] 后端/前端 lint、类型、单元和集成测试均通过。
+
+### 提交/推送节点
+
+- [ ] `S2-A`：FastAPI、持久化、健康端点和错误契约。
+- [ ] `S2-B`：任务租约、reaper、fencing 和恢复测试。
+- [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档。
+- [ ] 每个节点验证后独立提交并推送；Stage 2 完成时在本文更新状态。
+
+### 风险门禁
+
+- 不为单机毕设提前引入 Redis、Celery、微服务或独立向量数据库。
+- readiness 不把百炼短时故障等同于 API 容器不可用；模型健康单独展示。
+- 前端构建产物、OpenAPI 示例和测试日志不得包含 Key 或真实受限数据。
+
+## 6. Stage 3：数字文档入库主链路
+
+- **状态：** `TODO`
+- **预计工期：** 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` 单事务切换和持续对账。
+- [ ] 实现删除立即退出检索、后台物理清理和最小审计记录。
+- [ ] 实现知识库、文档列表、上传进度、复核状态和错误详情 UI。
+- [ ] 冻结 corpus manifest 与文档族 60/20/20 split；盲测标签由独立保管人控制。
+- [ ] 用允许使用的小规模数字 PDF 语料完成端到端入库演练。
+
+### 验收证据
+
+- [ ] 100% `searchable` 切片可追溯当前文档版本、页码和 outbound manifest。
+- [ ] `approved chunks == READY vector assignments`，维度和文本/profile 哈希一致。
+- [ ] 同一文件重复上传、任务重跑和中断恢复不产生重复记录或重复费用。
+- [ ] 新版本未完整 READY 前旧版本继续可检索；切换没有空窗。
+- [ ] 删除后在线查询立即不可命中，物理清理可审计。
+- [ ] 未获云审批的文档不会触发 Embedding、Rerank 或 LLM 请求。
+
+### 提交/推送节点
+
+- [ ] `S3-A`：上传、数据治理状态机和本地解析。
+- [ ] `S3-B`：结构切分、去重、向量任务和版本激活。
+- [ ] `S3-C`：文档 UI、删除/恢复测试、corpus manifest 和证据。
+- [ ] 每个节点通过安全与回归门禁后提交、推送。
+
+### 风险门禁
+
+- 权利、涉密等级、云处理权限任一不明确即停止外发。
+- `cloud_text`、处理器或 manifest 任一变化自动撤销原审批。
+- 解析失败页、跨页表和低置信内容必须显式失败或进入复核，不静默丢弃。
+
+## 7. Stage 4：检索与重排
+
+- **状态：** `TODO`
+- **预计工期：** 1 周
+- **依赖：** Stage 3 `DONE`；开发集 qrels/100 组三元组可用
+
+### 具体实现任务
+
+- [ ] 实现 query embedding，并在原生模式使用 `text_type=query`。
+- [ ] 实现同权限过滤条件下的 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 预算。
+- [ ] 实现检索实验室：展示查询配置、初召回、重排、来源和耗时。
+- [ ] 完善 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
+
+- **状态：** `TODO`
+- **预计工期：** 1 周
+- **依赖：** Stage 4 `DONE`
+
+### 具体实现任务
+
+- [ ] 建立版本化 Grounded Answer Prompt，要求仅依据编号证据回答。
+- [ ] 实现 `deepseek-v4-flash` SSE、取消传播、超时和流式错误事件。
+- [ ] 后端将模型引用编号映射到真实 chunk/doc/page，拒绝模型自造引用。
+- [ ] 实现证据不足拒答、模型失败时保留检索结果、资料冲突分来源陈述。
+- [ ] 实现会话与消息持久化、来源卡片、页码定位和用户反馈。
+- [ ] 实现文档管理、聊天、检索实验室、评测和系统状态页面导航。
+- [ ] 清理 Markdown/HTML，验证 XSS、危险链接和 Prompt Injection 回归。
+- [ ] 测试用户取消后 Embedding/Rerank/Chat 下游请求停止。
+- [ ] 记录 trace、阶段耗时、Token、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：正式验证集、盲测与消融
+
+- **状态：** `TODO`
+- **预计工期：** 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、CompleteHit、EvidenceGroupRecall、MRR、nDCG、专家答案、忠实度、引用和拒答指标。
+- [ ] 对查询做 1000 次 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. 下一步执行顺序
+
+当前只推进 Stage 1，建议按以下顺序开始：
+
+1. 轮换并受控注入新百炼 Key，确认真实端点不写入仓库。
+2. 创建最小 Python 包、数据库初始化、Alembic 和 `db + migrate` Compose。
+3. 用 fake server 实现并验证三模型适配器契约。
+4. 运行受控 live smoke，记录 provider profile 和能力指纹。
+5. 用 20 条虚构数据完成写入、检索、重排和幂等闭环。
+6. 扩展 `make verify`，保存验收证据，完成 S1-A/S1-B/S1-C 提交与推送。
+
+在 Stage 1 验收之前，不并行展开真实语料入库、完整 UI 或正式验证集调参。

docs/05-stage1-runbook.md

@@ -0,0 +1,108 @@
+# Stage 1 PoC 运行手册
+
+本手册只运行最小后端、PostgreSQL/pgvector、三模型能力探测和 20 条虚构数据 PoC。它不代表完整 React 产品已经完成。
+
+## 1. 安全前置
+
+聊天中曾出现的旧百炼 Key 必须先在控制台重置或删除。仓库没有保存、使用或回显该值；新的 Key 也只能进入被 `.gitignore` 排除的 `secrets/bailian_api_key`。
+
+初始化本地数据库 Secret：
+
+```bash
+make setup-hooks
+make backend-sync
+bash scripts/init-local-secrets.sh
+```
+
+脚本只生成三组彼此不同的随机 PostgreSQL 密码，文件权限为 `0600`。不带 `--with-bailian` 时不会创建模型 Key。
+
+## 2. 离线数据库与向量 PoC
+
+离线模式使用确定性的 1024 维 feature-hash 向量和词法重排器，只验证数据治理、批处理、迁移、向量写入、权限过滤、检索、重排和幂等性，不把它当成真实模型质量。
+
+```bash
+docker compose up -d --build db migrate
+docker compose --profile tools run --rm seed-demo-offline
+docker compose --profile tools run --rm seed-demo-offline
+```
+
+验收输出应满足：
+
+- 两次均为 `status=ok`；
+- `counts.chunks = counts.vectors = counts.searchable = 20`；
+- 第二次运行计数不增长；
+- 输出只含计数、模型标识、模式和聚合指标，不含文档正文、数据库密码或 Key。
+
+Seed 的实际流程是：
+
+1. 只接受 `source_type=synthetic` 且处于 `LOCAL_PARSED_PENDING_CLOUD_REVIEW` 的 20 条样例；
+2. 每批最多 10 条生成 1024 维向量；
+3. 用 UUIDv5 生成稳定的 document/version/chunk ID；
+4. 实算 `cloud_text`、`embedding_text`、profile 和 outbound manifest SHA-256；
+5. 先写 manifest 成员，再绑定 `CLOUD_APPROVED`，最后原子激活文档版本；
+6. 仅从当前 active、READY、同 access scope 的 searchable chunk 召回；
+7. 对 Top K 候选重排并输出虚构问题的 Hit@3；
+8. 相同输入再次执行使用相同 ID 和幂等 upsert，不增加行数。
+
+## 3. 真实百炼能力探测
+
+完成旧 Key 轮换后：
+
+1. 将 `.env.example` 复制为未提交的 `.env`；
+2. 把 `<workspace-id>` 替换为同一个北京地域 MaaS 工作空间 ID；
+3. OpenAI 兼容 URL 以 `/compatible-mode/v1` 结尾；
+4. Rerank URL 以 `/compatible-api/v1` 结尾；
+5. 本项目不使用用户提供的 `/apps/anthropic` 地址；
+6. 通过隐藏输入写入新 Key：
+
+```bash
+bash scripts/init-local-secrets.sh --with-bailian
+docker compose --profile tools run --rm provider-smoke
+```
+
+`provider-smoke` 依次验证：
+
+- `text-embedding-v4` 返回 1 个 1024 维有限非零向量；
+- `qwen3-rerank` 返回可映射到本地候选的下标和分数；
+- `deepseek-v4-flash` 在 `enable_thinking=false`、`enable_search=false` 下产生 SSE 文本。
+
+探测只输出 capability、status、模型、耗时、request ID 和脱敏错误类别。URL 必须属于同一个 `*.cn-beijing.maas.aliyuncs.com` 工作空间，否则在读取 Key 前拒绝运行。
+
+三模型通过后，可让同一批虚构数据走真实 Embedding/Rerank：
+
+```bash
+docker compose --profile tools run --rm seed-demo
+docker compose --profile tools run --rm seed-demo
+```
+
+真实模式仍只允许本仓库的虚构样例；任何真实地质报告必须等 Stage 3 的许可、涉密和 outbound manifest 审核链完成。
+
+## 4. 质量门禁与排障
+
+```bash
+make verify
+docker compose ps -a
+docker compose logs --no-log-prefix migrate
+```
+
+常见失败：
+
+| 现象 | 处理 |
+|---|---|
+| `invalid_local_configuration` | 检查是否仍是占位 URL、两个 URL 是否同一北京工作空间、新 Key 文件是否存在 |
+| migrate 等不到 DB | 检查三个数据库 Secret 是否存在且互不相同；查看 bootstrap 日志 |
+| 401/403 | 不重试风暴；检查新 Key、工作空间和模型授权 |
+| 429/5xx/timeout | 适配器执行有界指数退避；持续失败时保留脱敏 request ID 后停止 |
+| seed 计数不是 20 | 不进入下一阶段；检查迁移、manifest 约束和事务日志 |
+
+停止服务但保留数据：
+
+```bash
+docker compose down
+```
+
+不要在需要保留验证证据时执行 `docker compose down -v`，因为它会删除 PostgreSQL volume。
+
+## 5. 当前完成边界
+
+可在没有百炼 Key 时验收：配置/Secret 安全、MockTransport 契约、离线向量/重排、Compose 渲染、空卷迁移、20 条写入和幂等。只有轮换后的新 Key 完成三模型真实 smoke 与真实 seed 后，Stage 1 才能从 `IN_PROGRESS` 改为 `DONE`。

docs/README.md

@@ -1,11 +1,25 @@
 # 设计文档索引
 
+## 当前进度
+
+- Stage 0“仓库、安全和设计基线”已完成并推送。
+- Stage 1“模型与数据库 PoC”正在进行。
+- 当前整体完成度约 12%，合理区间为 10%–15%。
+- 00–03 的设计基线已完成；业务代码完成度约 8%，Stage 1 离线数据库/适配器/seed 子闭环已验收，真实百炼 smoke 与前端产品功能尚未完成。
+- 后续状态、依赖、验收证据、工期和提交节点以 [项目全生命周期 TODO](04-project-todo.md) 为准。
+
+## 文档列表
+
 | 文档 | 内容 | 状态 |
 |---|---|---|
 | [00-overall-design.md](00-overall-design.md) | 项目范围、总体架构、技术选型、接口、数据模型与 RAG 主流程 | 设计基线完成 |
 | [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 进行中 |
+| [05-stage1-runbook.md](05-stage1-runbook.md) | Secret 初始化、离线数据库/seed、真实三模型 smoke 和排障命令 | Stage 1 运行手册 |
 | [adr/](adr/) | 不易逆转的架构决策记录 | 持续维护 |
 
 文档中的工作空间地址统一使用 `<workspace-id>` 占位符；真实地址和凭证均属于部署配置，不写入仓库。
+
+建议首次阅读按 00 → 01 → 02 → 03 → 04 的顺序；日常执行查看 04，运行 PoC 查看 05。