结论先行

🕐 时效标注（2026-09-13 文档治理）：近期设计件，口径以 TASKS 现行与契约 v1.3 为准。

distribution/me 不建议新增 FastAPI 业务端点。建议由 BFF 提供稳定的 /api/v2/distribution/me，内部适配现有 /profile，前端不要直接绑定上游命名。
distribution/bind 不应简单映射到 /register 或 /activate。方案 B v2.2 是“商户发起邀请/绑定，分销员手机号匹配后激活”，所以前端应删除“游客主动绑定”动作，改成“查看邀请状态 / 注册 / 激活”。
按你贴出的清单，首页推荐、天气、运输、护照、历程、转山、SOS 主流程大多已有候选后端端点，但尚未接入新版；六个非运输品类的商品列表、SOS 联系人管理、提现/佣金等，未看到明确端点。
目前“前端实测 25 个端点、后端覆盖 17 个、真 404 2 个”还差 6 个端点的归类。这 6 个不能直接算缺失，可能是直连 FastAPI、BFF 未映射、HTTP Method 不一致、鉴权失败或动态路径未纳入统计。
现有 32 条 BFF 映射只能说明当前局部功能，不足以支撑 92 页完整数据化，也不足以覆盖 306/307 的完整分销业务，尤其是佣金、提现、邀请/激活状态。

一、两个真缺失的处理方案

1. `GET /api/miniapp/distribution/me`

建议

采用：

新版前端
  -> GET /api/v2/distribution/me
  -> BFF 转发/适配上游 GET /profile

不建议让新版前端直接改成上游 /profile，原因是：

/profile 可能是通用用户资料，不一定是分销员资料；
后续上游命名或返回结构变化会直接影响 C 端；
新旧小程序并存，BFF 应承担兼容和字段归一化；
之前已经发生过 share-code 字段错位，继续让前端直连上游会放大此类问题。

前端处理

前端逻辑应消费一个明确的分销员状态模型，例如：

{
  "isDistributor": true,
  "status": "pending",
  "distributorId": "xxx",
  "merchantId": "xxx",
  "inviteId": "xxx",
  "inviteExpireAt": "2025-01-01T00:00:00Z",
  "shareCode": "xxx",
  "commissionBalance": "0.00"
}

具体字段不必照搬上游，但至少要明确：

none       未注册为分销员
pending    商户已邀请/绑定，等待手机号匹配或激活
active     已激活
rejected   被拒绝
disabled   已停用

是否需要后端新增 `/me`

不是必需。

只有在现有 /profile 无法表达以下信息时，才需要补充上游接口或扩展 /profile：

当前分销员状态；
关联商户；
邀请/绑定记录；
激活所需信息；
分销码；
可提现余额或结算状态。

优先选择“扩展现有 /profile 或由 BFF 聚合”，不建议为了路径好看单独复制一套 /me 业务逻辑。

2. `POST /api/miniapp/distribution/bind`

不建议的做法

不要做以下映射：

POST /distribution/bind
  -> POST /register

或：

POST /distribution/bind
  -> POST /activate

因为这会把三个不同语义混在一起：

动作	语义
register	分销员注册/建立分销员身份
activate	已有商户邀请或 pending 关系后，完成激活
bind	游客主动选择并绑定某个商户

按方案 B v2.2，第三种“游客主动 bind”不是产品语义。

前端需要改什么

分销员端

删除或隐藏：

主动绑定商户
输入商户邀请码后立即绑定
任意游客点击“绑定分销员”

改为：

查看分销员状态
查看待激活邀请
输入/确认手机号
注册
激活
查看激活失败原因

状态展示建议：

状态	前端行为
未注册	展示“注册成为分销员”或“等待商户邀请”
pending	展示“已收到商户邀请，等待手机号匹配/激活”
active	进入分销员工作台
rejected	展示拒绝原因和重新申请规则
disabled	展示停用原因，不允许继续提现/接任务

商户端

商户工作台增加或确认以下动作：

