task-incentive-kickoff-20261107.md 8.4 KB

任务-激励批次 · 开工包(22 SC)

归属:契约补建计划 P0「任务-激励」· 生成 2026-11-07 01:05 数据源:sc-key-map.md(origin/cfclub,236 全量登记)· 端点核对:cfc-backend controller 源码(origin/cfclub 工作树)

批次定位

任务 → 心愿 → 勋章 → 积分/五维归因 → 家庭排行 → 活动打卡,覆盖家长/孩子/规划师/运营/AI教练/跨角色六视角;本批 22 个 SC 均无合法能力键(台账「对应能力键」列全为 —),需先定契约才能 --add-task 入池。 覆盖五段:孩子执行(任务/小游戏/心愿/勋章/打卡/积分兑换)→ 家长管理(频率/心愿审批/积分对账/排行/五维归因)→ 规划师审核与批量下发 → 运营勋章/挑战配置 → 跨角色任务激励闭环。

SC 明细

SC 角色 场景标题 建议能力键 契约接口范围 依赖 Controller
SC-A-05 平台运营 勋章配置 CRUD admin.badge.manage /api/badges/create、/api/badges/update、/api/badges/delete、/api/admin/challenge-score-config/list、/api/admin/challenge-score-config/update BadgeController、AdminChallengeScoreConfigController
SC-B-07 AI成长教练 个性化任务/饮食推荐与采纳 coach.recommend.adopt /api/food/recommendation、/api/meal、/api/tasks FoodRecommendController、MealRecommendController、TaskController
SC-C-02 孩子 执行任务 / 小游戏得积分 task.child.execute /api/tasks/{id}/complete、/api/tasks/{id}/start、/api/game/record TaskController、GameRecordController
SC-C-04 孩子 提心愿 wish.child.create /api/wishes/create WishController
SC-C-05 孩子 任务打卡 ⭐ task.child.checkin /api/tasks/{id}/complete、/api/daily/checkin/create TaskController、DailyCheckinController
SC-C-09 孩子 勋章墙 badge.child.wall /api/badges/member/list、/api/badges/all BadgeController
SC-C-10 孩子 勋章解锁提醒 badge.child.unlockNotice /api/badges/member/list、/api/badges/detail BadgeController
SC-C-14 孩子 任务驳回重做 task.child.rework /api/tasks/reject/{id}、/api/tasks/{id}/start TaskController
SC-C-22 孩子 商城浏览/积分兑换(孩子端消费) mall.child.exchange /api/points/exchange/product/list、/api/points/exchange/product/detail、/api/points/exchange/create、/api/points/exchange/records PointsExchangeController、MarketController
SC-C-24 孩子 小游戏/任务得分触发五维增长(仅自身可见) energy.child.trigger /api/game/record、/api/energy/* GameRecordController、EnergyController
SC-P-12 家长 任务频率/周期配置 task.parent.frequency /api/task/reminder-config/get、/api/task/reminder-config/save、/api/packages TaskReminderConfigController、TaskTemplatePackageController
SC-P-13 家长 心愿创建-审批-兑换闭环 wish.parent.closedLoop /api/wishes/create、/{id}/set-price、/{id}/approve-exchange、/{id}/exchange WishController
SC-P-14 家长 心愿驳回/失效处理 wish.parent.reject /api/wishes/{id}/reject、/api/wishes/{id}/cancel WishController
SC-P-15 家长 积分明细查看 points.parent.detail /api/points/exchange/records PointsExchangeController
SC-P-16 家长 积分流水对账 points.parent.reconcile /api/points/exchange/records、/api/tasks/statistics PointsExchangeController、TaskController
SC-P-77 家长 活动打卡/助力(营销) activity.parent.checkin /api/activity、/api/daily/checkin ActivityController、DailyCheckinController
SC-P-86 家长 成长打卡榜/家庭排行 task.parent.ranking /api/tasks/statistics/family、/api/daily-task/overview、/api/badges/ranking/family TaskController、DailyTaskController、BadgeController
SC-P-87 家长 任务完成触发五维能量按规则归因增长 task.parent.triggerFiveDim /api/tasks/{id}/complete、/api/attribution/analyze TaskController、AttributionController
SC-P-88 家长 心愿兑换扣减五维能量(余额不为负) wish.parent.exchangeDeduct /api/wishes/{id}/exchange、/api/energy/deduct-for-wish WishController、EnergyController
SC-T-06 成长规划师 家庭任务审核 task.guide.review /api/tasks/pending-review、/api/tasks/{id}/review TaskController
SC-T-18 成长规划师 批量任务下发 task.guide.batchDispatch /api/tasks/batch-complete、/api/tasks/batch-delete、/api/growth-task/batch-complete TaskController、GrowthTaskController
SC-X-05 跨角色 任务激励闭环 task.closedLoop.incentive 任务→心愿→勋章→积分→五维 全链路 全链路

建议能力键去重(22 个,22 SC 无重叠)

孩子执行(10)

  • task.child.execute
  • task.child.checkin
  • task.child.rework
  • wish.child.create
  • badge.child.wall
  • badge.child.unlockNotice
  • mall.child.exchange
  • energy.child.trigger

家长管理(8)

  • task.parent.frequency
  • task.parent.ranking
  • task.parent.triggerFiveDim
  • wish.parent.closedLoop
  • wish.parent.reject
  • wish.parent.exchangeDeduct
  • points.parent.detail
  • points.parent.reconcile

运营 / 规划师 / 跨角色(4)

  • admin.badge.manage
  • activity.parent.checkin
  • task.guide.review
  • task.guide.batchDispatch
  • task.closedLoop.incentive

开工步骤

  1. 定契约(按子域分 3 组并行评审,契约互不冲突):
    • 组 A 任务:TaskController(/api/tasks create|today|complete|start|review|history|pending-review|reject|batch-complete|batch-delete|statistics)+ DailyTaskController(overview)+ GrowthTaskController。重点写清「任务状态机」(待开始→进行中→已完成/已驳回→重做)与五维归因触发点。
    • 组 B 心愿/勋章:WishController(create|set-price|price|reject|exchange|approve-exchange|fulfill|confirm|cancel|list|pending)+ BadgeController(all|list|detail|create|update|delete|member/list|ranking/family)+ PointsExchangeController(product/list|product/detail|records)。重点写清「心愿审批-兑换」状态机与余额不为负约束。
    • 组 C 运营/积分/能量:AdminChallengeScoreConfigController、GameRecordController(record|history|leaderboard)、EnergyController(grant|deduct-for-wish|logs)、AttributionController(analyze)。重点写清「五维扣减/归因」规则来源与跨角色可见性。
  2. 契约合入 origin/cfclub → 逐组记录 sha(一组一 sha,便于分级 --design)。
  3. 映射能力键:--add-task <key> --requirement "SC-xxx:<场景标题>(tests/user-scenarios/应用场景总览.md)" --design <契约 sha>。
    • ⚠ --design 必须标注「契约已在 origin/cfclub;实现若在 feature 分支须显式说明、不得假定包路径」。
  4. 巡检派发 → 实现/测试 → 三类流证据(正常/异常/权限)→ 台账「跑通状态」标已跑通。
  5. 每组闭环后回填 sc-key-map.md「对应能力键 / 键阶段 / 跑通状态 / 三类流证据」四列。

前置/风险

  • 量中(22/216 = 10%):建议 A→B→C 顺序,A 组(任务 8 个)是主线入口,先打通可解锁 X-05。
  • SC-C-22 / C-24 跨商城/能量:积分兑换走 points/exchange 线、五维增长走 energy/attribution 线,能力键需在各自 Controller 补齐后聚合,建议拆分独立任务、不并入 mall.child 单键。
  • SC-T-18 批量下发:依赖 batch-complete/batch-delete 语义,须先明确「批量」是否含子任务递归下发,否则能力键名与实现会错位。
  • SC-B-07 依赖 AI 教练推荐流:/api/food/recommendation + /api/meal 已存在,但「采纳」动作语义(是否写回任务)尚未有契约定义,定契约前须确认推荐→任务转化规则。
  • SC-P-77 活动打卡/助力:/api/activity + /api/daily/checkin 已存在,但「助力」营销动作(分享/组队加成)属运营配置,需与 AdminActivityController 对齐,避免重复建键。
  • SC-X-05 跨角色全链路:必须等所属正向 SC 全部闭环后才能取证,放本批最后,且三类流要覆盖「家长发起 / 孩子执行 / 规划师审核」三视角。
  • SC-P-87 / C-24 涉及五维引擎:归因写入在 energy/attribution 线,能力键的两类流证据需引用五维能量批的契约 sha,避免重复建键。