# 智保通第三阶段后端

本目录是智保通第三阶段“生命周期工作流”的统一后端。项目在第二阶段 Agentic RAG、长期记忆、知识治理、多模态识别和运营分析能力之上，新增基于 LangGraph 的退保审批工作流，以及独立运行的退款 Worker。

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

## 1. 第三阶段核心能力

- 退保资格与可退金额试算。
- LangGraph 风险检查、条件分支、Interrupt、人工审批和 Resume。
- 低风险自动流转，高风险暂停等待运营人员处理。
- 退款 Worker 自动领取任务、执行退款、记录尝试并处理重试。
- Redis 单实例锁、任务租约和幂等约束，避免重复退款。
- 退款成功后在事务中同步收口申请、保单和时间线状态。
- 管理端查看工作流状态、风险依据、审批记录、Worker 状态和退款失败原因。
- 本地只读 MCP 合作医疗服务资源。
- LangSmith 与 OpenTelemetry 记录 Agent、Tool 和 LangGraph 轨迹。

## 2. 运行架构

第三阶段后端包含两个独立进程：

```text
zbt-serve（主管进程）
  ├── FastAPI API 进程
  │     ├── LangChain Agent Kernel
  │     ├── Agentic RAG / 客户长期记忆 / 多模态识别
  │     └── LangGraph 生命周期工作流
  └── Refund Worker 进程
        ├── Redis 单实例锁与心跳
        ├── 退款任务领取与租约
        ├── 幂等退款适配器
        └── 重试、异常记录与人工干预
```

API 与 Worker 独立运行，是为了隔离 HTTP 请求处理和后台资金任务；`zbt-serve` 负责统一启动、监控和停止两个进程。

## 3. 目录结构

```text
backend/
├── src/zbt/
│   ├── api/                 # FastAPI 路由、鉴权和响应封装
│   ├── commands/            # serve、Worker、初始化和评测命令
│   ├── core/                # 配置、安全、错误和公共能力
│   ├── domains/
│   │   ├── agent/           # Agent 会话、工具与运行记录
│   │   ├── knowledge/       # Agentic RAG 与知识治理
│   │   ├── service_request/ # 保单服务申请
│   │   └── surrender/       # 退保、LangGraph、退款与审计时间线
│   ├── harness/             # Persona、Skill、Policy 和结构化协议
│   ├── infrastructure/      # MySQL、Redis、Milvus、MCP 和模型适配器
│   └── main.py              # FastAPI 应用装配入口
├── migrations/              # S3 Core、Agent、Analytics 三库迁移
├── evals/                   # 真实模型评测数据
├── tests/                   # 自动化测试
├── var/                     # 本地材料和运行文件
├── alembic.ini
├── pyproject.toml
└── uv.lock
```

## 4. 环境配置

后端读取当前 `backend/.env`。除第二阶段的 MySQL、Redis、Milvus、BGE、DeepSeek、百炼和 LangSmith 配置外，第三阶段重点增加：

| 环境变量 | 作用 |
|---|---|
| `REFUND_WORKER_SINGLETON` | 是否启用退款 Worker 单实例运行策略 |
| `REFUND_WORKER_HEARTBEAT_SECONDS` | Worker 心跳上报间隔 |
| `REFUND_WORKER_INSTANCE_TTL_SECONDS` | Worker 实例状态过期时间 |
| `LANGSMITH_OTEL_ENABLED` | 是否启用 OpenTelemetry 链路导出 |

数据库和集合应使用第三阶段命名：

```dotenv
MYSQL_CORE_DATABASE=insurance_s3_core
MYSQL_AGENT_DATABASE=insurance_s3_agent
MYSQL_ANALYTICS_DATABASE=insurance_s3_analytics
REDIS_PREFIX=ins:s3:
MILVUS_COLLECTION_PREFIX=ins_s3_
```

