# 地质知识 RAG 工作台前端

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`
并不代表系统已经理解地图空间关系；页面不会把上传成功或解析成功显示为可检索。

## 运行环境与固定版本

- 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、连接数据库或读取模型 Secret。后端契约变化后运行：

```bash
npm run generate:api
```

如需对照正在运行的其他本机端口，可显式设置非敏感的 `OPENAPI_SCHEMA_URL`：

```bash
OPENAPI_SCHEMA_URL=http://127.0.0.1:8010/openapi.json npm run generate:api
```

生成脚本会确认 Demo、正式 Retrieval 与 Grounded Chat 契约均存在后才覆盖类型文件。
`npm run check:api` 会离线重新生成到内存并与提交文件逐字比较，CI 用它阻止后端和前端类型漂移。

## 质量门禁

```bash
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run build
```

也可使用 `npm run verify` 顺序执行全部门禁。

当前界面明确区分：索引 ready、空数据、不完整数据、422 输入边界、503 数据库不可用和网络错误。只有 ready 状态允许检索；结果中的“演示排序分”不是地质结论置信度。