284 lines
7.7 KiB
Markdown
284 lines
7.7 KiB
Markdown
# 文档规范
|
||
|
||
> 一个人开发不等于不需要文档。文档是给未来的自己看的——三个月后你绝对记不住今天写的代码为什么这样设计。
|
||
|
||
## 一、需要维护哪些文档
|
||
|
||
| 文档 | 位置 | 什么时候写 | 什么时候更新 |
|
||
|------|------|-----------|-------------|
|
||
| 需求文档 | `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. **先写再改** — 不要追求一次写完美，先把框架填上，后面慢慢改
|