sion/sionrui

Fork 0

Files

shenaowei 8d6a93c9dd 优化

2026-02-22 20:07:26 +08:00

9.0 KiB

Raw Blame History

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

核心流程：

前端传入 agentId + content
后端通过 agentId 获取智能体的 systemPrompt
调用 Dify API（固定工作流），传入 sysPrompt 参数
流式返回内容
流结束或用户停止时扣费

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	启用

配置文件只存公共配置：

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	状态

调用流程：

通过 agentId 获取智能体的 systemPrompt
从 muye_ai_model_config 获取 api_key + consume_points（platform=dify）
调用 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分钟自动清理预扣
事务隔离	核心操作加事务
异常处理	统一错误码
配置化	积分消耗可配置
业务解耦	公共服务复用

9.0 KiB Raw Blame History Unescape Escape

AI 服务积分扣减公共服务设计文档

模块一：公共积分扣减服务

1.1 服务定位

1.2 核心能力

1.3 数据模型

用户积分（muye_member_user_profile）

积分记录（muye_point_record）

积分配置（muye_ai_model_config）

1.4 业务规则

积分扣减规则

预扣过期规则

异常处理

1.5 依赖关系

模块二：Dify 工作流集成

2.1 业务概述

2.2 扣费流程

2.3 接口定义

阻塞模式

流式模式

2.4 配置方案

2.5 智能体表（无需修改）

模块三：各业务积分扣减集成

3.1 扣费模式总览

3.2 TikHub 集成

业务场景

扣费流程

积分配置

3.3 语音合成集成

业务场景

扣费流程

积分配置

3.4 数字人合成集成

业务场景

扣费流程

积分配置

附录

A. 业务类型枚举

B. 异常码

C. 开发计划

D. 成熟度检查

9.0 KiB

Raw Blame History