task-incentive-contractcheck-202611070117.md 13 KB

任务-激励批次 · 契约核对结论(22 SC · 防假 RED)

归属:契约补建计划 P0「任务-激励」· 核对时间 2026-11-07 01:17 开工包:docs/tdd/orchestration/task-incentive-kickoff-20261107.md(origin/cfclub @ ce8c4b4b7) 核对对象:origin/cfclub cfc-backend controller 源码(工作树 HEAD = origin/cfclub) 核对方法:类级 @RequestMapping + 方法级 @PostMapping 逐一比对,逐端点记录存在性;对字面路径缺失者定位等价实现(防假 RED:契约声明的接口范围必须能在真实源码中找到实现,而非仅按文档存在断言)

0. 结论摘要

  • 22 个 SC 契约接口范围均能在 origin/cfclub 找到真实实现,无「假 RED」缺口。
  • 端点核对范围(任务要求 10 组 Controller):全部端点存在,其中 3 处字面路径命名/归属差异,均为「语义已实现、路径不同」而非能力缺失,不影响定契约定稿。
  • 12 个指定 SC(P-13/P-14/P-15/P-16/P-88、C-09/C-10/C-22/C-24、A-05、P-77/P-86)逐条确认 「接口已实现」(详见 §2)。
  • 无新增 DB 迁移、未改动业务代码与测试文件(本批次仅新增本核对文档)。

1. 端点存在性核对表(10 组 Controller)

列:契约端点 → 实际源码端点(@RequestMapping 类级 + @PostMapping 方法级),结论。

1.1 WishController —— /api/wishes(controller/wish/WishController.java)

契约端点 实际端点 结论
create POST /api/wishes/create ✅ 存在
set-price POST /api/wishes/{id}/set-price ✅ 存在
price POST /api/wishes/{id}/price ✅ 存在
reject POST /api/wishes/{id}/reject ✅ 存在
exchange POST /api/wishes/{id}/exchange ✅ 存在
approve-exchange POST /api/wishes/{id}/approve-exchange ✅ 存在
fulfill POST /api/wishes/{id}/fulfill ✅ 存在
confirm POST /api/wishes/{id}/confirm ✅ 存在
cancel POST /api/wishes/{id}/cancel ✅ 存在
list POST /api/wishes/list ✅ 存在
pending POST /api/wishes/pending ✅ 存在
(附加) POST /api/wishes/{id}(详情) — 附加

1.2 BadgeController —— /api/badges

契约端点 实际端点 结论
all POST /api/badges/all ✅ 存在
list POST /api/badges/list ✅ 存在
detail POST /api/badges/detail ✅ 存在
create POST /api/badges/create ✅ 存在
update POST /api/badges/update ✅ 存在
delete POST /api/badges/delete ✅ 存在
member/list POST /api/badges/member/list ✅ 存在
ranking/family POST /api/badges/ranking/family ✅ 存在
(附加) grant、favorite、statistics/member — 附加

1.3 PointsExchangeController —— /api/points/exchange

契约端点 实际端点 结论
product/list POST /api/points/exchange/product/list ✅ 存在
product/detail POST /api/points/exchange/product/detail ✅ 存在
create POST /api/points/exchange/submit(方法 exchangeProduct) ⚠️ 命名差异:字面 /create 不存在,提交兑换语义由 /submit 承担,非能力缺失
records POST /api/points/exchange/records ✅ 存在
(附加) stats — 附加

1.4 EnergyController —— /api/energy

契约端点 实际端点 结论
grant POST /api/energy/grant ✅ 存在
deduct-for-wish POST /api/energy/deduct-for-wish ✅ 存在
logs POST /api/energy/logs ✅ 存在
(附加) sandbox、overview、configure、score-history、family-score-history、wealth-detail — 附加

1.5 AttributionController —— /api/attribution

契约端点 实际端点 结论
analyze POST /api/attribution/analyze ✅ 存在
adjust POST /api/attribution/adjust ✅ 存在
confirm-adjust POST /api/attribution/confirm-adjust ✅ 存在
plan POST /api/attribution/plan ✅ 存在

1.6 AdminChallengeScoreConfigController —— /api/admin/challenge-score-config(controller/admin/)

契约端点 实际端点 结论
list POST /api/admin/challenge-score-config/list ✅ 存在
update POST /api/admin/challenge-score-config/update ✅ 存在