如尚未创建 `.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. 安装依赖

Windows PowerShell：

```powershell
Set-Location backend
uv sync --locked
```

macOS：

```bash
cd backend
uv sync --locked
```

`uv sync --locked` 会根据 `uv.lock` 创建或更新本项目自己的 `.venv`。不需要提前激活其他阶段的虚拟环境。

## 6. 首次初始化数据

第三阶段首次运行所需的数据库快照、Milvus 初始化脚本和启动说明统一保存在：

[项目启动文档与数据准备.zip](../../02-zhibaotong-knowledge-services-analytics/database/项目启动文档与数据准备.zip)

请将压缩包解压到三个阶段项目的共同父目录，并按照其中 `智保通第一、二、三阶段启动指南.md` 的“第三阶段：全生命周期工作流”一节执行。该指南统一说明 Windows PowerShell 与 macOS/Linux 的依赖安装、第三阶段 MySQL 导入、Milvus 初始化和启动方式。

压缩包中的第三阶段 `mysql.sql` 只初始化 `insurance_s3_core`、`insurance_s3_agent` 和 `insurance_s3_analytics`，并已包含前两个阶段继承数据。不要再使用项目内旧 SQL，也不要额外执行 Alembic、`seed`、阶段继承或分析快照构建。

## 7. 启动后端

### 推荐方式：同时启动 API 与 Worker

Windows PowerShell：

```powershell
Set-Location backend
uv run zbt-serve
```

macOS：

```bash
cd backend
uv run zbt-serve
```

启动成功后会看到类似输出：

```text
智保通后端已启动：FastAPI 与退款工作器正在独立运行。
退款工作器已取得单实例锁：...
退款工作器初始化完成，开始轮询任务。
```

访问地址：

- 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>

### 仅启动 API

只进行接口或页面调试、不处理退款任务时可以运行：

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
```

此方式不会启动退款 Worker，管理端会显示 Worker 未在线，待退款任务也不会被自动领取。

### 仅启动 Worker

只有调试后台退款执行时才单独运行：

Windows PowerShell：

```powershell
Set-Location backend
uv run zbt-refund-worker
```

macOS：

```bash
cd backend
uv run zbt-refund-worker
```

不要在 `zbt-serve` 正常运行时再次启动 Worker。默认单实例锁会阻止多个主动 Worker 同时领取任务。

## 8. Worker 单实例与多实例边界

退款属于外部资金副作用。默认单实例策略可以降低本地误启动、重复请求支付渠道和状态竞争的风险，也便于在管理端观察唯一的执行者。

单实例并不代表系统架构只能支持一个 Worker。任务领取仍使用租约和幂等约束；在生产环境完成支付渠道幂等、监控告警和容量评估后，可以关闭单实例运行策略并部署多个 Worker 并行消费。

如果本地同时启动多个 Worker，可能出现：

- 多个实例竞争同一批任务，日志和状态更难排查。
- 支付渠道调用频率增加。
- 配置或幂等实现有缺陷时，重复退款风险被放大。
- 心跳记录和故障接管过程更难解释。

## 9. 真实模型评测

先启动完整后端，再在 `backend` 目录执行。Windows PowerShell 和 macOS 命令相同：

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

评测会调用真实模型、真实业务 Tool 和真实 HTTP 接口，并检查 Agent、RAG、LangGraph 和 Trace 关联。

## 10. 测试和代码检查

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

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

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

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

## 11. 数据库迁移

当前推荐使用完整 SQL 快照进行首次初始化。开发新的表结构变更时，在 `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
```

三个命令在 Windows PowerShell 和 macOS 中相同。已发布的迁移文件不要直接修改，表结构变化应新增 revision。

## 12. 命令行入口

| 命令 | 用途 |
|---|---|
| `uv run zbt-serve` | 统一启动并监管 FastAPI 与退款 Worker |
| `uv run zbt-refund-worker` | 单独启动退款 Worker |
| `uv run zbt-seed-surrenders` | 生成退保流程测试场景 |
| `uv run zbt-seed-surrender-policies` | 生成可用于退保测试的保障中保单 |
| `uv run zbt-settle-pending-refunds` | 处理历史待结算退款数据 |

后三个命令用于专项测试或历史数据处理，不属于每次启动项目的必执行步骤。

## 13. 构建安装包

Windows PowerShell：

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

macOS：

```bash
cd backend
uv build
```

构建结果生成在 `backend/dist`，包括 wheel 和源码包。

## 14. 相关文档

- `../README.md`：第三阶段项目总览和快速启动。
- `../docs/第三阶段新增业务与测试.md`：第三阶段功能与测试场景。
- `../docs/智保通三阶段业务与ProcessOn技术.md`：三个阶段的业务与技术映射。

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