v3 后端缺口盘点 与 v3/v4 分期对接方案 v1

起草:小冈(方案岗)| 2026-09-27 | 状态:待刘总拍板两处(§五)
事实基线:波波《C端可用能力交付文档 v1》(495 路由实测)+ v3 前端消费面 grep 实盘 + backend 路由注册清单

一、事实基线

结论:不存在「为新版提前准备后端」的大工程;真实缺口 6 项,其中仅 1 项需新开发端点。

二、缺口清单(6 项)

#项性质等谁
1情报/摆渡券购买态判定端点🔴 唯一新开发派工(契约见 §三)
2券单 SKU→多 SKU(voucher.packageId → packages 数组或读 intel.packageId/ferry.packageId)🟡 A端配置层,零代码运营录入
3福钥任务 URL 前缀 P0(v3 8 处 /api/miniapp/workbench/key-tasks → /api/miniapp/key-tasks,游客现 403/404)🟠 前端字面量修复波波(清单:docs/福钥任务-前后端接线修复清单-波波.md;验收 verify_key_tasks_c_gate.py 现 FAIL 18)
4/auth/phone/bind 生产部署🟠 重启容器刘总口令
5/api/miniapp/promoters 免登录暴露真实 user_id/姓名/价目🟠 安全裁定刘总裁定(加鉴权/脱敏/维持)
6微信支付通道⚪ 代码已备(miniapp_pay: prepay/notify/status 三端点),缺商户凭据刘总凭据

三、唯一新端点契约(#1)

GET /api/miniapp/orders/purchased?packageIds=7084,7085
鉴权:必须(get_current_user)
响应:{code:0, data:{purchased:[7084], pending:[], redeemed:[]}}
判定:orders 存在且 status 有效(pending 视业务=已购待付线下→情报应解锁,口径待刘总一句话)
零新表:只读 orders + order_items,不建任何表(刘总 09-26 二纠纪律)
验收三例实调:未购=[] / 已购pending=情报解锁 / 已核销=情报仍解锁(买断型不回收)

四、v3/v4 分期对接(前端开关驱动,后端单代码库永不分叉)

开关载体:content_items 键 v3.featureFlags(JSON),经已建的 config_governance 发布/回滚;C 端 app.ts 启动读一次缓存。

形态:{"tabs":{"play":false},"entries":{"intel":true,"ferry":true},"pay":{"online":false}}

期放开内容后端依赖门禁
P1 上线版四 tab 六页(现状)零新增提审过
P2 内容深化玩法回 tab + 情报/摆渡解锁#1 #2真机三例验收
P3 交易开通线上支付(房型/商品)#6 凭据涉钱 staging 人工 review(铁律4)
P4 增长放开分销/福钥/零售/语音/护照#3 + 零售真机渲染验收(波波 P2 盲区)逐域三件套
P5 治理收口暴露面按裁定收敛#5安全复测

放开粒度=域,每域三件套:flag 放开 + 该域真机验收 + 回执登记。禁按页碎放。

诚实说明:藏页面≠缩端点,31 个免登录端点 v3 期仍暴露;收敛=后端鉴权改造,默认不做,列裁定项。

五、待拍板(2 项)

  1. 端点 #1 派给谁:波波(正试炼 C 端,顺)或阿仁(后端核心岗)
  2. 暴露面默认不收敛,可否

附录 A:v3 前端 API 消费面(37 路径)

auth/login · auth/phone/bind · calendar/upcoming · distribution/{activate,commissions,profile,register,share-code} · feedback · guides · guides/categories · hotel/room-types · key-tasks/balance · merchants · messages · messages/read-all · messages/unread · orders · products · products/featured · recommendations/combo-cards · redemption-codes · reviews · user/{footprints,info,passport,wishlist} · voice-guide/{play-records,routes} · weather/today · workbench/key-tasks{,/balance,/claims/,/ledger,/mine}


v1.1 增补(2026-09-27 刘总裁定:所有券必须核销,核销留痕为佣金唯一依据)

不变量

核销主体按履约形态(数字履约一条待刘总确认)

履约形态核销主体channel / operator现状
住宿/套餐/摆渡(物理)商户扫码online 或 offline_* / 商户操作人已有流程,摆渡 7085 挂 8031 直接可用,零新开发
情报包(数字)系统自动写核销(解锁同事务)online / system:auto-unlock🟡 待建(小改动);待刘总确认主体语义

佣金闸门改造(涉钱→staging+人工 review,铁律4)

购买态端点契约修订


v1.2 增补(2026-09-27 刘总纠正:平台支付通道早就能用;小冈只读核验后修正)

事实核验(ssh 只读,未动生产)

修正

  1. P3 改名「订单域支付接通」(原「等凭据」表述作废):接真实统一下单调用(复用 service-fee wxpay_client 抽象)+补三配置+生产重启+一分钱实付验证;定金形态(deposit_fen 已建)同批通电,A端按商品配定金比例
  2. 免费下单形态不立(零预付下单=既有 offline 轨;0 元单污染佣金与统计)
  3. 小额加购(情报/摆渡)随主单同批次到店结算;情报包单独线上直购走 P3 接通后
  4. 派工:WIP-277(核销裁定)完工后小冈接 WIP-278 支付接通(刘总令看代码能力第二考场)