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.
3.3 KiB
3.3 KiB
React 离线检索演示运行手册
本手册用于启动 React + Nginx + gateway + FastAPI + PostgreSQL/pgvector 的同源离线演示。当前页面只展示合成数据的检索和重排结果，不调用百炼，不生成大模型答案，也不构成地质勘查结论。
1. 一键启动
首次运行先创建本地数据库 Secret：
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 演示：http://127.0.0.1:8000/
- FastAPI Swagger：http://127.0.0.1:8000/docs
- 数据库 readiness：http://127.0.0.1:8000/health/ready
- synthetic 状态：http://127.0.0.1:8000/api/v1/demo/status
2. 推荐演示流程
- 确认页面顶部持续显示“合成数据、离线模式、不调用云端模型”。
- 确认切片、向量和可检索计数均为 20。
- 选择示例问题或输入“花岗斑岩 铜矿化”，设置返回 3 条。
- 提交检索，查看合成标题、证据摘录、页码、演示排序分和不透明 citation ID。
- 说明 citation ID 尚不能打开真实报告页，当前没有 LLM 生成答案。
- 缩窄浏览器到移动宽度，验证表单和来源卡片仍可完整阅读。
3. 本地前端开发
先让 Docker Web/API 链保持运行，再启动 Vite：
cd frontend
npm ci
npm run dev
Vite 只监听 127.0.0.1，并把 /api、/health 和 /openapi.json 代理到本机 Docker Web 入口。前端 API 基址保持同源，构建产物中不存在数据库地址或百炼凭证。
后端 OpenAPI 改变后重新生成类型：
cd frontend
npm run generate:api
npm run typecheck
生成脚本会检查 demo status/search 路径是否存在，然后覆盖 src/api/schema.generated.ts；生成结果必须随 API 契约变更一起提交。
4. 质量门禁
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 数据：
docker compose down
不要在需要保留验收数据时使用 docker compose down -v。该命令会删除 PostgreSQL volume。
6. 当前边界
已实现的是可运行的离线检索演示；尚未实现登录、真实知识库、文件上传、OCR、生成答案、可点击原文页、会话、反馈、正式评测面板和真实百炼模型探测。只有轮换后的新 Key 完成三模型 smoke 后，Stage 1 才能标记为完成，Stage 2 也不能因页面可见而提前标记为完成。