邀请/关联分销员
查看 pending 分销员
取消邀请
启用/停用分销员
查看绑定手机号是否匹配

你给出的清单中有：

GET/其他 /api/miniapp/workbench/distributors
... /api/miniapp/workbench/distributors/:id/status

但仅凭路径看不出是否支持“创建邀请/绑定”。如果只有列表和状态修改，没有创建动作，则这里仍然需要补后端命令端点。

对旧版本的兼容

由于旧版和新版并存，建议：

新版彻底移除 bind 调用；
BFF 不要让 bind 产生隐式激活；
如果旧版仍会调用 /bind，可以保留一个兼容入口，但只返回明确业务错误，例如：

{
  "code": "INVITE_REQUIRED",
  "message": "请先由商户发起分销员邀请"
}

不要让旧接口绕过 pending/手机号匹配流程。

二、92 页中需要后端能力但尚未调用的页面

以下判断以你贴出的可见端点为准。你提供的文本路径数量明显少于“350 个端点”，且没有 HTTP Method、参数和响应结构，因此下表是“候选覆盖关系”，最终需要用实际 Network Trace 和 OpenAPI 再确认。

页面与端点对应关系

功能域/页面	可见后端端点	判断	前端动作
首页推荐	`/api/miniapp/recommendations`、`/recommendations/combo-cards`	后端已有候选	接首页推荐位、组合卡片、降级空态
首页天气	`/api/miniapp/weather`、`/weather/full`、`/weather/today`、`/weather/window`	后端已有	确认首页到底调用哪个，统一城市/经纬度参数
首页服务分类	`/api/miniapp/services/categories`	后端已有	用于首页品类入口，但不是商品列表
首页内容/信任	`/stories`、`/stories/:id`、`/stats/trust`、`/site-texts`	后端已有候选	接动态故事、信任数据、运营文案
运输列表	`/transport`	后端已有	直接接入
运输详情	`/transport/:id`	后端已有	直接接入
租车列表/详情	未看到明确端点	暂判缺口	增加专用端点或统一商品服务
餐厅列表/详情	未看到明确端点	暂判缺口	同上
向导列表/详情	未看到明确端点	暂判缺口	同上
徒步列表/详情	可能与 `/routes` 有关，但语义未确认	待核对	不要直接把路线接口当商品接口
套餐列表/详情	未看到明确端点	暂判缺口	增加商品目录接口
门票列表/详情	未看到明确端点	暂判缺口	增加商品目录接口
酒店列表/详情	未看到明确端点	暂判缺口	增加商品目录接口
护照	`/user/passport`	后端已有候选	接入个人护照数据
历程/足迹	`/user/footprints`	后端已有候选	接入足迹、按时间/地点分页
徽章/成就	`/user/medals`	后端已有候选	接入获得状态、进度
清单	`/user/checklist`、`/user/checklist/:id`	后端已有候选	确认 GET、完成/取消完成语义
转山路线	`/routes`、`/routes/:id`	后端已有候选	接路线列表和路线详情
转山进度	`/scenes/:id/progress`、`/scenes/checkin`、`/today/kora-trackers`	可能已有	核对是否真的是转山业务，而非通用场景任务
转山证书	`/scenes/certificate`	后端已有候选	确认生成条件和幂等性
SOS 一键求助	`/safety/sos`、`/safety/sos/:id/cancel`	主流程可能已有	接创建、当前状态、取消
SOS 联系人	未看到 `/safety/contacts` 等端点	暂判缺口	如果页面支持联系人增删改查，需要补接口
健康信息	`/safety/health`	后端已有候选	接健康档案或出行前健康信息
安全评估	`/safety/assessment`	后端已有候选	接评估问卷/结果
文化内容	`/stories`、`/stories/:id`	后端已有候选	动态内容可接，纯展示页可继续静态
会员	未看到明确会员端点	暂判缺口	核对是否被 `/user/info` 或其他未贴端点覆盖
地址	未看到地址 CRUD	暂判缺口	下单必需，建议优先核对
住宿申请	未看到明确端点	暂判缺口	若属于本期业务，需要补
需求广场	未看到明确端点	暂判缺口	若支持发布、报名、状态流转，需要补
订单链	贴出的清单未看到订单/支付端点	严重待核对	必须用实际调用和完整 OpenAPI 核对

