sionrui/openspec/proposals/points-service-integration.md

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

---