闲言APP — 用户任务系统指南（签到 / 任务 / 勋章 合并导航）

版本: v1.0.0 | 更新时间: 2026-08-15 作者: Xianyan（闲言）团队 作用: 跨文档导航，整合"签到、每日任务、勋章"三个相互交织的系统 关联文档: - API_USER_CENTER_DOC（最权威，本系统所有接口的完整定义） - API_USER_OPERATIONS_DOC（运营视角，部分重叠） - API_ACHIEVEMENT_DOC（勋章/成就系统）

一、为什么需要这份指南？

API_USER_CENTER_DOC、API_USER_OPERATIONS_DOC、API_ACHIEVEMENT_DOC 三份文档都涉及"用户任务激励系统"，但视角不同： - USER_CENTER：产品功能完整视角（签到/任务/勋章 都有） - USER_OPERATIONS：运营视角（积分规则/排行榜/任务运营） - API_ACHIEVEMENT：专注成就系统（勋章/打卡里程碑/补签）

本指南不重复内容，仅做索引 + 跳转 + 流程图，帮 APP 端开发者：

1. 快速找到需要的接口（按"我要做什么"分组）
2. 理解三个系统之间的关系（签到→任务→勋章→积分）
3. 跳转权威文档看完整字段

二、我要做什么 → 用什么接口（导航）

2.1 签到

签到奖励规则（USER_CENTER 3.1）：

2.2 每日任务

任务类型（USER_CENTER 14.1）：

2.3 勋章 / 成就

勋章稀有度（USER_CENTER 15.1）：

三、三系统的数据关系

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│  签到系统     │ ──────► │  积分 +1 ~ 125  │ ◄────── │ 每日任务系统   │
│ (signin_*)  │         │  (score 字段) │         │  (task_*)     │
└──────┬──────┘         └──────┬───────┘         └──────┬───────┘
       │                       │                          │
       │ 连续 7/30/100/365 天    │ 完成任务 +EXP/积分         │ 完成 → 解锁勋章
       ▼                       ▼                          ▼
┌──────────────────────────────────────────────────────────────────┐
│                     勋章系统 (achievement_*)                       │
│            触发条件：连续天数 / 任务累计 / 互动次数                │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                   ┌─────────────────────┐
                   │  个人主页徽章展示     │
                   │  /api/achievement/    │
                   │  badgeDisplay         │
                   └─────────────────────┘

四、APP 端典型业务流

用户首次进入"我的"页面

1. 并行调用 3 个接口（拉数据）：
   - GET /api/user_center/signin_calendar?month=2026-08（签到日历）
   - GET /api/task/today（今日任务）
   - GET /api/achievement/badges（勋章列表 + 解锁状态）
2. 渲染 3 个卡片：签到日历 / 任务列表 / 勋章墙
3. 用户点击"签到"按钮 → POST /api/user_center/signin
   - 成功后本地更新签到日历
   - 检查返回的 continuous 天数，如果达到 7/30/100 等里程碑，提示"获得 X 勋章"
4. 用户点击"领取"任务奖励 → POST /api/task/claim
   - 成功后更新积分 + 任务 claimed 状态
5. 用户打开"勋章墙"详情 → 直接显示（已经 GET 过了）

用户设置"个人主页展示勋章"

1. 进入"勋章墙"页面，已经加载了 /api/achievement/badges（含 is_displayed 字段）
2. 用户点击某勋章的"展示"按钮
3. 前端校验：当前展示数 < 3（max_display）
4. POST /api/achievement/badgeDisplay，body: badge_ids=1,3,5
5. 成功后刷新勋章列表（更新 is_displayed 字段）

五、跨系统联动与并发注意事项

六、错误码速查（跨文档合并）

七、下一步

• 想看完整字段说明 → USER_CENTER_DOC（推荐作为权威）
• 想看运营视角（金币记录、排行榜、运营活动） → USER_OPERATIONS_DOC
• 想看勋章系统深度（打卡里程碑、补签卡、好友对比） → ACHIEVEMENT_DOC

用户运营接口（7 模块 32 接口）

基础URL: https://tools.wktyl.com
维护: Xianyan 团队 | 更新时间: 2026-08-15
跳转: 任务/勋章/签到 - 业务总览 · 用户中心 · 安全/登录

职责：运营激励体系（排行榜 / 积分 / 等级 / 任务 / 勋章 / 签到）整合入口，详细场景看 USER_TASK_GUIDE.md。

