baodan/CLAUDE.md

# 保险智能客服系统

## 项目概述

基于 BaoDan 源码的保险行业智能客服系统。**直接在 BaoDan 源码上开发**，自研代码放在 `api/insurance/` 目录下，与 BaoDan 代码物理隔离，只改 BaoDan 的 `main.py` 注册路由。

## 架构

```
用户浏览器 / 企微 H5
    │
    ▼
┌─ BaoDan 服务（你的代码 + BaoDan 代码，同一进程）────────┐
│  BaoDan WebApp（对话界面）                               │
│  BaoDan 管理后台（知识库/Prompt/模型/日志）               │
│  你的 Extensions：                                     │
│    · api/insurance/wecom/     企微机器人 + OAuth       │
│    · api/insurance/recommend/ 产品推荐                 │
│    · api/insurance/permissions/角色权限                 │
│    └── api/insurance/stats/   数据统计                  │
└────────────────────────────────────────────────────────┘
         │
         └── 你的前端（Vue 3，独立项目）
```

## 核心原则

1. **在 BaoDan 源码上开发**，自研代码放 `api/insurance/`，与 BaoDan 代码隔离
2. **只改 BaoDan 的 `main.py`**（注册路由）和 `web/.env.local`（开启 iframe），其余 BaoDan 文件不动
3. **复用 BaoDan 基础设施**：认证、数据库、Redis、日志全部用 BaoDan 现有的，不重复造轮子
4. **BaoDan 升级安全**：你的代码在独立目录，升级时只合并 `main.py` 那几行改动
5. **前端独立**：Vue 3 项目，对话页面 iframe 嵌入 BaoDan WebApp

## 目录结构

```
baodan-main/
├── api/
│   ├── core/                    # BaoDan 核心（不动）
│   ├── controllers/              # BaoDan API 路由（不动）
│   ├── models/                   # BaoDan 数据模型（不动）
│   ├── services/                 # BaoDan 业务逻辑（不动）
│   ├── extensions/               # BaoDan 扩展（不动）
│   │
│   ├── insurance/                # ★ 你的代码（新建目录）
│   │   ├── __init__.py
│   │   ├── wecom/                #   企微机器人 + OAuth
│   │   │   ├── wecom_bot.py      #     消息回调处理
│   │   │   ├── wecom_oauth.py    #     OAuth 登录
│   │   │   └── routes.py         #     Blueprint 路由
│   │   ├── recommend/            #   产品推荐
│   │   │   ├── recommend_api.py  #     推荐接口
│   │   │   └── workflow_helper.py#     Workflow 调用封装
│   │   ├── permissions/          #   角色权限
│   │   │   ├── models.py         #     角色/权限模型
│   │   │   ├── middleware.py     #     权限校验
│   │   │   └── routes.py         #     角色管理接口
│   │   ├── stats/                #   数据统计
│   │   │   └── stats_api.py      #     统计接口
│   │   └── db/                   #   自研数据表
│   │       ├── wecom_user.py     #     企微用户映射
│   │       └── recommend_record.py#    推荐记录
│   │
│   └── main.py                   # ★ BaoDan 入口（只改这里：注册 insurance 路由）
│
├── web/
│   └── .env.local                # ★ BaoDan 前端配置（只改这里：开启 iframe）
│
├── docker/                       # Docker 部署配置
└── dev/                          # 开发脚本

frontend/                         # 你的前端（独立 Vue 3 项目）
├── src/
│   ├── pages/                    # 登录/对话/推荐/管理页面
│   ├── components/               # 通用组件
│   ├── composables/              # 组合函数
│   └── utils/                    # 工具函数
├── package.json
└── vite.config.ts

deploy/
├── sql/init.sql                  # 自研表建表脚本
└── nginx.conf                    # Nginx 反向代理

docs/                              # 所有项目文档
├── README.md                     # 文档索引（入口）
├── 保险智能客服系统_需求文档.md
├── 保险智能客服系统_API接口文档.md
├── 保险智能客服系统_编码规范.md
├── 保险智能客服系统_测试用例.md
├── 保险智能客服系统_文档规范.md
├── 前端开发计划.md
├── 开发计划.md
├── 开发任务清单.md
├── API_curl示例.md
└── 部署指南.md
```

