7.7 KiB
7.7 KiB
文档规范
一个人开发不等于不需要文档。文档是给未来的自己看的——三个月后你绝对记不住今天写的代码为什么这样设计。
一、需要维护哪些文档
| 文档 | 位置 | 什么时候写 | 什么时候更新 |
|---|---|---|---|
| 需求文档 | docs/保险智能客服系统_需求文档.md |
开发前写完 | 需求变更时 |
| 接口文档 | docs/保险智能客服系统_API接口文档.md |
写后端接口前 | 接口变更时 |
| 数据库设计 | docs/保险智能客服系统_需求文档.md（第六章） |
写后端前 | 表结构变更时 |
| 部署文档 | docs/部署文档_完整版.md |
第一次部署时 | 部署流程变化时 |
| 变更日志 | CHANGELOG.md |
每次发版 | 每次发版 |
二、需求文档
2.1 格式要求
每个功能模块用以下模板：
## 模块名称：XXX
### 功能概述
一句话说明这个模块做什么、给谁用。
### 用户故事
作为 [角色]，我希望 [操作]，以便 [目的]。
### 功能清单
| 编号 | 功能点 | 优先级 | 状态 |
|------|--------|--------|------|
| F-01 | XXX | P0（必须）/ P1（重要）/ P2（可选） | 待开发/开发中/已完成 |
### 业务规则
1. 规则描述
2. 规则描述
### 界面原型
（如果有的话，贴截图或画草图）
### 异常场景
| 场景 | 系统行为 |
|------|---------|
| XXX 失败 | 提示用户 XXX |
2.2 本项目的需求文档
所有需求集中在 docs/保险智能客服系统_需求文档.md 一个文件中，按模块章节组织：
- 第一章：智能问答（对话交互、回复展示、检索范围、反馈纠错）
- 第二章：产品推荐方案（信息录入、AI匹配、方案展示）
- 第三章：知识库管理（文档上传、状态监控、检索测试）
- 第四章：企微机器人（单聊、群聊 @触发、消息回调）
- 第五章：用户与权限（企微OAuth、角色权限）
- 第六章：数据库设计
- 第七章：系统配置（LLM模型、Prompt管理）
三、接口文档
3.1 格式要求
每个接口用以下模板：
## 接口名称
### 基本信息
- **URL**: `POST /api/xxx/yyy`
- **描述**: 一句话说明
- **认证**: 需要 Token / 不需要
### 请求参数
| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| name | string | 是 | 用户姓名 | "张三" |
| age | int | 是 | 年龄（1-150） | 30 |
### 请求示例
```json
{
"name": "张三",
"age": 30
}
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码，0=成功 |
| message | string | 提示信息 |
| data | object | 业务数据 |
响应示例
{
"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 设计原则
- 能不建表就不建表 — 配置信息用 .env，日志用 BaoDan 自带的
- 字段加注释 — 每个字段都要有"说明"列
- 时间字段用 TIMESTAMP — 统一用
created_at、updated_at - 主键用 SERIAL — 简单够用，不需要 UUID
- 字符串长度明确 — VARCHAR(64)、VARCHAR(128) 等，不用 TEXT
五、部署文档
5.1 格式要求
## 部署步骤
### 环境要求
| 软件 | 版本 | 用途 |
|------|------|------|
| ... | ... | ... |
### 安装步骤
1. 第一步
```bash
命令
- 第二步 ...
配置说明
| 配置项 | 文件 | 说明 | 示例值 |
|---|---|---|---|
| ... | ... | ... | ... |
验证方式
- 检查项 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 登录
七、文档维护原则
- 代码改了文档必须跟着改 — 不然文档就是误导
- 不要写废话 — 每句话都要有信息量
- 用表格 — 结构化信息用表格，比大段文字清晰
- 贴真实示例 — 请求/响应示例用真实数据，不要用 "xxx"
- 先写再改 — 不要追求一次写完美，先把框架填上，后面慢慢改