# 积分体系模块

## 概述
积分体系是追光AI的用户激励核心，包含20级成长系统、积分奖励引擎、积分商店、签到连击和Streak冻结保护，通过游戏化机制提升用户活跃度和留存率。

## 积分规则

| 行为 | 积分 | 每日上限 |
|------|------|----------|
| 发表评论 | +5 | 50 |
| 评论被点赞 | +2 | 20 |
| 发布论坛话题 | +10 | 无限制 |
| 论坛回复 | +5 | 30 |
| 发表评价 | +8 | 20 |
| 每日签到 | +1 (递增) | 1 |
| 签到连击 bonus | 连续7天+3, 连续30天+10 | - |

---

## 等级系统 - 20级成长体系

### 等级配置
- **配置文件**: `src/lib/level-config.ts` — 客户端安全（无Prisma依赖）
- 等级范围: LV01(0分) → LV20(50000分)
- 等级图标: ⭐(初级) → ⭐⭐⭐(中级) → 🌟(高级) → 🌟🌟(精英) → 🌟🌟🌟(大师)

### 等级表
| 等级 | 最低积分 | 徽章 | 每日限额 |
|------|----------|------|----------|
| LV01 | 0 | ⭐ | 50 |
| LV02 | 10 | ⭐ | 80 |
| LV03 | 30 | ⭐⭐ | 100 |
| LV04 | 60 | ⭐⭐ | 120 |
| LV05 | 100 | ⭐⭐ | 150 |
| LV06 | 200 | ⭐⭐⭐ | 180 |
| LV07 | 400 | ⭐⭐⭐ | 200 |
| LV08 | 700 | ⭐⭐⭐ | 250 |
| LV09 | 1000 | ⭐⭐⭐ | 300 |
| LV10 | 1500 | 🌟 | 400 |
| LV11 | 2000 | 🌟 | 500 |
| LV12 | 3000 | 🌟 | 600 |
| LV13 | 4500 | 🌟 | 700 |
| LV14 | 6000 | 🌟🌟 | 800 |
| LV15 | 8000 | 🌟🌟 | 1000 |
| LV16 | 11000 | 🌟🌟 | 1200 |
| LV17 | 15000 | 🌟🌟 | 1500 |
| LV18 | 20000 | 🌟🌟🌟 | 1800 |
| LV19 | 30000 | 🌟🌟🌟 | 2000 |
| LV20 | 50000 | 🌟🌟🌟 | 3000 |

### 旧等级迁移映射
BRONZE→LV01, SILVER→LV03, GOLD→LV06, PLATINUM→LV10

### 积分奖励引擎
- **文件**: `src/lib/points-reward.ts`
- `rewardPoints()` — 自动发放积分 + 日限额检查 + 事务写入
- `getUserStats()` — 获取用户综合统计（积分/评论数/话题数等）
- `getUserPointsHistory()` — 积分历史分页查询

---

## 签到系统

### 每日签到
- 基础+1分，连续签到递增奖励
- 连续7天: +3 bonus
- 连续30天: +10 bonus
- 中断重置

### CheckInCard 组件
- 位置: 用户中心顶部
- 功能: 签到按钮、连击天数显示、季度签到日历

---

## Streak 冻结保护

### 功能说明
- 用户可通过积分商店购买 Streak Freeze 卡片
- 当用户某天未签到时，自动消耗一张 Freeze 卡保护连击不断
- 最多持有 3 张 Freeze 卡

### 核心库
- **文件**: `src/lib/streak-freeze.ts`
- `checkAndApplyFreeze(userId)` — 检查是否需要冻结并自动应用
- `getFreezeCardCount(userId)` — 获取当前持有数量
- `useFreezeCard(userId)` — 消耗一张冻结卡

### 定时任务
- **脚本**: `scripts/grant-freeze-cards.mjs`
- 定期为活跃用户发放 Freeze 卡（每日01:00）

---

## 积分商店

### 功能概述
用户可使用积分兑换虚拟物品和社区权益。

### 商品定义
- **文件**: `src/lib/shop-items.ts`
- 商品类型: 头像框、昵称颜色、特效道具、Streak Freeze 卡

### API 接口

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/user/shop/items | GET | 获取可购买商品列表 |
| /api/user/shop/purchase | POST | 购买商品（扣积分） |
| /api/user/shop/my-items | GET | 获取用户已购物品 |

### 前端组件
- 积分商店页面（用户中心入口）
- 商品卡片（名称/图标/价格/库存/购买按钮）
- 已购物品展示（个人中心装饰效果）

---

## 数据模型

### PointsHistory (积分历史)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Int @id | 主键 |
| userId | Int | 用户ID |
| points | Int | 积分变动（正数获得/负数消耗） |
| reason | String | 积分原因 |
| detail | String? | 详细信息 |
| refType | String? | 关联类型 |
| refId | Int? | 关联ID |
| createdAt | DateTime | 创建时间 |

### StreakFreeze (冻结卡) 🆕
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Int @id | 主键 |
| userId | Int | 用户ID |
| cardCount | Int | 持有数量 |
| lastUsedAt | DateTime? | 最近使用时间 |
| createdAt | DateTime | 创建时间 |

### UserShopItem (已购物品) 🆕
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Int @id | 主键 |
| userId | Int | 用户ID |
| itemId | String | 商品ID |
| purchasedAt | DateTime | 购买时间 |
| isActive | Boolean | 是否启用/佩戴 |

---

## 前端组件

| 组件 | 文件 | 说明 |
|------|------|------|
| MemberBadge | `src/components/common/MemberBadge.tsx` | 会员等级徽章（⭐🌟 + 积分显示，3种尺寸） |
| LevelProgress | `src/components/common/LevelProgress.tsx` | 等级进度条（当前/下一级/进度百分比，动态变色） |
| CheckInCard | `src/components/common/CheckInCard.tsx` | 签到卡片（签到按钮/连击天数/季度日历） |

---

## 技术实现要点

### 积分自动奖励机制
所有评论/发帖/点赞操作自动通过 `rewardPoints()` 发放积分：
- 每日上限检查（防刷分）
- 事务写入（积分变更 + 历史记录同时写入）
- 等级自动随积分变化更新

### 日志分类
积分变动通过 `reason` 字段区分：
- `comment` — 评论
- `comment_liked` — 评论被点赞
- `topic_create` — 发帖
- `reply` — 回复
- `review` — 评价
- `check_in` — 签到
- `shop_purchase` — 商店消费（负数）