集合：徽章进度（badges）
字数
900 字
阅读时间
4 分钟
1. 目的与使用场景
- 记录用户在徽章成就体系中的解锁状态与进度，支撑“我的”页徽章墙、任务激励、推送通知。由
/api/badges、周报生成、激励云函数写入。
2. Schema 定义
| 字段 | 类型 | 必填 | 默认值 | 约束/校验 | 说明 | 隐私分级 |
|---|---|---|---|---|---|---|
| _id | string | 是 | - | TCB 自动 | 主键 | P1 |
| user_id | 指针id | 是 | - | 指向 users._id | 用户 | P1 |
| badge_code | string | 是 | - | 枚举(consistency_7d,consistency_30d,guardian_connect,community_support,task_master) | 徽章编码 | P1 |
| status | string | 是 | locked | 枚举(locked,in_progress,unlocked) | 当前状态 | P1 |
| progress_value | number | 否 | 0 | ≥0 | 当前进度 | P1 |
| progress_target | number | 否 | 0 | ≥0 | 目标 | P1 |
| progress_detail | object | 否 | - | {last_event, streak_days} | 进度详情 | P1 |
| unlocked_at | date | 否 | - | ISO 字符串 | 解锁时间 | P1 |
| first_completed_at | date | 否 | - | ISO 字符串 | 首次达成时间 | P1 |
| source | string | 否 | system | 枚举(system,ops) | 更新来源 | P1 |
| createdAt | date | 是 | - | 服务端时间 | 创建时间 | P1 |
| updatedAt | date | 是 | - | 服务端时间 | 更新时间 | P1 |
3. 索引与唯一约束
- 单字段索引：
user_id,badge_code - 复合索引：
[user_id, badge_code] - 唯一性约束：
[user_id, badge_code] - 设计理由：用户徽章需要快速查询；每种徽章仅一条记录。
4. 访问控制（TCB 权限）
json
{
"read": "user_id == auth.uid || auth.role in ['ops']",
"write": "auth.role in ['badge_service','ops']"
}徽章服务负责写入；用户只读自身进度。
- 关系与级联
user_id→users- 与
events、tasks、checkins等集合通过统计逻辑关联 - 删除策略：用户注销时软删；保留匿名统计。
- 反范式：
progress_detail缓存 streak 等信息，避免实时计算。
- 数据生命周期与合规
- 留存：随账号存在；注销后保留匿名指标 180 天。
- 匿名化：导出时移除
user_id，按批次聚合。 - 审计：
createdAt、updatedAt、source。
API/云函数契约映射 | 接口/函数 | 读/写 | 使用字段 | 过滤条件 | 排序/分页 | 备注 | |
/api/badgesGET | 读 | badge_code, status, progress_value, progress_target, unlocked_at |user_id = auth.uid| - | 我的页徽章墙 | |/api/badgesPATCH | 写 | status, unlocked_at |_id| - | 补发徽章 | | 激励云函数updateBadgeProgress| 写 | badge_code, progress_value, progress_detail, status |user_id| - | 根据行为事件更新 | | 周报生成器 | 读 | status, unlocked_at, badge_code |user_id, 时间范围 | - | 周报成就区域 |示例文档（≥3条）
json
{
"_id": "badge_usr001_7d",
"user_id": "usr_001",
"badge_code": "consistency_7d",
"status": "unlocked",
"progress_value": 7,
"progress_target": 7,
"progress_detail": {"streak_days": 7, "last_event": "2024-04-06"},
"unlocked_at": "2024-04-06T23:00:00Z",
"createdAt": "2024-03-31T00:00:00Z",
"updatedAt": "2024-04-06T23:00:00Z"
}
{
"_id": "badge_usr001_support",
"user_id": "usr_001",
"badge_code": "community_support",
"status": "in_progress",
"progress_value": 12,
"progress_target": 20,
"progress_detail": {"last_event": "2024-04-05T15:35:00Z"},
"createdAt": "2024-04-01T08:00:00Z",
"updatedAt": "2024-04-05T15:35:00Z"
}
{
"_id": "badge_usr002_guardian",
"user_id": "usr_002",
"badge_code": "guardian_connect",
"status": "locked",
"progress_value": 0,
"progress_target": 1,
"createdAt": "2024-03-20T10:00:00Z",
"updatedAt": "2024-03-20T10:00:00Z"
}- 常用查询样例（≥3条）
javascript
// 用户徽章列表
const badges = await db.collection('badges').where({ user_id: auth.uid }).get();
// 统计已解锁徽章数量
const unlockedCount = await db.collection('badges').where({
user_id: auth.uid,
status: 'unlocked'
}).count();
// 运营查看某徽章解锁用户
const unlockedUsers = await db.collection('badges').where({
badge_code: 'consistency_30d',
status: 'unlocked'
}).orderBy('unlocked_at', 'desc').limit(100).get();- 边界与错误码
- 重复解锁：已 unlocked 再次更新返回
E_BADGE_ALREADY_UNLOCKED。 - 越权写入：非授权角色返回
E_FORBIDDEN。 - 进度回退：小于当前进度返回
E_BADGE_PROGRESS_INVALID。
- 变更影响评估
- 新徽章需同步
/api/badges、徽章配置文件、埋点badge_unlock。 - 索引调整影响我的页加载速度与激励统计。
- 假设与待确认
- 假设徽章配置表存放于云函数配置，待确认是否需要
badge_catalog集合。 - 待确认
progress_detail是否需记录更多维度（如来源事件列表）。
贡献者
Cai Hongyu