# 积分冻结与过期机制 — 未实现功能设计

> 本文档仅覆盖**尚未实现的功能**中需要用到积分冻结/过期机制的场景。  
> 已实现功能（订单冻结、活动冻结、批次过期等）不在本文档范围内。  
> 编写日期：2026-03-21

---

## 一、积分转赠（待实现功能 #26）

### 1.1 冻结机制

| 环节 | 操作 | 说明 |
|------|------|------|
| 发起转赠 | `freezePoints(senderId, amount, transferId)` | A 发起转赠→冻结 A 的积分 |
| 对方接收 | `consumeFrozenPoints(senderId, amount, transferId)` + `earnPoints(receiverId, ...)` | B 确认→扣除 A 冻结积分，发放给 B |
| 对方拒绝/超时 | `unfreezePoints(senderId, amount, transferId)` | 超过24小时未接收→自动解冻退回 A |

### 1.2 过期机制

- B 收到的转赠积分创建新批次，有效期建议 **90天**（防止积分通过转赠无限续期）
- 转赠积分的有效期不应继承原批次剩余有效期（否则可通过互转刷新有效期）

### 1.3 风控要点

- 单日转赠上限：每人每日最多转出 500 积分
- 手续费：转赠扣除 10% 手续费（A 转 100，B 收到 90）
- 转赠积分不可再次转赠（标记 `source = 'transfer_in'`，转赠时校验批次来源）

### 1.4 数据库设计建议

```sql
CREATE TABLE points_transfers (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  sender_id BIGINT NOT NULL COMMENT '转出方用户ID',
  receiver_id BIGINT NOT NULL COMMENT '接收方用户ID',
  amount INT NOT NULL COMMENT '转赠积分（扣除手续费前）',
  fee INT NOT NULL DEFAULT 0 COMMENT '手续费积分',
  actual_amount INT NOT NULL COMMENT '实际到账积分',
  status ENUM('pending', 'accepted', 'rejected', 'expired', 'cancelled') DEFAULT 'pending',
  expired_at DATETIME NOT NULL COMMENT '接收截止时间（24小时）',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_sender (sender_id),
  INDEX idx_receiver (receiver_id),
  INDEX idx_status (status)
) COMMENT='积分转赠记录表';
```

### 1.5 接口设计

```
POST   /api/v1/points/transfer          发起转赠（冻结积分）
POST   /api/v1/points/transfer/{id}/accept  接收转赠（消费冻结+发放）
POST   /api/v1/points/transfer/{id}/reject  拒绝转赠（解冻退回）
GET    /api/v1/points/transfers          我的转赠记录
```

---

## 二、优惠券系统（待实现功能 #16）

### 2.1 冻结机制 — 积分兑换优惠券

| 环节 | 操作 | 说明 |
|------|------|------|
| 兑换优惠券 | `freezePoints(userId, amount, couponOrderId)` | 用户用积分兑换优惠券→先冻结 |
| 兑换确认 | `consumeFrozenPoints(userId, amount, couponOrderId)` | 系统发放优惠券成功→消费冻结积分 |
| 兑换失败 | `unfreezePoints(userId, amount, couponOrderId)` | 优惠券库存不足或系统异常→解冻退回 |

### 2.2 过期机制 — 优惠券与积分联动

- 优惠券本身有独立有效期，与积分过期无直接关系
- 但如果优惠券过期未使用且支持退还积分，退还的积分建议有效期 **30天**（短周期促消费）

### 2.3 风控要点

- 同一优惠券每人限兑 1 张（防囤券）
- 兑换冻结窗口 ≤ 5秒（快速确认，减少积分被长时间锁定）

---

## 三、限时折扣/秒杀活动（待实现功能 #17）

### 3.1 冻结机制 — 积分参与秒杀

| 环节 | 操作 | 说明 |
|------|------|------|
| 参与秒杀 | `freezeForActivity(userId, amount, activityId, title)` | 用户参与积分秒杀→冻结积分 |
| 秒杀成功 | `consumeFrozenForActivity(userId, amount, activityId, title)` | 中标→消费冻结积分，发放 Skill |
| 秒杀失败 | `unfreezeForActivity(userId, amount, activityId, title)` | 未中→解冻退回 |

### 3.2 过期机制 — 活动赠送积分

- 限时活动赠送的积分建议有效期 **7-15天**（制造紧迫感，推动快速消费）
- 活动积分批次 `source = 'activity'`，定时过期任务统一处理

### 3.3 关键设计

- 秒杀冻结必须原子操作（Redis + 乐观锁防超卖）
- 活动结束后批量解冻所有未中标用户的冻结积分（定时任务 / 活动结束回调）

---

## 四、安全风控体系（待实现功能 #25）

### 4.1 冻结机制 — 异常行为冻结

| 场景 | 冻结操作 | 说明 |
|------|---------|------|
| 刷积分检测 | 冻结全部可用积分 | 检测到短时间大量签到/邀请奖励异常→冻结账户积分 |
| 恶意退款检测 | 冻结退还积分 | 频繁购买-退款套利→冻结退还的积分待人工审核 |
| 多账号关联 | 冻结关联账号积分 | 检测到同设备/IP多账号互相邀请→冻结所有关联账号 |

### 4.2 实现方式

```java
// 风控冻结：与业务冻结区分，使用独立的 source 标记
void freezeByRisk(Long userId, int amount, String riskType, String reason);
void unfreezeByRisk(Long userId, int amount, Long auditId);  // 管理员审核后解冻
```

