docs(收付款): 接入文档补上「门店与订单」通道

接入文档页新增第 10、11 章，侧边栏最后一条「门店与订单」。

三条内容上的决定：

- 一个条目，不是十一条。第 10 章开头那张差异表（金额单位、幂等性）必须先读，
  拆成 10.1~10.5 会让读者直接跳到下单那一节。
- 通道一律用中性名。这几章是给租户看的，整章里没有任何上游厂商名。
- 切片靠标题原文匹配：take("## 10. …") 会一并吞掉其下的所有 ### 子块，
  所以不能改写成「## 10 + 各 ### 分开列」—— 那样差异表会被重复渲染五次。
  这是 collectionDoc.ts 里那条注释存在的原因，别当成冗余删掉。

frontend/src/views/module_payment/apikey/collectionDoc.ts

@@ -100,6 +100,15 @@ const SECTIONS: Array<{ key: string; title: string; parts: string[] }> = [
     title: "联调与常见问题",
     parts: ["## 8. 联调检查清单", "## 9. 常见问题"],
   },
+  // 另一条通道（/payment/openapi/har）。整章只给一个条目，不再拆成 10.1~10.5 ——
+  // 章首那张差异表（金额单位、幂等性）必须先读，拆开会让读者直接跳到 10.2 下单。
+  // 注意：`take("## 10. …")` 会一并吞掉其下所有 `###` 子块，所以这里**不能**改写成
+  // 「## 10 + 各 ### 分开列」—— 那样差异表会被重复渲染五次。
+  {
+    key: "har_endpoints",
+    title: "门店与订单",
+    parts: ["## 10. 门店与订单接口", "## 11. 门店与订单通道的联调检查清单"],
+  },
 ];
 
 export const collectionSections: Record<string, CollectionDocSection> = Object.fromEntries(

frontend/src/views/module_payment/apikey/docs/collection-openapi.md

@@ -1,7 +1,7 @@
 # 收付款 OpenAPI 接入文档
 
 > 适用对象：接入本平台「收付款」能力的商户 / 服务商技术对接人员
-> 版本：v1　|　最后更新：2026-09-22
+> 版本：v1　|　最后更新：2026-09-24
 
 本文档描述的是**本平台对外提供的接口**。你只需要按本文档实现，不需要、也不会接触到平台内部的任何实现细节。
 
@@ -9,7 +9,9 @@
 
 ## 1. 概述
 
-平台提供四类能力，共 7 个接口：
+平台提供五类能力，共 10 个接口，分属**两条通道**。
+
+**收付款通道 —— 路径前缀 `/payment/openapi/pay`（详解见 5）**
 
 | 能力 | 场景 | 接口 |
 |---|---|---|
@@ -21,7 +23,15 @@
 | 退款 | 发起退款 | `POST /payment/openapi/pay/refund` |
 | 退款 | 退款查询 | `POST /payment/openapi/pay/refund/query` |
 
-所有接口均为 **POST + JSON**，请求体必须带签名。
+**门店与订单通道 —— 路径前缀 `/payment/openapi/har`（详解见 10）**
+
+| 能力 | 场景 | 接口 |
+|---|---|---|
+| 门店 | 创建门店 | `POST /payment/openapi/har/shop/create` |
+| 收款 | 下单收款（被扫 / 主扫由 `auth_code` 决定） | `POST /payment/openapi/har/order/create` |
+| 查询 | 订单查询 | `POST /payment/openapi/har/order/query` |
+
+所有接口均为 **POST + JSON**，请求体必须带签名。两条通道的**认证与签名算法完全相同**（第 2、3 章对两者都适用），但**响应信封、金额单位、状态取值不同** —— 跨通道搬代码前，请先读 10 章开头的那张差异表。
 
 ---
 
@@ -33,7 +43,7 @@
 |---|---|
 | `api_key` | 你的身份标识，放在 `Authorization` 头 |
 | `api_secret` | 签名密钥，**只用于本地计算签名，任何情况下都不上网传输** |
-| 商户号 | 该 `api_key` 名下，每一个收款主体（企业）对应的商户号，下单时用 `enterprise_id` 指定 |
+| 商户号 | 该 `api_key` 名下可用的商户号。**一个租户可以有多个**：只有一个时什么都不用传，有多个时下单/建店/查单都要用 `merchant_code` 指定（见 10 章） |
 
 还需向平台方提供一个**回调地址**（`notify_url`），或在下单时逐笔传入。
 
@@ -237,7 +247,7 @@ attach=table-1&auth_code=280812345678901234&enterprise_id=ENT10001&order_body=%E
 }
 ```
 
-**B 型 —— 其余四个接口**用统一信封：
+**B 型 —— 其余接口**（`order/query`、`order/close`、`refund`、`refund/query`，以及 10 章的 3 个接口）用统一信封：
 
 ```json
 {
@@ -260,7 +270,7 @@ attach=table-1&auth_code=280812345678901234&enterprise_id=ENT10001&order_body=%E
 |---|---|---|
 | 参数校验失败（缺字段、金额非正、单号超长、**多了不认识的字段**等） | **400** | `{"code":400,"msg":"字段名: 具体原因", ...}` |
 | 认证 / 签名失败 | **401** | `{"code":10401,"msg":"...", ...}` |
-| 业务逻辑错误（订单不存在、状态不允许、退款超余额等） | **200** | `{"code":404 或 400 或 500,"msg":"...", ...}` |
+| 业务逻辑错误（订单不存在、状态不允许、退款超余额、无权操作该企业等） | **200** | `{"code":404 或 400 或 403 或 500,"msg":"...", ...}` |
 | 路径不存在（URL 拼错） | **404** | `{"code":404,"msg":"接口不存在", ...}` |
 | 服务端未预期异常 | **500** | `{"code":500,"msg":"服务器内部错误", ...}` |
 
@@ -284,7 +294,8 @@ attach=table-1&auth_code=280812345678901234&enterprise_id=ENT10001&order_body=%E
 | `0` | 成功 |
 | `400` | 参数错误，`msg` 会指明是哪个字段 |
 | `401` | 认证上下文缺失（正常情况下由 10401 覆盖，此码防御性保留） |
-| `404` | 订单 / 退款单不存在，或不属于你的 `api_key` |
+| `403` | 无权操作指定的企业（10 章专用，见 10 章开头） |
+| `404` | 订单 / 退款单不存在，或不属于你的 `api_key`；10 章里还包括「商户编号不存在或不属于你」 |
 | `500` | 业务处理未成功（如关单未生效、撤销被拒），**可重试** |
 | `10401` | 认证失败：缺少 `Authorization` / `Signature` 头、API Key 无效或已过期、签名验证不通过 |
 
@@ -722,3 +733,281 @@ Content-Type: application/x-www-form-urlencoded
 
 **Q：回调丢了怎么办？**
 平台最多重试 8 次。之后请主动调用 5.4 订单查询。建议你在自己的系统里对长时间处于 `CREATED` / `PAYING` 的订单做轮询兜底。
+
+---
+
+## 10. 门店与订单接口
+
+本章是**另一条通道**，路径前缀 `/payment/openapi/har`，与 5 章的收款接口不是同一个接口族。
+
+**相同的部分**：请求头与签名算法（3.2 / 3.3 逐字适用）、错误处理总则（3.6）、`enterprise_id` 的含义（2）。
+
+**不同的部分 —— 动手前先读完这张表**：
+
+| 项 | 5 章收款接口 | 本章 |
+|---|---|---|
+| 路径前缀 | `/payment/openapi/pay` | `/payment/openapi/har` |
+| 响应信封 | 三个下单接口 A 型，其余 B 型 | **3 个接口全部 B 型** |
+| `enterprise_id` | 必填 | **选填**：不传即按租户账号寻址，见下 |
+| 金额 | 整数，单位**分** | 小数，单位**元** |
+| 订单状态 | 文本枚举（`SUCCESS` / `PAYING`…），见 6 | **数字字符串**（`"0"` / `"1"`…），见 10.5 |
+| 下单幂等 | 同 `out_trade_no` 重发返回原单 | **不幂等**，每次调用都新建一笔，见 10.2 |
+| 退款 | 有（5.6 / 5.7） | **本章没有退款接口** |
+
+> ⚠️ **「不幂等」与「金额单位是元」这两条最容易出事。** 前者会让你在超时重发时收到两笔扣款，后者会把 1 元写成 1 分。请读完 10.2 的注意框再动手。
+
+**关于 `enterprise_id`**：本章三个接口的 `enterprise_id` **都是选填**。
+
+- **不传** ⇒ 平台按**你这条 API Key 所属的租户账号**寻址，取该租户名下由平台运营报备好的商户配置。租户下只有一个收款主体、也只配了一个商户号时，这是最省事的用法。
+- **传了** ⇒ 按该企业寻址，该企业必须已在平台完成商户报备，否则返回 `code=403`、`msg` 为 `无权限操作该企业`（平台有意不区分「这个企业不存在」与「不属于你」，避免被用来探测他人企业）。
+
+两种方式**并存**，不是替代：一个租户下有多个收款主体、需要分开记账时才传。**同一个租户下，两者的商户号是分开报备的** —— 之前一直不传的调用方，不要在某一笔里突然传一个从未报备过的 `enterprise_id`。
+
+**关于 `merchant_code`（新增，2026-09-24）**：平台**允许一个租户报备多个商户号**（例如你名下有多家门店主体，各自独立结算）。这时「这笔钱收进哪一个商户」必须由你在请求里说清楚，用 `merchant_code` 指定。
+
+- **不传** ⇒ 平台按顺序匹配：先看 `enterprise_id`，再看你租户下的商户配置。
+- **传了** ⇒ 一律以它为准（它**优先于** `enterprise_id`），且必须是你租户名下已报备的编号，否则返回 404。
+
+> ⚠️ **你租户下配了多个商户号、而你又不传 `merchant_code` 时，接口会直接**拒绝**（`code=400`，`msg` 为 `当前租户配置了多个商户编号，请在请求中指定 merchant_code`），不会替你挑一个。**这是有意的** —— 挑错了钱会进另一个商户的账户，而且全程没有任何报错，要等到对账才发现。**只配了一个商户号的调用方不受影响**，什么都不用改。
+
+> **怎么知道自己配了几个**：登录平台，在「商户配置」页可以看到你名下的全部商户号。三个接口都填同一个 `merchant_code` 即可。
+
+**门店与下单的关系**：10.2 里的 `shop_code` / `third_shop_code` 都是**选填**。门店不是下单的前置条件 —— 只有需要把交易归属到某个具体门店时才填。
+
+---
+
+### 10.1 创建门店
+
+为你的一个线下门店建号。平台侧**没有门店查询接口**，本接口的返回就是你日后核对门店状态的依据，请把 `shop_id` 存下来。
+
+```
+POST /payment/openapi/har/shop/create
+```
+
+**请求**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `enterprise_id` | string | 否 | 门店归属的企业标识。**不传即按你的租户账号寻址**，见本章开头 |
+| `merchant_code` | string | 否 | **你租户下配了多个商户号时必填**：门店建在哪一个商户下，见本章开头。只配了一个的不用传 |
+| `third_shop_id` | string | 是 | 你方的门店编码，≤32 字符。**同一个归属下不可重复**，见下 |
+| `shop_name` | string | 是 | 门店名称，≤128 字符 |
+
+**响应**（B 型，`data` 内）
+
+| 字段 | 说明 |
+|---|---|
+| `third_shop_id` | 原样返回 |
+| `shop_name` | 原样返回 |
+| `shop_id` | 平台门店编号，**建号成功才有值**；下单时作为 `shop_code` 传入 |
+| `create_status` | 建号结果，见下 |
+| `enterprise_id` | 归属企业。**按租户寻址建立的门店，这里是空的** |
+| `merchant_code` | 平台侧为该企业（或该租户）配置的商户编号（你无需关心，原样带回） |
+| `fail_reason` | `create_status` 非 `SUCCESS` 时的原因 |
+| `created_time` / `updated_time` | 记录时间 |
+
+`create_status` 取值：
+
+| 值 | 含义 | 你该做什么 |
+|---|---|---|
+| `SUCCESS` | 门店已建好，`shop_id` 可用 | 保存 `shop_id` |
+| `FAILED` | 明确被拒，不会建号 | 看 `fail_reason`，改好再调一次 |
+| `PENDING` | **结果未知** —— 调用超时或网络失败，无法确认门店是否已经建出来 | **不要直接重发**（可能建出两个门店），联系平台方人工核实 |
+
+> ⚠️ **`third_shop_id` 重复会被直接拒绝，而不是「返回原有门店」。** 同一个归属下重复提交同一个 `third_shop_id`，返回 `code=500`，`msg` 形如 `门店编码已存在: <你的编码>`。所以本接口的正确幂等做法是**先查你本地的记录，再决定要不要调**，而不是无脑重发。
+>
+> 这里的「归属」就是上面说的两条寻址路径：**传了 `enterprise_id` 的按企业查重，不传的按租户查重**，两者互不干扰。也就是说，同一个 `third_shop_id` 在「你租户下」和「你某个企业下」可以各存在一份 —— 如果你两边都在用，请自己保证编码不要混。
+
+> ⚠️ **`PENDING` 不是「处理中」。** 门店创建**不自动重试** —— 重试可能在上游建出两个门店。收到 `PENDING` 时唯一正确的动作是找平台方核实，不要自行重发。
+
+---
+
+### 10.2 下单收款
+
+同一个接口承担两种场景，由 `auth_code` 是否有值决定：
+
+| `auth_code` | 场景 | 行为 |
+|---|---|---|
+| **有值** | 被扫 —— 用户出示付款码，你扫码后把码传进来 | 立即发起扣款 |
+| **不传** | 主扫 —— 平台返回一条收款链接，你渲染成二维码给用户扫 | 只下单，等用户付款 |
+
+```
+POST /payment/openapi/har/order/create
+```
+
+**请求**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `enterprise_id` | string | 否 | 收款企业标识。**不传即按你的租户账号寻址**，见本章开头 |
+| `merchant_code` | string | 否 | **你租户下配了多个商户号时必填**：这笔钱收进哪一个商户，见本章开头。它**优先于** `enterprise_id` |
+| `price` | number | 是 | 金额，**单位元**，必须 > 0。与 5 章的「整数分」不同，见下 |
+| `title` | string | 是 | 商品名称，≤64 字符 |
+| `trade_type` | string | 是 | `alipay_payment` 支付宝支付 / `alipay_stage` 花呗分期 |
+| `out_biz_no` | string | 否 | 你自己的订单号，≤64 字符，原样存下供你查询 |
+| `auth_code` | string | 否 | 用户的付款码。有值走被扫，不传走主扫 |
+| `stage_num` | string | 否 | 分期期数：`3` / `6` / `12` / `24`。`trade_type=alipay_stage` 时必填 |
+| `percent` | string | 否 | 分期手续费承担方：`100` 商户承担 / `0` 用户承担。`trade_type=alipay_stage` 时必填 |
+| `shop_code` | string | 否 | 平台门店编号（10.1 返回的 `shop_id`） |
+| `third_shop_code` | string | 否 | 你方门店编码，≤32 字符 |
+| `pay_timeout` | int | 否 | 支付过期时间，取值 2–60（单位由上游定义，平台原样透传） |
+| `extra_params` | string | 否 | 透传字段 |
+
+**响应**（B 型，`data` 内）
+
+| 字段 | 说明 |
+|---|---|
+| `order_no` | **平台订单号**，后续查询（10.3）用它 |
+| `out_biz_no` | 原样返回 |
+| `upstream_order_no` | 上游订单号。下单成功才有值，下单超时时为空 |
+| `platform_trade_no` | 平台交易号，支付成功后才有值 |
+| `pay_url` | **主扫**：收款链接，渲染成二维码即可。**被扫**：为空 |
+| `trade_status` | 订单状态，见 10.5 |
+| `price` | 订单金额（元） |
+| `title` / `trade_type` / `stage_num` / `percent` | 原样返回 |
+| `shop_code` / `third_shop_code` | 原样返回 |
+| `trade_time` | 支付成功时间 |
+| `rcv_amount` | 实收金额（元），支付成功后有值 |
+| `fee_amount` / `channel_amount` | 手续费 / 渠道金额 |
+| `refund_time` | 退款时间。本章无退款接口，该字段恒为空 |
+| `notify_status` | 平台向你推送回调的结果，见 10.4 |
+| `created_time` / `updated_time` | 记录时间 |
+
+> ⚠️ **本接口不幂等 —— 重复调用会产生两笔订单、两次扣款。** 每次调用都会生成一个新的 `order_no` 并向上游发起一笔新的交易，平台**不做** `out_biz_no` 去重（也不做唯一约束）。超时后不要直接重发：先用 **10.3 订单查询** 按 `out_biz_no` 查一次，查到就用那一笔的结果。
+
+> ⚠️ **`price` 的单位是「元」，是小数，不是「分」。** `1.5` 表示 1 元 5 角；5 章那一套要写 `total_amount=150` 才是同样的金额。**跨通道搬代码时这是最容易错的一处。**
+
+> ⚠️ **金额的写法会直接影响签名。** 签名是对你**实际发出的那个值**做字符串化后算的（3.3），而平台把 JSON 数字读成双精度数：你写 `0.010`，平台看到的是 `0.01` —— 签名因此对不上，只会返回「签名验证失败」，不会告诉你原因。**请写成不带多余零的最简小数**（`0.01` / `1.5` / `100`），不要写 `0.010`、`1.50`。写成字符串（`"price": "0.01"`）也可以，字符串原样参与签名，最不容易出错。
+
+> ⚠️ **下单失败时本地记录仍在，不要当作「什么都没发生」。** 上游调用失败会以 `code=500` 返回（`msg` 形如 `下单失败: <原因>`），但平台**已经落了本地记录并排入了状态轮询** —— 这笔交易仍可能成功。收到失败后请用 10.3 确认，不要凭这一次返回就向用户宣称交易未发生。
+
+---
+
+### 10.3 订单查询
+
+```
+POST /payment/openapi/har/order/query
+```
+
+**请求**（`order_no` 与 `out_biz_no` **至少提供一个**；都提供时以 `order_no` 为准）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `enterprise_id` | string | 否 | 企业标识。**不传即按你的租户账号寻址**，见本章开头 |
+| `merchant_code` | string | 否 | **你租户下配了多个商户号时必填**，与上面两个接口同一个值。传了就只查这个商户的订单 |
+| `order_no` | string | 二选一 | 平台订单号（10.2 响应里的 `order_no`） |
+| `out_biz_no` | string | 二选一 | 你自己的订单号 |
+
+**响应**（B 型，`data` 内）—— 字段与 10.2 的响应一致，另加：
+
+| 字段 | 说明 |
+|---|---|
+| `upstream_create_time` | 上游建单时间 |
+
+> **本接口查的是平台已记录的状态，不会当场向上游发起查询。** 订单状态由平台的任务自动收敛（下单约 30 秒后开始查，之后按退避节奏重试），所以你刚下单就查、拿到的可能仍是 `"0"`；过一会儿再查即可。
+
+> `order_no` 与 `out_biz_no` 都没传，返回 `code=500`，`msg` 为 `order_no 与 out_biz_no 至少填一个`。
+
+> ⚠️ **查不到订单时返回的是 `code=500`，不是 `404`。** 这与 5.4 的行为不同。`msg` 为 `订单不存在`。**不属于你的企业的订单也返回同一个 `msg`** —— 平台有意不区分「不存在」与「不属于你」，避免被用来探测他人订单是否存在。
+
+---
+
+### 10.4 回调通知
+
+订单状态变化时，平台会向你推送一条回调。
+
+**回调地址取自你这把 API Key 上配置的 `return_url`**（未配置时退回该租户的默认回调地址）。**没配就不会推送**，此时只能靠主动查询（10.3）拿结果。
+
+```
+POST <你的 return_url>
+Content-Type: application/x-www-form-urlencoded
+```
+
+**请求体**（表单编码，三个字段）：
+
+| 字段 | 说明 |
+|---|---|
+| `notify_id` | 本次通知的唯一 ID，可用于去重 |
+| `timestamp` | 平台发出通知的时间，Unix 毫秒 |
+| `content` | **JSON 字符串**，业务内容见下（注意：是字符串，需要再解析一次） |
+
+`content` 示例：
+
+```json
+{
+  "third_order_no": "HAR1234567890",
+  "out_biz_no": "T20260924001",
+  "order_no": "2026092499001",
+  "platform_trade_no": "2026092499002",
+  "merchant_code": "M0001",
+  "third_shop_code": "S001",
+  "price": 1.50,
+  "title": "测试商品",
+  "trade_type": "alipay_payment",
+  "status": "1",
+  "trade_time": "2026-09-24T10:30:00+08:00",
+  "refund_time": null,
+  "rcv_amount": 1.50,
+  "fee_amount": 0.01,
+  "channel_amount": 1.49
+}
+```
+
+金额字段是 **JSON 数字**（不是字符串）；时间字段是 **ISO-8601 带时区偏移**的字符串。
+
+> ⚠️ **回调里的 `order_no` 与 10.2 响应里的 `order_no` 不是同一个号。**
+> 回调里的 `order_no` 是**上游订单号**（等于 10.2 响应里的 `upstream_order_no`）；
+> 回调里的 `third_order_no` 才是**平台订单号**（等于 10.2 响应里的 `order_no`）。
+> 名字是反的，但对账必须靠它们，请按这层对应关系取用。
+> **最省事的做法：始终用你自己生成的 `out_biz_no` 作主键做幂等，不要依赖这两个 `order_no`。**
+
+**你方需要做的**：
+
+1. **应答**：处理成功后返回 **HTTP 2xx**。返回非 2xx 视为投递失败。
+2. **去重**：同一笔订单可能收到多次通知。请用 `out_biz_no` + `status` 做幂等。
+3. **快速应答**：先应答再异步处理。平台最多尝试 3 次（失败后隔 1 秒、2 秒各重试一次），收到 4xx 时不再重试。
+
+> ⚠️ **平台只在收到上游通知时才会向你推送回调。** 若上游那条通知丢了，平台会靠自己的任务把本地状态收敛正确，但**不会**补推一条给你 —— 此时 10.3 能查到正确结果，你的回调却永远不会响。**请务必给长期停在 `"0"` 的订单做主动查询兜底。**
+
+> ⚠️ **回调不带签名。** 与 7.2 的情况相同 —— 不能仅凭收到回调就认定收款成功。请以 **10.3 订单查询** 的结果为准，把回调当作「该查了」的触发信号。
+
+---
+
+### 10.5 状态说明
+
+**`trade_status` 是数字字符串**（JSON 里带引号，不是数字）：
+
+| 值 | 含义 | 是否终态 |
+|---|---|---|
+| `"0"` | 等待支付 | 否 |
+| `"1"` | **支付成功，钱已到账** | 是 |
+| `"2"` | 已退款 | 是 |
+| `"4"` | 退款中 | 否 |
+| `"8"` | 交易关闭 | 是 |
+
+判断「是否收到过钱」用 `"1"` / `"2"`；判断「是否还要等」用 `"0"` / `"4"`。
+
+**门店 `create_status`**：`SUCCESS` / `FAILED` / `PENDING`，见 10.1。
+
+**订单 `notify_status`**（平台向你推送回调的结果）：
+
+| 值 | 含义 |
+|---|---|
+| `PENDING` | 尚未推送成功（含「你没有配置回调地址」这种情况） |
+| `SUCCESS` | 你方已成功接收 |
+| `FAILED` | 推送失败（对方返回非 2xx，或 3 次尝试均失败） |
+
+---
+
+## 11. 门店与订单通道的联调检查清单
+
+- [ ] 认证与签名复用 3.3 的实现，先跑通 3.4 的样例
+- [ ] `price` 用**元**、写成最简小数（不要 `1.50`、`0.010`）
+- [ ] 下单**不重发** —— 超时先查 10.3，确认没有再决定
+- [ ] `auth_code` 有值走被扫、不传走主扫，两种都测过
+- [ ] 主扫拿到了 `pay_url` 并能渲染成二维码
+- [ ] 按 `trade_status` 的**数字字符串**分支处理（`"1"` 才是钱到账）
+- [ ] 回调接口能处理表单编码，并把 `content` **再解析一次** JSON
+- [ ] 回调按 `out_biz_no` 做幂等
+- [ ] 对长期停在 `"0"` 的订单有主动查询兜底
+- [ ] 门店 `create_status` 收到 `PENDING` 时走人工核实，不自行重发