harness_zbt/backend

智保通第三阶段后端

本目录是智保通第三阶段“生命周期工作流”的统一后端。项目在第二阶段 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. 运行架构

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

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

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

3. 目录结构

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 链路导出

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

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：

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

macOS：

cd backend
touch .env
open -e .env

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

5. 安装依赖

Windows PowerShell：

Set-Location backend
uv sync --locked

macOS：

cd backend
uv sync --locked

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

6. 首次初始化数据

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

database/mysql.sql 只初始化 insurance_s3_core、insurance_s3_agent 和 insurance_s3_analytics，并已包含前两个阶段继承数据。不要额外执行 Alembic、seed、阶段继承或分析快照构建。

7. 启动后端

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

Windows PowerShell：

Set-Location backend
uv run zbt-serve

macOS：

cd backend
uv run zbt-serve

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

智保通后端已启动：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：

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

macOS：

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

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

仅启动 Worker

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

Windows PowerShell：

Set-Location backend
uv run zbt-refund-worker

macOS：

cd backend
uv run zbt-refund-worker

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

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

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

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

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

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

9. 真实模型评测

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

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 -ExecutionPolicy Bypass -File .\scripts\test.ps1

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

./scripts/test.sh

11. 数据库迁移

当前推荐使用完整 SQL 快照进行首次初始化。开发新的表结构变更时，在 backend 目录执行：

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：

Set-Location backend
uv build

macOS：

cd backend
uv build

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

14. 相关文档

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

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