SSmartPool开放平台

设计稿,未实现,未经沙箱验收。只作接口走查,不发送真实请求。基线已有能力单独列明,不代表此设计已经落地。

设计来源:支付服务 PR #17 · 提交 7d2ae11e91ecd073944f98473ef41a67cd0f6146

支付服务(易宝同款) · 5 组 · 17 个接口
组数量编号
A 易宝同款6A1—A6
B 接收易宝通知2B1—B2
C 自有接口5C1—C5
D 运维检查2D1—D2
E 旧接口2E1—E2

用途:收银台现在在用的旧付款码收款接口,新接口上线前继续用,只修安全问题。

P8另用第7个易宝接口“交易日账单下载”(bill-trade-day-download),由后台定时任务调用,不对收银台开放,不新增第18页。P1b、P8批次暂定;对账只记录差错和告警,不自动改资金状态。

E1 · 对应易宝接口

易宝名称付款码支付
接口标识aggpay-barcode-pay
在线文档编号348be29b03b2430fa8910175524d3bb4
易宝路径 / 事件/rest/v1.0/aggpay/pay
谁调谁调用方 → 本服务
基线现状已有旧 JSON 接口;只修安全问题,不加功能
开发批次(计划)P1(拒绝带 query 的请求)

和易宝不一样的地方

  • 保留旧 JSON 请求;响应外层在固定设计稿中未明确;不是新的易宝同款业务结果格式。按门店整体切换,同一账单不能混用。

旧接口付款人信息现状与待确认

  • 现状:两者返回本服务PaymentResource,不透传易宝返回,不带付款人信息。建议不改,只加并行期回归;建议仍待产品负责人确认。

后续范围(第22节)

各角色应得金额后续采用品牌总部转账、再提现,不用余额分账,另行设计;本轮不新增相关接口或执行资金操作。第一阶段分账字段仍一律拒绝。

待定问题与有条件决定

编号 / 问题方案状态与条件影响
Q4 并行期怎么切、序号位数按门店整体切换;序号 1—6 位、不补零(第 7 节)Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效P2
Q10 `biz_no`、`order_kind`不进易宝字段,内部按 bill_no 关联(第 7 节)Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效P2
备份恢复后收款怎么重新开放 恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节)产品负责人已定 11/11 14:11(亚利桑那)P1b、部署方案
旧接口 E1、E2 的付款人信息 旧 `/api/v1/payments/auth-code`、`/api/v1/payments/query` 返回里带不带现状:不带。两者都返回本服务自己的 `PaymentResource`(基线 `c7d23d3` 的 `app/Http/Resources/PaymentResource.php`),字段是内部单号、金额、状态、`channel_trade_no_last4` 等,不透传易宝返回,没有 `payerInfo`、`userId`、`buyerLogonId` 等。建议:不用改,在并行期回归里加一条“旧接口返回不出现付款人字段”现状已核对;建议待产品负责人确认P2 回归
  • 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
  • 设计稿未给完整旧接口字段表及 PaymentResource 返回 schema;不得从新接口倒推旧协议。
  • 设计稿未展开旧接口完整响应 schema;实际返回本服务 PaymentResource,不透传易宝付款人字段。
逐条来源规则与上下文

旧接口(v1)在并行期的处理(已定,P1 落地)

- `/api/v1/payments/auth-code`、`/api/v1/payments/query` 只认签过名的 JSON body。请求只要带了 query 串,在边界层直接 422 `VALIDATION_FAILED`,`error.details.query=["query_not_allowed"]`,不进入业务、不调通道(Lihao 已确认格式)。
- 两个 FormRequest 覆盖 `validationData()`,只返回 JSON 内容;`PaymentCollections` 只从验证后的 JSON 取 `biz_no` 等字段。
- v1 待签串不变:`method\npath\nsha256(body)\ntimestamp\nnonce`。

订单号与账单关联(01:54 第 5 条)

