# 勋章系统模块需求分析

**版本**: V1.2
**更新时间**: 2026-04-15

---

## 一、需求清单概览

| 需求ID | 描述 | 优先级 | 状态 |
|--------|------|--------|------|
| BADGE-001 | 勋章定义与分类 | P1 | ❌ 未实现 |
| BADGE-002 | 勋章解锁条件设置 | P1 | ❌ 未实现 |
| BADGE-003 | 勋章自动授予逻辑 | P1 | ❌ 未实现 |
| BADGE-004 | 勋章展示与收藏 | P1 | ❌ 未实现 |
| BADGE-005 | 勋章有效期与过期 | P1 | ❌ 未实现 |
| BADGE-006 | 勋章统计与排行 | P1 | ❌ 未实现 |

---

## 二、需求详细描述

### 2.1 勋章定义与分类（BADGE-001）

#### BADGE-001: 勋章定义与分类
- **描述**：系统支持定义多种勋章类型，每种勋章有唯一的标识、名称、图标、等级和分类
- **字段**：
  - `badgeId`：勋章唯一标识
  - `name`：勋章名称
  - `description`：勋章描述
  - `icon`：勋章图标
  - `category`：勋章分类（学习类/运动类/家务类/打卡类/综合类）
  - `level`：勋章等级（铜/银/金/钻石）
  - `rarity`：稀有度（普通/稀有/史诗/传说）
- **可选值**：
  - 分类：`学习` / `运动` / `家务` / `阅读` / `打卡` / `综合`
  - 等级：`铜牌` / `银牌` / `金牌` / `钻石`
  - 稀有度：`普通` / `稀有` / `史诗` / `传说`

---

### 2.2 勋章解锁条件设置（BADGE-002）

#### BADGE-002: 勋章解锁条件设置
- **描述**：每种勋章可以设置解锁条件，达到条件后自动或手动解锁
- **字段**：
  - `triggerType`：触发类型（任务完成次数 / 连续打卡天数 / 积分累计 / 兑换次数）
  - `threshold`：阈值
  - `childOnly`：是否仅孩子可解锁
- **可选值**：
  - 触发类型：`task_count` / `streak_days` / `points_total` / `reward_count` / `custom`
  - 阈值：整数，根据类型定义

---

### 2.3 勋章自动授予逻辑（BADGE-003）

#### BADGE-003: 勋章自动授予逻辑
- **描述**：系统根据解锁条件自动判断是否授予勋章，支持即时授予和家长审批后授予
- **实现**：
  - 定时任务扫描孩子的解锁条件
  - 或在关键动作（任务完成、打卡）时触发检查
  - 支持自动授予或需要审批
- **状态记录**：
  - `badgeId`：勋章ID
  - `childId`：获得者
  - `earnedAt`：获得时间
  - `status`：有效/已过期/已撤销

---

### 2.4 勋章展示与收藏（BADGE-004）

#### BADGE-004: 勋章展示与收藏
- **描述**：孩子在个人主页或勋章墙展示已获得勋章，支持收藏功能
- **前端页面**：
  - 勋章墙：展示所有已获得勋章，按分类/时间排列
  - 勋章详情：查看勋章名称、描述、获得时间、稀有度
  - 收藏功能：将喜欢的勋章置顶
- **展示规则**：
  - 未获得的勋章显示为锁定状态
  - 已获得的勋章显示正常图标和名称
  - 收藏的勋章显示在最前

---

### 2.5 勋章有效期与过期（BADGE-005）

#### BADGE-005: 勋章有效期与过期
- **描述**：部分勋章可以设置有效期，过期后变为过期状态，但仍保留展示
- **字段**：
  - `expireDays`：有效期天数（-1 表示永久有效）
  - `expireAt`：过期时间
- **逻辑**：
  - 定时任务每日检查勋章有效期
  - 过期后勋章仍保留在展示页，但状态标记为“已过期”
  - 可设置续期条件，重新激活勋章

---

### 2.6 勋章统计与排行（BADGE-006）

#### BADGE-006: 勋章统计与排行
- **描述**：提供勋章统计功能，包括个人勋章数量、分类统计、全家排行等
- **统计维度**：
  - 个人获得勋章总数
  - 各分类勋章数量
  - 各等级勋章数量
  - 稀有度分布
- **排行功能**：
  - 家庭内排行：按勋章数量或积分排序
  - 街道/区域排行（可选）

---

## 三、勋章数据模型

### 3.1 Badge 勋章定义实体

```java
// 基础字段
private Long id;
private String badgeId;      // 勋章唯一标识
private String name;         // 勋章名称
private String description;  // 勋章描述
private String icon;         // 勋章图标URL
private String category;     // 勋章分类
private String level;        // 勋章等级
private String rarity;       // 稀有度

// 解锁条件
private String triggerType;  // 触发类型
private Integer threshold;    // 阈值
private Boolean needApproval; // 是否需要审批
private Integer expireDays;  // 有效期天数

// 系统字段
private Integer sortOrder;   // 排序
private Integer isActive;    // 是否启用
private Date createdAt;
private Date updatedAt;
```