重点判断

1. 首页推荐和天气

后端已有明显对应：

GET /recommendations
GET /recommendations/combo-cards
GET /weather
GET /weather/full
GET /weather/today
GET /weather/window

这里大概率不是后端缺接口，而是前端尚未接入，或 BFF 尚未映射。

需要额外核对：

推荐是否支持首页不同模块；
推荐内容是否区分登录/未登录；
天气按城市还是经纬度查询；
天气接口是否有缓存；
无定位权限时的默认城市；
天气接口失败时是否允许首页正常展示。

2. 品类页商品列表

这是目前最明显的业务缺口之一。

/services/categories 只能解决：

有哪些品类
品类名称
图标
排序
是否可用

不能自然解决：

某品类商品列表
商品详情
价格
库存
可售时间
筛选/排序
分页
位置
服务商
上下架状态

运输已有：

/transport
/transport/:id

但租车、餐厅、向导、徒步、套餐、门票、酒店在可见清单中没有明确的列表/详情接口。

建议优先评估是否采用统一商品接口，例如：

GET /api/miniapp/services/{category}
GET /api/miniapp/services/{category}/{id}

其中 category 可以是：

transport
rental
restaurant
guide
hiking
package
ticket
hotel

如果不同品类字段差异很大，也可以保留独立接口，但必须统一分页、价格、图片、可售状态和错误结构。

3. 护照、历程、转山

这些不是后端完全没有，而是前端尚未接入。

可见候选端点：

/user/passport
/user/footprints
/user/medals
/user/checklist
/routes
/routes/:id
/scenes/:id/progress
/scenes/checkin
/scenes/certificate
/today/kora-trackers

建议不要仅凭名称直接绑定页面，要确认以下语义：

/routes 是旅游路线、徒步路线，还是转山路线；
/scenes 是文化打卡、福钥任务，还是转山场景；
checkin 是否需要 GPS、照片或时间窗口；
progress 是用户进度还是路线总体进度；
证书生成是否幂等；
足迹是否和订单、打卡、路线完成关联；
护照是否需要分页或增量同步。

4. SOS 联系人

现有：

/safety/sos
/safety/sos/:id/cancel

看起来可以支持：

发起 SOS
查询或返回 SOS 状态
取消 SOS

但没有看到：

GET    /safety/contacts
POST   /safety/contacts
PATCH  /safety/contacts/:id
DELETE /safety/contacts/:id

因此要区分两种页面：

如果页面只是“一键 SOS”，当前端点可能够用；
如果页面支持紧急联系人管理，后端还缺联系人 CRUD，不能用 /user/info 临时承载。

SOS 还应确认：

是否返回当前有效求助记录；
是否支持重复点击幂等；
是否上传经纬度；
是否需要联系人快照；
是否有 active/cancelled/resolved/expired 状态；
用户无定位权限时如何处理；
取消是否需要验证码或二次确认。

三、32 条 BFF 映射是否够用

结论

对于当前“已实际调用的 25 个端点”，32 条映射可能够支撑一部分页面；但对于：

92 页新版的完整数据化；
306/307 两种角色；
分销员注册、激活、佣金、提现；
福钥任务管理；
商户邀请制绑定；

32 条不能直接认为够用。

尤其是你贴出的后端清单里，未看到明确的分销员佣金和提现端点。workbench/bills 更像商户账单或对账，不应直接当成分销员提现 API。

建议的 BFF 映射分组

A. 分销员身份和激活

