# React 离线检索演示运行手册
本手册用于启动 React + Nginx + gateway + FastAPI + PostgreSQL/pgvector 的同源离线演示。当前页面只展示合成数据的检索和重排结果，不调用百炼，不生成大模型答案，也不构成地质勘查结论。
## 1. 一键启动
首次运行先创建本地数据库 Secret：
```bash
make setup-hooks
bash scripts/init-local-secrets.sh
docker compose up -d --build web
docker compose --profile tools run --rm seed-demo-offline
```
`web` 的依赖链会依次等待 `db -> migrate -> api -> gateway`。离线 seed 完成后刷新页面，即可看到 20/20/20 的演示数据状态。
访问入口：
- React 演示：
- FastAPI Swagger：
- 数据库 readiness：
- synthetic 状态：
## 2. 推荐演示流程
1. 确认页面顶部持续显示“合成数据、离线模式、不调用云端模型”。
2. 确认切片、向量和可检索计数均为 20。
3. 选择示例问题或输入“花岗斑岩 铜矿化”，设置返回 3 条。
4. 提交检索，查看合成标题、证据摘录、页码、演示排序分和不透明 citation ID。
5. 说明 citation ID 尚不能打开真实报告页，当前没有 LLM 生成答案。
6. 缩窄浏览器到移动宽度，验证表单和来源卡片仍可完整阅读。
## 3. 本地前端开发
先让 Docker Web/API 链保持运行，再启动 Vite：
```bash
cd frontend
npm ci
npm run dev
```
Vite 只监听 `127.0.0.1`，并把 `/api`、`/health` 和 `/openapi.json` 代理到本机 Docker Web 入口。前端 API 基址保持同源，构建产物中不存在数据库地址或百炼凭证。
后端 OpenAPI 改变后重新生成类型：
```bash
cd frontend
npm run generate:api
npm run typecheck
```
生成脚本会检查 demo status/search 路径是否存在，然后覆盖 `src/api/schema.generated.ts`；生成结果必须随 API 契约变更一起提交。
## 4. 质量门禁
```bash
make verify
docker compose --env-file .env.example ps -a
```
统一门禁包括：
- Secret、Markdown 链接和 Git diff 检查；
- Ruff、严格 mypy 和 pytest；
- Prettier、ESLint、严格 TypeScript、Vitest 和 Vite production build；
- Compose 配置与网络/Secret 合同测试。
容器级验收还应确认：
- 只有 `web` 发布 `127.0.0.1:8000`；
- `web` 和 `gateway` 没有 Secret；
- `api` 只连接 internal data 网络，公网 socket 探测失败；
- `gateway` 公网 socket 探测失败；Web 因普通 edge 网络可技术性出网，但无 Secret、无数据网络和挂载，此残余风险记录于 ADR-0004；
- `/api`、健康检查和 Swagger 经 Web 同源代理可用；
- SSE 响应在 gateway 与 Nginx 均不被整体缓冲。
## 5. 停止与清理
停止容器但保留 PostgreSQL 数据：
```bash
docker compose down
```
不要在需要保留验收数据时使用 `docker compose down -v`。该命令会删除 PostgreSQL volume。
## 6. 当前边界
已实现的是可运行的离线检索演示；尚未实现登录、真实知识库、文件上传、OCR、生成答案、可点击原文页、会话、反馈、正式评测面板和真实百炼模型探测。只有轮换后的新 Key 完成三模型 smoke 后，Stage 1 才能标记为完成，Stage 2 也不能因页面可见而提前标记为完成。