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.

frontend/README.md

@@ -1,23 +1,57 @@
-# Frontend
+# 地质知识离线检索前端
 
-React + TypeScript 前端代码位于本目录。构建产物由 Nginx 提供，并由同一入口反向代理 `/api` 与 SSE。
+React + TypeScript 的 synthetic/offline RAG 演示工作台。前端只访问同源 `/api`，不读取、保存或显示模型 Key、百炼工作区地址和数据库连接信息。
 
-规划边界：
+## 运行环境与固定版本
 
-```text
-frontend/
-├── src/
-│   ├── api/               类型安全的后端客户端
-│   ├── components/        通用展示组件
-│   ├── features/          chat、documents、retrieval、evaluation
-│   ├── hooks/
-│   ├── pages/
-│   ├── routes/
-│   ├── styles/
-│   └── types/
-└── tests/
-    ├── unit/
-    └── e2e/
+- Node.js `>=22.12.0`，本地验证版本 `22.22.3`
+- npm `>=10.9.0`，本地验证版本 `10.9.8`
+- React `19.2.7`
+- React Router `7.18.1`
+- TanStack Query `5.101.2`
+- Vite `8.1.4`
+- TypeScript `5.9.3`（`openapi-typescript 7.13.0` 当前要求 TypeScript 5.x）
+- Vitest `4.1.10`
+
+精确依赖和完整性哈希记录在 `package-lock.json`，不要绕过 lockfile 安装。
+
+## 本地开发
+
+先确保后端监听 `127.0.0.1:8000`，再运行：
+
+```bash
+npm ci
+npm run dev
 ```
 
-前端只展示后端返回的脱敏模型状态，不提供读取、编辑或回显真实模型密钥的页面。
+Vite 将同源 `/api` 代理到本机后端。生产构建输出到 `dist/`。
+
+## OpenAPI 类型
+
+`src/api/schema.generated.ts` 来自 FastAPI 的真实 OpenAPI 文档。后端 API 契约变化后，启动后端并运行：
+
+```bash
+npm run generate:api
+```
+
+如后端使用其他本机端口，可设置非敏感的 `OPENAPI_SCHEMA_URL`：
+
+```bash
+OPENAPI_SCHEMA_URL=http://127.0.0.1:8010/openapi.json npm run generate:api
+```
+
+生成脚本会确认 `/api/v1/demo/status` 和 `/api/v1/demo/search` 均存在后才覆盖类型文件。
+
+## 质量门禁
+
+```bash
+npm run format:check
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
+
+也可使用 `npm run verify` 顺序执行全部门禁。
+
+当前界面明确区分：索引 ready、空数据、不完整数据、422 输入边界、503 数据库不可用和网络错误。只有 ready 状态允许检索；结果中的“演示排序分”不是地质结论置信度。