sion/sionrui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
shenaowei
2026-02-24 22:11:30 +08:00
parent 7490298ded
commit 903dc7ce93
5 changed files with 4 additions and 1020 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
openspec/proposals/points-service-integration.md
View File

@@ -1,305 +0,0 @@
# 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分钟自动清理预扣 |
| 事务隔离 | 核心操作加事务 |
| 异常处理 | 统一错误码 |
| 配置化 | 积分消耗可配置 |
| 业务解耦 | 公共服务复用 |
---