BFF	上游	角色	处理
`GET /api/v2/distribution/me`	`GET /profile`	306/307	新增 BFF 适配，推荐保留前端逻辑路径
`POST /api/v2/distribution/register`	`POST /register`	307	现有上游可复用
`POST /api/v2/distribution/activate`	`POST /activate`	307	只允许 pending 邀请激活
`GET /api/v2/workbench/distributors`	`/workbench/distributors`	306	商户查看分销员
`PATCH/POST /api/v2/workbench/distributors/:id/status`	`/workbench/distributors/:id/status`	306	启停或状态变更
`POST /api/v2/workbench/distributors/invitations`	未见明确上游	306	若现有列表接口不支持创建邀请，则需补后端

B. 福钥任务

可见后端已有候选：

GET  /api/miniapp/tasks
GET  /api/miniapp/tasks-full/my
GET  /api/miniapp/tasks-full/pending-verify
POST /api/miniapp/tasks-full/publish
POST /api/miniapp/tasks-full/submit
POST /api/miniapp/tasks-full/verify
POST /api/miniapp/tasks/claim

建议映射关系：

功能	角色	上游
浏览可领取任务	307	`/tasks`
查看我的任务	307	`/tasks-full/my`
领取任务	307	`/tasks/claim`
提交任务成果	307	`/tasks-full/submit`
发布任务	306	`/tasks-full/publish`
查看待审核	306	`/tasks-full/pending-verify`
审核任务	306	`/tasks-full/verify`

需要重点确认：

tasks 和 tasks-full/my 是否是两个不同业务模型；
claim 是否幂等；
submit 是否支持图片、定位、文字等证据；
verify 是否只允许任务所属商户操作；
任务状态是否统一；
任务奖励是余额、福钥还是佣金；
任务完成后余额/流水是否实时更新。

C. 佣金和提现

在你贴出的清单中没有看到明确端点。建议后端至少提供以下逻辑能力：

GET  /distribution/commission/summary
GET  /distribution/commission/ledger
GET  /distribution/withdrawals
POST /distribution/withdrawals
GET  /distribution/withdrawals/:id
POST /distribution/withdrawals/:id/cancel
GET  /distribution/payout-account
PUT  /distribution/payout-account

不是所有端点都必须一次上线，但最低闭环需要：

余额
可提现金额
提现申请
提现记录
提现详情/状态
失败原因

不要把以下接口直接当成分销员提现：

/workbench/bills
/workbench/bills/:id/confirm
/workbench/bills/:id/dispute

它们从命名上更接近商户账单确认和争议处理。

D. BFF 设计建议

前端统一调用：

