YoVinchen
c3bad0f186
Some checks failed
verify / verify (push) Has been cancelled
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.
58 lines
1.6 KiB
Markdown
58 lines
1.6 KiB
Markdown
# 地质知识离线检索前端
|
||
|
||
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 状态允许检索；结果中的“演示排序分”不是地质结论置信度。
|