福钥任务 · 前后端接线修复清单（C端断链 + B端/A端已落地）

时效：2026-08-29 波波复核｜收件人：小齐（v2）/ 小冈（v3 + BFF）/ 阿仁（后端核对）

结论先行：C端 v2、v3 福钥任务 6 个游客端点的 URL 前缀写错（用了商户前缀 /workbench/key-tasks），断链属实，不是误报。修复＝把这 6 处前缀改回游客前缀 /api/miniapp/key-tasks。B端（商户侧）与 A端（运营只读）入口已在本轮接好。

一、后端真值（唯一权威契约）

来源：backend/app/routers/miniapp_key_tasks.py 文件头 docstring（已读源码确认）。后端有两个 router，前缀不同、受众不同：

main.py:176 两 router 均已 include_router 挂载，运行时均存在。

铁律：游客做任务＝用游客前缀（无 /workbench/）；商户建任务＝用商户前缀（带 /workbench/）。两者不能混。

二、C端断链证据（断链属实，非误报）

scripts/check_api_url_wiring.py（check_api_url_wiring 门禁）实测结果，C端调用了后端不存在的路由（幽灵端点）：

❌ /api/miniapp/workbench/key-tasks/mine           ← 游客端点，错用商户前缀
❌ /api/miniapp/workbench/key-tasks/balance         ← 游客端点，错用商户前缀
❌ /api/miniapp/workbench/key-tasks/ledger          ← 游客端点，错用商户前缀
❌ /api/miniapp/workbench/key-tasks/claims/{}/complete ← 游客端点，错用商户前缀
❌ /api/miniapp/workbench/key-tasks/{}/claim        ← 游客端点，错用商户前缀

根因：mb_router（/api/miniapp/workbench/key-tasks）里根本没有 /mine、/balance、/ledger、/claim、/claims/{id}/complete 这几个子路径（商户侧只有 list/create/detail/edit/publish/pause）。所以游客端这些调用运行时必 404（或 merchant-list 被游客调则 401/403）。

注：先前有「C端前缀实测正确、无需改动」的口头结论，本次全量 grep + 门禁复核已推翻——那条结论是误判。请以本清单为准。

断链点精确位置（v2 + v3 同构，逐文件逐行）

miniprogram-v2（8 处真实调用 + 2 处注释，合计 10 处）

• services/api/keyTasks.ts:70 apiGet('/api/miniapp/workbench/key-tasks', {limit}) → 列表
• services/api/keyTasks.ts:75 apiPost('/api/miniapp/workbench/key-tasks/' + taskId + '/claim') → 领取
• services/api/keyTasks.ts:80 apiGet('/api/miniapp/workbench/key-tasks/mine') → 我的
• services/api/keyTasks.ts:85 apiPost('/api/miniapp/workbench/key-tasks/claims/' + claimId + '/complete', …) → 完成
• services/api/keyTasks.ts:90 apiGet('/api/miniapp/workbench/key-tasks/balance') → 余额
• services/api/keyTasks.ts:95 apiGet('/api/miniapp/workbench/key-tasks/ledger', {limit}) → 流水
• services/dsl-sources.ts:21 ledger: { fn: () => apiGet('/api/miniapp/workbench/key-tasks/ledger'), … } → 流水(dsl)
• pages-sub/task-review/task-review.ts:18 apiGet('/api/miniapp/workbench/key-tasks/mine') → 我的(评测页)
• services/api/request.ts:50 * @param path 形如 '/api/miniapp/workbench/key-tasks'（注释，顺手改）
• pages/profile/profile.wxml:8 福钥额度 <- GET /api/miniapp/workbench/key-tasks/balance（注释块数据纪律，顺手改；v3 无此文件）

miniprogram-v3（7 处真实调用 + 1 处注释，结构与 v2 一致）

• services/api/keyTasks.ts:70/75/80/85/90/95（同上 6 处）
• services/dsl-sources.ts:21（ledger，同上）
• services/api/request.ts:50（注释）

三、修复清单（给小齐/小冈，机械替换即可）

改法：把上述文件里的字面量 /api/miniapp/workbench/key-tasks 全部替换为 /api/miniapp/key-tasks（去掉 /workbench 段）。其余路径（子路径 /mine、/balance、/ledger、/claim、/claims/{id}/complete）保持不变。

