# 打卡赚积分功能设计

> 状态：v1.0 Draft，待用户确认部分参数

---

## 一、设计目标

1. **保底权益不变**：免费用户 3 人 × 3 次/天配额硬约束，积分不替代、不叠加
2. **激励活跃**：每日签到 + 邀请 + 付费均可获得积分，提升用户粘性
3. **制造稀缺感**：积分当年有效，连续签到有额外奖励
4. **可消耗感知**：提供有实际价值的兑换项，让积分不只是数字
5. **与现有体系解耦**：积分兑换的特权不占用原有配额，独立通道

---

## 二、与现有配额的关系

| 体系 | 规则 | 备注 |
|------|------|------|
| 免费配额 | 3 人 × 3 次/天 | 硬约束，不变 |
| 积分兑换 | 独立计算，不占用免费配额 | 如兑换一次深度解读，不计入 3 次 |
| 付费会员 | 无限聊天，积分可兑换额外增值服务 | 双轨并行 |

---

## 三、积分获取规则

### 3.1 日常获取

| 事件 | 积分 | 说明 |
|------|------|------|
| 每日签到 | +1 | 每日首次进入小程序自动触发 |
| 首次完成咨询 | +1 | 每次完成一次完整的能量盘解读 |
| 邀请好友注册 | +5 | 好友通过推广码注册即得 |
| 好友首次付费 | +20 | 好友完成 ¥131 及以上购买即得 |

### 3.2 连续签到奖励

| 连续天数 | 额外奖励 | 说明 |
|---------|---------|------|
| 第 7 天 | +3 | 每周奖励 |
| 第 14 天 | +5 | 双周奖励 |
| 第 30 天 | +10 | 月度奖励 |
| 第 100 天 | +50 | 百日纪念 |

> 断签后连续天数归零，可从第 1 天重新开始计数。

### 3.3 规则说明

- 签到积分每日 00:00 刷新，用户当日未签到可后补（见补签机制）
- 邀请类积分只有上级获得，被邀请人无奖励
- 好友付费奖励一次性发放，不重复

---

## 四、积分消耗场景

| 兑换项 | 消耗积分 | 说明 | 是否占免费配额 |
|--------|---------|------|-------------|
| 一次深度解读 | 50 | AI 生成 3000+ 字深度专属解读 | ❌ 独立通道 |
| 能量师优先通道 | 100 | 24 小时内优先获得能量师回复 | ❌ 独立通道 |
| 专属数字祝福 | 10 | 随机抽取当日专属数字建议/祝福语 | — |
| 能量师短咨询 | 200 | 能量师 200 字以内快速回应（上线后） | ❌ 独立通道 |

> **设计原则**：最高价值档位 ≤100 积分，降低用户决策门槛。

---

## 五、过期机制

| 规则 | 说明 |
|------|------|
| 自然年有效 | 每年 12 月 31 日 23:59:59 清零上一年度积分 |
| 提前提醒 | 每年 11 月 1 日起，站内信提醒剩余积分及清零时间 |
| 不可逆 | 清零后无法恢复，已过期积分从账户中移除 |

---

## 六、补签机制

| 规则 | 说明 |
|------|------|
| 补签消耗 | 每次补签消耗 5 积分 |
| 每月上限 | 每月最多补签 3 次（含已消耗） |
| 新用户优惠 | 注册首月可免费补签 1 次（引导） |
| 连续天数中断 | 补签后连续天数仍归零（补签仅恢复当日签到状态，不续接连续天数） |

---

## 七、数据库设计

### 7.1 points_points（积分主表）