💡 签到/任务/勋章详细流程、字段定义已在 USER_TASK_GUIDE 内汇总（合并方案 B）；本文档保留各模块的端点清单与运营管理接口。

1. 通用约定

统一响应格式 {code, msg, time, data}，认证走 token（参见 USER_SECURITY §1.2）。

1.1 频率限制

2. 接口清单

2.1 排行榜

• GET /api/user_operations/rank?type=...&page=... — 总排行榜（按 type 切换：金币/学习时长/收藏/签到/勋章）
• GET /api/user_operations/rank/week — 周榜
• GET /api/user_operations/rank.month — 月榜
• GET /api/user_operations/myRank — 我的排名（各榜 + 距上一名差距）
• GET /api/user_operations/rankByCategory?category=poetry — 分类榜（按内容分类）

2.2 积分 / 金币

• GET /api/user_operations/coins — 当前金币余额
• GET /api/user_operations/coinHistory?type=earn|spend&page=... — 流水记录
• POST /api/user_operations/coins/signinReward — 签到金币奖励（合并到 USER_TASK_GUIDE）
• POST /api/user_operations/coins/transfer — 用户间转账（可选，未开放时返回错误）

2.3 等级

• GET /api/user_operations/level — 我的等级（当前等级/经验/距下一级）
• GET /api/user_operations/levelRules — 升级规则（公示）
• GET /api/user_operations/levelRewards — 等级奖励（解锁的皮肤/特权）
• POST /api/user_operations/claimLevelReward — 领取等级奖励

2.4 任务 / 成就（合并到 USER_TASK_GUIDE）

完整定义见 USER_TASK_GUIDE §任务系统。本文档仅保留运营查询接口：

• GET /api/user_operations/tasks/today — 今日每日任务（用户视角）
• POST /api/user_operations/tasks/claim/{task_id} — 领取任务奖励
• GET /api/user_operations/achievements/mine — 我的勋章列表
• POST /api/user_operations/achievements/claim/{id} — 领取新解锁勋章

2.5 活动 / 运营配置

• GET /api/user_operations/activeEvents — 当前生效活动列表
• GET /api/user_operations/event/{id} — 活动详情
• POST /api/user_operations/event/join/{id} — 参加活动
• GET /api/user_operations/event/{id}/rank — 活动排行榜

2.6 后台管理（需 admin 权限）

• POST /api/user_operations/admin/task/create — 创建任务（运营后台）
• POST /api/user_operations/admin/task/update — 修改任务
• POST /api/user_operations/admin/task/disable/{id} — 下架任务
• POST /api/user_operations/admin/event/create — 创建活动
• POST /api/user_operations/admin/event/end/{id} — 强制结束活动
• POST /api/user_operations/admin/coins/adjust — 手动调账（带审计日志）
• GET /api/user_operations/admin/coins/log — 调账审计日志

2.7 数据统计（管理端）

• GET /api/user_operations/admin/stats/overview — 运营总览（DAU / 任务完成率 / 勋章发放数）
• GET /api/user_operations/admin/stats/funnel — 用户漏斗
• GET /api/user_operations/admin/stats/event/{id} — 活动复盘

3. 关键示例

3.1 我的排名

GET /api/user_operations/myRank
Header: token: eyJ0eXAi...

# 响应
{
  "code": 1,
  "data": {
    "rankings": {
      "coins_week":    { "rank": 1234, "gap_to_next": 56 },
      "study_month":   { "rank": 42,   "gap_to_next": 0 },
      "checkin_total": { "rank": 8,    "gap_to_next": 12 }
    }
  }
}

3.2 手动调账（管理员，需二次验证）

POST /api/user_operations/admin/coins/adjust
Header: token: <admin_token>
Content-Type: application/json

{
  "user_id": 12345,
  "delta": 100,               // 可正可负
  "reason": "活动奖励补发",    // 必填，进入审计日志
  "two_factor_code": "123456"
}

4. 设计要点

