Make the offline RAG chain observable without widening credential access

Expose the verified synthetic retrieval path through a typed React client and a non-root Nginx edge while keeping database credentials and data-network reachability out of the browser tier. A fixed-origin gateway preserves request boundaries and now closes upstream streams even when downstream disconnects before body iteration. The deployment ADR and runbooks record the four-network topology and its accepted Web edge-egress risk.

Constraint: The previously exposed Bailian key must be revoked and no live provider credential may enter Git, images, logs, or the browser.
Rejected: Connect Web directly to the data network | expands lateral reach to PostgreSQL.
Rejected: Publish the database-aware API on the edge network | gives a credential-bearing process a public default route.
Rejected: Buffer streaming responses in either proxy | prevents incremental chat delivery in the future.
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Do not mark Stage 1 or Stage 2 complete until the rotated-key live smoke and remaining stage gates pass.
Tested: make verify; 65 backend tests; 14 frontend tests; Docker image build; container health and isolation probes; real HTTP demo/status/search/docs/OpenAPI checks.
Not-tested: Live Bailian models, real document ingestion, business chat SSE generation, and final browser screenshot automation because the browser skill runtime was unavailable.

docs/04-project-todo.md

@@ -7,7 +7,7 @@
 | 已完成阶段 | Stage 0：仓库、安全和设计基线 |
 | 整体完成度 | 约 12%，合理区间 10%–15% |
 | 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
-| 业务代码完成度 | 约 10%；Stage 1 的 Docker API、离线检索和数据库 PoC 已验收，真实百炼 smoke 仍待新 Key，前端产品功能尚未实现 |
+| 业务代码完成度 | 约 18%；Stage 1 的 Docker API、离线检索、数据库 PoC，以及 React 离线演示、Nginx 单入口和四网络隔离前置均已验收；真实百炼 smoke 仍待轮换后的新 Key |
 | 当前预计剩余工期 | 约 9–13 周，含 300 题正式标注、盲测、论文和答辩缓冲 |
 | 进度权威来源 | 本文的阶段状态、验收证据和已推送提交 |
 
@@ -50,7 +50,7 @@
 | Stage 9 答辩、发布与归档 | 3% | `TODO` | 0% |
 | **合计** | **100%** | — | **12%** |
 
-Stage 1 已完成可离线验收的数据库、适配器契约、synthetic seed 和只读 API 子闭环，阶段内部约完成 90%；但真实三模型 smoke 仍依赖轮换后的新 Key，因此 Stage 1 不提前计入整体里程碑。本文复选框表示“已通过验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑约 12%，Stage 1 离线后端可运行，真实百炼验证尚未完成。**
+Stage 1 已完成可离线验收的数据库、适配器契约、synthetic seed、只读 API 和 Web 演示子闭环，安全离线子阶段内部约完成 95%；但真实三模型 smoke 仍依赖轮换后的新 Key，因此 Stage 1 不提前计入整体里程碑。Stage 2 中不依赖云密钥的 React、Nginx、网络隔离和质量门禁前置已经完成，但 Worker 租约、完整产品工作流等必选项尚未完成，Stage 2 仍为 `TODO`。本文复选框表示“已通过验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑约 12%，业务代码约 18%，Stage 1 安全离线链路可运行，真实百炼验证尚未完成。**
 
 ## 2. 阶段依赖与关键路径
 
@@ -70,7 +70,7 @@ Stage 0 DONE
 | 阶段 | 必须依赖 | 可提前并行的工作 | 不得提前做的工作 |
 |---|---|---|---|
 | Stage 1 | Stage 0、已轮换 Secret、受控联网 | 虚构数据和 fake server 契约测试 | 使用真实地质资料，或使用已暴露密钥 |
-| Stage 2 | Stage 1 三模型和迁移 PoC | 前端静态布局、OpenAPI 生成脚本 | 绕过任务租约直接做不可恢复长任务 |
+| 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 |
@@ -165,7 +165,7 @@ Stage 0 DONE
 - [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] 63 项测试证明模型契约、健康检查、固定上游 gateway、离线 demo、数据治理和失败路径正确。
+- [x] 65 项后端测试证明模型契约、健康检查、固定上游 gateway、SSE 代理分块与早断连释放契约、离线 demo、数据治理和失败路径正确。
 - [x] `make verify`、Secret 扫描、固定镜像构建和 `git diff --check` 通过。
 
 ### 2026-07-12 已验证运行证据
