682 lines
19 KiB
Markdown
682 lines
19 KiB
Markdown
# 编码规范
|
||
|
||
> 一个人的项目更需要规范。没有规范，三个月后你自己都看不懂自己写的代码。
|
||
> 规范的核心目的：**让代码可读、可维护、不纠结**。
|
||
|
||
---
|
||
|
||
## 一、技术栈与语言
|
||
|
||
| 层级 | 语言 | 框架 | 代码放在哪 |
|
||
|------|------|------|-----------|
|
||
| 后端 | Python 3.12 + Flask | BaoDan 原生框架 | `api/insurance/` |
|
||
| 前端 | TypeScript | Vue 3 + Vite | `frontend/src/` |
|
||
| 脚本 | Python 3.12 | 脚本工具 | `scripts/` |
|
||
| 配置 | YAML / JSON | — | 项目根目录 |
|
||
|
||
---
|
||
|
||
## 二、命名规范
|
||
|
||
### 2.1 Python 后端
|
||
|
||
| 类型 | 规则 | 示例 | 反例 |
|
||
|------|------|------|------|
|
||
| 变量 | 小写 + 下划线 | `user_id`, `chat_history` | `userId`, `ChatHistory` |
|
||
| 常量 | 全大写 + 下划线 | `MAX_RETRY_COUNT`, `BAODAN_BASE_URL` | `maxRetry`, `baodanBaseUrl` |
|
||
| 函数 | 小写 + 下划线 | `get_user_info()`, `send_message()` | `GetUserInfo()`, `sendMessage()` |
|
||
| 类 | 大驼峰 | `WecomClient`, `BaoDanService` | `wecom_client`, `baodan_service` |
|
||
| 文件名 | 小写 + 下划线 | `wecom_client.py`, `config.py` | `WecomClient.py`, `Config.py` |
|
||
| 模块/包 | 小写 + 下划线 | `routers/wecom_oauth.py` | `routers/WecomOauth.py` |
|
||
|
||
### 2.2 TypeScript / Vue 前端
|
||
|
||
| 类型 | 规则 | 示例 | 反例 |
|
||
|------|------|------|------|
|
||
| 变量 | 小驼峰 | `userName`, `chatHistory` | `user_name`, `UserName` |
|
||
| 常量 | 全大写 + 下划线 | `MAX_RETRY_COUNT` | `maxRetryCount` |
|
||
| 函数 | 小驼峰 | `getUserInfo()`, `sendMessage()` | `get_user_info()` |
|
||
| 接口/类型 | 大驼峰，I 开头或直接命名 | `UserInfo`, `ApiResponse` | `userInfo`, `i_user_info` |
|
||
| Vue 组件 | 大驼峰 | `RecommendForm.vue`, `ChatPanel.vue` | `recommend-form.vue` |
|
||
| Vue 组件引用 | 大驼峰 | `<RecommendForm />` | `<recommend-form />` |
|
||
| CSS 类名 | 短横线 | `.chat-panel`, `.btn-primary` | `.chatPanel`, `.chat_panel` |
|
||
|
||
### 2.3 数据库
|
||
|
||
| 类型 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| 表名 | 小写 + 下划线，复数 | `wecom_users`, `recommend_logs` |
|
||
| 字段名 | 小写 + 下划线 | `created_at`, `user_id` |
|
||
| 主键 | `id` | `id SERIAL PRIMARY KEY` |
|
||
| 外键 | `{关联表单数}_id` | `user_id`, `document_id` |
|
||
|
||
### 2.4 API 路径
|
||
|
||
| 规则 | 示例 | 反例 |
|
||
|------|------|------|
|
||
| 小写 + 短横线 | `/api/wecom/oauth` | `/api/wecomOAuth` |
|
||
| 名词复数 | `/api/recommend/logs` | `/api/recommend/log` |
|
||
| 版本号可选 | `/api/v1/wecom/callback` | — |
|
||
|
||
---
|
||
|
||
## 三、注释规范
|
||
|
||
### 3.1 什么需要注释
|
||
|
||
**必须注释**：
|
||
- 所有公开函数/方法的 docstring
|
||
- 所有类的 docstring
|
||
- 复杂业务逻辑（不是显而易见的代码）
|
||
- 为什么要这样做的原因（"为什么"比"做了什么"重要）
|
||
|
||
**不需要注释**：
|
||
- 简单的 getter/setter
|
||
- 一看就懂的代码（`user_id = data["user_id"]`）
|
||
- TODO / FIXME（用 issue 追踪，不要堆在代码里）
|
||
|
||
### 3.2 Python 注释格式
|
||
|
||
```python
|
||
class BaoDanClient:
|
||
"""BaoDan API 客户端，负责与 BaoDan 后端通信。"""
|
||
|
||
def chat(self, user_id: str, query: str, conversation_id: str = "") -> dict:
|
||
"""发送对话消息并获取 AI 回复。
|
||
|
||
Args:
|
||
user_id: 企微用户 ID，作为 BaoDan 的用户标识
|
||
query: 用户的问题文本
|
||
conversation_id: 对话 ID，空字符串表示新对话
|
||
|
||
Returns:
|
||
dict: 包含 answer（回答文本）和 conversation_id（对话 ID）
|
||
|
||
Raises:
|
||
BaoDanAPIError: BaoDan 返回非 200 状态码时抛出
|
||
"""
|
||
# 企微要求 5 秒内响应，所以用 blocking 模式
|
||
# 如果 BaoDan 响应超过 5 秒，调用方需要用异步队列处理
|
||
resp = requests.post(...)
|
||
...
|
||
```
|
||
|
||
### 3.3 TypeScript / Vue 注释格式
|
||
|
||
```typescript
|
||
/**
|
||
* 调用 BaoDan Workflow 生成产品推荐方案
|
||
*
|
||
* @param formData - 用户填写的需求信息（年龄、职业、预算等）
|
||
* @returns 推荐方案的 Markdown 文本
|
||
* @throws 当 BaoDan API 调用失败时抛出错误
|
||
*/
|
||
async function generateRecommendation(formData: RecommendFormData): Promise<string> {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 产品推荐表单 — 用户填写需求信息 -->
|
||
<div class="recommend-form">
|
||
...
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
/**
|
||
* RecommendForm 组件
|
||
*
|
||
* 用户填写保险需求信息（年龄、职业、预算等），
|
||
* 提交后调用后端接口生成 AI 推荐方案。
|
||
*/
|
||
|
||
// 表单数据 — 所有字段都有默认值，避免提交时空值
|
||
const formData = ref<RecommendFormData>({
|
||
age: 30,
|
||
gender: 'male',
|
||
occupation: '',
|
||
annualIncome: 0,
|
||
budget: 0,
|
||
insuranceTypes: [],
|
||
})
|
||
</script>
|
||
```
|
||
|
||
### 3.4 中文还是英文
|
||
|
||
| 场景 | 语言 | 原因 |
|
||
|------|------|------|
|
||
| 变量名/函数名 | 英文 | 代码必须英文 |
|
||
| 注释 | 中文 | 你是中文团队，读中文比英文快 |
|
||
| Docstring | 中文 | 同上 |
|
||
| Git commit | 英文 | 国际惯例，工具兼容性好 |
|
||
| 日志 | 中文 | 方便排查问题 |
|
||
| 错误信息 | 中文 | 用户/管理员看得懂 |
|
||
|
||
---
|
||
|
||
## 四、代码格式
|
||
|
||
### 4.1 Python
|
||
|
||
使用自动格式化工具，不要手动对齐：
|
||
|
||
```bash
|
||
# 安装
|
||
pip install ruff
|
||
|
||
# 格式化
|
||
ruff format backend/
|
||
|
||
# 检查代码风格
|
||
ruff check backend/
|
||
```
|
||
|
||
**`pyproject.toml` 配置**（放在 `backend/` 目录下）：
|
||
|
||
```toml
|
||
[tool.ruff]
|
||
line-length = 120 # 行宽 120（比默认 88 宽一些，适合现代屏幕）
|
||
target-version = "py312" # Python 版本
|
||
|
||
[tool.ruff.format]
|
||
quote-style = "double" # 字符串用双引号
|
||
|
||
[tool.ruff.lint]
|
||
select = ["E", "F", "I"] # 基础检查 + import 排序
|
||
```
|
||
|
||
### 4.2 TypeScript / Vue
|
||
|
||
使用 ESLint + Prettier：
|
||
|
||
```bash
|
||
# 安装（在 frontend/ 目录下）
|
||
pnpm add -D eslint @vue/eslint-config-typescript prettier
|
||
|
||
# 格式化
|
||
pnpm prettier --write src/
|
||
|
||
# 检查
|
||
pnpm eslint src/
|
||
```
|
||
|
||
### 4.3 通用规则
|
||
|
||
| 规则 | Python | TypeScript |
|
||
|------|--------|------------|
|
||
| 行宽 | 120 字符 | 120 字符 |
|
||
| 缩进 | 4 空格 | 2 空格 |
|
||
| 引号 | 双引号 `"` | 单引号 `'` |
|
||
| 分号 | 不需要 | 不需要（Prettier 自动处理） |
|
||
| 尾逗号 | 是 | 是 |
|
||
|
||
---
|
||
|
||
## 五、项目结构规范
|
||
|
||
### 5.1 Python 后端
|
||
|
||
```
|
||
backend/
|
||
├── main.py # 入口文件，只做 app 初始化和路由注册
|
||
├── config.py # 配置读取，所有配置从这里获取
|
||
├── routers/ # 路由层：只做参数校验和响应，不写业务逻辑
|
||
│ ├── __init__.py
|
||
│ ├── wecom.py # 企微消息回调
|
||
│ ├── wecom_oauth.py # 企微 OAuth
|
||
│ └── recommend.py # 产品推荐
|
||
├── services/ # 业务层：核心逻辑在这里
|
||
│ ├── __init__.py
|
||
│ ├── baodan_client.py # 封装 BaoDan API 调用
|
||
│ └── wecom_client.py # 封装企微 API 调用
|
||
├── models/ # 数据模型
|
||
│ ├── __init__.py
|
||
│ └── schemas.py # Pydantic 请求/响应模型
|
||
├── utils/ # 工具函数
|
||
│ ├── __init__.py
|
||
│ └── crypto.py # 加解密工具
|
||
└── requirements.txt # 依赖列表（锁定版本号）
|
||
```
|
||
|
||
**分层原则**：
|
||
- `routers/` 只做 HTTP 相关的事（解析请求、校验参数、返回响应）
|
||
- `services/` 做业务逻辑（调 API、处理数据）
|
||
- `models/` 定义数据结构（Pydantic 模型）
|
||
- `utils/` 放通用工具函数
|
||
|
||
### 5.2 Vue 前端
|
||
|
||
```
|
||
frontend/src/
|
||
├── main.ts # 入口
|
||
├── App.vue # 根组件
|
||
├── router/
|
||
│ └── index.ts # 路由定义
|
||
├── pages/ # 页面组件（一个路由对应一个页面）
|
||
│ ├── ChatPage.vue # 对话页面
|
||
│ ├── RecommendPage.vue # 产品推荐页面
|
||
│ └── LoginPage.vue # 登录页面
|
||
├── components/ # 通用组件（可复用的 UI 组件）
|
||
│ ├── RecommendForm.vue
|
||
│ └── RecommendResult.vue
|
||
├── composables/ # 组合函数（复用逻辑）
|
||
│ ├── useApi.ts # API 请求封装
|
||
│ └── useAuth.ts # 登录状态管理
|
||
├── utils/
|
||
│ └── request.ts # HTTP 请求工具（axios 封装）
|
||
└── types/
|
||
└── index.ts # TypeScript 类型定义
|
||
```
|
||
|
||
**组件拆分原则**：
|
||
- 一个 `.vue` 文件不超过 300 行，超过就拆分
|
||
- `pages/` 放页面级组件（有路由）
|
||
- `components/` 放可复用组件（无路由）
|
||
- `composables/` 放可复用逻辑（类似 React hooks）
|
||
|
||
---
|
||
|
||
## 六、错误处理规范
|
||
|
||
### 6.1 Python 后端
|
||
|
||
```python
|
||
# 定义统一的错误响应格式
|
||
class AppError(Exception):
|
||
"""业务异常基类"""
|
||
def __init__(self, code: int, message: str):
|
||
self.code = code
|
||
self.message = message
|
||
|
||
class BaoDanAPIError(AppError):
|
||
"""BaoDan API 调用失败"""
|
||
def __init__(self, detail: str = ""):
|
||
super().__init__(code=2001, message=f"BaoDan API 调用失败: {detail}")
|
||
|
||
class WecomAPIError(AppError):
|
||
"""企微 API 调用失败"""
|
||
def __init__(self, detail: str = ""):
|
||
super().__init__(code=2002, message=f"企微 API 调用失败: {detail}")
|
||
|
||
|
||
# 全局异常处理器
|
||
@app.exception_handler(AppError)
|
||
async def app_error_handler(request, exc: AppError):
|
||
return JSONResponse(
|
||
status_code=200, # 业务异常用 200，靠 code 区分
|
||
content={"code": exc.code, "message": exc.message, "data": None},
|
||
)
|
||
|
||
@app.exception_handler(Exception)
|
||
async def general_error_handler(request, exc: Exception):
|
||
# 记录日志
|
||
logger.error(f"未处理的异常: {exc}", exc_info=True)
|
||
return JSONResponse(
|
||
status_code=500,
|
||
content={"code": 9999, "message": "服务器内部错误", "data": None},
|
||
)
|
||
```
|
||
|
||
### 6.2 Vue 前端
|
||
|
||
```typescript
|
||
// utils/request.ts
|
||
import axios from 'axios'
|
||
|
||
const request = axios.create({
|
||
baseURL: '/api',
|
||
timeout: 60000, // 产品推荐可能要等 30-60 秒
|
||
})
|
||
|
||
// 响应拦截器：统一处理错误
|
||
request.interceptors.response.use(
|
||
(response) => {
|
||
const { code, message, data } = response.data
|
||
if (code !== 0) {
|
||
// 业务错误，用组件库的 message 提示
|
||
ElMessage.error(message)
|
||
return Promise.reject(new Error(message))
|
||
}
|
||
return data
|
||
},
|
||
(error) => {
|
||
// 网络错误
|
||
ElMessage.error('网络异常，请稍后重试')
|
||
return Promise.reject(error)
|
||
},
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 七、日志规范
|
||
|
||
### 7.1 日志级别
|
||
|
||
| 级别 | 什么时候用 | 示例 |
|
||
|------|-----------|------|
|
||
| `DEBUG` | 开发调试信息 | 请求参数、API 响应详情 |
|
||
| `INFO` | 正常业务流程 | 收到企微消息、AI 回复成功 |
|
||
| `WARNING` | 不影响功能但需要注意 | API 响应慢、重试成功 |
|
||
| `ERROR` | 功能失败 | BaoDan 调用失败、企微回复失败 |
|
||
|
||
### 7.2 日志格式
|
||
|
||
```python
|
||
import logging
|
||
|
||
logging.basicConfig(
|
||
level=logging.INFO,
|
||
format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
|
||
datefmt="%Y-%m-%d %H:%M:%S",
|
||
)
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
# 使用
|
||
logger.info("收到企微消息: user=%s, content=%s", user_id, content[:50])
|
||
logger.error("BaoDan API 调用失败: status=%d, body=%s", resp.status_code, resp.text[:200])
|
||
```
|
||
|
||
### 7.3 日志原则
|
||
|
||
1. **记录关键节点**：收到请求、调用外部 API、返回结果
|
||
2. **不要记录敏感信息**：API Key、用户密码、完整的消息内容（记录前 50 字符即可）
|
||
3. **包含上下文**：user_id、request_id 等，方便排查
|
||
4. **日志不是调试工具**：不要到处 `print()`，用 `logger.debug()` 代替
|
||
|
||
---
|
||
|
||
## 八、Git 分支管理
|
||
|
||
### 8.1 分支策略
|
||
|
||
一个人的项目不需要复杂的 Git Flow，用简单的 **主分支 + 功能分支** 即可：
|
||
|
||
```
|
||
main ← 稳定版本，可随时部署
|
||
│
|
||
├── dev ← 日常开发分支，功能合入这里
|
||
│ │
|
||
│ ├── feature/wecom-bot ← 功能分支
|
||
│ ├── feature/recommend ← 功能分支
|
||
│ └── fix/timeout-bug ← 修复分支
|
||
│
|
||
└── hotfix/xxx ← 紧急修复（从 main 拉出）
|
||
```
|
||
|
||
### 8.2 分支命名
|
||
|
||
| 类型 | 命名规则 | 示例 |
|
||
|------|---------|------|
|
||
| 主分支 | `main` | — |
|
||
| 开发分支 | `dev` | — |
|
||
| 功能分支 | `feature/功能名` | `feature/wecom-bot` |
|
||
| 修复分支 | `fix/问题描述` | `fix/message-timeout` |
|
||
| 紧急修复 | `hotfix/问题描述` | `hotfix/crash-on-startup` |
|
||
|
||
### 8.3 Commit Message 规范
|
||
|
||
格式：`类型(范围): 描述`
|
||
|
||
```
|
||
类型：
|
||
feat 新功能
|
||
fix 修复 bug
|
||
docs 文档更新
|
||
style 代码格式调整（不影响功能）
|
||
refactor 重构
|
||
test 测试
|
||
chore 构建/依赖/配置变更
|
||
```
|
||
|
||
示例：
|
||
```
|
||
feat(wecom): 添加企微群聊消息接收功能
|
||
fix(recommend): 修复推荐结果为空时页面报错
|
||
docs(api): 更新产品推荐接口文档
|
||
refactor(baodan): 将 BaoDan 调用抽成独立 service
|
||
chore(deps): 升级 fastapi 到 0.115
|
||
```
|
||
|
||
### 8.4 工作流程
|
||
|
||
```
|
||
1. 从 dev 创建功能分支：git checkout -b feature/xxx dev
|
||
2. 开发 + 提交（一个小功能一个 commit）
|
||
3. 功能完成后合并回 dev：git checkout dev && git merge feature/xxx
|
||
4. 删除功能分支：git branch -d feature/xxx
|
||
5. dev 稳定后合并到 main：git checkout main && git merge dev
|
||
6. 打 tag：git tag v0.1.0
|
||
```
|
||
|
||
### 8.5 Git 忽略文件
|
||
|
||
```gitignore
|
||
# .gitignore（项目根目录）
|
||
|
||
# Python
|
||
__pycache__/
|
||
*.pyc
|
||
.venv/
|
||
*.egg-info/
|
||
|
||
# Node
|
||
node_modules/
|
||
dist/
|
||
|
||
# 环境变量（包含密钥，绝对不能提交）
|
||
.env
|
||
.env.local
|
||
.env.production
|
||
|
||
# IDE
|
||
.vscode/
|
||
.idea/
|
||
*.swp
|
||
|
||
# 系统文件
|
||
.DS_Store
|
||
Thumbs.db
|
||
|
||
# BaoDan 源码（如果作为子模块引入）
|
||
baodan/
|
||
|
||
# 上传的文件
|
||
uploads/
|
||
```
|
||
|
||
---
|
||
|
||
## 九、依赖管理
|
||
|
||
### 9.1 Python 依赖
|
||
|
||
```bash
|
||
# 安装时锁定版本
|
||
pip install fastapi==0.115.0
|
||
pip install uvicorn==0.32.0
|
||
|
||
# 生成 requirements.txt
|
||
pip freeze > requirements.txt
|
||
|
||
# requirements.txt 里必须锁定版本号，不要用 >= 或 ~=
|
||
# 正确：fastapi==0.115.0
|
||
# 错误：fastapi>=0.100
|
||
```
|
||
|
||
### 9.2 Node 依赖
|
||
|
||
```bash
|
||
# 安装时精确版本
|
||
pnpm add axios@1.7.0
|
||
|
||
# 不要混用 npm 和 pnpm，统一用 pnpm
|
||
```
|
||
|
||
### 9.3 核心依赖清单
|
||
|
||
**Python 后端（`backend/requirements.txt`）**：
|
||
```
|
||
fastapi==0.115.0
|
||
uvicorn==0.32.0
|
||
requests==2.32.0
|
||
python-dotenv==1.0.0
|
||
pydantic==2.10.0
|
||
wechatpy==1.8.18
|
||
cryptography==44.0.0
|
||
```
|
||
|
||
**Vue 前端（`frontend/package.json` 核心依赖）**：
|
||
```
|
||
vue: ^3.5.0
|
||
vue-router: ^4.4.0
|
||
axios: ^1.7.0
|
||
marked: ^15.0.0
|
||
element-plus: ^2.9.0
|
||
```
|
||
|
||
---
|
||
|
||
## 十、代码审查清单（自检用）
|
||
|
||
一个人没有 code review 搭档，但提交前自己过一遍这个清单：
|
||
|
||
### Python
|
||
- [ ] 函数有 docstring 吗？
|
||
- [ ] 参数有类型注解吗？
|
||
- [ ] 异常有处理吗？（不要裸 `except:`）
|
||
- [ ] 日志有记录关键节点吗？
|
||
- [ ] API Key / 密码等敏感信息没写死在代码里吧？
|
||
- [ ] `ruff format` 和 `ruff check` 通过了吗？
|
||
|
||
### Vue / TypeScript
|
||
- [ ] 组件不超过 300 行？
|
||
- [ ] 变量有类型定义吗？（不要到处 `any`）
|
||
- [ ] 有 loading / error 状态处理吗？
|
||
- [ ] API 请求超时设置合理吗？
|
||
- [ ] ESLint 和 Prettier 通过了吗？
|
||
|
||
### Git
|
||
- [ ] commit message 符合规范？
|
||
- [ ] `.env` 文件没有提交吧？
|
||
- [ ] 不相关的改动没有混在这个 commit 里吧？
|
||
|
||
---
|
||
|
||
## 十一、BaoDan 集成规范
|
||
|
||
### 11.1 架构说明
|
||
|
||
自研代码放在 `baodan-main/api/insurance/` 目录下，作为 Flask Blueprint 注册到 BaoDan 的 Flask 应用中。**不使用 FastAPI**，直接复用 BaoDan 的 Flask 框架。
|
||
|
||
### 11.2 代码组织
|
||
|
||
```
|
||
baodan-main/api/insurance/
|
||
├── __init__.py
|
||
├── wecom/
|
||
│ ├── 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 # 推荐记录表
|
||
```
|
||
|
||
### 11.3 调用 BaoDan 核心功能（直接 import）
|
||
|
||
```python
|
||
# 调用 BaoDan RAG 检索（直接 import，不走 HTTP）
|
||
from core.rag.retrieval.dataset_retrieval import DatasetRetrieval
|
||
|
||
# 调用 BaoDan LLM
|
||
from core.model_runtime.model_manager import ModelManager
|
||
|
||
# 调用 BaoDan Workflow
|
||
from core.workflow.workflow_engine import WorkflowEngine
|
||
|
||
# 复用 BaoDan 数据库连接
|
||
from extensions.ext_database import db
|
||
from models.dataset import Dataset, Document
|
||
|
||
# 复用 BaoDan 认证
|
||
from extensions.ext_login import login_required
|
||
```
|
||
|
||
### 11.4 禁止事项
|
||
|
||
- **不要在 `api/insurance/` 以外的目录写代码**
|
||
- **不要修改 `api/core/`、`api/controllers/`、`api/models/` 等 BaoDan 目录**
|
||
- **不要自己装 FastAPI**——直接用 BaoDan 的 Flask
|
||
- **不要自己建数据库连接**——用 `extensions.ext_database.db`
|
||
- **不要自己装 Redis 客户端**——用 BaoDan 的 Redis 连接
|
||
- **不要自己写日志系统**——用 BaoDan 的 logging
|
||
|
||
def chat(self, user_id: str, query: str, conversation_id: str = "") -> dict:
|
||
"""发送对话消息。返回 {answer, conversation_id, sources}"""
|
||
resp = requests.post(
|
||
f"{self.base_url}/chat-messages",
|
||
headers={"Authorization": f"Bearer {self.app_key}"},
|
||
json={
|
||
"query": query,
|
||
"response_mode": "blocking",
|
||
"user": user_id,
|
||
"conversation_id": conversation_id,
|
||
},
|
||
timeout=60,
|
||
)
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
return {
|
||
"answer": data.get("answer", ""),
|
||
"conversation_id": data.get("conversation_id", ""),
|
||
"sources": data.get("metadata", {}).get("retriever_resources", []),
|
||
}
|
||
|
||
def run_workflow(self, inputs: dict, user_id: str) -> dict:
|
||
"""执行 Workflow。返回 {status, outputs}"""
|
||
resp = requests.post(
|
||
f"{self.base_url}/workflows/run",
|
||
headers={"Authorization": f"Bearer {self.workflow_key}"},
|
||
json={"inputs": inputs, "response_mode": "blocking", "user": user_id},
|
||
timeout=120,
|
||
)
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
return {
|
||
"status": data.get("data", {}).get("status", "unknown"),
|
||
"outputs": data.get("data", {}).get("outputs", {}),
|
||
}
|
||
```
|
||
|
||
### 11.2 调用规则
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 统一入口 | 所有 BaoDan 调用走 `BaoDanClient`，不直接 `requests.post` |
|
||
| 超时设置 | Chat API 60 秒，Workflow API 120 秒 |
|
||
| 错误处理 | 捕获异常后抛出 `BaoDanAPIError`，不要吞掉异常 |
|
||
| 日志记录 | 每次调用记录 request_id、user_id、耗时 |
|
||
| 重试策略 | BaoDan 5xx 错误重试 1 次，4xx 不重试 |
|
||
| 用户标识 | 企微用户用 `wecom_{userid}`，网页用户用 `web_{baodan_user_id}` |
|
||
|
||
### 11.3 禁止事项
|
||
|
||
- 禁止在前端直接调用 BaoDan API（API Key 会暴露）
|
||
- 禁止在多个文件中重复写 BaoDan 调用逻辑
|
||
- 禁止不设超时调用 BaoDan（可能导致请求永久挂起）
|
||
- 禁止将 BaoDan 返回的原始 JSON 直接传给前端（需先清洗字段）
|