jerryandClaude Fable 5
1e94de7464
- BFF 薄适配层（FastAPI，8090）：QA 代理/SSE 中继/Neo4j 直连/抽取代理/会话持久化 - Vue3 前端：五相位检索流水线、文献来源与证据链、知识图谱、提取任务四 tab - 四档响应式（桌面/笔记本/平板/手机）、深浅主题 - 81 个 FR 全部实现，测试追溯矩阵 81/81，后端 121 测/前端 156 测 - 真实凭据已脱敏，运行时配置在 backend/.env（不入 git） Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
# PlantAI-rag-new —— 植物基因家族文献知识工作台
|
||
|
||
海古纪 PlantAI 的知识问答工作台：基于文献知识库（100 篇论文 / 44,595 条关系断言 / 382 万实体）的
|
||
基因家族问答系统。采用 `plantai-agent-ui-prototype` 的视觉设计（深色默认、青紫渐变、Agent 五相位时间线），
|
||
支持桌面 / 平板 / 手机四档响应式。
|
||
|
||
**架构**：薄适配层（BFF）+ 全新前端，不重写 RAG 算法。上游为现有运行中的服务，本项目只读消费。
|
||
|
||
```
|
||
浏览器 ──> BFF (FastAPI, 127.0.0.1:8090) ──> QA 7920（问答引擎）
|
||
│ ├─> RAG 8000/7900（论文抽取）
|
||
│ └─> Neo4j 18788（知识图谱，Bolt 直连）
|
||
└─> SQLite（会话历史，WAL）
|
||
```
|
||
|
||
## 目录
|
||
|
||
```
|
||
backend/ BFF（app/ 应用代码，mock/ 前端开发用 mock server）
|
||
frontend/ Vue 3 + Vite 前端（src/ 源码）
|
||
docs/ 全部文档：PRD / API / UI_SPEC / ARCHITECTURE / TEST_PLAN / TEST_CASES / DISCOVERY / 测试报告
|
||
deploy/ 部署脚本：sync.sh（本地→远端）、bff_restart.sh、start-dev.sh、集成检查、E2E 验收
|
||
tests/ 测试（backend 接口、frontend 单元、e2e）
|
||
```
|
||
|
||
## 快速启动（远端）
|
||
|
||
```bash
|
||
# 1. 启动 BFF（自动激活 conda plantai-bff）
|
||
ssh 100.109.52.26 'bash ~/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh'
|
||
|
||
# 2. 启动 Vite 开发服务器（开发模式）
|
||
ssh 100.109.52.26 'cd ~/5090/teamWorkspace/zh/PlantAI-rag-new/frontend && \
|
||
VITE_BFF_TARGET=http://127.0.0.1:8090 setsid nohup npm run dev > /tmp/plantai-vite.log 2>&1 < /dev/null & disown'
|
||
|
||
# 3. Mac 侧访问隧道
|
||
ssh -N -L 5180:127.0.0.1:5180 -L 8090:127.0.0.1:8090 100.109.52.26
|
||
# 浏览器打开 http://localhost:5180
|
||
```
|
||
|
||
生产形态：`npm run build` 产出 `frontend/dist`，BFF 启动时自动静态托管，单进程从 `:8090` 直接服务。
|
||
|
||
## 开发工作流
|
||
|
||
- **本地编辑** `/Users/jerry/haiguji/PlantAI-rag-new/`，**远端运行** `/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/`
|
||
- 同步（PM 执行）：`bash deploy/sync.sh`（rsync，排除 node_modules/venv/data/dist）
|
||
- 前端开发期 API 指向 mock（8099，`scenario=normal|empty|slow|error|degraded` 经 `X-Mock-Scenario` 头切换）；
|
||
集成期 `VITE_BFF_TARGET=http://127.0.0.1:8090` 指向真实 BFF
|
||
- 契约文档（docs/）是开发与测试的唯一依据，变更需 PM 裁决
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 后端（conda plantai-bff 或本地 .venv-backend）
|
||
cd backend && python -m pytest . -q # 单元 + 接口
|
||
# 前端
|
||
cd frontend && npx vitest run --config vitest.config.js # 单元 + 组件
|
||
cd frontend && npx playwright test # E2E 三档视口（mobile/tablet/desktop）
|
||
# 上游连通冒烟
|
||
bash tests/smoke_upstreams.sh
|
||
```
|
||
|
||
## 上游与端口
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|---|---|---|
|
||
| QA V1.1.73（问答引擎） | 7920 | 只读消费；LLM 依赖 DeepSeek 余额 |
|
||
| Gene Family RAG System（抽取） | 8000 | 回落 7900 |
|
||
| Neo4j（知识图谱） | 18788 | canonical schema，Bolt 直连 |
|
||
|
||
## 已知限制
|
||
|
||
- 上游 QA 无 token 级流式（答案在终态一次返回），打字机为客户端揭示动画
|
||
- 每次提问独立检索（`max_rounds:1`），无多轮上下文
|
||
- DeepSeek 余额用尽时答案退化为证据列表（检索/图谱/来源不受影响）
|
||
|
||
详细设计见 `docs/`：PRD.md（81 个功能点）、API.md（BFF 契约）、UI_SPEC.md（设计令牌）、
|
||
ARCHITECTURE.md（分工与协作约定）、DISCOVERY.md（上游探测事实）、TEST_PLAN.md（测试纪律）。
|