# 智保通第二阶段后端

本目录是智保通第二阶段“知识服务与数据分析”的统一后端。项目完整继承第一阶段的智能投保、订单、支付、保单、推广归因和后台治理能力，并在同一个 Agent Kernel 上增加 **Agentic RAG、客户长期记忆、多模态材料识别、保单服务和运营趋势分析**。

后端采用 Python 3.12、FastAPI 和 `src/zbt` 可安装包布局，通过 uv 管理依赖和虚拟环境。

## 1. 第二阶段新增能力

### H5 客户端

- Agentic RAG 保险咨询：复杂问题拆分、查询改写、多轮检索和证据聚合。
- 有依据时展示知识来源；知识库未明确时拒绝推测。
- 客户长期记忆：保存明确表达的保障偏好，在新会话中召回并支持删除。
- 敏感信息保护：手机号、身份证号、银行卡号等内容禁止写入长期记忆。
- 保单服务：从保障中的保单发起申请，上传图片并使用多模态模型识别材料。
- 服务记录：查看申请状态和运营处理结果。

### 运营管理端

- 知识中心：`上传/创建 → 索引 → 检索测试 → 发布`。
- 检索测试记录持久化；发布前必须存在有效的检索测试记录。
- 服务申请中心：查看原始材料、识别字段和识别可信度，并进行受理或不受理处理。
- 运营智能体：分析订单量、订单保费、有效保单量和有效保单保费。
- 趋势分析：支持最近 7、30、90 天，并按日期或产品生成图表数据。
- Agent 历史会话和运行记录按用户、人格与权限范围隔离。

## 2. Agent 技术架构

项目保留“一个内核、两种人格”的设计：

- `customer`：客户保障顾问，负责保险咨询、投保引导、知识问答和客户记忆。
- `operation`：运营数据助手，负责业务指标、趋势和推广归因分析。
- Agent Kernel：统一管理 Persona、Skill、Tool 白名单、策略校验、结构化 UI Block、运行事件和异常边界。

主要调用链：

```text
HTTP 请求
  → AgentThreadService
  → Agent Kernel
  → Persona + Skill + Policy
  → LangChain create_agent
  → DeepSeek
  → 受控业务 Tool / 知识检索 Tool
  → 结构化响应
  → MySQL 运行记录 + Redis 热状态 + LangSmith Trace
```

知识检索链路：

```text
问题拆分与改写
  → BGE-M3 向量化
  → Milvus 向量召回 + 关键词召回
  → BGE Reranker 重排
  → 证据聚合与去重
  → 带来源回答或拒绝推测
```

医疗材料识别通过阿里云百炼兼容接口调用 `qwen3.5-plus`，识别结果作为候选字段保存，不能替代用户确认和运营处理。

## 3. 目录结构

```text
backend/
├── src/zbt/
│   ├── api/                 # FastAPI 路由、鉴权和响应封装
│   ├── commands/            # 数据、知识库和评测命令
│   ├── core/                # 配置、安全、错误和公共能力
│   ├── domains/             # 投保、Agent、知识、记忆、服务申请等领域
│   ├── harness/             # Agent 内核、Persona、Skill、Policy 和结构协议
│   ├── infrastructure/      # MySQL、Redis、Milvus 和外部模型适配器
│   └── main.py              # FastAPI 应用装配入口
├── migrations/              # Core、Agent、Analytics 三库迁移
├── evals/                   # 真实模型评测数据
├── tests/                   # 自动化测试
├── var/                     # 本地服务材料等运行文件
├── alembic.ini
├── pyproject.toml
└── uv.lock
```

## 4. 运行环境

需要提前安装并启动：

- Python 3.12
- uv
- MySQL 8
- Redis
- Milvus
- Node.js 22 和 pnpm（启动前端时需要）

后端读取 `backend/.env`。主要配置包括：

