baodan/docs/保险智能客服系统_文档规范.md

# 文档规范

> 一个人开发不等于不需要文档。文档是给未来的自己看的——三个月后你绝对记不住今天写的代码为什么这样设计。

## 一、需要维护哪些文档

| 文档 | 位置 | 什么时候写 | 什么时候更新 |
|------|------|-----------|-------------|
| 需求文档 | `docs/保险智能客服系统_需求文档.md` | 开发前写完 | 需求变更时 |
| 接口文档 | `docs/保险智能客服系统_API接口文档.md` | 写后端接口前 | 接口变更时 |
| 数据库设计 | `docs/保险智能客服系统_需求文档.md`（第六章） | 写后端前 | 表结构变更时 |
| 部署文档 | `docs/部署文档_完整版.md` | 第一次部署时 | 部署流程变化时 |
| 变更日志 | `CHANGELOG.md` | 每次发版 | 每次发版 |

---

## 二、需求文档

### 2.1 格式要求

每个功能模块用以下模板：

```markdown
## 模块名称：XXX

### 功能概述
一句话说明这个模块做什么、给谁用。

### 用户故事
作为 [角色]，我希望 [操作]，以便 [目的]。

### 功能清单
| 编号 | 功能点 | 优先级 | 状态 |
|------|--------|--------|------|
| F-01 | XXX | P0（必须）/ P1（重要）/ P2（可选） | 待开发/开发中/已完成 |

### 业务规则
1. 规则描述
2. 规则描述

### 界面原型
（如果有的话，贴截图或画草图）

### 异常场景
| 场景 | 系统行为 |
|------|---------|
| XXX 失败 | 提示用户 XXX |
```

### 2.2 本项目的需求文档

所有需求集中在 `docs/保险智能客服系统_需求文档.md` 一个文件中，按模块章节组织：

- 第一章：智能问答（对话交互、回复展示、检索范围、反馈纠错）
- 第二章：产品推荐方案（信息录入、AI匹配、方案展示）
- 第三章：知识库管理（文档上传、状态监控、检索测试）
- 第四章：企微机器人（单聊、群聊 @触发、消息回调）
- 第五章：用户与权限（企微OAuth、角色权限）
- 第六章：数据库设计
- 第七章：系统配置（LLM模型、Prompt管理）

---

## 三、接口文档

### 3.1 格式要求

每个接口用以下模板：

```markdown
## 接口名称

### 基本信息
- **URL**: `POST /api/xxx/yyy`
- **描述**: 一句话说明
- **认证**: 需要 Token / 不需要

### 请求参数
| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| name | string | 是 | 用户姓名 | "张三" |
| age | int | 是 | 年龄（1-150） | 30 |

### 请求示例
```json
{
  "name": "张三",
  "age": 30
}
```

### 响应参数
| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码，0=成功 |
| message | string | 提示信息 |
| data | object | 业务数据 |

### 响应示例
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

### 错误码
| code | 说明 |
|------|------|
| 0 | 成功 |
| 1001 | 参数错误 |
| 1002 | 未授权 |
| 2001 | BaoDan 调用失败 |
| 2002 | 企微 API 调用失败 |

### 注意事项
- 特殊说明
```

### 3.2 本项目的接口列表

你的后端（Flask）只写这几个接口，不多不少：

| 编号 | 接口 | 说明 |
|------|------|------|
| API-01 | `POST /api/wecom/callback` | 企微消息回调（GET 验证 + POST 接收） |
| API-02 | `GET /api/wecom/oauth` | 企微 OAuth 登录入口 |
| API-03 | `GET /api/wecom/oauth/callback` | 企微 OAuth 回调 |
| API-04 | `POST /api/recommend/generate` | 产品推荐（调 BaoDan Workflow） |
| API-05 | `GET /health` | 健康检查 |

其余所有接口（对话、知识库管理、用户管理等）全部走 **BaoDan 自己的 API**，你不需要重复写。

### 3.3 BaoDan API 参考

BaoDan 的 API 文档在你部署后的地址：
- `http://你的服务器:5001/console/api` （管理端 API）
- BaoDan 官方文档：https://docs.baodan.ai/guides/application-publishing/developing-with-apis

你用到的 BaoDan API 主要有：

