# 算力积分体系与服务重组总结

> **完成时间**：2025-01-14  
> **执行人**：系统架构师

---

## 一、任务概述

本次任务包含两个主要部分：

1. **算力积分体系设计**：将订阅制改为纯积分体系
2. **服务文档重组**：按业务领域重新组织服务文档

---

## 二、算力积分体系

### 2.1 核心变更

**移除订阅制**：

- 删除 `subscription_tier`（免费版/专业版/企业版）
- 删除 `subscription_expires_at`（订阅过期时间）

**引入积分体系**：

- `ai_credits_balance`：当前积分余额
- `total_recharged_amount`：累计充值金额
- `total_credits_earned`：累计获得积分
- `total_credits_consumed`：累计消耗积分

### 2.2 新增服务

#### 1. 算力积分管理服务 (`credit-service.md`)

- 积分查询（余额、流水、消耗记录）
- 积分操作（增加、消耗、退还）
- 积分定价（动态计算所需积分）
- 积分套餐管理
- 积分赠送

#### 2. 充值管理服务 (`recharge-service.md`)

- 创建充值订单
- 支付处理（微信/支付宝）
- 支付回调处理
- 订单管理（查询、取消、超时）

#### 3. 支付服务 (`payment-service.md`)

- 统一支付接口
- 微信支付集成
- 支付宝支付集成
- 支付回调验证

### 2.3 数据库设计

新增 7 张表：

| 表名                      | 说明         | 记录数预估 |
| ------------------------- | ------------ | ---------- |
| `recharge_orders`         | 充值订单     | 百万级     |
| `credit_transactions`     | 积分流水     | 千万级     |
| `credit_consumption_logs` | 消耗记录     | 千万级     |
| `credit_packages`         | 积分套餐     | 十条级     |
| `credit_pricing`          | 定价配置     | 十条级     |
| `payment_callbacks`       | 支付回调日志 | 百万级     |
| `credit_gifts`            | 积分赠送记录 | 十万级     |

### 2.4 业务流程

#### 充值流程

```
选择套餐 → 创建订单 → 调用支付 → 用户支付
→ 接收回调 → 验证签名 → 增加积分 → 记录流水
```

#### 消耗流程

```
发起任务 → 计算积分 → 检查余额 → 预扣积分
→ AI 生成 → 成功：确认扣减 / 失败：退还积分
```

### 2.5 技术亮点

1. **并发安全**：数据库行锁 + 事务保证余额不为负
2. **积分冻结**：预扣 → 确认/退还，防止重复扣款
3. **支付幂等**：检查订单状态，防止重复回调
4. **对账机制**：定时任务验证流水与余额一致性
5. **灵活定价**：JSON 配置支持动态定价规则

---

## 三、服务文档重组

### 3.1 重组前后对比

**重组前**：19 个服务文档平铺在同一目录

**重组后**：按业务领域分为 4 个子目录

```
04-services/
├── README.md (总览)
├── user/ (6 个服务)
│   ├── user-service.md
│   ├── sms-service.md
│   ├── wechat-service.md
│   ├── credit-service.md
│   ├── recharge-service.md
│   └── payment-service.md
├── project/ (8 个服务)
│   ├── project-service.md
│   ├── project-resource-service.md
│   ├── folder-service.md
│   ├── script-service.md
│   ├── storyboard-service.md
│   ├── timeline-service.md
│   ├── comment-service.md
│   └── export-service.md
├── resource/ (3 个服务)
│   ├── resource-service.md
│   ├── attachment-service.md
│   └── file-storage-service.md
└── ai/ (2 个服务)
    ├── ai-service.md
    └── video-service.md
```

### 3.2 分类依据

| 目录        | 业务领域                     | 服务数量 |
| ----------- | ---------------------------- | -------- |
| `user/`     | 用户认证、积分、充值、支付   | 6        |
| `project/`  | 项目管理、脚本、分镜、时间轴 | 8        |
| `resource/` | 素材资源、附件、云存储       | 3        |
| `ai/`       | AI 生成、视频处理            | 2        |

