勋章系统模块需求分析
版本: 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：勋章IDchildId：获得者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 勋章定义实体
// 基础字段
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 儿童勋章关联实体
// 关联字段
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 勋章定义表
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 儿童勋章关联表
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 第一阶段：基础功能
- Badge 实体与 CRUD API
- ChildBadge 关联表与授予逻辑
- 勋章墙前端展示
9.2 第二阶段：解锁与过期
- 解锁条件引擎（定时任务）
- 勋章过期检查定时任务
- 收藏功能
9.3 第三阶段：统计与扩展
- 勋章统计 API
- 家庭内排行
- 勋章续期与活动勋章
