harness_zbt/backend

智保通后端

本目录是智保通的统一后端，使用 Python 3.12 和 FastAPI 开发，负责 API、 业务规则、身份认证及数据库访问。

技术栈

• Python 3.12
• FastAPI、Pydantic
• SQLAlchemy、Alembic
• LangChain 1.x、DeepSeek、LangSmith
• MySQL 8、Redis
• uv（依赖与虚拟环境管理）
• pytest、Ruff、mypy（测试与代码检查）

项目使用 pyproject.toml 和 uv.lock 管理依赖，不使用 requirements.txt、Poetry 或 Conda。

目录结构

backend/
├── src/
│   └── zbt/               # 可安装的智保通 Python 包
│       ├── api/           # HTTP 路由、请求参数和响应格式
│       ├── commands/      # 初始化数据等命令行工具
│       ├── core/          # 配置、安全、密码和公共错误
│       ├── domains/       # 业务模型、仓储接口和业务服务
│       ├── harness/       # Agent 内核、策略和资源
│       ├── infrastructure/# MySQL、Redis、Milvus 等基础设施实现
│       └── main.py        # FastAPI 应用入口
├── migrations/            # 三个数据库的 Alembic 迁移
├── tests/                 # 自动化测试
├── alembic.ini
├── pyproject.toml
└── uv.lock

项目采用 src 布局，uv sync 会以可编辑模式安装 zbt 包；执行 uv build 可以生成 wheel 和源码包。

代码主要调用方向：

HTTP 请求 → api 路由 → domain service → repository → MySQL

AI Agent 的主要调用方向：

Agent API → Agent service → LangChain create_agent
          → DeepSeek（OpenAI 兼容接口）→ 产品目录 Tool
          → Agent MySQL 持久化 + LangSmith Trace

环境配置

后端读取当前 backend 目录中的 .env。

首次使用时，在 backend 目录创建并配置 .env：

notepad .env

常用配置包括：

• MYSQL_HOST、MYSQL_PORT：MySQL 地址和端口
• MYSQL_USER、MYSQL_PASSWORD：后端数据库账号
• REDIS_URL：Redis 连接地址
• JWT_ACCESS_SECRET、JWT_REFRESH_SECRET：登录令牌密钥
• DEV_FIXED_OTP：开发环境固定验证码
• DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL：模型配置
• LANGSMITH_API_KEY、LANGSMITH_ENDPOINT、LANGSMITH_PROJECT、 LANGSMITH_TRACING：Agent 链路追踪配置
• MOCK_PAYMENT_CALLBACK_SECRET：本地模拟支付回调的 HMAC 签名密钥

不要把包含真实密码和密钥的 .env 提交到 Git。

安装后端依赖

Set-Location backend
uv sync --locked

uv sync --locked 会按照 uv.lock 创建或更新 .venv，确保每台电脑安装 相同版本的依赖。

初始化数据库

请先启动 MySQL 8 和 Redis，然后在项目根目录执行：

.\scripts\check-env.ps1
.\scripts\init-databases.ps1
.\scripts\migrate.ps1
.\scripts\inherit-stage-one.ps1
.\scripts\seed.ps1
.\scripts\build-analytics.ps1
.\scripts\verify-seed.ps1

这些脚本依次完成环境检查、创建数据库、建表、继承第一阶段持久化数据、 写入第二阶段初始数据、构建分析数据和验证初始化结果。

单独启动后端

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

启动后访问：

• API 文档：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

按 Ctrl + C 停止后端。

测试和代码检查

在 backend 目录执行：

uv run pytest
uv run ruff check .
uv run mypy src/zbt

也可以在项目根目录执行 .\scripts\test.ps1，同时检查前端和后端。

数据库迁移

项目使用三个相互独立的数据库：

• insurance_s2_core
• insurance_s2_agent
• insurance_s2_analytics

需要手动执行迁移时，在 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

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