### 3.3 新增索引文档

每个子目录都包含 `README.md`：

- 服务列表
- 核心功能概述
- 服务依赖关系
- 业务流程图
- 相关文档链接

---

## 四、交付文档清单

### 4.1 服务文档（3 个新增）

- ✅ `docs/需求/backend/04-services/user/credit-service.md`
- ✅ `docs/需求/backend/04-services/user/recharge-service.md`
- ✅ `docs/需求/backend/04-services/user/payment-service.md`

### 4.2 方案文档（1 个）

- ✅ `docs/方案/算力积分体系设计.md`

### 4.3 计划文档（1 个）

- ✅ `docs/计划/算力积分体系实施计划.md`

### 4.4 索引文档（5 个）

- ✅ `docs/需求/backend/04-services/README.md`
- ✅ `docs/需求/backend/04-services/user/README.md`
- ✅ `docs/需求/backend/04-services/project/README.md`
- ✅ `docs/需求/backend/04-services/resource/README.md`
- ✅ `docs/需求/backend/04-services/ai/README.md`

### 4.5 修复文档（1 个）

- ✅ `docs/修复/服务文档重组.md`

### 4.6 调整文档（1 个）

- ✅ `docs/需求/backend/04-services/user/user-service.md`（移除订阅管理）

---

## 五、数据统计

### 5.1 文档数量

- **服务文档总数**：19 个（新增 3 个）
- **索引文档**：5 个
- **方案文档**：1 个
- **计划文档**：1 个
- **修复文档**：1 个
- **总计**：27 个文档

### 5.2 代码行数（预估）

- **Service 层**：约 2000 行
- **Repository 层**：约 800 行
- **Model 层**：约 500 行
- **Schema 层**：约 400 行
- **API 层**：约 600 行
- **总计**：约 4300 行

### 5.3 数据库表

- **新增表**：7 张
- **调整表**：1 张（users）
- **总计**：8 张表变更

---

## 六、后续工作

### 6.1 立即执行（高优先级）

- [ ] 数据库迁移脚本编写
- [ ] 后端服务代码实现
- [ ] API 接口开发
- [ ] 单元测试编写

### 6.2 前端开发（中优先级）

- [ ] 充值页面
- [ ] 积分管理页面
- [ ] 支付流程
- [ ] 积分流水展示

### 6.3 测试验证（高优先级）

- [ ] 功能测试
- [ ] 并发测试
- [ ] 支付测试
- [ ] 安全测试

### 6.4 文档完善（低优先级）

- [ ] 检查并更新文档引用路径
- [ ] API 文档生成
- [ ] 部署文档编写

---

## 七、风险提示

### 7.1 数据迁移风险

**风险**：现有用户数据迁移可能出错

**应对**：

- 测试环境先验证
- 生产环境备份
- 迁移后数据校验

### 7.2 支付安全风险

**风险**：支付回调可能被伪造

**应对**：

- 严格验证签名
- 记录所有回调日志
- 订单金额二次验证

### 7.3 并发扣款风险

**风险**：多个请求同时扣款导致余额为负

**应对**：

- 数据库行锁
- 事务保证原子性
- 余额检查

---

## 八、总结

### 8.1 完成情况

✅ **算力积分体系设计**：完整的业务流程、数据模型、技术方案  
✅ **服务文档重组**：按业务领域分类，清晰易维护  
✅ **文档交付**：27 个文档，覆盖设计、实施、修复全流程

### 8.2 核心价值

1. **灵活的商业模式**：从订阅制改为按需付费
2. **清晰的文档结构**：按业务领域组织，易于查找
3. **完善的技术方案**：并发安全、支付安全、数据一致性
4. **可扩展的架构**：支持未来功能扩展

### 8.3 预计工期

- **后端开发**：3-4 天
- **前端开发**：2-3 天
- **测试验证**：1-2 天
- **总计**：5-7 个工作日

---

**完成时间**：2025-01-14  
**状态**：✅ 设计阶段完成，进入开发阶段