### 3.2 ChildBadge 儿童勋章关联实体

```java
// 关联字段
private Long id;
private Long childId;        // 孩子ID
private Long badgeId;        // 勋章ID（对应Badge.id）

// 获得信息
private Date earnedAt;       // 获得时间
private Date expireAt;       // 过期时间
private Integer status;      // 状态：1-有效 0-过期 -1-已撤销
private Boolean isFavorite;  // 是否收藏

// 系统字段
private Date createdAt;
private Date updatedAt;
```

### 3.3 状态说明

| 状态码 | 含义 | 说明 |
|--------|------|------|
| 1 | 有效 | 勋章正常使用 |
| 0 | 已过期 | 已超过有效期 |
| -1 | 已撤销 | 被管理员撤销 |

---

## 四、勋章流程说明

### 4.1 勋章生命周期

```
定义勋章 → 设置解锁条件 → 孩子达成条件 → 系统判断 → 授予勋章 → 展示/收藏 → 过期/续期
```

### 4.2 阶段与角色

| 阶段 | 家长/管理员 | 孩子 | 系统 |
|------|------------|------|------|
| 定义阶段 | 创建/编辑勋章模板 | 不参与 | 校验字段 |
| 解锁阶段 | 设置解锁条件 | 执行任务/打卡 | 检查触发条件 |
| 授予阶段 | 审批（如需要） | 等待/获得 | 写入获得记录 |
| 展示阶段 | 查看全家勋章 | 查看/收藏个人勋章 | 渲染勋章墙 |
| 过期阶段 | 查看统计 | 查看过期勋章 | 检查并标记过期 |

---

## 五、API接口设计

### 5.1 勋章管理

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| POST | /api/badges | 创建勋章定义 | 管理员 |
| GET | /api/badges | 获取勋章列表 | 公开 |
| GET | /api/badges/{id} | 获取勋章详情 | 公开 |
| PUT | /api/badges/{id} | 编辑勋章定义 | 管理员 |
| DELETE | /api/badges/{id} | 删除勋章 | 管理员 |

### 5.2 勋章授予

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| POST | /api/badges/grant | 手动授予勋章 | 家长/管理员 |
| POST | /api/badges/check | 检查并授予勋章 | 系统 |
| GET | /api/badges/child/{childId} | 获取孩子的勋章 | 孩子/家长 |
| PUT | /api/badges/{id}/favorite | 收藏/取消收藏 | 孩子 |

### 5.3 勋章统计

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | /api/badges/statistics/child/{childId} | 孩子勋章统计 | 孩子/家长 |
| GET | /api/badges/statistics/family/{familyId} | 家庭勋章统计 | 家长 |
| GET | /api/badges/ranking/family/{familyId} | 家庭内排行 | 家长 |

---

## 六、前端页面设计

| 页面 | 路径 | 功能 |
|------|------|------|
| 勋章墙 | `/pages/badges/badges` | 展示已获得勋章 |
| 勋章详情 | `/pages/badges/detail` | 勋章详细信息 |
| 勋章库 | `/pages/badges/library` | 浏览所有勋章定义 |
| 勋章统计 | `/pages/badges/statistics` | 统计与排行 |

---

## 七、待完善事项

| 功能 | 优先级 | 说明 |
|------|--------|------|
| 勋章定义CRUD | P1 | 后端实体与API |
| 解锁条件引擎 | P1 | 定时任务+事件触发 |
| 勋章墙前端 | P1 | 小程序/WEB展示 |
| 勋章过期逻辑 | P1 | 定时任务 |
| 勋章统计排行 | P1 | 统计API |

---

## 八、数据库设计建议

### 8.1 勋章定义表

```sql
CREATE TABLE badge (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    badge_id VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    icon VARCHAR(255),
    category VARCHAR(20),
    level VARCHAR(20),
    rarity VARCHAR(20),
    trigger_type VARCHAR(20),
    threshold INT DEFAULT 0,
    need_approval TINYINT DEFAULT 0,
    expire_days INT DEFAULT -1,
    sort_order INT DEFAULT 0,
    is_active TINYINT DEFAULT 1,
    created_at DATETIME,
    updated_at DATETIME
);
```

### 8.2 儿童勋章关联表

```sql
CREATE TABLE child_badge (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    child_id BIGINT NOT NULL,
    badge_id BIGINT NOT NULL,
    earned_at DATETIME,
    expire_at DATETIME,
    status TINYINT DEFAULT 1,
    is_favorite TINYINT DEFAULT 0,
    created_at DATETIME,
    updated_at DATETIME,
    UNIQUE KEY uk_child_badge (child_id, badge_id)
);
```

---

## 九、后续开发建议

### 9.1 第一阶段：基础功能
1. Badge 实体与 CRUD API
2. ChildBadge 关联表与授予逻辑
3. 勋章墙前端展示

### 9.2 第二阶段：解锁与过期
1. 解锁条件引擎（定时任务）
2. 勋章过期检查定时任务
3. 收藏功能

### 9.3 第三阶段：统计与扩展
1. 勋章统计 API
2. 家庭内排行
3. 勋章续期与活动勋章