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/06-frontend-demo-runbook.md

@@ -0,0 +1,91 @@
+# React 离线检索演示运行手册
+
+本手册用于启动 React + Nginx + gateway + FastAPI + PostgreSQL/pgvector 的同源离线演示。当前页面只展示合成数据的检索和重排结果，不调用百炼，不生成大模型答案，也不构成地质勘查结论。
+
+## 1. 一键启动
+
+首次运行先创建本地数据库 Secret：
+
+```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
+```
+
+`web` 的依赖链会依次等待 `db -> migrate -> api -> gateway`。离线 seed 完成后刷新页面，即可看到 20/20/20 的演示数据状态。
+
+访问入口：
+
+- React 演示：<http://127.0.0.1:8000/>
+- FastAPI Swagger：<http://127.0.0.1:8000/docs>
+- 数据库 readiness：<http://127.0.0.1:8000/health/ready>
+- synthetic 状态：<http://127.0.0.1:8000/api/v1/demo/status>
+
+## 2. 推荐演示流程
+
+1. 确认页面顶部持续显示“合成数据、离线模式、不调用云端模型”。
+2. 确认切片、向量和可检索计数均为 20。
+3. 选择示例问题或输入“花岗斑岩 铜矿化”，设置返回 3 条。
+4. 提交检索，查看合成标题、证据摘录、页码、演示排序分和不透明 citation ID。
+5. 说明 citation ID 尚不能打开真实报告页，当前没有 LLM 生成答案。
+6. 缩窄浏览器到移动宽度，验证表单和来源卡片仍可完整阅读。
+
+## 3. 本地前端开发
+
+先让 Docker Web/API 链保持运行，再启动 Vite：
+
+```bash
+cd frontend
+npm ci
+npm run dev
+```
+
+Vite 只监听 `127.0.0.1`，并把 `/api`、`/health` 和 `/openapi.json` 代理到本机 Docker Web 入口。前端 API 基址保持同源，构建产物中不存在数据库地址或百炼凭证。
+
+后端 OpenAPI 改变后重新生成类型：
+
+```bash
+cd frontend
+npm run generate:api
+npm run typecheck
+```
+
+生成脚本会检查 demo status/search 路径是否存在，然后覆盖 `src/api/schema.generated.ts`；生成结果必须随 API 契约变更一起提交。
+
+## 4. 质量门禁
+
+```bash
+make verify
+docker compose --env-file .env.example ps -a
+```
+
+统一门禁包括：
+
+- Secret、Markdown 链接和 Git diff 检查；
+- Ruff、严格 mypy 和 pytest；
+- Prettier、ESLint、严格 TypeScript、Vitest 和 Vite production build；
+- Compose 配置与网络/Secret 合同测试。
+
+容器级验收还应确认：
+
+- 只有 `web` 发布 `127.0.0.1:8000`；
+- `web` 和 `gateway` 没有 Secret；
+- `api` 只连接 internal data 网络，公网 socket 探测失败；
+- `gateway` 公网 socket 探测失败；Web 因普通 edge 网络可技术性出网，但无 Secret、无数据网络和挂载，此残余风险记录于 ADR-0004；
+- `/api`、健康检查和 Swagger 经 Web 同源代理可用；
+- SSE 响应在 gateway 与 Nginx 均不被整体缓冲。
+
+## 5. 停止与清理
+
+停止容器但保留 PostgreSQL 数据：
+
+```bash
+docker compose down
+```
+
+不要在需要保留验收数据时使用 `docker compose down -v`。该命令会删除 PostgreSQL volume。
+
+## 6. 当前边界
+
+已实现的是可运行的离线检索演示；尚未实现登录、真实知识库、文件上传、OCR、生成答案、可点击原文页、会话、反馈、正式评测面板和真实百炼模型探测。只有轮换后的新 Key 完成三模型 smoke 后，Stage 1 才能标记为完成，Stage 2 也不能因页面可见而提前标记为完成。