• 运营接口与用户接口分离：所有 /admin/* 都要求 admin 权限 + 二次验证，调账强制审计日志
• 排行榜分维分时：总/周/月 + 金币/学习/签到/勋章 × N 大类，避免一个超大接口渲染所有
• 任务/勋章/签到合并到 USER_TASK_GUIDE：避免文档冗余（方案 B 整合）
• 活动是临时配置：每个活动带独立 leaderboard 与时间窗，过期自动归档
• 调账带 reason 必填：审计追溯可定位到具体运营人员与触发原因

5. 关联文档

• 用户任务指南（合并查看）
• 用户中心
• 成就系统（勋章稀有度）
• 管理后台（运营）
• 统计与分析（活跃度指标）

成就系统接口（勋章 18 类）

基础URL: https://tools.wktyl.com
维护: Xianyan 团队 | 更新时间: 2026-08-15
业务总览: USER_TASK_GUIDE §勋章系统 · 用户运营

职责：勋章定义（稀有度/分类/隐藏）+ 获得条件 + 用户勋章查询 + 后台运营 CRUD。

💡 业务逻辑（如何获得勋章、稀有度说明、游戏化设计）见 USER_TASK_GUIDE.md。本文档聚焦「接口字段 + 后台管理」。

1. 模型

1.1 解锁条件结构

{
  "type": "stat|action|combo",
  "target": "checkin_total",
  "threshold": 100,
  "window": "all_time|month|week|day",
  "extra": { /* 类型特定参数 */ }
}

支持的 type：

2. 认证 / 频率限制

• 用户端：需登录，普通 token 即可
• 后台端：需 admin 权限 + 二次验证（具体看 API_ADMIN_DOC.md）
• 用户查询：60 / 60s；后台管理：30 / 300s

3. 接口清单

3.1 用户视角

• GET /api/achievement/categories — 按分类分组的勋章列表（含已解锁/未解锁图标）
• GET /api/achievement/list?category=...&rarity=... — 勋章列表（可筛选）
• GET /api/achievement/{id} — 勋章详情（含解锁条件、解锁用户数）
• GET /api/achievement/mine — 我已解锁的勋章（公开）
• GET /api/achievement/mine/pending — 我"接近解锁"勋章（提示用户）
• POST /api/achievement/check — 检查并触发徽章解锁（系统主动调用，亦可前端触发）

3.2 用户画像

• GET /api/achievement/featured — 我"置顶展示"的勋章（用户最多选 5 个）
• POST /api/achievement/featured/set — 设置置顶列表
• GET /api/achievement/wall/{user_id} — 某用户勋章墙（公开主页）

3.3 后台管理

• POST /api/achievement/admin/create — 创建勋章
• POST /api/achievement/admin/update/{id} — 修改勋章
• POST /api/achievement/admin/disable/{id} — 下架（已解锁的不会消失）
• POST /api/achievement/admin/reissue/{id} — 补发（推送给指定用户列表）
• GET /api/achievement/admin/stats — 解锁率 / 分类分布
• GET /api/achievement/admin/leaderboard — 拥有勋章数排行

3.4 事件扩展

• POST /api/achievement/checkin — 签到触发（合并入口到 USER_TASK_GUIDE）
• POST /api/achievement/event/{event_name} — 自定义事件触发（如 "task_completed"）

4. 核心示例

4.1 我的勋章墙

GET /api/achievement/mine
Header: token: ...

# 响应
{
  "code": 1,
  "data": {
    "total": 18,
    "by_rarity": {
      "mythic":   ["绝代诗仙"],
      "legendary": ["万卷书","千日勤"],
      "epic":     [...],
      "rare":     [...],
      "common":   [...]
    },
    "featured": ["千日勤", "百日勤"]  // 我置顶的 5 个以内
  }
}

4.2 后台创建勋章

POST /api/achievement/admin/create
Header: token: <admin_token>
{
  "name": "百日勤",
  "description": "连续签到 100 天",
  "rarity": "epic",
  "category": "学习",
  "is_hidden": false,
  "icon": "https://cdn.xianyan.cc/badge/100d.png",
  "condition": {
    "type": "stat",
    "target": "checkin_streak",
    "threshold": 100,
    "window": "all_time"
  }
}

5. 设计要点

• 稀有度配色统一：common(灰) / rare(绿) / epic(蓝) / legendary(紫) / mythic(金)，前端 CSS 自动渲染
• is_hidden = 严格保护：未解锁用户查不到任何信息（连 name 都隐藏），防止攻略泄露
• 解锁条件结构化：放在 JSON condition 字段，支持定时任务定期扫描 + 实时触发（用户行为时）
• 后台可下架但不可删除：保留历史用户的勋章历史，下架仅阻止新解锁

6. 关联文档

• 任务/勋章/签到 - 业务总览
• 用户运营（勋章领取入口）
• 管理后台
• 统计与分析（勋章解锁数据）