# 智保通（第一阶段：智能投保）

智保通第一阶段由本地 H5 公众号模拟器、运营管理后台和统一 FastAPI 后端组成。系统已贯通客户咨询、方案推荐、确定性报价、投保确认、订单、模拟支付回调、任务调度、保单签发、推广归因和运营查询。

## 项目结构

```text
./
├── backend/          # FastAPI、Agent Harness、业务领域与数据访问
├── frontend/
│   └── apps/
│       ├── h5/       # 本地 H5 公众号模拟器
│       └── admin/    # 运营管理后台
├── scripts/          # 环境、迁移、种子、启动和质量门禁
├── docs/             # 技术边界、测试用例和验证报告
└── README.md
```

## 核心技术

- Agent Harness：一个统一内核，客户顾问与运营助手两种人格。
- Agent 运行时：LangChain `create_agent`、DeepSeek、文件化 Prompt/Skill、Tool Registry、Policy Engine、结构化 UI Block/Action。
- 可观测性：统一 SSE 运行事件、本地 Run 持久化、Redis 热状态与限流、LangSmith 精确 Trace 深链。
- 业务后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、Alembic。
- 数据：本地 MySQL 8、Redis；RabbitMQ 通过 `TaskDispatcher` 抽象保留替换边界。
- 前端：Vue 3、TypeScript、Vite、pnpm workspace。
- 依赖与质量：uv、pytest、Ruff、mypy、vue-tsc。

第一阶段不引入 Milvus/RAG、多模态、显式 LangGraph、退保退款和人工审批。这些属于后续阶段，现有内核和协议可以直接继承。

## 首次初始化

先启动本地 MySQL 8 和 Redis，并准备 Python 3.12、uv、Node.js 22、pnpm。

如果希望使用 Docker 启动 MySQL 和 Redis，请先阅读 [Docker 基础环境使用说明](database/Docker基础环境使用说明.md)，并使用其中的 `database/compose.yaml`。

项目只读取 `backend/.env`。确认其中的 MySQL、Redis、DeepSeek、LangSmith 和本地安全密钥后，在项目根目录运行：

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

Set-Location backend
uv run python -m zbt.commands.seed_business_data
Set-Location ..

.\scripts\build-analytics.ps1
.\scripts\verify-seed.ps1

Set-Location frontend
pnpm install --frozen-lockfile
Set-Location ..
```

macOS / Linux：

```bash
./scripts/check-env.sh
./scripts/init-databases.sh
./scripts/migrate.sh
./scripts/seed.sh

cd backend
uv run python -m zbt.commands.seed_business_data
cd ..

./scripts/build-analytics.sh
./scripts/verify-seed.sh

cd frontend
pnpm install --frozen-lockfile
cd ..
```

基础种子包含管理员、角色、产品、业务员和推广码；业务种子生成多状态、多时间、多人员归因的订单、支付和保单数据。

## 启动

在项目根目录运行：

```powershell
.\scripts\dev.ps1
```

macOS / Linux：

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

- H5：http://127.0.0.1:5173
- 管理后台：http://127.0.0.1:5174
- API 文档：http://127.0.0.1:8000/docs

本地 H5 验证码为 `147258`；初始后台账号为 `admin`，密码为 `zaq1XSW@`。

## LangSmith

在 `backend/.env` 中配置：

```dotenv
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=你的密钥
LANGSMITH_PROJECT=智保通-第一阶段-智能投保
```

启动项目后，在 H5 Agent 回复或后台“运营智能体 → 智能体运行中心”中点击“打开 LangSmith”，即可进入该次调用的精确 Trace，而不是只打开 LangSmith 首页。Trace 未完成同步时，刷新运行中心即可重新解析深链。

## 真实模型评测

先启动整个项目，再在 `backend` 目录执行：

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

macOS / Linux：

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

两套评测均调用真实 DeepSeek、真实业务工具和真实 HTTP 接口，并检查回答、工具覆盖和 Trace 关联；配置 LangSmith 密钥后，基准样本与自动评分会同步到 LangSmith。

## 质量门禁

```powershell
.\scripts\test.ps1
```

macOS / Linux：

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

该脚本执行后端测试、Ruff、mypy、前端类型检查与双端生产构建。真实 MySQL/Redis 集成测试以及真实模型评测单独执行，避免普通代码检查意外消耗模型额度。

所有 `scripts/*.ps1` 均提供同名的 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。数据库迁移脚本可安全处理字段已存在但 Alembic 版本记录尚未更新的中断状态。