C端 可用能力交付文档（A/B端 为 C端 提供的后端能力清单）

出品：波波（后端主力 / B端全权 / A端）　生成时间：2026-09-26 01:55　版本：v1
读者：C端 开发（小齐 / 小冈）
数据性质：全部来自 staging 运行时实测（/openapi.json 取全量路由 → 不带 token 真调 → 记录真实状态码与响应），非静态扫代码。
⚠️ 免责：本文只描述「A/B端 后端当前真实提供了什么」，不含 C端 前端改造方案；C端 前端接线归小齐/小冈，我不代改。

一、先说结论（C端 最该知道的 5 件事）

  1. 后端目前共 495 个路由，其中 /api/miniapp/* 前缀下按业务分了 60+ 个组，C端 游客类 GET 端点 194 个。
  2. 免登录公开 31 个（实测不带 token 即 200，清单见 §三），其余 127 个需鉴权（401/403）。
  3. 响应包有两套写法，两种都要兼容：{ok:true, data, success} 和 {code:0, data, success, request_id}（见 §五）。
  4. 福钥任务 C端 仍是坏的：v2/v3 把 URL 写成商户前缀 /api/miniapp/workbench/key-tasks，游客调会拿 403/422，共 18 处未修（见 §七）。
  5. 有一个暴露面风险待裁定：/api/miniapp/promoters 免登录可拉全量分销员，含真实人名 / user_id / 商户名（见 §七）。

二、本次 A/B 端系统性检验结果（先自证后端是好的）

端检验方式结果
A端 admin-console真 Chrome 遍历 26 个业务路由（登录态，收集 console 错误 + 渲染指标）26/26 PASS，控制台错误 0
B端 b-workbench（餐饮）真 Chrome，商户 8001 真实 token4/4 PASS（菜品/桌台/订单/概览）
B端 b-workbench（分销/福钥）真 Chrome2/2 PASS（我的分销 / 福钥任务）
B端 b-workbench（零售 5 页）真 Chrome未通过验收，但属门禁生效：prod 无任何商户开通 retail 包，返回「该功能不属于您的业态包」（body 35 字符，非白屏）⇒ 零售页前端渲染目前是验收盲区
后端（staging）全量路由 × 免登录真调495 路由；公开 31 / 需鉴权 127 / 其他 36（多为 {id} 占位未填导致的 422，属预期）

顺带修的：PanelRenderer.css 从未被 import，导致 B端 工作台面板长期裸渲染（无卡片底/间距/按钮样式）——本轮已接线修复。

顺带清理的：一条验收脚本在 prod 遗留了 2 条「渲染验证-甲/乙」测试商品，已删除，prod retail_products 计数归 0。

三、免登录公开端点（31 个，实测不带 token 即 200）

这批 C端 可以不登录直接调。凡不在此清单内的，都需带 token，否则 401/403。

几个要留意的：

四、需鉴权端点（127 个 GET，按业务组）

不带 token 一律 401/403。带游客 token 后即可调（具体权限以各端点鉴权实现为准）。

merchant-console（40 个）

messages（6 个）

user（6 个）

demands（5 个）

review（5 个）

docs（4 个）

key-tasks（4 个）

merchant-applications（4 个）

orders（4 个）

packages（4 个）

admin-settings（3 个）

agent（3 个）

homestay-apply（3 个）

kora-routes-c（3 个）

scenes（3 个）

stories（3 个）

guide-profiles（2 个）

hotel（2 个）

identity（2 个）

kora-routes（2 个）

redemption-codes（2 个）

reviews（2 个）

tasks-full（2 个）

weather（2 个）

content（1 个）

emergency-contacts（1 个）

feed（1 个）

feedback（1 个）

inventory（1 个）

leader（1 个）

notifications（1 个）

pay（1 个）

points（1 个）

safety（1 个）

site-texts（1 个）

五、响应契约（实测两种包法，都要兼容）

包法 A：{ok, data, success}

{"ok": true, "data": {"served_travelers": 36, "certified_guides": 4}, "success": true, "request_id": "08231d81..."}

包法 B：{code, data, success, request_id}

{"code": 0, "data": [], "success": true, "request_id": "019b6db2..."}

实测样例（免登录，/api/miniapp/stats/trust）：

{"ok": true, "data": {"served_travelers": 36, "certified_guides": 4, "sop_cover_rate": 92,
  "insurance_gift_per_order": false, "updated_at": "2026-09-26T01:51:55.800533+08:00"},
 "success": true, "request_id": "08231d81637f"}

取值注意：

六、关键业务链路（C端 常用）

链路说明鉴权
商品浏览/api/miniapp/products、/products/search、/products/featured、/products/curated免登录
攻略/向导/api/miniapp/guides、/guides/categories、/content/guide-articles免登录
推荐/api/miniapp/recommendations、/recommendations/combo-cards免登录
天气/api/miniapp/weather/today、/weather/window（和风天气 qweather；取不到时 source="unavailable"，不得冒充来源）免登录
在地页内容/api/miniapp/content/items（A端录入）免登录
站点文案/api/miniapp/site-texts、/config/site免登录
商户检索/api/miniapp/merchants/search、/merchants/recommended免登录（无参数时返回空数组）
福钥任务后端游客路由是 /api/miniapp/key-tasks（无 /workbench）需游客 token；C端 当前 URL 写错，见 §七
分销/api/miniapp/distribution/*、/promoters需 token
订单/核销/api/miniapp/orders/*、/redemption-codes/*需 token
语音导览/api/miniapp/voice-guide/routes免登录

七、已知问题与风险（C端 对接前必读）

🔴 P0 · 福钥任务 C端 URL 前缀写错（18 处，未修）

🟠 P1 · /api/miniapp/promoters 免登录暴露真实身份信息

🟡 P2 · 零售链路前端渲染未验证（验收盲区）

🟡 P2 · A端 5 个页面存在 errAlert

ℹ️ 免登录机制说明（避免误判）

八、C端 自检方法（接完自己验一遍）

# 1. 福钥任务前缀（改完必须转绿）
python3 scripts/verify_key_tasks_c_gate.py

# 2. 前端调了后端没有的 URL（幽灵端点，真机才 404，编译期静默）
python3 scripts/check_api_url_wiring.py

# 3. 藏语字典（bo 复制 zh 假翻译）
python3 scripts/check_locale_dict.py

# 4. 改样式前先确认 CSS 不是僵尸文件（改了不生效）
python3 scripts/check_zombie_css.py

通用纪律：编译通过 ≠ 能用。tsc / vite build 对「菜单有条目但无路由」「前端调了后端没有的 URL」「僵尸 CSS」全程静默。前端改动必须真 Chrome 渲染验收 + 造数据，白屏必留 PAGEERROR。

九、本文数据的复现方式

# 全量路由（运行时，勿静态扫代码）
curl -s http://<staging>:8089/openapi.json | python3 -c "import json,sys; print(len(json.load(sys.stdin)['paths']))"

# 免登录判定：不带 token 真调，200=公开，401/403=需鉴权
curl -s -o /dev/null -w '%{http_code}' http://<staging>:8089/api/miniapp/products
本文所有状态码与响应样例均于 2026-09-26 01:50 前后在 staging（100.64.1.230:8089）实测取得。
A/B 端真机渲染验收使用 Chrome headless 打生产（a.kailashi.cn / b.kailashi.cn），商户 token 为 8001（hotel+restaurant）。