@@ -177,6 +177,10 @@ Stage 0 DONE
 - 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 / egress` 四网络边界已落地；Web 不可解析数据库，API 与 gateway 无公网 TCP 出口，Web 与 gateway 均不持有 Secret。
+- gateway 与 Nginx 已关闭代理缓冲，自动测试证明两个 SSE 事件保持为独立下游分块，且响应头阶段断连也会释放上游流；真实聊天生成与取消传播仍属于 Stage 5，尚未实现。
 - 唯一未验收项是真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` smoke 与真实模式 seed。
 
 ### 提交/推送节点
@@ -202,6 +206,7 @@ Stage 0 DONE
 - **状态：** `TODO`
 - **预计工期：** 3–4 个工作日
 - **依赖：** Stage 1 `DONE`
+- **已完成前置：** 不依赖云密钥的 React 离线演示、OpenAPI 类型、Nginx 单入口、四网络隔离和当前质量门禁已验收；这不代表 Stage 2 已启动或完成。
 
 ### 具体实现任务
 
@@ -211,26 +216,26 @@ Stage 0 DONE
 - [ ] 建立 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 只在内部网络。
+- [x] 建立 React + TypeScript strict、路由、TanStack Query 和 OpenAPI 客户端生成。
+- [x] 建立 Nginx，仅发布 Web 端口；当前 API、DB 只在内部网络，Worker 落地后必须沿用同一边界。
 - [ ] 建立完整 Compose：`web/api/worker/db/migrate`，OCR profile 默认关闭。
-- [ ] 建立 Ruff、类型、pytest、ESLint、TypeScript、Vitest 和镜像检查。
-- [ ] 建立 Gitea CI 的 fake provider 测试；外部 PR 不运行真实 Key 测试。
+- [x] 建立当前范围的 Ruff、类型、pytest、ESLint、TypeScript、Vitest 和镜像检查；Stage 2 新模块必须继续纳入门禁。
+- [x] 建立 Gitea CI 的 fake provider 测试；外部 PR 不运行真实 Key 测试。
 
 ### 验收证据
 
 - [ ] 空白机器仅按 README 执行即可启动完整骨架。
 - [ ] migration 只执行一次，失败时 API readiness 不通过。
-- [ ] `docker compose ps` 只暴露 Nginx/Web 端口。
+- [x] 当前 `docker compose ps` 只暴露 Nginx/Web 回环端口；加入 Worker 后须重新验收。
 - [ ] Docker 重启后数据库数据保留。
 - [ ] 强杀 Worker 后验证可重领、耗尽进入 `FAILED`、旧 token 不能提交。
-- [ ] 后端/前端 lint、类型、单元和集成测试均通过。
+- [x] 当前后端 65 项、前端 14 项测试及两端 lint、类型和构建门禁均通过；Stage 2 新功能仍需增量验证。
 
 ### 提交/推送节点
 
 - [ ] `S2-A`：FastAPI、持久化、健康端点和错误契约。
 - [ ] `S2-B`：任务租约、reaper、fencing 和恢复测试。
-- [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档。
+- [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档；其中 React/Nginx/CI 前置已完成，缺 Worker 与完整 Compose 验收，节点不得提前关闭。
 - [ ] 每个节点验证后独立提交并推送；Stage 2 完成时在本文更新状态。
 
 ### 风险门禁
@@ -555,13 +560,13 @@ Stage 0 DONE
 
 ## 15. 下一步执行顺序
 
-当前只推进 Stage 1，建议按以下顺序开始：
+当前主线仍是关闭 Stage 1 的真实供应商门禁；已完成的 React/Nginx 工作仅作为 Stage 2 安全前置保留。建议按以下顺序继续：
 
-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 提交与推送。
+1. 在百炼控制台撤销聊天中暴露的旧 Key，创建新 Key，并仅通过未提交的 Docker Secret 注入。
+2. 分别运行 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash` 受控 live smoke，记录脱敏 provider profile、能力指纹、维度、流式协议和错误映射。
+3. 用现有 20 条 synthetic 数据运行真实 Embedding/Rerank/Chat 链路和幂等 seed；真实地质资料仍不得出域。
+4. 关闭 S1-B 并把 Stage 1 标记为 `DONE` 后，再实现 Stage 2 的 Worker 租约、fencing、reaper、恢复测试和完整 Compose。
+5. Stage 3 实现数字 PDF/DOCX/TXT/Markdown 的隔离解析、页码/章节恢复、审批状态机、切分、向量化写库和可追溯版本激活。
+6. Stage 4 完成真实向量召回、重排与验证集评测；Stage 5 再实现 grounded chat SSE、取消传播、引用解析和聊天 UI，不把当前代理分块测试误称为聊天功能完成。
 
-在 Stage 1 验收之前，不并行展开真实语料入库、完整 UI 或正式验证集调参。
+在 Stage 1 验收之前，不展开真实语料云端入库或正式验证集调参；前端可继续做不接触 Secret、不会绕过阶段门禁的离线可用性修正。