Make the governed RAG evidence path executable end to end

Separate local parsing from model indexing, bind review decisions to immutable manifests, persist vectors behind active profiles, and expose retrieval, chat, evaluation, and document workflows through the React workbench.

Constraint: Live Bailian authentication currently fails for all three configured capabilities

Rejected: Direct upload-to-embedding flow | bypasses local review and manifest binding

Confidence: high

Scope-risk: broad

Directive: Keep private-data deployment blocked until authentication, RBAC, and separate database roles land

Tested: make verify; fresh and replay Docker document smoke; worker recovery smoke; frozen synthetic evaluation; migration 0003-0004 roundtrip

Not-tested: Successful live Bailian calls, OCR, real multi-user authorization

frontend/README.md

@@ -1,6 +1,19 @@
-# 地质知识离线检索前端
+# 地质知识 RAG 工作台前端
 
-React + TypeScript 的 synthetic/offline RAG 演示工作台。前端只访问同源 `/api`，不读取、保存或显示模型 Key、百炼工作区地址和数据库连接信息。
+React + TypeScript 的地质知识 RAG 工作台，覆盖离线演示、正式检索、证据问答和受控文档入库。前端只访问同源 `/api`，不读取、保存或显示模型 Key、百炼工作区地址和数据库连接信息。
+
+## 文档入库工作台
+
+访问 `/documents` 可验证完整的治理流程：
+
+1. 浏览器计算文件 SHA-256，以 UUID `Idempotency-Key` 创建上传声明；
+2. 以 `application/octet-stream` 写入隔离存储，完成后轮询本地解析作业；
+3. 加载全部分页复核包，核对页、块、Chunk、profile 与出域 manifest；
+4. 人工确认后以 `expected_revision` 和 manifest 提交批准，或选择明确原因拒绝；
+5. 批准后轮询向量索引作业，直到完整性校验与激活完成。
+
+支持 TXT、Markdown、DOCX 和 PDF，浏览器侧限制 100 MiB。PDF 进入 `OCR_REQUIRED`
+并不代表系统已经理解地图空间关系；页面不会把上传成功或解析成功显示为可检索。
 
 ## 运行环境与固定版本
 
@@ -28,19 +41,20 @@ Vite 将同源 `/api` 代理到本机后端。生产构建输出到 `dist/`。
 
 ## OpenAPI 类型
 
-`src/api/schema.generated.ts` 来自 FastAPI 的真实 OpenAPI 文档。后端 API 契约变化后，启动后端并运行：
+`src/api/schema.generated.ts` 来自 FastAPI 应用工厂的真实 OpenAPI 文档。默认离线导出，不需要启动 API、连接数据库或读取模型 Secret。后端契约变化后运行：
 
 ```bash
 npm run generate:api
 ```
 
-如后端使用其他本机端口，可设置非敏感的 `OPENAPI_SCHEMA_URL`：
+如需对照正在运行的其他本机端口，可显式设置非敏感的 `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` 均存在后才覆盖类型文件。
+生成脚本会确认 Demo、正式 Retrieval 与 Grounded Chat 契约均存在后才覆盖类型文件。
+`npm run check:api` 会离线重新生成到内存并与提交文件逐字比较，CI 用它阻止后端和前端类型漂移。
 
 ## 质量门禁