设计稿,未实现,未经沙箱验收。只作接口走查,不发送真实请求。基线已有能力单独列明,不代表此设计已经落地。
设计来源:支付服务 PR #17 · 提交 7d2ae11e91ecd073944f98473ef41a67cd0f6146
| 组 | 数量 | 编号 |
|---|---|---|
| A 易宝同款 | 6 | A1—A6 |
| B 接收易宝通知 | 2 | B1—B2 |
| C 自有接口 | 5 | C1—C5 |
| D 运维检查 | 2 | D1—D2 |
| E 旧接口 | 2 | E1—E2 |
用途:查看一张账单的全部收款尝试、已确认金额与退款进度。
P8另用第7个易宝接口“交易日账单下载”(bill-trade-day-download),由后台定时任务调用,不对收银台开放,不新增第18页。P1b、P8批次暂定;对账只记录差错和告警,不自动改资金状态。
C4 · 对应易宝接口
易宝名称易宝没有
接口标识易宝没有
易宝路径 / 事件易宝没有
谁调谁收银台(POS,走内网)→ 支付服务
基线现状建议路径;字段名和 Lihao 对齐后冻结
开发批次(计划)P7
和易宝不一样的地方
- 本服务自有协议,易宝没有对应接口。
- 退款约束:原订单必须 SUCCESS;累计退款不超过实付;单笔大于 0.01 元;失败后同一个 refundRequestId 重提。退款期限仍待易宝确认。
未完整定义的字段说明
以下为来源点名的内容或脱敏规则,不补造协议字段名、返回位置、类型或媒体格式。
| 位置 | 来源内容 / 中性标签 | 说明 |
|---|---|---|
| 返回 | 各次收款状态(字段名未明确) | 含内部UNKNOWN和待核原因。 |
| 返回 | 已确认金额及来源(字段名未明确) | 展示确认过的金额与证据来源。 |
| 返回 | 是否可重扫及阻断原因(字段名未明确) | 说明能否继续扫码及不能继续的原因。 |
| 返回 | 退款进度和可退额度(字段名未明确) | 各次退款进度、占额及剩余可退额度。 |
| 返回 | channel_trade_no_last4 | 各次收款的渠道交易号后4位;和第二跳推送同名,A3查单不添加此字段。 |
后续范围(第22节)
各角色应得金额后续采用品牌总部转账、再提现,不用余额分账,另行设计;本轮不新增相关接口或执行资金操作。第一阶段分账字段仍一律拒绝。
待定问题与有条件决定
| 编号 / 问题 | 方案 | 状态与条件 | 影响 |
|---|---|---|---|
| Q10 `biz_no`、`order_kind` | 不进易宝字段,内部按 bill_no 关联(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q14 新错误码名字和 HTTP 状态 | 按第 5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 起 |
| Q18 `REFUND_IN_PROGRESS`、`REFUND_AMOUNT_EXCEEDED` | 按第 3.7、5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |
| 渠道交易号后 4 位放哪 查单是否加 | 查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节) | 文档前后统一 | P7 |
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。
逐条来源规则与上下文
内部接口(非易宝,P7)
易宝没有“待收银员处理的晚到成功”这类接口,单列为本服务内部接口,签名用 v1 JSON POST(只认 body),路径和字段名和 Lihao 对齐后冻结: | 建议路径 | 用途 | 主要入参 | 主要出参 | | --- | --- | --- | --- | | `POST /api/v1/collections/pending` | 待收银员处理的晚到成功、两笔都成功 | `store_ref`,可选 `bill_no`、游标 | 每条:`order_id`、`bill_no`、金额(分)、`arrived_at`(可信到账时间,未知为 null)、`observed_at`、原因(`late_success` / `success_after_unknown`)、处理状态 | | `POST /api/v1/collections/pending/handle` | 记录收银员选择 | `order_id`、`choice`(`counted` / `refund`)、`choice=refund` 时必填 `refund_request_id`(POS 先生成好的退款请求号)、`operator`、`request_ref` | 处理回执;同 `request_ref` 重发返回第一次结果;同一笔只能选一次,改选 409 | | `POST /api/v1/collections/facts` | 一张账单的全部收款尝试和内部事实 | `store_ref`、`bill_no` | 各次 orderId、状态(含内部 UNKNOWN、待核原因)、已确认金额及来源、渠道交易号后 4 位 `channel_trade_no_last4`(成功单有值,其余 null;GPAY02-07)、是否可重扫及阻断原因、退款进度和可退额度 | 这些内部状态只在内部接口出现,不加进易宝 `status`。 **选“原路退款”以后的中断恢复**(Jim 第 3 条): - `handle(choice=refund)` 只记选择和 POS 给的 `refund_request_id`,这笔从“待选择”变成“待退款”,**不算处理完**;只有同号退款到 `SUCCESS` 才移出待处理。选择本身不当成退款成功。 - POS 记下选择后崩溃、还没调退款:重启后 `pending` 和 `facts` 仍列出这笔(状态“待退款”,带 `refund_request_id`、退款进度“未发起”),POS 用**同一个** `refund_request_id` 调 `/rest/v1.0/trade/refund` 继续。 - 退款调用超时或重放:同号按第 3.7 节规则处理(在途 409、处理中返回原结果、明确失败才重派),不会产生第二笔退款。 - 退款最终 FAILED / CANCEL:仍留在“待退款”,提示可以同号重试;不因此改成自动退款。 - 同一笔选了 `counted`(计入本单):直接移出待处理,facts 里保留选择记录。
申请退款 `POST /rest/v1.0/trade/refund`
**请求字段** | 字段 | 第一阶段 | 规则 | | --- | --- | --- | | parentMerchantNo | 可选,服务补 | 绑定原交易发起方,不重新路由 | | merchantNo | 必填 | 原收款商户 | | orderId | 必填 | 原收款 orderId;第一阶段只支持按 orderId 定位 | | uniqueOrderNo、bankOrderId | 拒绝 | 只按 orderId 定位(Q8 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那)) | | refundRequestId | 必填 | 只允许字母、数字、下划线(GPAY 已定规则 12);由 POS 生成;**同一收款商户(`merchantNo`)内唯一**(易宝要求商户端退款请求号不重复);失败后重试用同一个号 | | refundAmount | 必填 | 元,精确转分;见下方额度规则 | | description | 可选 | 原样转发 | | memo | 可选 | 原样转发 | | notifyUrl | 可选 | 只用于第二跳 | | refundAccountType、divideBackDetail、terminalInfo、ypPromotionRefundInfo | 拒绝 | 改变资金来源、分账归还、营销退款,第一阶段不支持 | **返回字段**:`code`、`message`、`parentMerchantNo`、`merchantNo`、`orderId`、`refundRequestId`、`uniqueRefundNo`、`status`、`refundAmount`、`refundRequestDate`、`refundMerchantFee`、`refundAccountDetail`、`refundCsFinishDate`、`creditOrderId`,原样原类型返回。`OPR00000` 只是受理,结果看 `status`(PROCESSING / SUCCESS / FAILED / CANCEL / SUSPEND;注意退款失败是 `FAILED`,不是支付的 `FAIL`)。 **内部照做**: - 只有本地已确认成功、且有可信实收金额的收款可以退;晚到成功(含两笔都成功)由收银员选择原路退款时,同样按普通退款走(GPAY08-21)。 - **额度原子控制**:可退 = 实收 − 已成功退款 − 处理中和结果不明的退款占额。同一原单上锁计算,并发两笔合计超出时只受理不超的那一笔(PAY-r7 PAY04-10)。处理中、结果不明的占额不因超时释放。 - 返回码判定沿用《易宝接口字段核对》退款表:文档要求同号重试的码(OPR00042、OPR13005、OPR13021、OPR15003、OPR15004、OPR15044、OPR16001、OPR99999)和未列码算结果不明,查退款;文档列出的其他错误码和网关拒收三类(40042、40047、40029)算“明确未受理”。**退款失败和 `SUSPEND`(Q9 已定,产品负责人 11/10)**:先**不开通**易宝“补充卡信息退款”。所以正常不会出现 `SUSPEND`;原路退款失败时,能取到支付卡信息的易宝自动转打款,转打款也失败或取不到卡信息的,钱退回商户易宝账户。退款 FAILED / CANCEL、以及万一收到的 `SUSPEND`,都标待核、发资金类告警、转人工处理;本服务**不自动重退**,也不自动调 `trade/refund/supply` 或 `trade/refund/end`。人工决定再退时,由 POS 用同一个 `refundRequestId` 重提(按下表)。 - **同一个 `refundRequestId` 再次提交时怎么办**(重放和重试的区别)。退款单按“`merchantNo` + `refundRequestId`”唯一(数据库唯一键),同时记下它绑定的原单 orderId 和最近一次派发的结果。 - 同商户已有这个号、但绑定的是**另一笔原单**:409 `IDEMPOTENCY_CONFLICT`,不调用渠道,也不返回另一笔原单的退款结果(防止拿别人的号查到别人的退款)。 - 同商户、同原单、同号:按下表处理。 | 最近一次结果 | 同号、同内容再提交 | 同号、内容不同 | | --- | --- | --- | | 本服务还没派发完(在途) | 409 `REFUND_IN_PROGRESS`(新,Q14/Q18 已定),不派发、不动占额 | 409 `IDEMPOTENCY_CONFLICT` | | PROCESSING、结果不明、SUSPEND | 返回最近一次已验证的结果(结果不明时 504 / 502 同第 5 节),**不派发、不释放占额**;后台继续查退款 | 409 `IDEMPOTENCY_CONFLICT` | | SUCCESS | 返回最近一次结果,不派发 | 409 `IDEMPOTENCY_CONFLICT` | | 明确未受理(上表的码、网关拒收)、FAILED、CANCEL | **重试**:在原单锁内重新算可退额度、重新占额,用同一个 `refundRequestId` 再派发一次,`attempt_count + 1`;额度不够 409 `REFUND_AMOUNT_EXCEEDED`(新,Q14/Q18 已定) | 409 `IDEMPOTENCY_CONFLICT` | - 触发重试的只有调用方再次提交同号同内容;本服务后台不自动重退。 - **怎么识别“同一轮重试”**:每次派发有递增的 `attempt_no`。请求进来时先读一次退款单当前的 `attempt_no` 和状态(快照),再在原单行锁里复核:只有“当前 `attempt_no` 仍等于快照、且状态可重试”才派发新一轮;如果拿到锁时 `attempt_no` 已经变了(别的请求已经发起了这一轮),就**不派发**,直接按新一轮的最新状态回(在途 409 `REFUND_IN_PROGRESS`,有结果就回结果)。 - 所以并发两个相同的重试,不论第一个是慢应答还是很快又被明确拒绝,第二个都不会再派发:同一轮只多 1 次渠道写调用。第二个请求如果是在上一轮失败**已经记下之后**才到,它的快照就是新的 `attempt_no`,属于下一轮合法重试,会再派发一次(序列见 21.6 R-9—R-11)。 - 每次派发前后都写第②段日志,`attempt_count` 和每次的渠道结果都可在 facts 接口看到。 - 验收序列见第 21.6 节。 - 易宝在线文档写明的退款约束(Claude 11/11 按官方 Skill 和在线文档核对):原订单必须是 `SUCCESS`;累计退款不超过实付;单笔大于 0.01 元;失败后同号重提。退款期限文档没有,仍待易宝确认。 - 后台查退款:沿用收款轮询节奏(前 2 分钟每 5 秒,之后每分钟,30 分钟待核,24 小时停自动查并告警)。 - 退款期限(易宝答复 Q4 只答了到账速度)和通知重试规则(Q20)未答,相关期望标“待易宝确认”。
状态分层(01:54 第 4 条)
| 内部事实 | 对外 | | --- | --- | | 渠道可信 SUCCESS,身份和金额完整 | 返回渠道原结果(`status=SUCCESS`) | | UNKNOWN(超时、坏签、未列码、预算耗尽) | 504 或 502,不映射成任何易宝 status | | terminal_conflict、existence_conflict、identity_mismatch | 查单时 409 `EVIDENCE_CONFLICT`;内部待处理接口可见 | | late_success(晚到的可信成功) | 查原单返回真实成功;“晚到”这一事实只在内部待处理接口里给 | | OPR18012 已付提示、金额未核实 | 阻止再扣款(409 `PAYMENT_PROTECTED`),不生成成功金额 | | unpaid_resolved(到期仍不存在,按未支付了结) | 查单如实返回渠道结果(`OPR12002` 订单不存在原样返回);内部记了结事件 | 已确认成功不会被随后的负结果抹掉;矛盾保留审计、标待核、告警。
PR 拆分与验收项
每个 PR 一个能力,PR 描述写清覆盖的验收项;Claude 复审,产品负责人按提交号批准,Lihao 合并并做合并后验收,Jim 在批准前用易宝沙箱按验收清单逐项验收并写在 PR 评论里。测试以 GitHub CI(PHP 8.5 + 真 MySQL,含 `--group=mysql-contract`)为准。 | PR | 内容 | 主要验收项(用例 v3) | 部署清单 | | --- | --- | --- | --- | | P0 | 本设计文档 | — | — | | P1 | 旧 POST 拒 query;签名 v2(GET 查询串、POST form 严格解析)+固定向量 | PAY-02、PAY-13 | — | | P1b | 报文记录(第 13 节:`payment_exchange_logs` 表+报文文件双写、独立提交、状态事件写文件和补写任务);内部只读查询 `POST /api/v1/internal/exchange-logs` | PAY-12(记录部分);第 21.12 节 L-1—L-7 | C1—C3、D、E(代码部分) | | P2 | 付款码、查单的易宝同款接口;可信 payAmount 来源;第 5 节错误码冻结 | PAY-01、03、04、05、06、09 | C1—C3(接入点) | | P3 | 本单二维码 pay-link(含到期、已付保护、通知) | PAY-01、05、06、07 | — | | P4 | 退款、查退款、退款通知;占额并发 | PAY-01、07、08、09 | — | | P5 | 关单公共接口(同步有界+后台) | PAY-01、06 | — | | P6 | 告警表与投递、就绪检查 | PAY-12(告警部分) | F、G | | P7 | 第二跳推送、内部待处理与账单事实接口 | PAY-07、PAY-10(POS 端到端部分) | — | | P8 | 每日对账(第 13.5 节):下载易宝交易日账单、逐笔核对、记差错并告警 | 第 21.12 节 RC-1—RC-10 | — | 和 11/10 指示的顺序(本单二维码 → 退款 → 关单 → 日志和告警)的关系:P1(安全阻断项,11/07 已定“第一个 PR 做”)和 P2(付款码 / 查单换成易宝同款,二维码和退款都要复用它的解析、鉴权、错误和查单)是前置;P3—P6 按 11/10 的顺序;P7 是 01:54 拆分里的第 5 项。产品负责人已认可这个顺序(Q13 已定)。11/11 暂定调整:报文记录从 P6 提到 **P1b**(单独一个 PR,紧跟 P1,不混进签名安全 PR;P2 第一个易宝同款接口联调时四段报文已经在记),内部只读查询接口一起提前;告警、就绪检查留在 P6。**P8 每日对账**排在 P7 之后,是上线收真钱的前置条件。 PAY-11(并行期和回滚)在 P2 起每个 PR 回归;PAY-10(C05 配置、C06 沙箱、HTTPS 通知、POS 端到端)依赖产品负责人和 Lihao 准备的环境。 **需求编号 → 章节 → 交付 → 验收步骤 → 判定**(第一阶段实际涉及的): | 需求 | 本文章节 | 交付 | 验收步骤 / 证据 | 判定 | | --- | --- | --- | --- | --- | | GPAY08-17 结果不明后关单、重扫 | 3.6、8、10 | P2、P5 | 21.5 C-1—C-4;21.7 付款码表;新扫码是新 orderId | facts 显示原单继续查、未推待核;新单独立 | | GPAY08-18 一直“订单不存在”,到期了结 | 6.3、9 | P2 | 注入查单 `OPR12002` 至过期 | 到期后才了结,满 30 分钟不标待核 | | GPAY08-19 改方式后原单晚到成功 | 6.3、8、12 | P2、P7 | 21.4 注入通知成功 | 成功+异常+告警,不退款;pending 能查到 | | GPAY08-20 重扫成功后原单也成功 | 8、12 | P2、P7 | 两单都成功 | 只有原单写异常 | | GPAY08-21 晚到成功选原路退款 | 3.7、12 | P4、P7 | 21.6;第 12 节恢复流程 | 普通退款、可查、失败同号重退 | | GPAY08-22 先处理中后“不存在” | 6.3 | P2 | 注入查单序列 | 不了结,标待核、告警 | | GPAY14-01—05 推送 | 11.2 | P7 | 21.8 P-1—P-5 | 见表 | | GPAY16-01—03 多实例、查单上限、失败重入队 | 9、21.2 | P2 起 | 双调度节点、注入 worker 失败 | 每单只处理一次;不重复写调用 | | GPAY02-07 渠道交易号后 4 位 | 12、11.2、13.1、21.9 | P7 | facts 接口(第 12 节)每次收款尝试的 `channel_trade_no_last4`;第二跳推送正文里同一个值。**易宝同款查单(第 3.5 节)不加这个字段**,按第 6.1 节原样返回易宝业务结果 | facts / 推送:成功单有值,其余 null;查单返回里没有本服务加的字段 | 分账、归集、提现、资金方案、资金退回等 GPAY 其他卡不在第一阶段,继续标后续。 **部署清单 A、B、H 的承接**:这三组不由 P1—P8 覆盖,单列为“部署验收”批次,前置条件是产品负责人给出资产清单、服务器、数据库和密钥装配(部署方案第十节);在部署窗口按清单逐项验收,结果写在部署记录里。C、D、E 组的代码部分由 **P1b** 交付(报文记录、双写、脱敏、权限前提),F、G 组由 P6 交付(告警、就绪检查);部署验收时再在目标环境复验,代码合并不等于部署清单通过。D 组原“保留 180 天”已被长期保留的决定替代,不再有清理。
待定问题与决定
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.3.4.1payment-service-C4
C4 账单收款事实支付设计
查看一张账单的全部收款尝试、已确认金额与退款进度。
契约状态:设计稿实现状态:设计未实现;基线:建议路径;字段名和 Lihao 对齐后冻结真实接口验收:未经沙箱验收
POST
/api/v1/collections/factsDESIGN ONLY · NO LIVE CALLi
设计稿,未实现,未经沙箱验收
字段、规则、错误和有条件决定取自固定设计提交;只作展示,不运行请求或模拟成功。
- 仅静态合成示例;设计未实现、未经沙箱验收;不启用模拟成功,不发送 HTTP。
01接口说明
业务端 / 模块支付服务(易宝同款) / C 自有接口
请求格式application/json
鉴权与权限本服务签名 v1,JSON POST只认已签名body(第4.1、12节)。旧 POST 下线时 v1 不能一起下线,除非内部接口也已换签名。 · 设计展示,禁止网络请求
技术服务归属(元信息)支付服务
收银台(POS,走内网)→ 支付服务目录引用不授予调用权限。
来源业务约束
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。
02请求头 5 个字段
| 字段名 | 类型 | 必填 | 说明与约束 | 示例值 |
|---|---|---|---|---|
Content-Type | string | 必填 | 来自请求体 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
| 字段名 | 类型 | 必填 | 第一阶段处理 | 说明与约束 | 示例值 |
|---|---|---|---|---|---|
store_ref | 未定义 | 未明确 | 未明确易宝必填:未明确 | 易宝必填性:未明确;第一阶段处理:未明确。主要入参;必填性未明确 | null |
bill_no | 未定义 | 未明确 | 未明确易宝必填:未明确 | 易宝必填性:未明确;第一阶段处理:未明确。主要入参;必填性未明确 | null |
04响应参数
只列来源点名的业务字段;完整外层、类型、HTTP状态未明确。
| 字段名 | 类型 | 必填 | 说明与约束 | 示例值 |
|---|---|---|---|---|
orderId | 未定义 | 未明确 | 易宝必填性:未明确;第一阶段处理:未明确。设计稿点名的业务字段;完整响应层级、类型与必填性未明确。 | null |
refund_request_id | 未定义 | 未明确 | 易宝必填性:未明确;第一阶段处理:未明确。设计稿点名的业务字段;完整响应层级、类型与必填性未明确。 | null |
attempt_count | 未定义 | 未明确 | 易宝必填性:未明确;第一阶段处理:未明确。设计稿点名的业务字段;完整响应层级、类型与必填性未明确。 | null |
channel_trade_no_last4 | 未定义 | 未明确 | 本服务字段;facts每次收款尝试中提供,成功单有值,其余null,第二跳提供同一个值;A3不加此字段(第12、17节)。 | null |
05错误码 沿用来源定义
设计稿未明确错误响应,保留待确认,不补造错误码。
06来源与状态
契约状态:设计稿实现状态:设计未实现;基线:建议路径;字段名和 Lihao 对齐后冻结真实接口验收:未经沙箱验收
sourceCommit
7d2ae11e91ecd073944f98473ef41a67cd0f6146查看原始契约、引用与状态记录
{
"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": "只列来源点名的业务字段;完整外层、类型、HTTP状态未明确。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"orderId": {
"x-payment-required-label": "未明确",
"x-payment-processing": "未明确",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:未明确。设计稿点名的业务字段;完整响应层级、类型与必填性未明确。"
},
"refund_request_id": {
"x-payment-required-label": "未明确",
"x-payment-processing": "未明确",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:未明确。设计稿点名的业务字段;完整响应层级、类型与必填性未明确。"
},
"attempt_count": {
"x-payment-required-label": "未明确",
"x-payment-processing": "未明确",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:未明确。设计稿点名的业务字段;完整响应层级、类型与必填性未明确。"
},
"channel_trade_no_last4": {
"x-payment-required-label": "未明确",
"x-payment-processing": "未明确",
"x-supplier-required": "未明确",
"description": "本服务字段;facts每次收款尝试中提供,成功单有值,其余null,第二跳提供同一个值;A3不加此字段(第12、17节)。"
}
},
"required": []
},
"example": {}
}
}
}
},
"sourceExtensions": {
"x-permission": "设计展示,禁止网络请求",
"x-source-sections": [
"12",
"3.7",
"6.3",
"17",
"19",
"22"
]
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"store_ref": {
"x-payment-required-label": "未明确",
"x-payment-processing": "未明确",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:未明确。主要入参;必填性未明确"
},
"bill_no": {
"x-payment-required-label": "未明确",
"x-payment-processing": "未明确",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:未明确。主要入参;必填性未明确"
}
},
"required": []
},
"example": {}
}
}
}
},
"status": {
"contract": "设计稿",
"implementation": "设计未实现;基线:建议路径;字段名和 Lihao 对齐后冻结",
"realApiAcceptance": "未经沙箱验收"
},
"provenance": {
"sourceCommit": "7d2ae11e91ecd073944f98473ef41a67cd0f6146",
"sourceBlob": "74501663abc0df79dd867f39057b29e7cd1345b3",
"sourceUrl": "https://github.com/SmartPool-Dev/smartpool-payment-service/pull/17",
"paymentService": {
"code": "C4",
"group": "本服务内部与推送",
"purpose": "查看一张账单的全部收款尝试、已确认金额与退款进度。",
"direction": "收银台(POS,走内网)→ 支付服务",
"supplier": {
"name": "易宝没有",
"id": "易宝没有",
"path": "易宝没有"
},
"phase": "P7",
"baselineStatus": "建议路径;字段名和 Lihao 对齐后冻结",
"differences": [
"本服务自有协议,易宝没有对应接口。",
"退款约束:原订单必须 SUCCESS;累计退款不超过实付;单笔大于 0.01 元;失败后同一个 refundRequestId 重提。退款期限仍待易宝确认。"
],
"openQuestions": [
{
"id": "Q10",
"question": "`biz_no`、`order_kind`",
"decision": "不进易宝字段,内部按 bill_no 关联(第 7 节)",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2"
},
{
"id": "Q14",
"question": "新错误码名字和 HTTP 状态",
"decision": "按第 5 节",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2 起"
},
{
"id": "Q18",
"question": "`REFUND_IN_PROGRESS`、`REFUND_AMOUNT_EXCEEDED`",
"decision": "按第 3.7、5 节",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P4"
},
{
"id": "渠道交易号后 4 位放哪",
"question": "查单是否加",
"decision": "查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节)",
"status": "文档前后统一",
"impact": "P7"
}
],
"sourceSections": [
{
"id": "12",
"title": "内部接口(非易宝,P7)",
"body": "易宝没有“待收银员处理的晚到成功”这类接口,单列为本服务内部接口,签名用 v1 JSON POST(只认 body),路径和字段名和 Lihao 对齐后冻结:\n\n| 建议路径 | 用途 | 主要入参 | 主要出参 |\n| --- | --- | --- | --- |\n| `POST /api/v1/collections/pending` | 待收银员处理的晚到成功、两笔都成功 | `store_ref`,可选 `bill_no`、游标 | 每条:`order_id`、`bill_no`、金额(分)、`arrived_at`(可信到账时间,未知为 null)、`observed_at`、原因(`late_success` / `success_after_unknown`)、处理状态 |\n| `POST /api/v1/collections/pending/handle` | 记录收银员选择 | `order_id`、`choice`(`counted` / `refund`)、`choice=refund` 时必填 `refund_request_id`(POS 先生成好的退款请求号)、`operator`、`request_ref` | 处理回执;同 `request_ref` 重发返回第一次结果;同一笔只能选一次,改选 409 |\n| `POST /api/v1/collections/facts` | 一张账单的全部收款尝试和内部事实 | `store_ref`、`bill_no` | 各次 orderId、状态(含内部 UNKNOWN、待核原因)、已确认金额及来源、渠道交易号后 4 位 `channel_trade_no_last4`(成功单有值,其余 null;GPAY02-07)、是否可重扫及阻断原因、退款进度和可退额度 |\n\n这些内部状态只在内部接口出现,不加进易宝 `status`。\n\n**选“原路退款”以后的中断恢复**(Jim 第 3 条):\n- `handle(choice=refund)` 只记选择和 POS 给的 `refund_request_id`,这笔从“待选择”变成“待退款”,**不算处理完**;只有同号退款到 `SUCCESS` 才移出待处理。选择本身不当成退款成功。\n- POS 记下选择后崩溃、还没调退款:重启后 `pending` 和 `facts` 仍列出这笔(状态“待退款”,带 `refund_request_id`、退款进度“未发起”),POS 用**同一个** `refund_request_id` 调 `/rest/v1.0/trade/refund` 继续。\n- 退款调用超时或重放:同号按第 3.7 节规则处理(在途 409、处理中返回原结果、明确失败才重派),不会产生第二笔退款。\n- 退款最终 FAILED / CANCEL:仍留在“待退款”,提示可以同号重试;不因此改成自动退款。\n- 同一笔选了 `counted`(计入本单):直接移出待处理,facts 里保留选择记录。"
},
{
"id": "3.7",
"title": "申请退款 `POST /rest/v1.0/trade/refund`",
"body": "**请求字段**\n\n| 字段 | 第一阶段 | 规则 |\n| --- | --- | --- |\n| parentMerchantNo | 可选,服务补 | 绑定原交易发起方,不重新路由 |\n| merchantNo | 必填 | 原收款商户 |\n| orderId | 必填 | 原收款 orderId;第一阶段只支持按 orderId 定位 |\n| uniqueOrderNo、bankOrderId | 拒绝 | 只按 orderId 定位(Q8 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那)) |\n| refundRequestId | 必填 | 只允许字母、数字、下划线(GPAY 已定规则 12);由 POS 生成;**同一收款商户(`merchantNo`)内唯一**(易宝要求商户端退款请求号不重复);失败后重试用同一个号 |\n| refundAmount | 必填 | 元,精确转分;见下方额度规则 |\n| description | 可选 | 原样转发 |\n| memo | 可选 | 原样转发 |\n| notifyUrl | 可选 | 只用于第二跳 |\n| refundAccountType、divideBackDetail、terminalInfo、ypPromotionRefundInfo | 拒绝 | 改变资金来源、分账归还、营销退款,第一阶段不支持 |\n\n**返回字段**:`code`、`message`、`parentMerchantNo`、`merchantNo`、`orderId`、`refundRequestId`、`uniqueRefundNo`、`status`、`refundAmount`、`refundRequestDate`、`refundMerchantFee`、`refundAccountDetail`、`refundCsFinishDate`、`creditOrderId`,原样原类型返回。`OPR00000` 只是受理,结果看 `status`(PROCESSING / SUCCESS / FAILED / CANCEL / SUSPEND;注意退款失败是 `FAILED`,不是支付的 `FAIL`)。\n\n**内部照做**:\n- 只有本地已确认成功、且有可信实收金额的收款可以退;晚到成功(含两笔都成功)由收银员选择原路退款时,同样按普通退款走(GPAY08-21)。\n- **额度原子控制**:可退 = 实收 − 已成功退款 − 处理中和结果不明的退款占额。同一原单上锁计算,并发两笔合计超出时只受理不超的那一笔(PAY-r7 PAY04-10)。处理中、结果不明的占额不因超时释放。\n- 返回码判定沿用《易宝接口字段核对》退款表:文档要求同号重试的码(OPR00042、OPR13005、OPR13021、OPR15003、OPR15004、OPR15044、OPR16001、OPR99999)和未列码算结果不明,查退款;文档列出的其他错误码和网关拒收三类(40042、40047、40029)算“明确未受理”。**退款失败和 `SUSPEND`(Q9 已定,产品负责人 11/10)**:先**不开通**易宝“补充卡信息退款”。所以正常不会出现 `SUSPEND`;原路退款失败时,能取到支付卡信息的易宝自动转打款,转打款也失败或取不到卡信息的,钱退回商户易宝账户。退款 FAILED / CANCEL、以及万一收到的 `SUSPEND`,都标待核、发资金类告警、转人工处理;本服务**不自动重退**,也不自动调 `trade/refund/supply` 或 `trade/refund/end`。人工决定再退时,由 POS 用同一个 `refundRequestId` 重提(按下表)。\n- **同一个 `refundRequestId` 再次提交时怎么办**(重放和重试的区别)。退款单按“`merchantNo` + `refundRequestId`”唯一(数据库唯一键),同时记下它绑定的原单 orderId 和最近一次派发的结果。\n\n - 同商户已有这个号、但绑定的是**另一笔原单**:409 `IDEMPOTENCY_CONFLICT`,不调用渠道,也不返回另一笔原单的退款结果(防止拿别人的号查到别人的退款)。\n - 同商户、同原单、同号:按下表处理。\n\n| 最近一次结果 | 同号、同内容再提交 | 同号、内容不同 |\n| --- | --- | --- |\n| 本服务还没派发完(在途) | 409 `REFUND_IN_PROGRESS`(新,Q14/Q18 已定),不派发、不动占额 | 409 `IDEMPOTENCY_CONFLICT` |\n| PROCESSING、结果不明、SUSPEND | 返回最近一次已验证的结果(结果不明时 504 / 502 同第 5 节),**不派发、不释放占额**;后台继续查退款 | 409 `IDEMPOTENCY_CONFLICT` |\n| SUCCESS | 返回最近一次结果,不派发 | 409 `IDEMPOTENCY_CONFLICT` |\n| 明确未受理(上表的码、网关拒收)、FAILED、CANCEL | **重试**:在原单锁内重新算可退额度、重新占额,用同一个 `refundRequestId` 再派发一次,`attempt_count + 1`;额度不够 409 `REFUND_AMOUNT_EXCEEDED`(新,Q14/Q18 已定) | 409 `IDEMPOTENCY_CONFLICT` |\n\n - 触发重试的只有调用方再次提交同号同内容;本服务后台不自动重退。\n - **怎么识别“同一轮重试”**:每次派发有递增的 `attempt_no`。请求进来时先读一次退款单当前的 `attempt_no` 和状态(快照),再在原单行锁里复核:只有“当前 `attempt_no` 仍等于快照、且状态可重试”才派发新一轮;如果拿到锁时 `attempt_no` 已经变了(别的请求已经发起了这一轮),就**不派发**,直接按新一轮的最新状态回(在途 409 `REFUND_IN_PROGRESS`,有结果就回结果)。\n - 所以并发两个相同的重试,不论第一个是慢应答还是很快又被明确拒绝,第二个都不会再派发:同一轮只多 1 次渠道写调用。第二个请求如果是在上一轮失败**已经记下之后**才到,它的快照就是新的 `attempt_no`,属于下一轮合法重试,会再派发一次(序列见 21.6 R-9—R-11)。\n - 每次派发前后都写第②段日志,`attempt_count` 和每次的渠道结果都可在 facts 接口看到。\n - 验收序列见第 21.6 节。\n- 易宝在线文档写明的退款约束(Claude 11/11 按官方 Skill 和在线文档核对):原订单必须是 `SUCCESS`;累计退款不超过实付;单笔大于 0.01 元;失败后同号重提。退款期限文档没有,仍待易宝确认。\n- 后台查退款:沿用收款轮询节奏(前 2 分钟每 5 秒,之后每分钟,30 分钟待核,24 小时停自动查并告警)。\n- 退款期限(易宝答复 Q4 只答了到账速度)和通知重试规则(Q20)未答,相关期望标“待易宝确认”。"
},
{
"id": "6.3",
"title": "状态分层(01:54 第 4 条)",
"body": "| 内部事实 | 对外 |\n| --- | --- |\n| 渠道可信 SUCCESS,身份和金额完整 | 返回渠道原结果(`status=SUCCESS`) |\n| UNKNOWN(超时、坏签、未列码、预算耗尽) | 504 或 502,不映射成任何易宝 status |\n| terminal_conflict、existence_conflict、identity_mismatch | 查单时 409 `EVIDENCE_CONFLICT`;内部待处理接口可见 |\n| late_success(晚到的可信成功) | 查原单返回真实成功;“晚到”这一事实只在内部待处理接口里给 |\n| OPR18012 已付提示、金额未核实 | 阻止再扣款(409 `PAYMENT_PROTECTED`),不生成成功金额 |\n| unpaid_resolved(到期仍不存在,按未支付了结) | 查单如实返回渠道结果(`OPR12002` 订单不存在原样返回);内部记了结事件 |\n\n已确认成功不会被随后的负结果抹掉;矛盾保留审计、标待核、告警。"
},
{
"id": "17",
"title": "PR 拆分与验收项",
"body": "每个 PR 一个能力,PR 描述写清覆盖的验收项;Claude 复审,产品负责人按提交号批准,Lihao 合并并做合并后验收,Jim 在批准前用易宝沙箱按验收清单逐项验收并写在 PR 评论里。测试以 GitHub CI(PHP 8.5 + 真 MySQL,含 `--group=mysql-contract`)为准。\n\n| PR | 内容 | 主要验收项(用例 v3) | 部署清单 |\n| --- | --- | --- | --- |\n| P0 | 本设计文档 | — | — |\n| P1 | 旧 POST 拒 query;签名 v2(GET 查询串、POST form 严格解析)+固定向量 | PAY-02、PAY-13 | — |\n| P1b | 报文记录(第 13 节:`payment_exchange_logs` 表+报文文件双写、独立提交、状态事件写文件和补写任务);内部只读查询 `POST /api/v1/internal/exchange-logs` | PAY-12(记录部分);第 21.12 节 L-1—L-7 | C1—C3、D、E(代码部分) |\n| P2 | 付款码、查单的易宝同款接口;可信 payAmount 来源;第 5 节错误码冻结 | PAY-01、03、04、05、06、09 | C1—C3(接入点) |\n| P3 | 本单二维码 pay-link(含到期、已付保护、通知) | PAY-01、05、06、07 | — |\n| P4 | 退款、查退款、退款通知;占额并发 | PAY-01、07、08、09 | — |\n| P5 | 关单公共接口(同步有界+后台) | PAY-01、06 | — |\n| P6 | 告警表与投递、就绪检查 | PAY-12(告警部分) | F、G |\n| P7 | 第二跳推送、内部待处理与账单事实接口 | PAY-07、PAY-10(POS 端到端部分) | — |\n| P8 | 每日对账(第 13.5 节):下载易宝交易日账单、逐笔核对、记差错并告警 | 第 21.12 节 RC-1—RC-10 | — |\n\n和 11/10 指示的顺序(本单二维码 → 退款 → 关单 → 日志和告警)的关系:P1(安全阻断项,11/07 已定“第一个 PR 做”)和 P2(付款码 / 查单换成易宝同款,二维码和退款都要复用它的解析、鉴权、错误和查单)是前置;P3—P6 按 11/10 的顺序;P7 是 01:54 拆分里的第 5 项。产品负责人已认可这个顺序(Q13 已定)。11/11 暂定调整:报文记录从 P6 提到 **P1b**(单独一个 PR,紧跟 P1,不混进签名安全 PR;P2 第一个易宝同款接口联调时四段报文已经在记),内部只读查询接口一起提前;告警、就绪检查留在 P6。**P8 每日对账**排在 P7 之后,是上线收真钱的前置条件。\n\nPAY-11(并行期和回滚)在 P2 起每个 PR 回归;PAY-10(C05 配置、C06 沙箱、HTTPS 通知、POS 端到端)依赖产品负责人和 Lihao 准备的环境。\n\n**需求编号 → 章节 → 交付 → 验收步骤 → 判定**(第一阶段实际涉及的):\n\n| 需求 | 本文章节 | 交付 | 验收步骤 / 证据 | 判定 |\n| --- | --- | --- | --- | --- |\n| GPAY08-17 结果不明后关单、重扫 | 3.6、8、10 | P2、P5 | 21.5 C-1—C-4;21.7 付款码表;新扫码是新 orderId | facts 显示原单继续查、未推待核;新单独立 |\n| GPAY08-18 一直“订单不存在”,到期了结 | 6.3、9 | P2 | 注入查单 `OPR12002` 至过期 | 到期后才了结,满 30 分钟不标待核 |\n| GPAY08-19 改方式后原单晚到成功 | 6.3、8、12 | P2、P7 | 21.4 注入通知成功 | 成功+异常+告警,不退款;pending 能查到 |\n| GPAY08-20 重扫成功后原单也成功 | 8、12 | P2、P7 | 两单都成功 | 只有原单写异常 |\n| GPAY08-21 晚到成功选原路退款 | 3.7、12 | P4、P7 | 21.6;第 12 节恢复流程 | 普通退款、可查、失败同号重退 |\n| GPAY08-22 先处理中后“不存在” | 6.3 | P2 | 注入查单序列 | 不了结,标待核、告警 |\n| GPAY14-01—05 推送 | 11.2 | P7 | 21.8 P-1—P-5 | 见表 |\n| GPAY16-01—03 多实例、查单上限、失败重入队 | 9、21.2 | P2 起 | 双调度节点、注入 worker 失败 | 每单只处理一次;不重复写调用 |\n| GPAY02-07 渠道交易号后 4 位 | 12、11.2、13.1、21.9 | P7 | facts 接口(第 12 节)每次收款尝试的 `channel_trade_no_last4`;第二跳推送正文里同一个值。**易宝同款查单(第 3.5 节)不加这个字段**,按第 6.1 节原样返回易宝业务结果 | facts / 推送:成功单有值,其余 null;查单返回里没有本服务加的字段 |\n\n分账、归集、提现、资金方案、资金退回等 GPAY 其他卡不在第一阶段,继续标后续。\n\n**部署清单 A、B、H 的承接**:这三组不由 P1—P8 覆盖,单列为“部署验收”批次,前置条件是产品负责人给出资产清单、服务器、数据库和密钥装配(部署方案第十节);在部署窗口按清单逐项验收,结果写在部署记录里。C、D、E 组的代码部分由 **P1b** 交付(报文记录、双写、脱敏、权限前提),F、G 组由 P6 交付(告警、就绪检查);部署验收时再在目标环境复验,代码合并不等于部署清单通过。D 组原“保留 180 天”已被长期保留的决定替代,不再有清理。"
},
{
"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": "store_ref",
"supplierRequired": "未明确",
"processing": "未明确",
"required": false,
"description": "主要入参;必填性未明确"
},
{
"name": "bill_no",
"supplierRequired": "未明确",
"processing": "未明确",
"required": false,
"description": "主要入参;必填性未明确"
}
],
"responseFields": [
{
"name": "orderId",
"supplierRequired": "未明确",
"processing": "未明确",
"required": false,
"description": "设计稿点名的业务字段;完整响应层级、类型与必填性未明确。"
},
{
"name": "refund_request_id",
"supplierRequired": "未明确",
"processing": "未明确",
"required": false,
"description": "设计稿点名的业务字段;完整响应层级、类型与必填性未明确。"
},
{
"name": "attempt_count",
"supplierRequired": "未明确",
"processing": "未明确",
"required": false,
"description": "设计稿点名的业务字段;完整响应层级、类型与必填性未明确。"
},
{
"name": "channel_trade_no_last4",
"supplierRequired": "未明确",
"processing": "未明确",
"required": false,
"description": "本服务字段;facts每次收款尝试中提供,成功单有值,其余null,第二跳提供同一个值;A3不加此字段(第12、17节)。"
}
],
"uncertainty": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。"
],
"displayFields": [
{
"location": "response",
"label": "各次收款状态(字段名未明确)",
"description": "含内部UNKNOWN和待核原因。"
},
{
"location": "response",
"label": "已确认金额及来源(字段名未明确)",
"description": "展示确认过的金额与证据来源。"
},
{
"location": "response",
"label": "是否可重扫及阻断原因(字段名未明确)",
"description": "说明能否继续扫码及不能继续的原因。"
},
{
"location": "response",
"label": "退款进度和可退额度(字段名未明确)",
"description": "各次退款进度、占额及剩余可退额度。"
},
{
"location": "response",
"label": "channel_trade_no_last4",
"description": "各次收款的渠道交易号后4位;和第二跳推送同名,A3查单不添加此字段。"
}
],
"keyRules": [],
"authDescription": "本服务签名 v1,JSON POST只认已签名body(第4.1、12节)。旧 POST 下线时 v1 不能一起下线,除非内部接口也已换签名。"
}
},
"diagnostics": {
"networkEnabled": false,
"documentationOnly": true
},
"businessRules": [
"本服务自有协议,易宝没有对应接口。",
"退款约束:原订单必须 SUCCESS;累计退款不超过实付;单笔大于 0.01 元;失败后同一个 refundRequestId 重提。退款期限仍待易宝确认。"
],
"issues": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。"
]
}