/api/v2/*

BFF 负责：

上游路径适配；
字段 snake_case/camelCase 转换；
分页结构统一；
错误码统一；
306/307 角色鉴权；
上游多个接口聚合；
旧版兼容；
过期接口降级或灰度。

不要让新版同时出现：

/api/v2/*
/api/miniapp/*
FastAPI staging 直连

否则很难做环境切换、权限校验和数据对账。

四、派工岗可直接立单的清单

P0：发布阻断项

后端补充/核对

B-001：补齐分销员邀请制绑定能力

验收要求：

商户可发起分销员邀请/绑定；
生成 pending 关系；
分销员手机号匹配后才允许激活；
重复邀请、手机号不一致、邀请过期有明确错误码；
不能通过 /bind 绕过邀请制；
商户只能操作自己名下分销员。

B-002：确认 `/profile` 是否包含分销员状态

至少需要返回：

distributorId
status
merchantId
inviteId
inviteExpireAt
shareCode

如果不包含，由后端扩展 /profile 或新增内部聚合接口。

B-003：补齐六个非运输品类商品目录接口

最低能力：

列表
详情
分页
筛选
价格
库存/可售状态
上下架状态
图片
服务商

如果现有 350 端点中其实已有这些能力，应改为 BFF 映射任务，不要重复开发。

B-004：核对订单和支付完整链路

贴出的清单未出现明确的 C 端订单端点。必须确认是否存在：

创建订单
订单详情
订单列表
发起支付
支付确认/回调
支付结果
取消订单
退款或售后

如果确实没有，应作为最高优先级后端补充。

B-005：确认 SOS 联系人能力

如果新版页面支持联系人管理，补：

联系人列表
新增联系人
编辑联系人
删除联系人
默认联系人

如果只做一键 SOS，则至少确认 /safety/sos 支持定位、幂等和当前状态查询。

B-006：补齐 BFF 32 条之外的角色路由

明确 306/307 的权限矩阵：

306：商户工作台、邀请分销员、发布任务、审核任务
307：分销员注册、激活、领取任务、提交任务、查看佣金、提现

角色不能由前端传入后直接信任，应该由 token/session 或服务端关系判断。

P0：前端适配

F-001：移除新版主动 `distribution/bind`

改为：

查询分销员状态
展示 pending
注册
激活
激活失败处理

F-002：接入首页推荐和天气

接入：

/recommendations
/recommendations/combo-cards
/weather/today
/weather/window

不建议首页一次请求全部天气端点。应根据页面需求选择一个主接口，其他接口用于详情或扩展。

F-003：接入品类列表

优先顺序建议：

transport
hotel
ticket
restaurant
rental
guide/hiking
package

列表页面必须支持：

loading；
空列表；
网络失败；
分页；
商品下架；
价格缺失；
登录态差异。

F-004：补齐订单状态机

前端不能只按页面名判断订单状态，必须与后端状态枚举建立映射，例如：

created
pending_payment
paid
processing
completed
cancelled
refunding
refunded
failed

F-005：接入 SOS 主流程

至少包括：

发起前确认
定位权限处理
请求中防重复点击
当前 SOS 状态
取消
失败重试

P1：核心体验补全

后端/接口核对

护照数据；
足迹和历程；
徽章；
清单完成状态；
转山路线详情；
转山进度；
打卡；
证书；
健康档案和安全评估；
会员信息；
地址 CRUD；
住宿申请；
需求广场。

前端适配

/user/passport
/user/footprints
/user/medals
/user/checklist
/routes
/routes/:id
/scenes/:id/progress
/scenes/checkin
/scenes/certificate
/today/kora-trackers
/safety/health
/safety/assessment

这些页面可先实现“接口接入 + 空态 + 错误态”，再补动画和运营内容。

P1：306/307 分销业务

306 一号端

分销员列表
邀请/绑定分销员
查看 pending
启停分销员
发布福钥任务
查看待审核任务
审核任务
查看商户账单

307 二号端

注册
激活
查看分销员状态
查看可领取任务
领取任务
提交任务成果
查看佣金余额
查看佣金流水
提交提现
查看提现记录和状态

其中“佣金余额、佣金流水、提现”如果没有上游 API，应优先于非核心内容页补齐。

P2：静态内容页

以下页面如果当前只是内容展示，可以暂不接业务数据：

文化介绍
部分护照说明
转山知识说明
健康科普
品牌故事

但需要区分：

静态说明页
用户数据页
用户操作页

例如“转山介绍”可以静态，“我的转山进度”不能静态。

五、当前对账中还缺少的关键维度

1. 先解决数量对不上

目前数字是：

前端实际调用：25
后端已覆盖：17
实测 404：2
未归类：6

这 6 个必须单独建表，逐一标记为：

BFF 未映射
直接调用 FastAPI
路径不同但已存在
HTTP Method 不一致
鉴权失败
参数错误
动态路径未识别
实际未触发成功请求

不要把“没有在 32 条映射中”直接等同于“后端缺失”。

2. 端点级对账

每一行至少要有：

字段	示例
页面	`profile-distributor`
前端调用方	文件名/方法名
环境	preview/staging
Host	BFF 或 FastAPI
HTTP Method	GET/POST/PATCH
前端路径	`/api/v2/distribution/me`
上游路径	`/profile`
是否映射	是/否
实际状态码	200/401/403/404/422/500
鉴权角色	游客/306/307
是否幂等	是/否
负责人	前端/后端/BFF
处理结论	接入/补接口/废弃

你给的后端清单目前只有路径，没有 HTTP Method，因此无法完整判断：

POST /tasks/claim
GET /tasks/claim
PATCH /distributors/:id/status

这些业务含义完全不同。

3. 字段级对账

重点检查以下差异：

命名

shareCode       vs share_code
inviteId        vs invite_id
distributorId   vs distributor_id
createdAt       vs created_at

类型

id：number vs string
amount：分 vs 元
amount：number vs string
latitude：string vs number
isActive：boolean vs 0/1

包装结构

[]

和：

{
  "data": [],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

前端必须只依赖 BFF 统一后的结构。

空值

明确区分：

null
undefined
""
[]
{}

尤其是：

没有分销员；
没有 SOS；
没有天气；
没有护照记录；
没有佣金流水；
没有商品库存。

枚举

不要让前端自行猜状态值：

pending
PENDING
wait_activate
WAITING_ACTIVATION

应由 BFF 统一为稳定枚举，或生成共享类型。

4. 业务状态机对账

重点检查：

分销员

none -> pending -> active
pending -> expired
pending -> rejected
active -> disabled

任务

draft
published
claimed
submitted
pending_verify
approved
rejected
completed

提现

created
reviewing
approved
processing
paid
rejected
failed
cancelled

SOS

created
dispatched
processing
resolved
cancelled
expired

如果前后端状态枚举不一致，页面即使接口返回 200，也可能展示错误按钮。

5. 错误码对账

不要只按 HTTP 状态码处理。

至少建立：

INVITE_REQUIRED
INVITE_EXPIRED
PHONE_MISMATCH
ALREADY_ACTIVE
TASK_ALREADY_CLAIMED
TASK_NOT_SUBMITTABLE
INSUFFICIENT_BALANCE
WITHDRAWAL_REVIEWING
SOS_ALREADY_ACTIVE
LOCATION_REQUIRED

BFF 将上游错误归一化，前端按业务码展示，不要直接展示 FastAPI 原始英文报错。

6. 权限和数据范围

重点验证：

306 是否能查看其他商户的分销员；
306 是否能审核不属于自己的任务；
307 是否能修改其他人的任务；
用户是否能查看其他人的佣金；
pending 分销员是否能提前提现；
被停用分销员是否还能领取任务；
SOS 详情是否会泄露联系人或定位；
管理端接口是否误开放给普通 C 端。

7. 幂等、重复提交和重试

必须测试：

重复领取任务；
重复提交任务；
重复激活；
重复发起提现；
重复发起 SOS；
支付确认重复回调；
网络超时后前端重试。

特别是以下请求不应因为客户端重试产生重复数据：

activate
claim
submit
withdraw
sos
payment-confirm

8. 环境和域名对账

新版是独立域，必须确认：

新版请求是否全部走 BFF
BFF 是否允许 preview 域名
staging token 是否能访问 BFF
Cookie/Authorization 是否正确透传
上传域名是否一致
支付域名是否一致
回调域名是否一致

这类问题常被误判成“后端没有接口”。

六、建议交付给派工岗的最小产物

建议派工时要求每个接口任务同时提交：

OpenAPI 路由和 HTTP Method；
请求参数示例；
成功响应示例；
空态响应示例；
401/403/404/409/422 示例；
状态枚举表；
字段类型说明；
权限角色说明；
幂等规则；
前端调用页面和验收截图；
BFF 映射路径；
新旧版本兼容策略。

最终建议形成一张“页面—前端调用—BFF—FastAPI—字段—权限—状态码”的矩阵，而不是只维护端点路径清单。

最终建议排序

P0-1  修正分销员 me/bind 语义和 404
P0-2  查清 25 = 17 + 2 + 6 的剩余六项
P0-3  订单创建、支付、结果链路
P0-4  首页推荐、天气、核心商品目录
P0-5  SOS 主流程及联系人能力
P1-1  护照、历程、路线、转山进度
P1-2  306/307 的任务发布、领取、提交、审核
P1-3  佣金、余额、提现
P1-4  会员、地址、住宿申请、需求广场
P2    文化和其他静态内容页数据化

其中，若 306/307 是本次独立上线范围，则将“任务 + 佣金 + 提现”整体提升为该项目的 P0。