## 修改 BaoDan 源码清单

| 文件 | 改动 | 改动量 |
|------|------|:---:|
| `api/main.py` | 注册 insurance Blueprint | ~5 行 |
| `web/.env.local` | 开启 iframe 嵌入 | 1 行 |
| **合计** | **只改 2 个 BaoDan 文件** | **~6 行** |

## 开发规范

详见 `docs/保险智能客服系统_编码规范.md`，关键点：

- 自研代码全部放在 `api/insurance/` 下，不往 BaoDan 其他目录写代码
- 后端文件名/变量名：snake_case
- 前端组件名/变量名：camelCase / PascalCase
- 复用 BaoDan 的数据库连接、Redis、日志系统
- 统一响应格式：`{"code": 0, "message": "success", "data": {...}}`
- 注释用中文，commit message 用英文

## 运行方式

```bash
# 1. 启动 BaoDan（源码模式）
cd baodan-main
./dev/setup                        # 安装依赖
./dev/start-api                    # 后端（含你的 insurance 模块）
./dev/start-worker                 # Celery Worker
./dev/start-web                    # 前端

# 2. 启动你的 Vue 前端
cd frontend
pnpm install && pnpm dev

# 3. 验证
curl http://localhost:5001/api/health
curl http://localhost:5001/api/wecom/callback  # 企微回调
```

## 开发文档

所有文档已整理到 `docs/` 目录，完整索引见 [docs/README.md](docs/README.md)：

- `docs/保险智能客服系统_需求文档.md` — 完整需求
- `docs/保险智能客服系统_API接口文档.md` — 45 个 API 接口
- `docs/保险智能客服系统_编码规范.md` — 编码标准
- `docs/保险智能客服系统_测试用例.md` — 测试用例
- `docs/前端开发计划.md` — 前端开发详细计划
- `docs/开发计划.md` — 8 阶段开发计划
- `docs/开发任务清单.md` — 185 项可勾选任务
- `docs/API_curl示例.md` — 接口调试 curl 示例
- `docs/部署指南.md` — BaoDan 源码集成指南
- `docs/保险智能客服系统_文档规范.md` — 文档编写标准

## BaoDan 对接要点

- 复用 BaoDan 的数据库连接（SQLAlchemy），自研表直接用 BaoDan 的 DB
- 复用 BaoDan 的认证系统，在上面叠加你的角色权限
- 调 BaoDan 的 RAG 引擎：**直接 import Python 函数**，不走 HTTP
- 调 BaoDan 的 Workflow：通过 Python API 调用，不走 HTTP
- 按险种筛选：创建多个 BaoDan 应用，你的路由代码按用户选择分发

## BaoDan 升级流程

```bash
cd baodan-main
git stash                          # 暂存你的 insurance/ 目录改动
git pull origin main               # 拉取 BaoDan 新版本
git stash pop                      # 恢复你的改动
# 如果 main.py 有冲突 → 手动合并（只合并注册路由的 5 行）
# 如果 .env.local 有冲突 → 重新加那一行
# insurance/ 目录永远不会冲突（新增的目录）
```

## 注意事项

- `.env` 文件不要提交到 Git
- BaoDan 的 `NEXT_PUBLIC_ALLOW_EMBED` 必须开启才能 iframe 嵌入
- 企微回调必须在 5 秒内返回 `success`，异步处理消息
- BaoDan WebApp 和你的前端必须**同源部署**
- 自研表的数据库迁移用 Alembic，放在 `api/insurance/db/` 下