1.7 GameRecordController —— /api/game

契约端点 实际端点 结论
record POST /api/game/record ✅ 存在
history POST /api/game/history ✅ 存在
leaderboard POST /api/game/leaderboard ✅ 存在
(附加) best、stats — 附加

1.8 ActivityController —— /api/activity

契约端点 实际端点 结论
(类级) @RequestMapping("/api/activity") ✅ 存在
(方法) list、detail、create、update、publish、end、submit-review、register、cancel-registration、my-registrations、registration-roster、checkin、checkin-review ✅ 存在

1.9 FoodRecommendController —— /api/food/recommendation

契约端点 实际端点 结论
(类级) @RequestMapping("/api/food/recommendation") ✅ 存在
(方法) index、history、by-family、caution、members、trend ✅ 存在

1.10 MealRecommendController —— /api/meal

契约端点 实际端点 结论
(类级) @RequestMapping("/api/meal") ✅ 存在
(方法) recommend、replace、log、logs、nutrition-summary ✅ 存在

2. 逐 SC「接口已实现」确认(指定 12 个)

契约接口范围见开工包 SC 明细列。凡 SC 内某端点为字面路径差异者,标注「语义等价映射」并给出真实实现端点。

SC 建议能力键 契约接口范围 核对结论 说明
SC-P-13 wish.parent.closedLoop /api/wishes/create、/{id}/set-price、/{id}/approve-exchange、/{id}/exchange ✅ 接口已实现 心愿创建-审批-兑换闭环四端点齐全
SC-P-14 wish.parent.reject /api/wishes/{id}/reject、/{id}/cancel ✅ 接口已实现 驳回 + 失效(取消)端点齐全
SC-P-15 points.parent.detail /api/points/exchange/records ✅ 接口已实现 积分明细端点存在
SC-P-16 points.parent.reconcile /api/points/exchange/records、/api/tasks/statistics ✅ 接口已实现(1 处路径映射差异) /api/points/exchange/records 存在;/api/tasks/statistics 字面不存在,实际统计端点在 TaskReminderController:POST /api/task-reminders/statistics/{memberId}、/api/task-reminders/statistics/category/{memberId}、/api/task-reminders/statistics/date/{memberId}、/api/task-reminders/statistics/family(对账所需流水 + 统计均可用,语义等价)
SC-P-88 wish.parent.exchangeDeduct /api/wishes/{id}/exchange、/api/energy/deduct-for-wish ✅ 接口已实现 心愿兑换扣减 + 能量扣减(余额不为负约束由 EnergyController.deductForWish 承担)端点齐全
SC-C-09 badge.child.wall /api/badges/member/list、/api/badges/all ✅ 接口已实现 勋章墙两端点齐全
SC-C-10 badge.child.unlockNotice /api/badges/member/list、/api/badges/detail ✅ 接口已实现 勋章解锁提醒所需列表 + 详情端点齐全
SC-C-22 mall.child.exchange /api/points/exchange/product/list、/product/detail、/create、/records ✅ 接口已实现(1 处路径映射差异) 商品列表/详情/记录端点存在;/create 字面不存在,提交兑换语义由 POST /api/points/exchange/submit 承担
SC-C-24 energy.child.trigger /api/game/record、/api/energy/* ✅ 接口已实现 /api/game/record + /api/energy(grant/deduct-for-wish/logs 等)齐全,五维触发链路可用
SC-A-05 admin.badge.manage /api/badges/create、/update、/delete、/api/admin/challenge-score-config/list、/update ✅ 接口已实现 勋章 CRUD + 挑战分配置 list/update 端点齐全
SC-P-77 activity.parent.checkin /api/activity、/api/daily/checkin ✅ 接口已实现 ActivityController(类级 /api/activity,含 checkin/register 等)与 DailyCheckinController(类级 /api/daily/checkin,含 create 等)均存在
SC-P-86 task.parent.ranking /api/tasks/statistics/family、/api/daily-task/overview、/api/badges/ranking/family ✅ 接口已实现(1 处路径映射差异) /api/daily-task/overview(DailyTaskController)与 /api/badges/ranking/family 存在;/api/tasks/statistics/family 字面不在 TaskController,实际为 POST /api/task-reminders/statistics/family(TaskReminderController),家庭排行语义等价

3. 字面路径缺失 / 归属差异清单(非能力缺口,期望值 0 缺失)

下列均为「语义已实现、字面路径命名/归属不同」,不属于「假 RED」能力缺失;契约定稿时建议将契约接口范围对齐到真实端点,避免后续 --design 标注包路径错位。

# 契约声明 实际实现 影响 SC 处置建议
1 /api/points/exchange/create POST /api/points/exchange/submit(exchangeProduct) SC-C-22 契约接口范围改用 /submit 或注明别名映射
2 /api/tasks/statistics POST /api/task-reminders/statistics/{memberId}(及 category/date/family 变体,TaskReminderController) SC-P-16 契约接口范围对齐到 TaskReminderController 统计端点
3 /api/tasks/statistics/family POST /api/task-reminders/statistics/family(TaskReminderController) SC-P-86 契约接口范围改用 /api/task-reminders/statistics/family
4 /api/growth-task/batch-complete(开工包 SC-T-18 契约前置) 不存在(GrowthTaskController 无此端点;批量完成仅 TaskController.batch-complete POST /api/tasks/batch-complete) SC-T-18 契约接口范围改用 /api/tasks/batch-complete(batch-delete 同样在 TaskController)

注:SC-T-18 不在本批 12 个「逐条确认」清单内,此处仅作为开工包全量 22 SC 端点核对的补充登记,避免定契约时误标注 growth-task/batch-complete。


4. 开工包其余 SC 端点补充核对(非逐条确认清单,供契约定稿参考)

SC 建议能力键 契约接口范围 核对结论
SC-B-07 coach.recommend.adopt /api/food/recommendation、/api/meal、/api/tasks ✅ 均存在(类级);「采纳→任务写回」规则待契约定义(见开工包前置风险)
SC-C-02 task.child.execute /api/tasks/{id}/complete、/{id}/start、/api/game/record ✅ 均存在
SC-C-04 wish.child.create /api/wishes/create ✅ 存在
SC-C-05 task.child.checkin /api/tasks/{id}/complete、/api/daily/checkin/create ✅ 均存在
SC-C-14 task.child.rework /api/tasks/reject/{id}、/{id}/start ✅ 均存在
SC-P-12 task.parent.frequency /api/task/reminder-config/get、/save、/api/packages ✅ 均存在(TaskReminderConfigController、TaskTemplatePackageController)
SC-P-87 task.parent.triggerFiveDim /api/tasks/{id}/complete、/api/attribution/analyze ✅ 均存在
SC-T-06 task.guide.review /api/tasks/pending-review、/{id}/review ✅ 均存在
SC-T-18 task.guide.batchDispatch /api/tasks/batch-complete、/batch-delete、/api/growth-task/batch-complete ⚠️ growth-task/batch-complete 不存在(见 §3#4),前两者存在
SC-X-05 task.closedLoop.incentive 全链路 ✅ 所属正向 SC 端点均已实现,待全部闭环后取证

5. 核对结论与后续动作

  1. 防假 RED 结论:本批 22 SC 契约接口范围在 origin/cfclub 均可定位到真实实现,无能力缺口;3 处路径命名/归属差异(§3#1/#2/#3)+ 1 处 SC-T-18 前置端点归属差异(§3#4),均为「语义已实现、路径不同」,契约定稿前建议在契约接口范围对齐真实端点。
  2. 定稿前置:契约三组(A 任务 / B 心愿勋章 / C 运营积分能量)在编写时,对 §3 差异端点直接采用真实端点路径;SC-B-07「采纳→任务写回」与 SC-T-18「批量递归下发」语义仍需契约定义(非端点缺口,属规则待定)。
  3. 映射能力键:12 个指定 SC 的「接口已实现」结论成立,可进入 --add-task 入池,--design 标注 origin/cfclub 契约 sha(本批契约合入后回填)。
  4. 台账回填:本核对文档合入后,sc-key-map.md 中 22 个 SC 的「对应能力键」仍为 —(待 --add-task 后回填),本批仅登记「契约接口范围已核对实现」。

核对依据:origin/cfclub @ ce8c4b4b7(开工包)+ 各 Controller 源码 @ 同 sha;核对人:TDD 契约核对会话(OpenCode)。本批未修改业务代码、测试文件、DB 迁移;仅新增本文档。