docs: 支付方式配置 App 接入文档（用户端/骑手端：storePayMethods/闪送payType/骑手收款设置与确认收款）并更正闪送文档 §7.5 支付字段说明

docs/flash-delivery-app-api.md

@@ -699,7 +699,7 @@ GET /system/flashDelivery/orders?page=1&size=10&role=sender
 GET /system/flashDelivery/orders/{id}
 ```
 
-订单发件人和当前绑定的收件人均可访问。响应 `data` 直接为 App 完整订单字段，包括订单快照、三类图片数组、骑手摘要和可选的交付 PIN，不返回原始状态日志。响应不包含支付状态或支付方式字段，详情页不要展示“已付款”等支付信息。
+订单发件人和当前绑定的收件人均可访问。响应 `data` 直接为 App 完整订单字段，包括订单快照、三类图片数组、骑手摘要和可选的交付 PIN，不返回原始状态日志。订单视图含 `payType` 与 `paymentStatus`（`0` 未确认收款、`1` 骑手已确认收款）；线下转账单（`payType=6`）送达后寄件人详情额外返回 `riderBankCard`。本节原“响应不包含支付状态或支付方式字段”的说明自 2026-09-29（031 支付方式配置）起作废，接入以 [支付方式配置 App 接入文档](pay-method-config-app-api.md) 为准。
 
 ### 7.6 用户取消订单
 

docs/pay-method-config-app-api.md

@@ -0,0 +1,341 @@
+# 支付方式配置 App 接入文档
+
+本文档供用户端 App 和骑手端 App 接入支付方式配置（031）使用，以当前后端实现为准。文档只描述接口契约和业务流程，不包含 App 前端实现代码。商家 PC 端（foodie-store）与平台后台的支付方式管理页面已另行完成，不在本文档范围。
+
+> 更新时间：2026-09-29。本文覆盖 031 全量 App 侧增量：用户端结算页支付方式查询、现金自取/堂食语义、闪送支付方式与确认收款、骑手端收款方式设置与银行卡管理。
+
+当前契约要点：
+
+- 支付方式可用性由后端「平台开关 × 收款方选择 × 就绪度」三层闸门统一判定。App 一律以查询接口的返回渲染可选支付方式，不得本地写死可用性；下单提交未开放的支付方式会被后端拒绝。
+- 支付方式按「组代码 methodCode」管理，一个组可对应一个或多个 `payType` 数值；App 对用户展示自己的文案，下单时提交 `payType` 数值。
+- 用户端餐饮结算页新增匿名接口 `GET /system/storePayMethods`，替代旧版"按 bankInfo 是否有数据判断线下转账显隐"的做法；`bankInfo` 接口继续负责线下转账的收款信息内容，路径与返回结构不变。
+- 现金（payType=4）仅自取（type=1）和堂食（type=2）可用；现金订单创建后直接进入"进行中"（payStatus=1），不经"待付款"。
+- 闪送首页与报价响应新增 `payMethods` 列表；下单 `payType` 缺省为现金 4，线下转账为 6；订单视图新增 `paymentStatus`，线下转账单送达后向寄件人展示骑手收款卡。
+- 骑手端新增收款方式设置、本人银行卡管理和送达后确认收款三个能力；骑手待抢列表按骑手接受的支付方式过滤订单。
+
+## 1. 功能范围
+
+当前支持：
+
+- 平台按"商家餐饮"和"骑手闪送"两个维度独立开关支付方式；开关关闭的方式对所有相关方不可见、不可用。
+- 商家在商家 PC 端勾选自己接受的支付方式（未设置视为全部接受）；本文档的查询接口已折算该选择。
+- 线下转账的就绪度按收款方是否有启用银行卡判定；商家与骑手各自维护本人（商家为主账号）银行卡。
+- 用户餐饮结算页按门店查询可用支付方式，含就绪度标记；现金仅出现在自取/堂食场景。
+- 餐饮现金自取/堂食下单：商家接受现金时可用，订单创建后 payStatus=1，直接进入进行中。
+- 闪送下单选择现金（默认）或线下转账；骑手待抢列表按骑手接受的支付方式过滤；送达后骑手确认收款，寄件人在送达后看到骑手收款卡用于线下转账结清。
+
+当前不包含：在线支付新渠道接入、退款、找零、开票；这些仍走各自既有流程。
+
+## 2. 通用约定
+
+### 2.1 基础地址和请求头
+
+接口路径均为相对路径，实际请求地址为 `{baseUrl}{接口路径}`。
+
+| 请求头 | 必填 | 说明 |
+|---|---:|---|
+| `token` | 标注"登录"的接口必填 | App 登录后取得的 JWT。不要放在 `Authorization` 中 |
+| `Content-Type` | POST/PUT JSON 接口必填 | `application/json` |
+
+用户身份、骑手身份、商家身份均由 `token` 解析，请求体中不提交 `userId`。标注"匿名"的接口不需要 `token`，携带了也会被忽略。
+
+### 2.2 统一响应
+
+与闪送接口一致：App 必须以响应体 `code` 判断业务是否成功，不能只依赖 HTTP 状态码。`msg` 已由后端国际化，可直接用于错误提示。
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {}
+}
+```
+
+业务失败时 `code=500`，`msg` 为国际化文案；登录失效时 `code=401`。
+
+## 3. 支付方式枚举
+
+### 3.1 组代码与 payType 对照
+
+| 组代码 `methodCode` | `payType` | 含义 | 说明 |
+|---|---|---|---|
+| `COD` | `1` | 货到付款 | 默认开放，无额外就绪度要求 |
+| `CARD_OMG` | `2` / `5` | 信用卡 / Apple Pay | 同组同开同关，就绪度一致；接口按 payType 展开为两项 |
+| `LINE_PAY` | `3` | LINE Pay | — |
+| `CASH` | `4` | 现金 | 仅商家餐饮维度；且仅自取/堂食场景返回与可用 |
+| `OFFLINE_TRANSFER` | `6` | 线下转账 | 就绪度取决于收款方启用银行卡 |
+
+下单接口提交的是 `payType` 数值字符串；查询接口返回的是 `methodCode` + `payType` 成对出现，App 按 `payType` 回传。
+
+### 3.2 各端可用集合
+
+| 维度 | 可出现的组 | 说明 |
+|---|---|---|
+| 商家餐饮（用户结算页） | `COD`、`CARD_OMG`、`LINE_PAY`、`OFFLINE_TRANSFER`、`CASH` | `CASH` 仅当查询参数 `type` 为 1 或 2 且商家接受时出现 |
+| 骑手闪送（首页/报价、骑手设置） | `COD`、`LINE_PAY`、`OFFLINE_TRANSFER` | 闪送款项直达骑手，无线上卡支付组；现金为缺省支付，不在列表中 |
+
+最终可用 = 平台开关（关闭的组不返回）∩ 收款方勾选（未设置视为全部）∩ 就绪度。App 只按接口返回渲染。
+
+### 3.3 闪送订单 `paymentStatus`
+
+| 值 | 含义 |
+|---|---|
+| `0` | 骑手尚未确认收到款项（默认） |
+| `1` | 骑手已确认收到款项 |
+
+`paymentStatus` 出现在闪送用户订单列表/详情和骑手订单列表/详情中。它只表示骑手侧的线下收款确认，不发起任何在线支付或扣款。
+
+## 4. 用户端接口
+
+### 4.1 结算页可用支付方式
+
+```http
+GET /system/storePayMethods?storeId={storeId}&type={type}
+```
+
+匿名接口，无需 `token`。App 进入餐饮结算页时调用，按返回渲染支付方式列表。
+
+查询参数：
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `storeId` | 是 | 门店 ID；门店不存在时返回空数组 |
+| `type` | 否 | 订单类型：`1` 自取、`2` 堂食、`0` 外送 |
+
+响应 `data` 为数组，每项：
+
+```json
+[
+  { "methodCode": "COD", "payType": "1", "ready": true },
+  { "methodCode": "CARD_OMG", "payType": "2", "ready": true },
+  { "methodCode": "CARD_OMG", "payType": "5", "ready": true },
+  { "methodCode": "OFFLINE_TRANSFER", "payType": "6", "ready": false }
+]
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `methodCode` | string | 组代码，取值见 3.1 |
+| `payType` | string | 下单时提交的支付方式数值 |
+| `ready` | boolean | 就绪度；`false` 的项 App 不得渲染（如商家未启用银行卡的线下转账） |
+
+规则：
+
+- `type=1` 或 `2` 且商家接受现金（勾选含 `CASH` 或未设置）时，返回中追加 `{ "methodCode": "CASH", "payType": "4", "ready": true }`。
+- `type=0`（外送）或不传 `type` 时不返回现金项。老版本 App 不传 `type`，行为与旧接口完全一致。
+- 用户切换自取/堂食/外送后必须重新调用本接口刷新列表。
+- 线下转账 `ready=false` 时不渲染；`ready=true` 时渲染选项，但收款账户信息仍从 4.3 的 `bankInfo` 获取。
+
+### 4.2 餐饮下单提交支付方式
+
+下单仍走既有 `UserOrderController.createOrder`，支付方式字段的增量语义：
+
+- 提交的 `payType` 必须是 4.1 返回过的值（或老版本既有的到付/卡/LINE Pay 值）；提交后端判定不可用的方式会返回 `code=500`、`msg=该支付方式当前不可用，请更换支付方式`，订单不会创建。
+- 现金（`payType=4`）仅当订单 `type=1` 自取或 `2` 堂食且商家接受时可用；外送订单直传 `4` 一律被拒绝。
+- 现金订单创建成功后 `payStatus=1`（同到付的线下收款语义），订单直接出现在"进行中"，不会出现在"待付款"页签。
+- 现金订单的取消、售后行为与到付订单一致。
+
+### 4.3 线下转账收款信息
+
+```http
+GET /chanting/store/bankInfo?id={storeId}
+```
+
+匿名接口，路径、参数与返回结构保持不变。用户选择线下转账后，用 `data` 中的 `bankAccountName`、`bankName`、`bankAccountNo` 三字段展示收款信息；商家无启用银行卡或线下转账未开放时 `data=null`，App 隐藏收款信息区。
+
+本接口只管"转账信息内容"，选项显隐一律以 4.1 的 `ready` 为准，不要再按 `bankInfo` 是否有数据决定支付方式选项的显隐。
+
+### 4.4 闪送支付方式（既有接口增量）
+
+闪送首页 `GET /system/flashDelivery/home` 与报价 `POST /system/flashDelivery/quote` 的响应新增 `payMethods` 字段：
+
+```json
+{
+  "payMethods": [
+    { "methodCode": "OFFLINE_TRANSFER", "payType": "6", "ready": true }
+  ]
+}
+```
+
+- 列表是现金之外的可选支付方式；现金（`payType=4`）为缺省值，恒可用，不在列表中。
+- `ready=false` 的项不渲染（如当前没有启用银行卡的骑手群体时，平台仍开放线下转账，但就绪度需按返回处理；用户下单时以列表返回为准）。
+- App 按 `payMethods` 渲染选项，不要本地写死只有"现金/线下转账"两项；未来平台开放其他闪送支付方式时无需改版。
+
+创建闪送订单 `POST /system/flashDelivery/orders` 的请求体新增可选字段 `payType`：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `payType` | string | 否 | 支付方式：缺省 `4` 现金；`6` 线下转账。闪送款项直达骑手，下单后锁定，不可修改 |
+
+提交列表之外的值会被拒绝：`msg=该支付方式当前不可用，请更换支付方式`。
+
+闪送订单详情与列表新增 `paymentStatus`（见 3.3）。寄件人视角的订单详情，在线下转账单状态到达 `DELIVERED` 或 `COMPLETED` 后，额外返回 `riderBankCard`：
+
+```json
+{
+  "riderBankCard": {
+    "bankName": "台湾银行",
+    "accountNo": "123456789012",
+    "accountName": "陈骑手"
+  }
+}
+```
+
+- 仅寄件人视角、且订单 `payType=6`、状态为已送达或已完成时返回；其他情况该字段为 `null`，App 不展示。
+- 该卡片是中单骑手的启用收款卡，用于寄件人线下转账结清；转账完成由骑手确认（见 5.5），确认后 `paymentStatus=1`。
+
+## 5. 骑手端接口
+
+所有接口均要求骑手登录 `token`，且账号 `userType` 必须为 `2`；非骑手调用按无权限处理（`msg=用户已停用`）。
+
+### 5.1 查询收款方式设置
+
+```http
+GET /system/riderFlashPayMethods
+```
+
+响应 `data`：
+
+```json
+{
+  "available": [
+    { "methodCode": "COD", "payType": "1", "ready": true },
+    { "methodCode": "LINE_PAY", "payType": "3", "ready": true },
+    { "methodCode": "OFFLINE_TRANSFER", "payType": "6", "ready": false }
+  ],
+  "selected": ["OFFLINE_TRANSFER"]
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `available` | 平台闪送维度开放的支付方式全集，附就绪度；线下转账的 `ready` 表示骑手本人当前是否有启用银行卡 |
+| `selected` | 骑手当前勾选；空数组表示未设置，语义为"接受全部可用方式" |
+
+骑手设置页按 `available` 渲染勾选列表，`ready=false` 的项可展示但应标注未就绪原因（如"请先添加银行卡"）。
+
+### 5.2 保存收款方式
+
+```http
+PUT /system/riderFlashPayMethods
+```
+
+请求体：
+
+```json
+{
+  "methodCodes": ["OFFLINE_TRANSFER"]
+}
+```
+
+- `methodCodes` 内的每个值必须是 5.1 `available` 中出现过的 `methodCode`，否则返回 `msg=支付方式设置参数不合法`。
+- 空数组或传 `[]` 表示清空选择，回落"接受平台开放的全部方式"。
+- 保存成功无 `data`。保存后立即影响本人待抢列表的订单过滤。
+
+### 5.3 银行卡管理
+
+骑手本人收款卡的新增、维护。线下转账就绪度取决于是否存在 `isActive=1` 的卡。
+
+```http
+GET    /system/bankCard
+POST   /system/bankCard
+PUT    /system/bankCard
+DELETE /system/bankCard/{id}
+PUT    /system/bankCard/activate/{id}
+```
+
+查询列表响应 `data` 为数组，启用卡排在前：
+
+```json
+[
+  {
+    "id": 3,
+    "userId": 20001,
+    "bankName": "台湾银行",
+    "accountNo": "123456789012",
+    "accountName": "陈骑手",
+    "isActive": 1,
+    "createTime": "2026-09-20 10:00:00",
+    "updateTime": "2026-09-20 10:00:00"
+  }
+]
+```
+
+新增/修改请求体（新增不传 `id`，修改必传）：
+
+```json
+{
+  "id": null,
+  "bankName": "台湾银行",
+  "accountNo": "123456789012",
+  "accountName": "陈骑手"
+}
+```
+
+| 字段 | 必填 | 规则 |
+|---|---:|---|
+| `bankName` | 是 | 最长 64 字符；必须与平台字典 `taiwan_bank_list` 的银行名称完全一致，否则 `msg=银行名称不合法` |
+| `accountNo` | 是 | 最长 64 字符 |
+| `accountName` | 是 | 最长 64 字符 |
+
+规则：
+
+- 同一骑手最多 10 张卡，超出返回 `msg=最多只能保存10张银行卡`。
+- 第一张卡新增后自动启用；之后新增的卡默认停用，需调用启用接口。
+- 启用接口 `PUT /system/bankCard/activate/{id}` 会自动停用原启用卡，保证同一骑手最多一张启用卡；启用后付款方下次查询即看到新卡。
+- 删除启用卡后本人回到"无启用卡"状态，线下转账不再就绪。
+- 只能操作本人卡；操作他人卡 ID 按无权限处理。
+- 骑手订单列表按支付方式过滤后，未启用银行卡且未勾选线下转账的骑手看不到线下转账订单；启用卡并勾选后新订单立即可见。
+
+### 5.4 抢单列表的支付方式过滤（行为说明）
+
+`GET /system/flashDelivery/rider/orders` 的 `newTask` 列表按当前骑手接受的支付方式过滤：
+
+- 现金（`payType=4`）订单对所有人恒可见，不受勾选影响。
+- 线下转账订单只对"平台开放 ∩ 本人勾选（或未设置）∩ 本人存在启用银行卡"的骑手可见。
+- 骑手列表摘要的 `payType` 字段照常返回；App 可据此在订单卡片上展示"线下转账"标识，提示送达后需向寄件人收款并确认。
+
+### 5.5 确认收款
+
+```http
+POST /system/flashDelivery/rider/orders/{id}/confirmPayment
+```
+
+无请求体。`{id}` 为订单 ID（路径参数）。
+
+条件与效果：
+
+- 仅本人中单的订单；非本人订单返回 `msg=快送订单不存在或无权访问`。
+- 订单状态必须已达 `DELIVERED` 或 `COMPLETED`；未送达时返回 `msg=订单尚未送达，不能确认收款`。
+- 成功后订单 `paymentStatus` 0→1，并写入操作日志；状态推进本身不受影响。
+- 幂等：`paymentStatus` 已为 1 时重复调用仍返回成功。
+
+App 流程：线下转账单送达后，在订单详情向骑手展示"确认收款"入口（按 `paymentStatus=0` 且状态已送达/已完成显示）；点击确认成功后刷新本地 `paymentStatus`，入口变为已确认状态。现金单同样可以确认，但 App 可按 `payType` 决定是否强调该入口。
+
+## 6. 常见业务错误与处理建议
+
+| `msg` 含义 | 常见原因 | App 处理建议 |
+|---|---|---|
+| 该支付方式当前不可用，请更换支付方式 | 平台关闭、收款方未勾选、就绪度不满足，或现金用于外送订单 | 重新拉取可用支付方式列表，让用户换选 |
+| 支付方式设置参数不合法 | 骑手保存了列表之外的 `methodCode` | 重新拉取 5.1 数据后按返回值提交 |
+| 银行卡信息不合法 | 必填缺失、超长或修改时缺 `id` | 返回表单修正 |
+| 银行名称不合法 | `bankName` 不在 `taiwan_bank_list` 字典 | 银行名称必须从字典/下拉选择，不允许自由输入 |
+| 最多只能保存10张银行卡 | 卡数达上限 | 提示先删除不用的卡 |
+| 订单尚未送达，不能确认收款 | 确认收款时订单未到 `DELIVERED` | 隐藏入口，送达后再展示 |
+| 快送订单不存在或无权访问 | 确认收款时订单非本人中单或已不存在 | 返回列表并刷新 |
+| 用户已停用 | 非骑手调用骑手端接口，或账号状态异常 | 引导重新登录或联系平台 |
+| token 已过期 | 登录态失效 | 清理登录态并重新登录 |
+
+## 7. 接入验收清单
+
+- 结算页支付方式列表只按 `GET /system/storePayMethods` 的返回渲染，不本地写死；`ready=false` 的项不渲染。
+- 切换自取/堂食/外送时重新查询支付方式列表；现金项仅在自取/堂食出现。
+- 线下转账的选项显隐以 `ready` 为准；收款信息仍取自 `bankInfo`，两个接口各司其职。
+- 现金订单创建成功后直接按"进行中"展示，不出现"待付款"状态。
+- 闪送首页/报价按 `payMethods` 渲染可选支付方式，现金为缺省项；创建订单原样回传所选 `payType`，缺省不传即现金。
+- 寄件人仅在线下转账单送达/完成后展示 `riderBankCard` 三要素，其余状态不展示。
+- 骑手设置页按 `available` 渲染、按 `selected` 回显；空勾选保存后语义为"接受全部"。
+- 骑手银行卡银行名称从字典下拉选择，不允许自由输入；首张卡自动启用、多卡单启用由 activate 接口保证。
+- 骑手"确认收款"入口仅在 `paymentStatus=0` 且状态为已送达/已完成时展示；确认成功后刷新为已确认，重复点击不报错。
+- 待抢列表对线下转账订单可展示"线下转账"标识，金额文案仍为"订单金额"，不使用"收益"。
+- 所有接口以响应体 `code` 判断成功失败；`msg` 直接展示，不做本地拼接。