| API | 用途 | 你在哪用 |
|-----|------|---------|
| `POST /chat-messages` | 发送对话消息 | 企微机器人后端 |
| `POST /workflows/run` | 执行工作流 | 产品推荐后端 |
| `GET /datasets` | 知识库列表 | 不需要调，直接用 BaoDan 后台 |
| `POST /datasets/{id}/documents` | 上传文档 | 批量导入脚本 |

---

## 四、数据库设计

### 4.1 说明

你的项目大部分数据存在 BaoDan 的数据库里（PostgreSQL），你自己只需要建**少量额外的表**：

| 表 | 用途 | 你是否需要建 |
|---|---|---|
| 用户表、对话表、知识库表等 | BaoDan 核心数据 | ❌ BaoDan 自己管理 |
| 企微用户映射表 | 企微 userid ↔ BaoDan user 映射 | ✅ 你建 |
| 推荐方案记录表 | 产品推荐的历史记录 | ✅ 你建（第二期） |
| 系统配置表 | 你的后端配置 | ❌ 用 .env 文件够了 |

### 4.2 表结构定义格式

```markdown
## 表名：wecom_user_mapping（企微用户映射表）

### 用途
存储企微用户 ID 与 BaoDan 用户 ID 的对应关系，避免重复创建 BaoDan 用户。

### 字段
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | SERIAL | PRIMARY KEY | 自增主键 |
| wecom_userid | VARCHAR(64) | NOT NULL, UNIQUE | 企微用户 ID |
| baodan_user_id | VARCHAR(64) | NOT NULL | BaoDan 内部用户 ID |
| username | VARCHAR(128) | | 用户姓名 |
| department | VARCHAR(128) | | 所属部门 |
| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |
| last_active_at | TIMESTAMP | | 最后活跃时间 |

### 索引
- UNIQUE INDEX ON wecom_userid
- INDEX ON baodan_user_id
```

### 4.3 设计原则

1. **能不建表就不建表** — 配置信息用 .env，日志用 BaoDan 自带的
2. **字段加注释** — 每个字段都要有"说明"列
3. **时间字段用 TIMESTAMP** — 统一用 `created_at`、`updated_at`
4. **主键用 SERIAL** — 简单够用，不需要 UUID
5. **字符串长度明确** — VARCHAR(64)、VARCHAR(128) 等，不用 TEXT

---

## 五、部署文档

### 5.1 格式要求

```markdown
## 部署步骤

### 环境要求
| 软件 | 版本 | 用途 |
|------|------|------|
| ... | ... | ... |

### 安装步骤
1. 第一步
   ```bash
   命令
   ```
2. 第二步
   ...

### 配置说明
| 配置项 | 文件 | 说明 | 示例值 |
|--------|------|------|--------|
| ... | ... | ... | ... |

### 验证方式
- [ ] 检查项 1
- [ ] 检查项 2

### 常见问题
**Q: 出现 XXX 错误怎么办？**
A: 原因是 XXX，解决方法是 XXX。
```

### 5.2 需要写哪些部署文档

```
docs/
├── 快速启动指南.md              # 本地开发一键启动
├── 部署指南.md                 # BaoDan 源码集成指南
├── 部署文档_完整版.md           # 完整部署 + 架构图 + 环境变量
├── 宝塔面板部署指南.md          # 宝塔面板 Docker 部署
├── 企业微信接入指南.md          # 企微后台配置步骤
└── 前端移动端适配指南.md        # 移动端适配方案
```

---

## 六、变更日志（CHANGELOG.md）

每次发版时记录：

```markdown
# 变更日志

## [0.2.0] - 2026-06-20

### 新增
- 产品推荐方案功能
- 企微群聊 @机器人 支持

### 修复
- 企微消息回调超时问题

### 变更
- Prompt 优化，回答更简洁

## [0.1.0] - 2026-06-01

### 新增
- BaoDan 部署 + 知识库入库
- 智能问答基础功能
- 企微单聊机器人
- 企微 OAuth 登录
```

---

## 七、文档维护原则

1. **代码改了文档必须跟着改** — 不然文档就是误导
2. **不要写废话** — 每句话都要有信息量
3. **用表格** — 结构化信息用表格，比大段文字清晰
4. **贴真实示例** — 请求/响应示例用真实数据，不要用 "xxx"
5. **先写再改** — 不要追求一次写完美，先把框架填上，后面慢慢改