# 地质知识离线检索前端

React + TypeScript 的 synthetic/offline RAG 演示工作台。前端只访问同源 `/api`，不读取、保存或显示模型 Key、百炼工作区地址和数据库连接信息。

## 运行环境与固定版本

- 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 状态允许检索；结果中的“演示排序分”不是地质结论置信度。