### 4.3 数据库设计建议

```sql
CREATE TABLE risk_freeze_records (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT NOT NULL,
  freeze_amount INT NOT NULL COMMENT '冻结积分数',
  risk_type VARCHAR(50) NOT NULL COMMENT '风险类型: point_abuse/refund_abuse/multi_account',
  reason VARCHAR(500) COMMENT '冻结原因',
  status ENUM('frozen', 'unfrozen', 'deducted') DEFAULT 'frozen',
  auditor_id BIGINT COMMENT '审核人ID',
  audit_note VARCHAR(500) COMMENT '审核备注',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  resolved_at DATETIME COMMENT '处理时间',
  INDEX idx_user (user_id),
  INDEX idx_status (status)
) COMMENT='风控冻结记录表';
```

### 4.4 风控规则示例

| 规则 | 触发条件 | 冻结策略 |
|------|---------|---------|
| 签到异常 | 同一设备 ≥3 个账号当天签到 | 冻结所有关联账号当天签到积分 |
| 邀请刷量 | 24小时内邀请 ≥10 人且被邀请人无后续活跃 | 冻结邀请奖励积分 |
| 退款套利 | 30天内退款 ≥3 次 | 冻结账户全部积分，人工审核 |

---

## 五、积分规则后台配置（待实现功能 #30）

### 5.1 过期机制 — 差异化有效期配置

当前 `DEFAULT_EXPIRE_DAYS = 365` 是硬编码。需要改为后台可配置：

```sql
-- 在 points_rules 表新增字段
ALTER TABLE points_rules ADD COLUMN expire_days INT DEFAULT 365 COMMENT '积分有效期（天），0=永不过期';
```

### 5.2 配置示例

| 积分来源 | 建议有效期 | 配置字段 |
|---------|-----------|---------|
| register | 30天 | `expire_days = 30` |
| sign_in | 90天 | `expire_days = 90` |
| invite | 180天 | `expire_days = 180` |
| recharge | 365天 | `expire_days = 365` |
| activity | 7-15天 | `expire_days = 7` (按活动单独配置) |
| review | 90天 | `expire_days = 90` |
| admin_add | 0（永不过期） | `expire_days = 0` |
| refund | 180天 | `expire_days = 180` |
| transfer_in | 90天 | `expire_days = 90` |

### 5.3 代码改造要点

```java
// PointsServiceImpl.createBatch() 改为从 rules 表读取 expire_days
private void createBatch(Long userId, String source, int amount, Long relatedId, String relatedType) {
    int expireDays = getExpireDaysBySource(source);  // 从 points_rules 表查询
    LocalDateTime expireAt = expireDays > 0
        ? LocalDateTime.now().plusDays(expireDays)
        : LocalDateTime.of(2099, 12, 31, 23, 59, 59);  // 0=永不过期
    // ... 创建批次
}
```

---

## 六、在线客服/工单系统（待实现功能 #22）

### 6.1 冻结机制 — 争议工单积分冻结

| 场景 | 操作 | 说明 |
|------|------|------|
| 用户提交争议工单 | 可选冻结争议订单关联积分 | 涉及积分纠纷的工单，客服可手动冻结相关积分 |
| 工单解决 | 解冻或扣除 | 根据裁决结果解冻退回或扣除 |

### 6.2 实现方式

- 客服后台增加"冻结用户积分"操作按钮
- 记录操作日志（关联工单ID），审计可追溯
- 解冻需要高级客服或管理员权限

---

## 七、实现优先级建议

| 优先级 | 功能 | 冻结/过期关键点 | 依赖 |
|--------|------|----------------|------|
| **P1** | #30 积分规则后台配置 | 差异化有效期是所有过期策略的基础 | 无 |
| **P1** | #25 风控体系 | 风控冻结是防刷核心手段 | 无 |
| **P2** | #26 积分转赠 | 冻结防并发+过期防续期 | 无 |
| **P2** | #16 优惠券系统 | 兑换冻结+退还过期 | 优惠券模块 |
| **P2** | #17 秒杀活动 | 参与冻结+活动积分短过期 | 活动模块增强 |
| **P3** | #22 客服工单 | 争议冻结 | 客服系统 |

---

## 八、通用技术要点

### 8.1 冻结与解冻的幂等性

所有冻结/解冻操作必须带业务ID（orderId/transferId/activityId），防止重复冻结：

```java
// 冻结前检查是否已冻结
boolean alreadyFrozen = recordRepo.exists(
    new LambdaQueryWrapper<PointsRecord>()
        .eq(PointsRecord::getRelatedId, bizId)
        .eq(PointsRecord::getRelatedType, bizType)
        .eq(PointsRecord::getPointsType, "freeze")
);
if (alreadyFrozen) return; // 幂等，跳过
```

### 8.2 过期批次的FIFO消费

消费积分时优先扣最早到期的批次（已实现 `consumeBatchesFIFO`），确保：
- 用户总是先用"快过期"的积分
- 减少过期浪费，提升用户体验

### 8.3 冻结积分不参与过期

被冻结的积分在冻结期间不应触发过期（过期定时任务需排除冻结状态的批次）。如果业务解冻后发现原批次已过期，应创建新批次并设合理有效期。

---

*本文档随功能开发进度持续更新*