# 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（测试纪律）。