306 lines
9.0 KiB
Markdown
306 lines
9.0 KiB
Markdown
# AI 服务积分扣减公共服务设计文档
|
||
|
||
> 版本: v1.2
|
||
> 日期: 2025-02-20
|
||
> 状态: 待确认
|
||
> 用途: 业务规范文档，供后续开发参考
|
||
|
||
---
|
||
|
||
# 模块一：公共积分扣减服务
|
||
|
||
## 1.1 服务定位
|
||
|
||
**积分扣减公共服务** - 位于 `tik` 模块下，供所有 AI 服务复用的基础设施。
|
||
|
||
**职责：**
|
||
- 积分配置查询
|
||
- 积分预检与扣减
|
||
- 预扣记录管理
|
||
- 积分流水记录
|
||
|
||
## 1.2 核心能力
|
||
|
||
| 能力 | 说明 | 使用场景 |
|
||
|------|------|---------|
|
||
| 获取积分配置 | 根据平台+类型获取消耗积分 | 所有业务调用前 |
|
||
| 预检积分 | 检查余额是否充足，不足抛异常 | 调用前验证 |
|
||
| 即时扣减 | 直接扣减并记录流水 | 同步调用成功后 |
|
||
| 创建预扣 | 创建待确认的扣减记录 | 流式/异步任务开始时 |
|
||
| 确认扣减 | 确认预扣，实际扣减积分 | 流式结束/任务成功时 |
|
||
| 取消预扣 | 删除预扣记录，不扣费 | 流式出错/任务失败时 |
|
||
|
||
## 1.3 数据模型
|
||
|
||
### 用户积分（muye_member_user_profile）
|
||
- `remaining_points` - 剩余积分（扣减来源）
|
||
- `used_points` - 已用积分
|
||
|
||
### 积分记录（muye_point_record）
|
||
- `point_amount` - 变动数量（负数为扣减）
|
||
- `biz_type` - 业务类型（dify_chat/voice_tts 等）
|
||
- `biz_id` - 业务关联ID
|
||
- `status` - 状态：`pending`(预扣) / `confirmed`(已确认) / `canceled`(已取消)
|
||
|
||
### 积分配置（muye_ai_model_config）
|
||
- `platform` - 平台：dify / tikhub / voice / digital_human
|
||
- `model_type` - 类型：high/low / tts/clone / latentsync/kling
|
||
- `consume_points` - 消耗积分
|
||
- `api_key` - API 密钥（Dify 工作流密钥等）★
|
||
- `api_url` - API 地址（可选，覆盖默认配置）
|
||
|
||
## 1.4 业务规则
|
||
|
||
### 积分扣减规则
|
||
- **原子性**：使用 SQL 条件更新，确保不会超扣
|
||
- **乐观锁**：`WHERE remaining_points >= points`
|
||
- **幂等性**：同一预扣记录只能确认/取消一次
|
||
|
||
### 预扣过期规则
|
||
- 预扣记录超过 30 分钟自动清理
|
||
- 定时任务每 5 分钟执行一次清理
|
||
|
||
### 异常处理
|
||
- 积分不足：抛出 `POINTS_INSUFFICIENT` 异常
|
||
- 配置不存在：抛出 `POINTS_CONFIG_NOT_FOUND` 异常
|
||
- 扣减失败：抛出 `POINTS_DEDUCT_FAILED` 异常
|
||
|
||
## 1.5 依赖关系
|
||
|
||
```
|
||
业务服务（Dify/TikHub/Voice/DigitalHuman）
|
||
↓
|
||
PointsService（公共服务）
|
||
↓
|
||
├── AiModelConfigService → 获取积分配置
|
||
├── MemberUserProfileMapper → 扣减积分
|
||
└── PointRecordMapper → 记录流水
|
||
```
|
||
|
||
---
|
||
|
||
# 模块二：Dify 工作流集成
|
||
|
||
## 2.1 业务概述
|
||
|
||
**Dify 工作流** - AI 对话服务，支持智能体配置和流式响应。
|
||
|
||
**设计原则：**
|
||
- 所有智能体共用一个"文案生成"工作流（同一个 api_key）
|
||
- 智能体之间只通过 `systemPrompt` 区分
|
||
- 前端只需传 `agentId`
|
||
|
||
**核心流程：**
|
||
1. 前端传入 `agentId` + `content`
|
||
2. 后端通过 `agentId` 获取智能体的 `systemPrompt`
|
||
3. 调用 Dify API（固定工作流），传入 `sysPrompt` 参数
|
||
4. 流式返回内容
|
||
5. 流结束或用户停止时扣费
|
||
|
||
## 2.2 扣费流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Dify 流式扣费流程 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 1. 获取智能体配置（systemPrompt） │
|
||
│ 2. 获取积分配置（platform=dify） │
|
||
│ 3. 预检积分 → 积分不足则拒绝 │
|
||
│ 4. 创建预扣记录 │
|
||
│ 5. 调用 Dify 流式 API（传入 sysPrompt） │
|
||
│ ├─ 流正常结束 → 确认扣费（全额） │
|
||
│ ├─ 用户取消 → 确认扣费（按实际消耗或最低消费） │
|
||
│ └─ 出错 → 取消预扣（不扣费） │
|
||
│ 6. 记录使用记录 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 2.3 接口定义
|
||
|
||
### 阻塞模式
|
||
- **URL**: `POST /api/tik/dify/chat`
|
||
- **入参**: agentId, content, conversationId
|
||
- **出参**: content, conversationId, consumePoints
|
||
|
||
### 流式模式
|
||
- **URL**: `POST /api/tik/dify/chat/stream`
|
||
- **入参**: agentId, content, conversationId
|
||
- **出参**: SSE 流（event: message / done）
|
||
|
||
**说明：**
|
||
- `agentId` 用于获取智能体的 `systemPrompt`
|
||
- 所有智能体共用同一个 Dify 工作流
|
||
|
||
## 2.4 配置方案
|
||
|
||
**Dify 配置存储在 `muye_ai_model_config` 表：**
|
||
|
||
| 字段 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| model_name | Dify 文案生成 | 配置名称 |
|
||
| platform | dify | 平台标识 |
|
||
| model_type | writing | 类型 |
|
||
| consume_points | 10 | 消耗积分 |
|
||
| api_key | app-xxx | Dify 工作流密钥 ★ |
|
||
| status | 1 | 启用 |
|
||
|
||
**配置文件只存公共配置：**
|
||
|
||
```yaml
|
||
yudao:
|
||
dify:
|
||
api-url: http://8.155.172.147:8088
|
||
timeout: 60
|
||
```
|
||
|
||
## 2.5 智能体表（无需修改）
|
||
|
||
现有 `muye_ai_agent` 表已有字段：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| agent_id | 智能体ID |
|
||
| agent_name | 智能体名称 |
|
||
| system_prompt | 系统提示词（传递给 Dify 的 sysPrompt 参数） |
|
||
| status | 状态 |
|
||
|
||
**调用流程：**
|
||
1. 通过 `agentId` 获取智能体的 `systemPrompt`
|
||
2. 从 `muye_ai_model_config` 获取 `api_key` + `consume_points`（platform=dify）
|
||
3. 调用 Dify API，传入 `sysPrompt` 参数
|
||
|
||
---
|
||
|
||
# 模块三：各业务积分扣减集成
|
||
|
||
## 3.1 扣费模式总览
|
||
|
||
| 业务 | 扣费模式 | 扣费时机 | 失败处理 |
|
||
|------|---------|---------|---------|
|
||
| Dify 工作流 | 流式结束扣费 | 流结束/用户停止时 | 不扣费 |
|
||
| TikHub | 成功后扣费 | API 调用成功后 | 不扣费 |
|
||
| 语音合成 | 成功后扣费 | TTS 生成成功后 | 不扣费 |
|
||
| 数字人合成 | 任务完成扣费 | 任务成功完成时 | 不扣费 |
|
||
|
||
**统一原则：失败不扣费**
|
||
|
||
## 3.2 TikHub 集成
|
||
|
||
### 业务场景
|
||
- 抖音/小红书数据抓取
|
||
- 用户信息、视频、帖子等
|
||
|
||
### 扣费流程
|
||
```
|
||
1. 获取积分配置（platform=tikhub, modelType=fetch）
|
||
2. 预检积分
|
||
3. 调用 TikHub API
|
||
4. 成功 → 扣减积分
|
||
5. 失败 → 不扣费
|
||
```
|
||
|
||
### 积分配置
|
||
| platform | model_type | consume_points |
|
||
|----------|------------|----------------|
|
||
| tikhub | fetch | 5 |
|
||
|
||
## 3.3 语音合成集成
|
||
|
||
### 业务场景
|
||
- TTS 语音生成
|
||
- 音色克隆
|
||
|
||
### 扣费流程
|
||
```
|
||
1. 获取积分配置（platform=voice, modelType=tts/clone）
|
||
2. 预检积分
|
||
3. 执行语音合成
|
||
4. 成功 → 扣减积分
|
||
5. 失败 → 不扣费
|
||
```
|
||
|
||
### 积分配置
|
||
| platform | model_type | consume_points |
|
||
|----------|------------|----------------|
|
||
| voice | tts | 2 |
|
||
| voice | clone | 10 |
|
||
|
||
## 3.4 数字人合成集成
|
||
|
||
### 业务场景
|
||
- 口型同步视频生成
|
||
- 支持 Latentsync / 可灵 两种供应商
|
||
|
||
### 扣费流程
|
||
```
|
||
1. 获取积分配置（platform=digital_human, modelType=latentsync/kling）
|
||
2. 预检积分
|
||
3. 创建预扣记录
|
||
4. 创建任务并异步处理
|
||
5. 任务成功 → 确认扣费
|
||
6. 任务失败/取消 → 取消预扣
|
||
```
|
||
|
||
### 积分配置
|
||
| platform | model_type | consume_points |
|
||
|----------|------------|----------------|
|
||
| digital_human | latentsync | 15 |
|
||
| digital_human | kling | 20 |
|
||
|
||
---
|
||
|
||
# 附录
|
||
|
||
## A. 业务类型枚举
|
||
|
||
| 类型码 | 说明 |
|
||
|--------|------|
|
||
| dify_chat | Dify对话 |
|
||
| ai_chat | AI聊天 |
|
||
| image_gen | 图像生成 |
|
||
| tikhub_fetch | TikHub数据抓取 |
|
||
| voice_tts | 语音合成 |
|
||
| voice_clone | 音色克隆 |
|
||
| digital_human | 数字人合成 |
|
||
| kling_video | 可灵视频 |
|
||
|
||
## B. 异常码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1001001 | 积分不足 |
|
||
| 1001002 | 积分配置不存在 |
|
||
| 1001003 | 积分扣减失败 |
|
||
|
||
## C. 开发计划
|
||
|
||
| 步骤 | 内容 |
|
||
|------|------|
|
||
| 1 | 数据库：muye_point_record 新增 status 字段 |
|
||
| 2 | 公共服务：PointsService 接口 + 实现 |
|
||
| 3 | Dify 集成：配置类 + 客户端 + 服务 + Controller |
|
||
| 4 | TikHub 集成：添加积分扣减逻辑 |
|
||
| 5 | 语音合成集成：添加积分扣减逻辑 |
|
||
| 6 | 数字人集成：添加积分扣减逻辑 |
|
||
| 7 | 测试验证 |
|
||
|
||
**无需修改的表：**
|
||
- `muye_ai_agent` - 无需改动
|
||
- `muye_ai_model_config` - 已有 api_key 字段，无需改动
|
||
|
||
## D. 成熟度检查
|
||
|
||
| 检查项 | 说明 |
|
||
|--------|------|
|
||
| 原子扣减 | SQL 条件更新，防止超扣 |
|
||
| 乐观锁 | WHERE remaining_points >= points |
|
||
| 预扣机制 | 支持流式/异步场景 |
|
||
| 过期清理 | 30分钟自动清理预扣 |
|
||
| 事务隔离 | 核心操作加事务 |
|
||
| 异常处理 | 统一错误码 |
|
||
| 配置化 | 积分消耗可配置 |
|
||
| 业务解耦 | 公共服务复用 |
|
||
|
||
---
|
||
|