🕐 时效标注（2026-09-13 文档治理）：近期设计件，口径以 TASKS 现行与契约 v1.3 为准。
版本：v1.0 ｜ 日期：2026-09-02 ｜ 起草：波波（云端）｜ 状态：施工图，待义父派工口令 🟡 部分落地——①C 端四真页 ✅ 已验收（WIP-139 M0-M4，commit 419ceaf：play-scene/local-scene/scene-kora/scene-certificate）＋底座四件（WIP-136，00afca2）＋场景卡配置化（WIP-137/138，6601421）；②B 端点位任务面板 ✅ 已交付（WIP-138 M1 PointTasks）；③admin 配置端 + B 端剩余两页仍待派工（WIP-151 📋 已登记）。⇒ 本细则 §三 B 端/admin 段尚未全部施工，勿按「全落地」理解｜状态词修正 2026-09-09（波波 WIP-237 倒挂治理，刘总授权）
上位：《C端场景引擎主轴方案 v1.0》《场景玩法脑暴池 v1.0》（骨架级 ①⑤⑥ 已入本章）｜ 载体：C 端小程序 + admin 配置端 + B 端 H5 点位任务
对齐基线：迁移至 036（本细则新表从 037 起）；site_config 维度注册制；task_templates（035）家族字段 attract/instore/reputation/…
一、数据模型（027+ 新表，全部幂等建表）
1.1 场景配置（零发版扩展的载体）
scene_cards（site_config 新维度 key=scene_cards，validate 函数照注册制补 _validate_scenes）
├─ scenes[]：scene_id / 名称 / 状态(active|draft) / 排序 / 背景图 / 状态条文案组
├─ points[]：point_id / 名称 / 码牌绑定码值 / 坐标(仅展示非判定) / 叙事卡引用(内容池 id) / 关联商户(可空)
└─ 判定参数默认值（产品可在制作时覆盖，见 1.3）
1.2 游客侧表
scene_checkins 打卡流水：user_id / point_id / scene_id / checked_at / client_queue_id(离线幂等) / sync_at
scene_progress 进行中场景：user_id / scene_id / started_at / last_point_at / status(active|done|abandoned)
scene_certificates 完成证书：user_id / product_id(判定来源，见 1.3) / scene_id / serial_no / issued_at / meta(JSONB: 圈数/用时/点位集)
1.3 判定配置随产品走（义父 17:21 拍板）
products 表（既有）增列 completion_rule JSONB NULL：
{ "required_points": ["talin","drolma-la",...], // 必集点位（商户制作产品时多选）
"min_gap_days": 0, // 最少间隔天数（Camino 式，默认 0）
"tier": "loose|strict" } // loose=首尾即成 / strict=含关键点
- 规则：NULL=该产品不涉完成判定（纯商品）；证书序列号挂在 product_id——证书只发判定配置生效的产品走完的旅程
- 商户产品：B 端产品编辑页（77/88 静态稿对应页）加"完成判定配置"段；自营产品：admin 同段
二、接口契约清单（进 OpenAPI，先契约后前端）
| # | 接口 | 方法 | 说明 |
|---|
| 1 | /scenes | GET | 场景卡列表（site_config 驱动，含我的进行中状态） |
| 2 | /scenes/{id}/judge | GET | 实时判定（weather_window 按场景参数出结论） |
| 3 | /scenes/{id}/progress | GET/POST | 我的进度 / 开始·放弃 |
| 4 | /scenes/checkin | POST | 打卡提交（码值+client_queue_id 幂等；离线队列回放） |
| 5 | /scenes/certificate | GET | 我的证书列表/详情（复用 17 页数据面） |
| 6 | /notifications/badge | GET | 红点（WIP-131 共用） |
| 7 | /admin/scenes | CRUD | 场景管理（admin 二期，零发版加场景） |
| 8 | /points/{code}/task | GET | 点位福钥任务挂载查询（铁三角：商户 task_templates 触发） |
三、页面清单
C 端小程序（静态稿 92-95 → 真页）
| 静态稿 | 真页 | 内容 |
|---|
| 92 | pages/play-scene | 场景卡流+进行中卡+判定状态 |
| 93 | pages/local-scene | 在地服务方+沿线筛选 |
| 94 | pages/scene-kora | 转山进行时（判定卡/点位 timeline/叙事卡/扫码底栏） |
| 95 | pages/scene-cert | 完成证书+判定来源卡 |
B 端 H5（依赖 WIP-131 骨架）
- 商户换装卡新增"我的点位任务"面板：选预算/画面值/绑自己的码——写 task_templates，场景引擎自动挂点位（脑暴池咬合点三）
admin 配置端
- "场景管理"页：换装卡 CRUD（§1.1 schema），零发版扩展能力本体
四、玩法池升级设计（骨架级 ①⑤⑥ 进 v1.1 核心章）
① 主线任务链（业态=任务 NPC）
- 实现=task_templates 触发器绑定 scene_points：点位打卡成功 → 校验该点位商户活跃任务 → 下发福钥（走 035 既有 judge_type/四道闸，零新资金口）
- 链结构=场景卡配置里的 chapters[]（纯配置，无新表）
⑤ 一站一业（线路自动铺单）
- 场景卡增 services[] 推荐序（品类+场景过滤）→ 玩法页场景详情"你将需要"区块 → 点击落回既有品类频道/下单链（复用唯一可信设施，不新建交易流）
⑥ 业态互导
- 完成证书页尾部推荐位：完赛→温泉（下一场景卡）；温泉详情→轻量转山——推荐关系=场景卡配置 cross_sell[]，纯配置
五、板块包拆分建议（派工等义父口令）
| 包 | 内容 | 依赖 | 建议 |
|---|
| WIP-136 | 027 迁移+场景契约+C 端四真页（转山首发） | 132 码牌、124/125 内容池 | 扣子一号/二号任一 |
| WIP-137 | admin 场景管理页（配置化扩展本体） | 136 | 排 136 后 |
| WIP-138 | B 端"我的点位任务"面板（H5） | 131 骨架 | 可与 136 并行 |
六、验收锚点（各包通用）
- 打卡幂等：同 client_queue_id 重放不重复计章
- 离线：无网打卡本地暂存，恢复后自动补同步，界面状态正确
- 判定：天气窗口结论与场景参数一致；参数在 site_config 改动后即时生效（零发版验证）
- 证书：未配置 completion_rule 的产品不产生证书；serial_no 全局唯一
- 福钥：点位任务发放走 035 四道闸记录可查；无商户点位打卡零福钥
- 视觉：四真页与静态稿 92-95 逐区一致（A8 同款令牌检查）