• v2 改 8 处真实调用 + 2 注释；v3 改 7 处真实调用 + 1 注释；合计 18 处。
• 唯一真源＝门禁 scripts/verify_key_tasks_c_gate.py（当前 FAIL 18，改完应 PASS 0）。
• 改完跑 python3 scripts/verify_key_tasks_c_gate.py，应 GATE PASS（0 处）。

（不要用 check_api_url_wiring.py 验这项——它只抓 404 幽灵端点，而本 bug 是受众错：

/api/miniapp/workbench/key-tasks 在商户 router 里真实存在，游客调只拿 403/422，不报 404，旧脚本看不见。）

• 字段契约无需改：keyTasks.ts 的 FuyueTask / MyFuyueTask / FuyueBalance / FuyueLedgerItem 等接口与后端 router 返回字段一致（camelCase）。

本清单只指出问题与修法，不代改 C端代码（C端归小齐/小冈）。修复后由 C端 真机验收（见第五节）。

四、B端 / A端 已完成（波波本轮落地，供对账）

B端（商户建福钥任务）— 已接好

• 页面 b-workbench/src/pages/KeyTasks.tsx（列表 / 创建 / 上架下架 / 详情统计），调商户前缀 /api/miniapp/workbench/key-tasks，响应包 {ok, data}，失败诚实降级 + 重试按钮。
• 入口三处接实（已跑 check_pack_wiring.py 四路全绿、无孤儿路由）：
• b-workbench/src/App.tsx:32 import + :169 <Route path="/key-tasks">
• b-workbench/src/pages/Workbench.tsx:71 QUICK_ACTIONS 九宫格「🔑 福钥任务」
• b-workbench/src/utils/business-pack.ts:92 BASE_ROUTES 恒开（跨业态营销，不进 entitlement）
• b-workbench/src/pages/Workbench.css:25 九宫格网格 4→5 列
• 校验：4 个文件 esbuild 语法全过；check_pack_wiring.py ✅ 四路接线一致。

A端（运营只读总览）— 已接好

• 后端 backend/app/routers/admin_distribution.py:778 GET /api/admin/distribution/key-tasks（按目的地隔离，L2 经营数据只读，不写不删；响应 {code:0, data:{items,total}}）。
• 前端 admin-console/src/pages/KeyTasks.tsx（状态筛选 + 表格：商户/任务/奖励/状态/领取/参与/有效期）。
• 入口：admin-console/src/App.tsx:94 路由 + admin-console/src/components/Layout.tsx:106 NAV_GROUPS「福钥任务」（只读条幅由 L2 moneyReadOnly 渲染）。
• 修复一处契约 bug：A端 页原读 env.data（数组），后端实际返回 env.data.items ⇒ 已改为 env.data?.items。否则表格空渲染。esbuild 已复验通过。

五、C端修复后验收步骤（小齐/小冈）

1. staging 环境（services/api/request.ts 切 ENV.staging，开发者工具勾「不校验合法域名」，需 Tailscale 内网）。
2. 跑 check_api_url_wiring.py → 过滤 key-task 应 0 个 ❌。
3. 游客登录 → 福钥任务列表（GET /api/miniapp/key-tasks）出现任务卡；领取→我的→完成→余额/流水全链路打通。
4. 边界：断网重试、空数据空态、重复领取幂等，对照 docs/miniprogram-v2/福钥任务-验证清单.md 逐条打勾。

六、唯一剩余风险（非断链，是数据缺口）

prod 当前零真实商户、零真实福钥任务数据（仅有 test 商户）。即使 C端 前缀修好，游客列表仍可能为空——这是「没建任务」的数据缺口，不是接线问题。修复优先级：先让 1~2 个真实商户在 B端 建任务，游客端才有内容可验。

七、待办 / 不在本范围

• MyDistribution（分销）属 WIP-307 另一块，本次未做（非福钥指令范围）。
• v1（miniprogram，09-17 已停更）41 条断链低优先级，未纳入本次修复。
• 部署：B端/A端 改动待 git push main → 自动 staging；需义父拍板后执行。