# 智保通后端

本目录是智保通的统一后端，使用 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。

## 目录结构

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

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

代码主要调用方向：

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

AI Agent 的主要调用方向：

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

## 环境配置

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

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

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

## 安装后端依赖

```powershell
Set-Location C:\Users\yxl\Desktop\new_harness\01-zhibaotong-smart-enrollment\backend
uv sync --locked
```

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

## 初始化数据库

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

```powershell
.\scripts\check-env.ps1
.\scripts\init-databases.ps1
.\scripts\migrate.ps1
.\scripts\seed.ps1
.\scripts\build-analytics.ps1
.\scripts\verify-seed.ps1
```

这些脚本依次完成环境检查、创建数据库、建表、写入初始数据、构建分析数据
和验证初始化结果。

## 单独启动后端

```powershell
Set-Location C:\Users\yxl\Desktop\new_harness\01-zhibaotong-smart-enrollment\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` 目录执行：

```powershell
uv run pytest
uv run ruff check .
uv run mypy app
```

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

## 数据库迁移

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

- `insurance_s1_core`
- `insurance_s1_agent`
- `insurance_s1_analytics`

需要手动执行迁移时，在 `backend` 目录运行：

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