| 配置类别 | 环境变量 |
|---|---|
| MySQL | `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、三个 `MYSQL_*_DATABASE` |
| Redis | `REDIS_URL`、`REDIS_PREFIX` |
| Milvus | `MILVUS_URI`、`MILVUS_TOKEN`、`MILVUS_COLLECTION_PREFIX` |
| 向量模型 | `BGE_M3_MODEL_PATH`、`BGE_M3_DEVICE`、`BGE_RERANKER_MODEL_PATH`、`BGE_RERANKER_DEVICE` |
| 文本模型 | `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL` |
| 多模态模型 | `DASHSCOPE_API_KEY`、`DASHSCOPE_BASE_URL`、`DASHSCOPE_VISION_MODEL` |
| 可观测性 | `LANGSMITH_TRACING`、`LANGSMITH_API_KEY`、`LANGSMITH_ENDPOINT`、`LANGSMITH_PROJECT` |
| 安全配置 | `JWT_ACCESS_SECRET`、`JWT_REFRESH_SECRET`、`FIELD_ENCRYPTION_KEY` |

如尚未创建 `.env`：

Windows PowerShell：

```powershell
Set-Location backend
New-Item -ItemType File -Path .env -ErrorAction SilentlyContinue
notepad .env
```

macOS：

```bash
cd backend
touch .env
open -e .env
```

不要将包含真实数据库密码和模型密钥的 `.env` 提交到 Git。

## 5. 首次初始化

第二阶段完整数据库快照位于 `../database/mysql.sql`。请回到仓库根目录按照 `README.md` 执行 `scripts/init-databases.ps1` 或 `scripts/init-databases.sh`，脚本会将快照导入 Docker 中的 MySQL。

`database/mysql.sql` 只初始化 `insurance_s2_core`、`insurance_s2_agent` 和 `insurance_s2_analytics`，并已包含第一阶段继承数据。不要额外执行 Alembic、`seed`、`inherit_stage_one` 或 `build_analytics`。

## 6. 启动项目

### 6.1 Windows 一次启动

在项目根目录执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1
```

该脚本同时启动 FastAPI、H5 和运营管理后台。

### 6.2 Windows 分别启动

后端：

```powershell
Set-Location backend
uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
```

H5：

```powershell
Set-Location frontend
pnpm dev:h5
```

管理后台：

```powershell
Set-Location frontend
pnpm dev:admin
```

### 6.3 macOS / Linux 一次启动

```bash
./scripts/dev.sh
```

不要在 `frontend/apps/h5` 或 `frontend/apps/admin` 目录执行 `pnpm dev:h5`、`pnpm dev:admin`；这两个命令属于前端 workspace 根目录。

### 6.4 运行地址

- H5：<http://127.0.0.1:5173>
- 管理后台：<http://127.0.0.1:5174>
- Swagger：<http://127.0.0.1:8000/docs>
- OpenAPI JSON：<http://127.0.0.1:8000/openapi.json>
- 健康检查：<http://127.0.0.1:8000/api/v1/system/health/live>

测试账号：

- H5：`18800000001`，验证码 `147258`
- 管理员：`admin / zaq1XSW@`
- 运营人员：`operator01 / zaq1XSW@`
- 审核人员：`reviewer01 / zaq1XSW@`

## 7. 单独启动后端

如果只调试 API，可只运行 FastAPI。

Windows PowerShell：

```powershell
Set-Location backend
uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
```

macOS：

```bash
cd backend
uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
```

后端启动时会预加载 BGE-M3 和 BGE Reranker。首次下载或首次载入模型时，终端可能长时间显示 Hugging Face 下载和权重加载信息；出现 `Application startup complete` 后再测试知识问答。

## 8. 真实模型评测

先启动项目，再在 `backend` 目录执行。

Windows PowerShell：

```powershell
uv run python -m zbt.commands.evaluate_agents --suite smoke
uv run python -m zbt.commands.evaluate_agents --suite full
```

macOS：

```bash
uv run python -m zbt.commands.evaluate_agents --suite smoke
uv run python -m zbt.commands.evaluate_agents --suite full
```

评测会调用真实文本模型、真实业务 Tool 和真实 HTTP 接口。启用 LangSmith 后，可在对应项目中查看运行 Trace 和评测记录。

## 9. 测试和代码检查

Windows PowerShell（在项目根目录执行）：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1
```

macOS / Linux（在项目根目录执行）：

```bash
./scripts/test.sh
```

普通代码检查不会替代真实模型评测。涉及 Agent 决策、知识引用和 Tool 调用顺序的行为，应另外运行第 8 节的评测命令。

## 10. 数据库迁移命令

当前推荐使用完整 SQL 快照进行首次初始化。只有在开发新的表结构变更时，才需要手动执行 Alembic。

Windows PowerShell 与 macOS 均在 `backend` 目录执行：

```bash
uv run alembic -c alembic.ini --name alembic_core upgrade head
uv run alembic -c alembic.ini --name alembic_agent upgrade head
uv run alembic -c alembic.ini --name alembic_analytics upgrade head
```

已经发布的迁移文件不要直接修改；表结构发生变化时应创建新的 revision。

## 11. 构建后端安装包

Windows PowerShell：

```powershell
Set-Location backend
uv build
```

macOS：

```bash
cd backend
uv build
```

构建结果生成在 `backend/dist`，包括 wheel 和源码包。日常开发继续使用 `uv sync --locked` 和 `uv run`，无需手工安装构建产物。

## 12. 相关文档

- `../README.md`：第二阶段项目总览和快速启动。
- `../docs/第二阶段新增能力与测试.md`：第二阶段新增业务及建议测试场景。
- `../docs/智保通第一、二阶段启动指南.md`：两个阶段的完整启动说明。

项目根目录中的每个 `scripts/*.ps1` 均提供同名 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。