```sql
CREATE TABLE `points_points` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `user_id` BIGINT NOT NULL,
  `balance` INT NOT NULL DEFAULT 0 COMMENT '当前可用积分余额',
  `year` INT NOT NULL COMMENT '所属年度（2026）',
  `last_checkin_date` DATE COMMENT '最后签到日期',
  `consecutive_days` INT NOT NULL DEFAULT 0 COMMENT '连续签到天数',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY `uk_user_year` (`user_id`, `year`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 7.2 points_records（积分流水）

```sql
CREATE TABLE `points_records` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `user_id` BIGINT NOT NULL,
  `type` VARCHAR(20) NOT NULL COMMENT 'checkin/invite/charge/redeem/expire/refund',
  `amount` INT NOT NULL COMMENT '变动积分（正=获得，负=消耗）',
  `balance_after` INT NOT NULL COMMENT '变动后余额',
  `ref_id` VARCHAR(64) COMMENT '关联ID（订单ID/兑换记录ID）',
  `remark` VARCHAR(200) COMMENT '备注',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX `idx_user_created` (`user_id`, `created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 7.3 points_rewards（兑换奖励表）

```sql
CREATE TABLE `points_rewards` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `name` VARCHAR(50) NOT NULL COMMENT '奖励名称',
  `cost` INT NOT NULL COMMENT '所需积分',
  `type` VARCHAR(20) NOT NULL COMMENT 'reward_type',
  `is_active` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否上架',
  `sort` INT NOT NULL DEFAULT 0 COMMENT '排序权重',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

---

## 八、sys_config 参数

```sql
INSERT INTO sys_config (`key`, `value`, `desc`, `value_type`) VALUES
('points.checkin.daily', '1', '每日签到积分', 'number'),
('points.invite.registered', '5', '邀请好友注册积分', 'number'),
('points.invite.paid', '20', '好友首次付费积分', 'number'),
('points.consultation.complete', '1', '完成一次咨询积分', 'number'),
('points.redeem.consume_min', '10', '最低兑换积分门槛', 'number'),
('points.checkin.repair_cost', '5', '每次补签消耗积分', 'number'),
('points.checkin.repair_limit_monthly', '3', '每月最多补签次数', 'number'),
('points.year_expire_enabled', 'true', '是否开启年度过期', 'boolean'),
('points.year_remind_day', '1101', '过期提醒日期（MMDD）', 'number');
```

---

## 九、API 设计

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/points/checkin` | POST | 今日签到（每日首次调用触发） |
| `/api/points/balance` | POST | 查询当前积分余额及年度信息 |
| `/api/points/records` | POST | 积分流水列表（含类型筛选） |
| `/api/points/redeem` | POST | 积分兑换（`reward_id` + 消耗积分） |
| `/api/points/repair` | POST | 补签（消耗积分，返回剩余次数） |
| `/api/points/expire-warn` | POST | 即将到期积分查询（用于提醒展示） |
| `/api/admin/points/rewards` | CRUD | 兑换奖励后台增删改查 |

---

## 十、前端改动

### 10.1 个人中心积分卡片

```
┌─────────────────────────────────────┐
│ 🪙 我的积分                           │
│                                      │
│  128 分    连续签到 12 天              │
│  [签到打卡]    [补签 ×3次/月]          │
│  [积分商城 →]                         │
└─────────────────────────────────────┘
```

### 10.2 积分商城页面

- 奖励列表卡片（图片 + 名称 + 消耗积分 + 兑换按钮）
- 积分不足时按钮置灰，显示"还差 XX 分"
- 兑换成功弹窗 + 积分扣除通知

### 10.3 年底清零提醒

- 每年 11 月 1 日起，个人中心顶部显示横幅提示
- 内容：*"您还有 XXX 积分将于 12 月 31 日清零，快来使用吧！"*

---

## 十一、与现有系统兼容

| 现有功能 | 影响 | 处理方式 |
|---------|------|---------|
| 免费配额（3人3次） | 无影响 | 积分独立，不叠加 |
| 付费会员无限聊天 | 无影响 | 积分兑换为增值服务，不替代 |
| 分销佣金 | 无影响 | 积分与佣金体系完全解耦 |
| 管理后台 | 无影响 | 新增积分奖励配置模块 |

---

## 十二、待确认事项

1. **兑换项数值**：深度解读 50 积分 / 优先通道 100 积分是否合理？是否要增减兑换项？
2. **邀请奖励**：好友付费 +20 积分是否足够激励？
3. **连续签到权重**：第7天+3分到第100天+50分，阶梯是否合适？
4. **补签设计**：每月补签 3 次（每次 5 分），是否过严或过松？

---

## 十三、实现优先级建议

```
Phase 1（必做）：
□ 每日签到 + 连续签到 + 积分流水记录
□ 积分余额查询 + 前端展示
□ 积分兑换（深度解读/优先通道）
□ 补签机制

Phase 2（可延后）：
□ 邀请好友注册/付费积分自动发放
□ 年底清零提醒 + 定时任务
□ 积分商城完整UI
□ lilishop 商城商品兑换
```