- orderId 由 POS 生成,格式 `<bill_no>_<seq>`:`bill_no` 是 POS 的 18 位账单号(`100000000000000000—999999999999999999`),`seq` 是正整数,1—6 位、不补零(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。本服务按正则 `^([1-9][0-9]{17})_([1-9][0-9]{0,5})$` 校验并解析出 `bill_no`(账单号首位 1—9,和现有 `PaymentOrderNumbers` 一致)。
- 账单关联 subject = 应用 + 品牌 + 门店 + `bill_no`;品牌、门店由 `merchantNo` 经 C05 目录唯一映射,并核对应用授权。同账单锁、进行中保护、前代已付保护、晚到成功都按这个 subject 生效。不靠 nonce、付款码或 memo 推断同一账单。
- 序号由 POS 分配,本服务不重排、不补号;只保证同一商户下 orderId 唯一(现有 `merchant_order_id` 唯一索引)。同一账单出现跳号允许;同号不同内容 409。
- 旧接口的服务端配号(`payment_order_sequences`)只给旧接口用,旧订单编号不改、不迁移。并行期**同一张账单只能走一种接口**,否则两边分配的序号可能撞号(唯一索引会挡住,但会表现为 409)——所以并行期**按门店整体切换**:一家门店一旦切到新接口,该门店所有账单都走新接口(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。
- `biz_no`(SaaS 单号)和 `order_kind` 不在易宝字段里:第一阶段直收不需要它们参与资金计算;`biz_no` 用于账单展示和对账,由内部账单查询接口按 `bill_no` 关联,不塞进 memo(Q10 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。

### 7.1 商户结构(产品负责人 11/11 确认)

| 角色 | 是谁 | 易宝类型 | 状态 |
| --- | --- | --- | --- |
| 服务商 | 西安禾斗 | SaaS 服务商,本身不收单 | 已确认 |
| 平台商 | 品牌总部 | 服务商接入的平台商(`PLATFORM_MERCHANT`) | 已确认 |
| 入驻商户 | 品牌门店的收款账户 | 入驻商户(`SETTLED_MERCHANT`),上级是品牌总部 | 已确认 |
| 待确认 | 教练、供应链、商户池中的商户 | 未确认,**不默认成标准商户,也不默认成入驻商户** | 待确认 |

- 本服务用服务商的应用和密钥,一套服务对多个品牌;“接入应用 → 品牌 → 门店 → 商编”的授权核对照旧。
- 商编填法按易宝《产品决策》第一节和付款码、聚合码在线文档:平台商代下属入驻商户收款时,`parentMerchantNo` 是平台商编、`merchantNo` 是收款子商户;标准商户收款时两者一致,都是本商户编号。
- C05 目录里每个收款商编登记一个“发起方商编”(`parent_merchant_no`),按商编配置、不写死:
  - **默认(门店)**:发起方商编 = 品牌总部的平台商编,和 `merchantNo` 不同;关单时对应 `OPR00025`“系统商版父子商编必须不一致”的规则。
  - **另一种填法(标准商户)**:发起方商编 = 自己的商编;对应 `OPR00024`“标准版父子商编必须一致”。
  - 教练、供应链、商户池中的商户:第一阶段不收款,确认类型后再登记。
- 易宝商户角色(服务商入网接口 `businessRole`)(Claude 11/11 按官方 Skill 和在线文档核对):`ORDINARY_MERCHANT` 标准商户、`PLATFORM_MERCHANT` 平台商(入网时 `parentMerchantNo` 填服务商商编);`SETTLED_MERCHANT` 入驻商户只能挂在特定平台商下(入网时 `parentMerchantNo` 填平台商编);另有 `SHARE_MERCHANT` 分账接收方、`HEAD_CHAIN` / `BRANCH_CHAIN` 连锁总店 / 分店。
- 对账:平台商用平台商编下载的交易日账单包含平台商和下面全部入驻商户的交易;标准商户用自己的商编下载(第 20 节)。

旧接口并行与切换

- 新旧接口并存到 POS 全部切到新接口;旧接口只修安全问题(P1 拒 query),不再加功能。
- 历史订单(旧接口发起的)可以用新 GET 查单按原 `merchant_order_id` 查到;退款也可按原 orderId 发起。
- 旧接口下线时间由产品负责人定;下线前确认没有调用(看第①段日志)。
- 回滚:新接口有问题时 POS 切回旧接口;已发生的渠道扣款不随应用回滚消失,用原 orderId 查单和对账。

现有代码的保留与改动

| 现有 | 处理 |
| --- | --- |
| #12 幂等、状态证据、通知、重扫前保护、晚到成功、轮询、审计 | 保留;对外适配层新写;`PaymentResource` 只给旧接口用 |
| #13 12 秒共享预算 | 保留 |
| #14 失败 / 过期通知金额兼容 | 保留;不作为对 POS 补金额的依据 |
| #15 nonce 原子认领与清理、MySQL CI | 保留;v2 签名复用同一 nonce 认领 |
| #16 官方向量 | 保留;P3/P4 补 pay-link、refund、refund/query 向量,P1 加 v2 签名向量 |
| `YeepayClient::evidence` 成功金额取 `orderAmount` | P2 改为成功必须有可信 `payAmount` 并记录来源 |
| `UnconfiguredPaymentDirectory`(C05 未接) | 不变;装配由产品负责人 / Lihao 提供登记与 `.env` 后另行替换 |
| `config/logging.php` 只有 stderr / single | P1b 增加报文文件通道(只追加、按天、带节点标识),报文以数据库表和文件两份为准 |

待定问题与决定

11/11 产品负责人定了全部非易宝项。“产品负责人已定”立即生效;“Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效”这几条由 Lihao 在 #17 提异议,有异议就按他的意见改文档后重新复审。只有 Q15 挡 P1,其余到 P2、P4、P7 才用到。

| # | 问题 | 决定 | 状态 | 影响 |
| --- | --- | --- | --- | --- |
| Q1 | 返回业务结果对象还是完整 YOP 网关响应 | 只返回易宝业务结果对象(第 3.3、6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q2 | 是否加本服务响应签名 | 第一阶段不加(第 6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q3 | `merchantNo` 是否必填 | 必填(第 3.3 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q4 | 并行期怎么切、序号位数 | 按门店整体切换;序号 1—6 位、不补零(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q5 | `expiredTime` 范围 | 付款码 1—15 分钟、不传补 15 分钟;二维码 1—60 分钟、不传补 5 分钟(第 3.3、3.4 节) | 产品负责人已定 11/11 | P2、P3 |
| Q6 | 二维码 `scene` 默认值 | 不传时补 `{"WECHAT":"OFFLINE","ALIPAY":"OFFLINE"}`(第 3.4 节) | 产品负责人已定 11/11 | P3 |
| Q7 | 二维码换新、隐式关前代 | 去掉 `renew`,POS“关单 → 新 orderId”;不做隐式关前代,未关旧码时 409 拦住(第 3.4、10 节) | 产品负责人已定 11/11;POS 流程部分同 Q1 的异议期 | P3、P5 |
| Q8 | 退款 / 查退款定位方式 | 只按 orderId(第 3.7、3.8 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |
| Q9 | 退款失败、`SUSPEND` | 不开通补充卡信息退款;失败类都标待核、资金类告警、转人工,不自动重退、不自动结束退款(第 3.7 节) | 产品负责人已定 11/10 | P4 |
| Q10 | `biz_no`、`order_kind` | 不进易宝字段,内部按 bill_no 关联(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q11 | 付款人信息 | 不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节) | 产品负责人已定 11/11 | P1b(日志脱敏)、P7(推送) |
| Q12 | 告警接收 | 专门的 Slack 频道;接收人产品负责人、Lihao;资金类 15 分钟内响应,其他当天;webhook 只放 `.env`,P6 前提供(第 14.2 节) | 产品负责人已定 11/11 | P6 |
| Q13 | PR 顺序 | P1→P7(第 17 节);11/11 暂定加 P1b(紧跟 P1)和 P8(P7 之后) | 产品负责人已定 11/11 | 全部 |
| Q14 | 新错误码名字和 HTTP 状态 | 按第 5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 起 |
| Q15 | 签名 v2 逐字节规则 | 按第 4.3 节;`Content-Type` 只认 `application/x-www-form-urlencoded`,不带 charset | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | **P1** |
| Q16 | 第二跳是否推 `payment.unknown` | 第一阶段不推(第 11.2 节) | 产品负责人已定 11/11 | P7 |
| Q17 | 通过标准数值 | 按第 21.3 节 | 产品负责人已定 11/11 | 验收 |
| Q18 | `REFUND_IN_PROGRESS`、`REFUND_AMOUNT_EXCEEDED` | 按第 3.7、5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |
| Q19 | 第二跳推送签名 v2 | 按第 11.2 节,POS 侧同步实现 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P7 |
| 报文存储 | 报文怎么存、存多久 | 数据库+文件双写,两份都长期保留,不设清理;文件和库不同盘、每天复制到服务器外(第 13.2、13.3 节) | 产品负责人已定 11/11 | P1b、部署 |
| 报文记录批次 | 报文记录何时做 | 从 P6 提到 P1b,内部只读查询一起提前(第 17 节) | 产品负责人暂定 11/11 | P1b |
| 每日对账 | 上线前是否加对账 | 加 P8 每日对账,收真钱前置;差错只记录告警、不自动改资金状态(第 13.5 节) | 批次暂定;“不自动改状态”已定 11/11 | P8 |
| 判断顺序(11/11 复审) | `Content-Type` 不对回什么 | 统一 401,在验签前判断(第 3.2、4.3 节) | 文档前后统一,属 Q15 范围,异议期同 Q15 | **P1** |
| orderId 序号写法 | 序号能否 0 开头 | 不能,`_01` 回 422(第 3.3、7 节),与 Q4 一致 | 文档前后统一 | P2 |
| 401 原因 | 401 能否分清原因 | `details.reason` 八个取值(含 `nonce_unavailable`)、日志同一套、带 `WWW-Authenticate`;调用方自己生成一次表单字节再签名发送;向量 11 组(第 4.3 节) | Lihao 11/11 要求;名字按他举例,异议期同 Q15 | **P1** |
| 同步返回里的付款人字段 | 付款码、查单的同步返回按 Q1 原样会带上易宝给的付款人字段(`payerInfo` 等),要不要也去掉 | 去掉,清单见第 3.3 节,其余字段照旧(第 1 节第 4 处例外) | 产品负责人已定 11/11 12:49(亚利桑那) | P2 |
| 备份恢复后收款怎么重新开放 | 恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦 | 先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节) | 产品负责人已定 11/11 14:11(亚利桑那) | P1b、部署方案 |
| 旧接口 E1、E2 的付款人信息 | 旧 `/api/v1/payments/auth-code`、`/api/v1/payments/query` 返回里带不带 | 现状:**不带**。两者都返回本服务自己的 `PaymentResource`(基线 `c7d23d3` 的 `app/Http/Resources/PaymentResource.php`),字段是内部单号、金额、状态、`channel_trade_no_last4` 等,不透传易宝返回,没有 `payerInfo`、`userId`、`buyerLogonId` 等。建议:不用改,在并行期回归里加一条“旧接口返回不出现付款人字段” | 现状已核对;建议待产品负责人确认 | P2 回归 |
| 渠道交易号后 4 位放哪 | 查单是否加 | 查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节) | 文档前后统一 | P7 |
| 商户结构 | 品牌总部、门店、教练等的易宝类型 | 门店是品牌总部下的入驻商户(发起方商编 = 平台商编);按商编可配置(第 7.1 节) | 门店:产品负责人已定 11/11;教练、供应链、商户池中的商户:**待确认** | P2 配置 |
| 易宝 | 付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4) | — | **待易宝确认**(产品负责人线下问) | P2—P5、验收 |

不在本设计范围

- 分账、归集、资金方案、循环收款池、提现、余额(GPAY-04—GPAY-21 的资金类)。对账只做第 13.5 节的收款、退款逐笔核对(P8),分账账单、资金账单核对不在第一阶段。
- 公众号 / 小程序 / 支付宝预下单(GPAY-07)。
- 部署执行、采购、改服务器、开公网(部署方案另行审批)。
- 真实扣款和退款:只用易宝沙箱或测试商户。
- 入网(进件):门店、教练、供应链、商户池商户的入网走服务商入网接口,第一阶段不加接口(产品负责人 11/11)。
- 转账和提现(产品负责人 11/11):系统记录门店、教练、供应商、品牌总部各自应得的金额;到提现时间点由品牌总部按应得金额转给门店、教练、供应商,再自动提现到对方账户。后续阶段再设计;品牌总部转给对方用“转账”接口,**不用余额分账**。第一阶段收款、退款接口里的分账字段继续一律拒绝。后续会用到的易宝接口(只记出处,现在不设计):转账下单 `POST /rest/v1.0/account/transfer/b2b/order`(在线文档 `docs-v3/api/options_rest_v1.0_account_transfer_b2b_order.md`),结果通知 `account.business.transfer-result`;提现下单 `POST /rest/v1.0/account/withdraw/order`(Skill 的 `withdraw-order`)。
API REFERENCE 13.5.1.1payment-service-E1

E1 旧付款码接口支付设计

收银台现在在用的旧付款码收款接口,新接口上线前继续用,只修安全问题。

契约状态:设计稿实现状态:设计未实现;基线:已有旧 JSON 接口;只修安全问题,不加功能真实接口验收:未经沙箱验收
POST/api/v1/payments/auth-codeDESIGN ONLY · NO LIVE CALL
i
设计稿,未实现,未经沙箱验收

字段、规则、错误和有条件决定取自固定设计提交;只作展示,不运行请求或模拟成功。

  • 仅静态合成示例;设计未实现、未经沙箱验收;不启用模拟成功,不发送 HTTP。
设计稿 · 仅展示 · 不发送请求

01接口说明

业务端 / 模块支付服务(易宝同款) / E 旧接口
请求格式application/json
鉴权与权限本服务签名 v1,JSON POST只认已签名body(第4.1、12节);旧POST带query拒绝。旧 POST 下线时 v1 不能一起下线,除非内部接口也已换签名。 · 设计展示,禁止网络请求
技术服务归属(元信息)支付服务

调用方 → 本服务目录引用不授予调用权限。

来源业务约束
  • 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
  • 设计稿未给完整旧接口字段表及 PaymentResource 返回 schema;不得从新接口倒推旧协议。
  • 设计稿未展开旧接口完整响应 schema;实际返回本服务 PaymentResource,不透传易宝付款人字段。

02请求头 5 个字段

示例值为来源示例或按来源 schema 合成;子字段的必填约束在父对象出现时适用。
字段名类型必填说明与约束示例值
Content-Typestring必填来自请求体 media type枚举:"application/json""application/json"
X-SP-Instance未定义必填v1 JSON 只签 body;完整规则按来源。"SYNTHETIC_ONLY"
X-SP-Timestamp未定义必填v1 JSON 只签 body;完整规则按来源。"SYNTHETIC_ONLY"
X-SP-Nonce未定义必填v1 JSON 只签 body;完整规则按来源。"SYNTHETIC_ONLY"
X-SP-Signature未定义必填v1 JSON 只签 body;完整规则按来源。"SYNTHETIC_ONLY"

03请求参数 Body

示例值为来源示例或按来源 schema 合成;子字段的必填约束在父对象出现时适用。
字段名类型必填第一阶段处理说明与约束示例值
biz_no未定义未明确未明确易宝必填:未明确易宝必填性:未明确;第一阶段处理:未明确。第4.2节仅点名此旧 JSON 字段,未提供完整请求字段表null

04响应参数

设计稿未明确旧接口完整响应结构;不从任务卡data/meta或新接口推导旧实现。

来源没有可展开的字段定义。完整约束可在「来源与状态」查看。

05错误码 沿用来源定义

HTTP 状态来源业务码来源说明
422VALIDATION_FAILED旧 POST 带 query:error.details.query=["query_not_allowed"];只读签过名的 JSON body。

06来源与状态

契约状态:设计稿实现状态:设计未实现;基线:已有旧 JSON 接口;只修安全问题,不加功能真实接口验收:未经沙箱验收
sourceCommit7d2ae11e91ecd073944f98473ef41a67cd0f6146
查看原始契约、引用与状态记录
{
  "contract": {
    "parameters": [
      {
        "name": "X-SP-Instance",
        "in": "header",
        "required": true,
        "description": "v1 JSON 只签 body;完整规则按来源。",
        "schema": {},
        "example": "SYNTHETIC_ONLY"
      },
      {
        "name": "X-SP-Timestamp",
        "in": "header",
        "required": true,
        "description": "v1 JSON 只签 body;完整规则按来源。",
        "schema": {},
        "example": "SYNTHETIC_ONLY"
      },
      {
        "name": "X-SP-Nonce",
        "in": "header",
        "required": true,
        "description": "v1 JSON 只签 body;完整规则按来源。",
        "schema": {},
        "example": "SYNTHETIC_ONLY"
      },
      {
        "name": "X-SP-Signature",
        "in": "header",
        "required": true,
        "description": "v1 JSON 只签 body;完整规则按来源。",
        "schema": {},
        "example": "SYNTHETIC_ONLY"
      }
    ],
    "responses": {
      "default": {
        "description": "设计稿未明确旧接口完整响应结构;不从任务卡data/meta或新接口推导旧实现。"
      }
    },
    "sourceExtensions": {
      "x-permission": "设计展示,禁止网络请求",
      "x-source-sections": [
        "4.2",
        "7",
        "16",
        "18",
        "19",
        "22"
      ]
    },
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "biz_no": {
                "x-payment-required-label": "未明确",
                "x-payment-processing": "未明确",
                "x-supplier-required": "未明确",
                "description": "易宝必填性:未明确;第一阶段处理:未明确。第4.2节仅点名此旧 JSON 字段,未提供完整请求字段表"
              }
            },
            "required": []
          },
          "example": {}
        }
      }
    }
  },
  "status": {
    "contract": "设计稿",
    "implementation": "设计未实现;基线:已有旧 JSON 接口;只修安全问题,不加功能",
    "realApiAcceptance": "未经沙箱验收"
  },
  "provenance": {
    "sourceCommit": "7d2ae11e91ecd073944f98473ef41a67cd0f6146",
    "sourceBlob": "74501663abc0df79dd867f39057b29e7cd1345b3",
    "sourceUrl": "https://github.com/SmartPool-Dev/smartpool-payment-service/pull/17",
    "paymentService": {
      "code": "E1",
      "group": "旧接口并行期",
      "purpose": "收银台现在在用的旧付款码收款接口,新接口上线前继续用,只修安全问题。",
      "direction": "调用方 → 本服务",
      "supplier": {
        "name": "付款码支付",
        "id": "aggpay-barcode-pay",
        "path": "/rest/v1.0/aggpay/pay",
        "documentId": "348be29b03b2430fa8910175524d3bb4"
      },
      "phase": "P1(拒绝带 query 的请求)",
      "baselineStatus": "已有旧 JSON 接口;只修安全问题,不加功能",
      "differences": [
        "保留旧 JSON 请求;响应外层在固定设计稿中未明确;不是新的易宝同款业务结果格式。按门店整体切换,同一账单不能混用。"
      ],
      "openQuestions": [
        {
          "id": "Q4",
          "question": "并行期怎么切、序号位数",
          "decision": "按门店整体切换;序号 1—6 位、不补零(第 7 节)",
          "status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
          "impact": "P2"
        },
        {
          "id": "Q10",
          "question": "`biz_no`、`order_kind`",
          "decision": "不进易宝字段,内部按 bill_no 关联(第 7 节)",
          "status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
          "impact": "P2"
        },
        {
          "id": "备份恢复后收款怎么重新开放",
          "question": "恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦",
          "decision": "先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节)",
          "status": "产品负责人已定 11/11 14:11(亚利桑那)",
          "impact": "P1b、部署方案"
        },
        {
          "id": "旧接口 E1、E2 的付款人信息",
          "question": "旧 `/api/v1/payments/auth-code`、`/api/v1/payments/query` 返回里带不带",
          "decision": "现状:不带。两者都返回本服务自己的 `PaymentResource`(基线 `c7d23d3` 的 `app/Http/Resources/PaymentResource.php`),字段是内部单号、金额、状态、`channel_trade_no_last4` 等,不透传易宝返回,没有 `payerInfo`、`userId`、`buyerLogonId` 等。建议:不用改,在并行期回归里加一条“旧接口返回不出现付款人字段”",
          "status": "现状已核对;建议待产品负责人确认",
          "impact": "P2 回归"
        }
      ],
      "sourceSections": [
        {
          "id": "4.2",
          "title": "旧接口(v1)在并行期的处理(已定,P1 落地)",
          "body": "- `/api/v1/payments/auth-code`、`/api/v1/payments/query` 只认签过名的 JSON body。请求只要带了 query 串,在边界层直接 422 `VALIDATION_FAILED`,`error.details.query=[\"query_not_allowed\"]`,不进入业务、不调通道(Lihao 已确认格式)。\n- 两个 FormRequest 覆盖 `validationData()`,只返回 JSON 内容;`PaymentCollections` 只从验证后的 JSON 取 `biz_no` 等字段。\n- v1 待签串不变:`method\\npath\\nsha256(body)\\ntimestamp\\nnonce`。"
        },
        {
          "id": "7",
          "title": "订单号与账单关联(01:54 第 5 条)",
          "body": "- orderId 由 POS 生成,格式 `<bill_no>_<seq>`:`bill_no` 是 POS 的 18 位账单号(`100000000000000000—999999999999999999`),`seq` 是正整数,1—6 位、不补零(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。本服务按正则 `^([1-9][0-9]{17})_([1-9][0-9]{0,5})$` 校验并解析出 `bill_no`(账单号首位 1—9,和现有 `PaymentOrderNumbers` 一致)。\n- 账单关联 subject = 应用 + 品牌 + 门店 + `bill_no`;品牌、门店由 `merchantNo` 经 C05 目录唯一映射,并核对应用授权。同账单锁、进行中保护、前代已付保护、晚到成功都按这个 subject 生效。不靠 nonce、付款码或 memo 推断同一账单。\n- 序号由 POS 分配,本服务不重排、不补号;只保证同一商户下 orderId 唯一(现有 `merchant_order_id` 唯一索引)。同一账单出现跳号允许;同号不同内容 409。\n- 旧接口的服务端配号(`payment_order_sequences`)只给旧接口用,旧订单编号不改、不迁移。并行期**同一张账单只能走一种接口**,否则两边分配的序号可能撞号(唯一索引会挡住,但会表现为 409)——所以并行期**按门店整体切换**:一家门店一旦切到新接口,该门店所有账单都走新接口(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。\n- `biz_no`(SaaS 单号)和 `order_kind` 不在易宝字段里:第一阶段直收不需要它们参与资金计算;`biz_no` 用于账单展示和对账,由内部账单查询接口按 `bill_no` 关联,不塞进 memo(Q10 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。\n\n### 7.1 商户结构(产品负责人 11/11 确认)\n\n| 角色 | 是谁 | 易宝类型 | 状态 |\n| --- | --- | --- | --- |\n| 服务商 | 西安禾斗 | SaaS 服务商,本身不收单 | 已确认 |\n| 平台商 | 品牌总部 | 服务商接入的平台商(`PLATFORM_MERCHANT`) | 已确认 |\n| 入驻商户 | 品牌门店的收款账户 | 入驻商户(`SETTLED_MERCHANT`),上级是品牌总部 | 已确认 |\n| 待确认 | 教练、供应链、商户池中的商户 | 未确认,**不默认成标准商户,也不默认成入驻商户** | 待确认 |\n\n- 本服务用服务商的应用和密钥,一套服务对多个品牌;“接入应用 → 品牌 → 门店 → 商编”的授权核对照旧。\n- 商编填法按易宝《产品决策》第一节和付款码、聚合码在线文档:平台商代下属入驻商户收款时,`parentMerchantNo` 是平台商编、`merchantNo` 是收款子商户;标准商户收款时两者一致,都是本商户编号。\n- C05 目录里每个收款商编登记一个“发起方商编”(`parent_merchant_no`),按商编配置、不写死:\n  - **默认(门店)**:发起方商编 = 品牌总部的平台商编,和 `merchantNo` 不同;关单时对应 `OPR00025`“系统商版父子商编必须不一致”的规则。\n  - **另一种填法(标准商户)**:发起方商编 = 自己的商编;对应 `OPR00024`“标准版父子商编必须一致”。\n  - 教练、供应链、商户池中的商户:第一阶段不收款,确认类型后再登记。\n- 易宝商户角色(服务商入网接口 `businessRole`)(Claude 11/11 按官方 Skill 和在线文档核对):`ORDINARY_MERCHANT` 标准商户、`PLATFORM_MERCHANT` 平台商(入网时 `parentMerchantNo` 填服务商商编);`SETTLED_MERCHANT` 入驻商户只能挂在特定平台商下(入网时 `parentMerchantNo` 填平台商编);另有 `SHARE_MERCHANT` 分账接收方、`HEAD_CHAIN` / `BRANCH_CHAIN` 连锁总店 / 分店。\n- 对账:平台商用平台商编下载的交易日账单包含平台商和下面全部入驻商户的交易;标准商户用自己的商编下载(第 20 节)。"
        },
        {
          "id": "16",
          "title": "旧接口并行与切换",
          "body": "- 新旧接口并存到 POS 全部切到新接口;旧接口只修安全问题(P1 拒 query),不再加功能。\n- 历史订单(旧接口发起的)可以用新 GET 查单按原 `merchant_order_id` 查到;退款也可按原 orderId 发起。\n- 旧接口下线时间由产品负责人定;下线前确认没有调用(看第①段日志)。\n- 回滚:新接口有问题时 POS 切回旧接口;已发生的渠道扣款不随应用回滚消失,用原 orderId 查单和对账。"
        },
        {
          "id": "18",
          "title": "现有代码的保留与改动",
          "body": "| 现有 | 处理 |\n| --- | --- |\n| #12 幂等、状态证据、通知、重扫前保护、晚到成功、轮询、审计 | 保留;对外适配层新写;`PaymentResource` 只给旧接口用 |\n| #13 12 秒共享预算 | 保留 |\n| #14 失败 / 过期通知金额兼容 | 保留;不作为对 POS 补金额的依据 |\n| #15 nonce 原子认领与清理、MySQL CI | 保留;v2 签名复用同一 nonce 认领 |\n| #16 官方向量 | 保留;P3/P4 补 pay-link、refund、refund/query 向量,P1 加 v2 签名向量 |\n| `YeepayClient::evidence` 成功金额取 `orderAmount` | P2 改为成功必须有可信 `payAmount` 并记录来源 |\n| `UnconfiguredPaymentDirectory`(C05 未接) | 不变;装配由产品负责人 / Lihao 提供登记与 `.env` 后另行替换 |\n| `config/logging.php` 只有 stderr / single | P1b 增加报文文件通道(只追加、按天、带节点标识),报文以数据库表和文件两份为准 |"
        },
        {
          "id": "19",
          "title": "待定问题与决定",
          "body": "11/11 产品负责人定了全部非易宝项。“产品负责人已定”立即生效;“Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效”这几条由 Lihao 在 #17 提异议,有异议就按他的意见改文档后重新复审。只有 Q15 挡 P1,其余到 P2、P4、P7 才用到。\n\n| # | 问题 | 决定 | 状态 | 影响 |\n| --- | --- | --- | --- | --- |\n| Q1 | 返回业务结果对象还是完整 YOP 网关响应 | 只返回易宝业务结果对象(第 3.3、6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q2 | 是否加本服务响应签名 | 第一阶段不加(第 6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q3 | `merchantNo` 是否必填 | 必填(第 3.3 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q4 | 并行期怎么切、序号位数 | 按门店整体切换;序号 1—6 位、不补零(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q5 | `expiredTime` 范围 | 付款码 1—15 分钟、不传补 15 分钟;二维码 1—60 分钟、不传补 5 分钟(第 3.3、3.4 节) | 产品负责人已定 11/11 | P2、P3 |\n| Q6 | 二维码 `scene` 默认值 | 不传时补 `{\"WECHAT\":\"OFFLINE\",\"ALIPAY\":\"OFFLINE\"}`(第 3.4 节) | 产品负责人已定 11/11 | P3 |\n| Q7 | 二维码换新、隐式关前代 | 去掉 `renew`,POS“关单 → 新 orderId”;不做隐式关前代,未关旧码时 409 拦住(第 3.4、10 节) | 产品负责人已定 11/11;POS 流程部分同 Q1 的异议期 | P3、P5 |\n| Q8 | 退款 / 查退款定位方式 | 只按 orderId(第 3.7、3.8 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |\n| Q9 | 退款失败、`SUSPEND` | 不开通补充卡信息退款;失败类都标待核、资金类告警、转人工,不自动重退、不自动结束退款(第 3.7 节) | 产品负责人已定 11/10 | P4 |\n| Q10 | `biz_no`、`order_kind` | 不进易宝字段,内部按 bill_no 关联(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q11 | 付款人信息 | 不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节) | 产品负责人已定 11/11 | P1b(日志脱敏)、P7(推送) |\n| Q12 | 告警接收 | 专门的 Slack 频道;接收人产品负责人、Lihao;资金类 15 分钟内响应,其他当天;webhook 只放 `.env`,P6 前提供(第 14.2 节) | 产品负责人已定 11/11 | P6 |\n| Q13 | PR 顺序 | P1→P7(第 17 节);11/11 暂定加 P1b(紧跟 P1)和 P8(P7 之后) | 产品负责人已定 11/11 | 全部 |\n| Q14 | 新错误码名字和 HTTP 状态 | 按第 5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 起 |\n| Q15 | 签名 v2 逐字节规则 | 按第 4.3 节;`Content-Type` 只认 `application/x-www-form-urlencoded`,不带 charset | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | **P1** |\n| Q16 | 第二跳是否推 `payment.unknown` | 第一阶段不推(第 11.2 节) | 产品负责人已定 11/11 | P7 |\n| Q17 | 通过标准数值 | 按第 21.3 节 | 产品负责人已定 11/11 | 验收 |\n| Q18 | `REFUND_IN_PROGRESS`、`REFUND_AMOUNT_EXCEEDED` | 按第 3.7、5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |\n| Q19 | 第二跳推送签名 v2 | 按第 11.2 节,POS 侧同步实现 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P7 |\n| 报文存储 | 报文怎么存、存多久 | 数据库+文件双写,两份都长期保留,不设清理;文件和库不同盘、每天复制到服务器外(第 13.2、13.3 节) | 产品负责人已定 11/11 | P1b、部署 |\n| 报文记录批次 | 报文记录何时做 | 从 P6 提到 P1b,内部只读查询一起提前(第 17 节) | 产品负责人暂定 11/11 | P1b |\n| 每日对账 | 上线前是否加对账 | 加 P8 每日对账,收真钱前置;差错只记录告警、不自动改资金状态(第 13.5 节) | 批次暂定;“不自动改状态”已定 11/11 | P8 |\n| 判断顺序(11/11 复审) | `Content-Type` 不对回什么 | 统一 401,在验签前判断(第 3.2、4.3 节) | 文档前后统一,属 Q15 范围,异议期同 Q15 | **P1** |\n| orderId 序号写法 | 序号能否 0 开头 | 不能,`_01` 回 422(第 3.3、7 节),与 Q4 一致 | 文档前后统一 | P2 |\n| 401 原因 | 401 能否分清原因 | `details.reason` 八个取值(含 `nonce_unavailable`)、日志同一套、带 `WWW-Authenticate`;调用方自己生成一次表单字节再签名发送;向量 11 组(第 4.3 节) | Lihao 11/11 要求;名字按他举例,异议期同 Q15 | **P1** |\n| 同步返回里的付款人字段 | 付款码、查单的同步返回按 Q1 原样会带上易宝给的付款人字段(`payerInfo` 等),要不要也去掉 | 去掉,清单见第 3.3 节,其余字段照旧(第 1 节第 4 处例外) | 产品负责人已定 11/11 12:49(亚利桑那) | P2 |\n| 备份恢复后收款怎么重新开放 | 恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦 | 先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节) | 产品负责人已定 11/11 14:11(亚利桑那) | P1b、部署方案 |\n| 旧接口 E1、E2 的付款人信息 | 旧 `/api/v1/payments/auth-code`、`/api/v1/payments/query` 返回里带不带 | 现状:**不带**。两者都返回本服务自己的 `PaymentResource`(基线 `c7d23d3` 的 `app/Http/Resources/PaymentResource.php`),字段是内部单号、金额、状态、`channel_trade_no_last4` 等,不透传易宝返回,没有 `payerInfo`、`userId`、`buyerLogonId` 等。建议:不用改,在并行期回归里加一条“旧接口返回不出现付款人字段” | 现状已核对;建议待产品负责人确认 | P2 回归 |\n| 渠道交易号后 4 位放哪 | 查单是否加 | 查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节) | 文档前后统一 | P7 |\n| 商户结构 | 品牌总部、门店、教练等的易宝类型 | 门店是品牌总部下的入驻商户(发起方商编 = 平台商编);按商编可配置(第 7.1 节) | 门店:产品负责人已定 11/11;教练、供应链、商户池中的商户:**待确认** | P2 配置 |\n| 易宝 | 付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4) | — | **待易宝确认**(产品负责人线下问) | P2—P5、验收 |"
        },
        {
          "id": "22",
          "title": "不在本设计范围",
          "body": "- 分账、归集、资金方案、循环收款池、提现、余额(GPAY-04—GPAY-21 的资金类)。对账只做第 13.5 节的收款、退款逐笔核对(P8),分账账单、资金账单核对不在第一阶段。\n- 公众号 / 小程序 / 支付宝预下单(GPAY-07)。\n- 部署执行、采购、改服务器、开公网(部署方案另行审批)。\n- 真实扣款和退款:只用易宝沙箱或测试商户。\n- 入网(进件):门店、教练、供应链、商户池商户的入网走服务商入网接口,第一阶段不加接口(产品负责人 11/11)。\n- 转账和提现(产品负责人 11/11):系统记录门店、教练、供应商、品牌总部各自应得的金额;到提现时间点由品牌总部按应得金额转给门店、教练、供应商,再自动提现到对方账户。后续阶段再设计;品牌总部转给对方用“转账”接口,**不用余额分账**。第一阶段收款、退款接口里的分账字段继续一律拒绝。后续会用到的易宝接口(只记出处,现在不设计):转账下单 `POST /rest/v1.0/account/transfer/b2b/order`(在线文档 `docs-v3/api/options_rest_v1.0_account_transfer_b2b_order.md`),结果通知 `account.business.transfer-result`;提现下单 `POST /rest/v1.0/account/withdraw/order`(Skill 的 `withdraw-order`)。"
        }
      ],
      "requestFields": [
        {
          "name": "biz_no",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "第4.2节仅点名此旧 JSON 字段,未提供完整请求字段表"
        }
      ],
      "responseFields": [],
      "uncertainty": [
        "未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
        "设计稿未给完整旧接口字段表及 PaymentResource 返回 schema;不得从新接口倒推旧协议。",
        "设计稿未展开旧接口完整响应 schema;实际返回本服务 PaymentResource,不透传易宝付款人字段。"
      ],
      "displayFields": [],
      "keyRules": [
        {
          "title": "旧接口付款人信息现状与待确认",
          "items": [
            "现状:两者返回本服务PaymentResource,不透传易宝返回,不带付款人信息。建议不改,只加并行期回归;建议仍待产品负责人确认。"
          ]
        }
      ],
      "authDescription": "本服务签名 v1,JSON POST只认已签名body(第4.1、12节);旧POST带query拒绝。旧 POST 下线时 v1 不能一起下线,除非内部接口也已换签名。"
    }
  },
  "diagnostics": {
    "networkEnabled": false,
    "documentationOnly": true
  },
  "businessRules": [
    "保留旧 JSON 请求;响应外层在固定设计稿中未明确;不是新的易宝同款业务结果格式。按门店整体切换,同一账单不能混用。"
  ],
  "issues": [
    "未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
    "设计稿未给完整旧接口字段表及 PaymentResource 返回 schema;不得从新接口倒推旧协议。",
    "设计稿未展开旧接口完整响应 schema;实际返回本服务 PaymentResource,不透传易宝付款人字段。"
  ]
}
SmartPool 接口文档源码/候选文档 · 不可真实调用