docs: 新增打卡赚积分功能设计（获取/消耗/过期/补签/API/sys_config）

docs/points-system.md

@@ -0,0 +1,233 @@
+# 打卡赚积分功能设计
+
+> 状态：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 商城商品兑换
+```