设计稿,未实现,未经沙箱验收。只作接口走查,不发送真实请求。基线已有能力单独列明,不代表此设计已经落地。
设计来源:支付服务 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批次暂定;对账只记录差错和告警,不自动改资金状态。
D2 · 对应易宝接口
易宝名称易宝没有
接口标识易宝没有
易宝路径 / 事件易宝没有
谁调谁负载均衡 / 监控 → 本服务
基线现状新增设计,未实现
开发批次(计划)P6
和易宝不一样的地方
- 本服务自有协议,易宝没有对应接口。
后续范围(第22节)
各角色应得金额后续采用品牌总部转账、再提现,不用余额分账,另行设计;本轮不新增相关接口或执行资金操作。第一阶段分账字段仍一律拒绝。
待定问题与有条件决定
| 编号 / 问题 | 方案 | 状态与条件 | 影响 |
|---|---|---|---|
| Q17 通过标准数值 | 按第 21.3 节 | 产品负责人已定 11/11 | 验收 |
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。
逐条来源规则与上下文
就绪检查(P6)
- `GET /up` 保留为存活检查(只说明应用起来了)。 - 新增 `GET /ready`(只对负载均衡和监控开放,不对公网): - 数据库:能连、能读写一张心跳表、迁移是最新; - 缓存 / 锁存储:能取放锁(多节点时必须是共享存储,不能是本机文件); - C05:应用目录不是 `UnconfiguredPaymentDirectory`,幂等摘要密钥已装配; - 通道材料:已加载、未过期(只回布尔,不回任何密钥信息); - 定时任务心跳:`payment:poll` 最近一次在 60 秒内、`payment:prune-nonces` 在 10 分钟内; - 积压:待查订单、待投递推送、待发告警超过阈值时降级; - 生产环境下故障注入开关(第 21.4 节)必须是关的,开着就 503。 - 全部通过 200,否则 503,正文只给每项 `ok` / `fail`。 - 不在就绪检查里实时调用易宝(外部依赖另做渠道延迟和错误率监控)。
待定问题与决定
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、验收 |通过标准(Q17 已定)
| 项 | 标准 | | --- | --- | | 付款码 12 秒预算 | 本服务收到请求到返回 ≤ 12.2 秒(含 0.2 秒测量误差);预算耗尽不发出新 POST | | 查单节奏 | 前 2 分钟每 5 秒(±2 秒),之后每 60 秒(±10 秒);满 30 分钟在下一次查询时标待核;满 24 小时停止自动查 | | 告警送达 | 触发事务提交后 60 秒内测试接收端收到;同一笔同一原因只收到 1 条 | | 第二跳 | 首次投递在 15 秒内;退避间隔按第 11.2 节 ±10% | | 就绪检查 | 定时任务心跳超时后 90 秒内 `/ready` 变 503;恢复后 90 秒内回 200 | | 渠道写调用次数 | 每例给出期望次数,实际必须完全相等 |
故障注入
- 开关:`PAYMENT_FAULT_INJECTION`。只在 `APP_ENV=testing` 或 `sandbox` 且通道地址是沙箱地址时生效;`APP_ENV=production` 时应用**启动即拒绝**带这个开关的配置,`/ready` 也报失败。开关状态写进每条第②段日志。 - 注入点在通道适配层(替换 HTTP 应答),不 mock 本服务业务和数据库;唯一例外是下表最后一行的“事务提交后、写文件前”中断点,只在隔离环境生效: | 故障 | 怎么造 | 适用 | | --- | --- | --- | | 渠道超时(发出前 / 发出后) | 适配层延迟或丢弃应答 | 付款码、二维码、查单、关单、退款 | | 坏签、缺 `x-yop-sign`(夹具 ①) | 在合法签名的应答上改一个字节或去掉签名头 | 同上;期望停在验签,`signature_result=bad/missing` | | 签名有效但缺 `payAmount`、金额不一致、身份不一致(夹具 ②) | 见下方说明 | 查单、通知;期望验签通过后在金额 / 身份检查拒绝 | | 未列码、网关拒收 40042 / 40047 / 40029 | 固定应答 | 全部 | | 通知重复、乱序、未知订单 | 隔离环境用测试平台密钥封装通知(沙箱里无法伪造易宝签名) | 支付、退款通知 | | 数据库死锁、锁等待超时 | 真实 MySQL 双连接(沿用 #15 的 harness) | 收款、退款、nonce | | worker 停跑 | 停调度进程 | 查单、推送、告警 | | 派发后进程中断 | 隔离记录型通道收到请求后杀掉本服务进程 | 收款、退款、关单;见 21.11 | | 事务提交后、写文件前中断 | 只在隔离环境开启的测试钩子:业务事务提交后、追加状态行(和第③段报文)进文件前让进程退出;生产配置里没有这个钩子,开启开关只认测试环境 | 报文双写、补写和重建;L-5、L-5b、L-5c | 两类夹具必须分开(Jim C): - 夹具 ① 只验证“坏签被验签拦下”,不能当作金额、身份检查的证据。 - 夹具 ② 在**完全隔离的配置**里用临时生成的测试平台密钥对(不是易宝密钥,也不向任何人要易宝密钥)对改过字段的应答或通知**重新签名 / 封装**,本服务的验签代码照常运行、不绕过,验签通过后由金额 / 身份检查拒绝。 - 每例证据记录:实际到达的检查(`signature_result`、`match_result` 等字段)和拒绝原因;结果标“隔离模拟”,不冒充易宝沙箱业务实证。沙箱里因为没有易宝私钥,造不出夹具 ②。
部署路径与来源(部署清单 A3,Jim 第 6 条)
| 路径 | 方法 | 允许来源 | | --- | --- | --- | | `/api/v1/notify/yeepay` | POST | 公网 443,易宝回调来源(按《回调网络配置》用域名 `out.yeepay.com` 解析同步,不写死 IP) | | `/api/v1/notify/yeepay/refund` | POST | 同上 | | `/rest/v1.0/*`、`/api/v1/payments/*`(旧接口并行期) | 按各接口 | 私网,或已核实的业务后端出口 IP | | `/api/v1/collections/*`、`/api/v1/internal/*` | POST | 私网 | | `/ready`、`/up` | GET | 负载均衡和监控所在私网 | - 只放行上面两条回调的**精确路径**,不放宽整个 `/api/*`。 - 验收:两条回调从公网可达;其余路径从未授权公网来源探测必须被拒(拿实际探测结果,不只看安全组 443 截图);业务调用只从私网或已核实出口成功。
不在本设计范围
- 分账、归集、资金方案、循环收款池、提现、余额(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.4.2.1payment-service-D2
D2 就绪检查支付设计
供负载均衡和监控检查依赖、配置及后台任务是否就绪。
契约状态:设计稿实现状态:设计未实现;基线:新增设计,未实现真实接口验收:未经沙箱验收
GET
/readyDESIGN ONLY · NO LIVE CALLi
设计稿,未实现,未经沙箱验收
字段、规则、错误和有条件决定取自固定设计提交;只作展示,不运行请求或模拟成功。
- 仅静态合成示例;设计未实现、未经沙箱验收;不启用模拟成功,不发送 HTTP。
01接口说明
业务端 / 模块支付服务(易宝同款) / D 运维检查
请求格式来源未定义
鉴权与权限只对负载均衡和监控所在私网开放,不对公网开放(第15、21.10节);具体请求鉴权头未明确。 · 设计展示,禁止网络请求
技术服务归属(元信息)支付服务
负载均衡 / 监控 → 本服务目录引用不授予调用权限。
来源业务约束
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。
02请求头 0 个字段
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
03请求参数 按来源列示,未明确部分不补造
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
04响应参数
所有就绪项通过;正文只给每项 ok / fail,字段名、层级和媒体类型未明确。
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
05错误码 沿用来源定义
| HTTP 状态 | 来源业务码 | 来源说明 |
|---|---|---|
503 | 来源未定义 | 任一项失败;正文只给每项 ok / fail,字段名、层级和媒体类型未明确。 |
06来源与状态
契约状态:设计稿实现状态:设计未实现;基线:新增设计,未实现真实接口验收:未经沙箱验收
sourceCommit
7d2ae11e91ecd073944f98473ef41a67cd0f6146查看原始契约、引用与状态记录
{
"contract": {
"parameters": [],
"responses": {
"200": {
"description": "所有就绪项通过;正文只给每项 ok / fail,字段名、层级和媒体类型未明确。"
},
"503": {
"description": "任一项失败;正文只给每项 ok / fail,字段名、层级和媒体类型未明确。"
}
},
"sourceExtensions": {
"x-permission": "设计展示,禁止网络请求",
"x-source-sections": [
"15",
"19",
"21.3",
"21.4",
"21.10",
"22"
]
}
},
"status": {
"contract": "设计稿",
"implementation": "设计未实现;基线:新增设计,未实现",
"realApiAcceptance": "未经沙箱验收"
},
"provenance": {
"sourceCommit": "7d2ae11e91ecd073944f98473ef41a67cd0f6146",
"sourceBlob": "74501663abc0df79dd867f39057b29e7cd1345b3",
"sourceUrl": "https://github.com/SmartPool-Dev/smartpool-payment-service/pull/17",
"paymentService": {
"code": "D2",
"group": "健康检查",
"purpose": "供负载均衡和监控检查依赖、配置及后台任务是否就绪。",
"direction": "负载均衡 / 监控 → 本服务",
"supplier": {
"name": "易宝没有",
"id": "易宝没有",
"path": "易宝没有"
},
"phase": "P6",
"baselineStatus": "新增设计,未实现",
"differences": [
"本服务自有协议,易宝没有对应接口。"
],
"openQuestions": [
{
"id": "Q17",
"question": "通过标准数值",
"decision": "按第 21.3 节",
"status": "产品负责人已定 11/11",
"impact": "验收"
}
],
"sourceSections": [
{
"id": "15",
"title": "就绪检查(P6)",
"body": "- `GET /up` 保留为存活检查(只说明应用起来了)。\n- 新增 `GET /ready`(只对负载均衡和监控开放,不对公网):\n - 数据库:能连、能读写一张心跳表、迁移是最新;\n - 缓存 / 锁存储:能取放锁(多节点时必须是共享存储,不能是本机文件);\n - C05:应用目录不是 `UnconfiguredPaymentDirectory`,幂等摘要密钥已装配;\n - 通道材料:已加载、未过期(只回布尔,不回任何密钥信息);\n - 定时任务心跳:`payment:poll` 最近一次在 60 秒内、`payment:prune-nonces` 在 10 分钟内;\n - 积压:待查订单、待投递推送、待发告警超过阈值时降级;\n - 生产环境下故障注入开关(第 21.4 节)必须是关的,开着就 503。\n - 全部通过 200,否则 503,正文只给每项 `ok` / `fail`。\n- 不在就绪检查里实时调用易宝(外部依赖另做渠道延迟和错误率监控)。"
},
{
"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": "21.3",
"title": "通过标准(Q17 已定)",
"body": "| 项 | 标准 |\n| --- | --- |\n| 付款码 12 秒预算 | 本服务收到请求到返回 ≤ 12.2 秒(含 0.2 秒测量误差);预算耗尽不发出新 POST |\n| 查单节奏 | 前 2 分钟每 5 秒(±2 秒),之后每 60 秒(±10 秒);满 30 分钟在下一次查询时标待核;满 24 小时停止自动查 |\n| 告警送达 | 触发事务提交后 60 秒内测试接收端收到;同一笔同一原因只收到 1 条 |\n| 第二跳 | 首次投递在 15 秒内;退避间隔按第 11.2 节 ±10% |\n| 就绪检查 | 定时任务心跳超时后 90 秒内 `/ready` 变 503;恢复后 90 秒内回 200 |\n| 渠道写调用次数 | 每例给出期望次数,实际必须完全相等 |"
},
{
"id": "21.4",
"title": "故障注入",
"body": "- 开关:`PAYMENT_FAULT_INJECTION`。只在 `APP_ENV=testing` 或 `sandbox` 且通道地址是沙箱地址时生效;`APP_ENV=production` 时应用**启动即拒绝**带这个开关的配置,`/ready` 也报失败。开关状态写进每条第②段日志。\n- 注入点在通道适配层(替换 HTTP 应答),不 mock 本服务业务和数据库;唯一例外是下表最后一行的“事务提交后、写文件前”中断点,只在隔离环境生效:\n\n| 故障 | 怎么造 | 适用 |\n| --- | --- | --- |\n| 渠道超时(发出前 / 发出后) | 适配层延迟或丢弃应答 | 付款码、二维码、查单、关单、退款 |\n| 坏签、缺 `x-yop-sign`(夹具 ①) | 在合法签名的应答上改一个字节或去掉签名头 | 同上;期望停在验签,`signature_result=bad/missing` |\n| 签名有效但缺 `payAmount`、金额不一致、身份不一致(夹具 ②) | 见下方说明 | 查单、通知;期望验签通过后在金额 / 身份检查拒绝 |\n| 未列码、网关拒收 40042 / 40047 / 40029 | 固定应答 | 全部 |\n| 通知重复、乱序、未知订单 | 隔离环境用测试平台密钥封装通知(沙箱里无法伪造易宝签名) | 支付、退款通知 |\n| 数据库死锁、锁等待超时 | 真实 MySQL 双连接(沿用 #15 的 harness) | 收款、退款、nonce |\n| worker 停跑 | 停调度进程 | 查单、推送、告警 |\n| 派发后进程中断 | 隔离记录型通道收到请求后杀掉本服务进程 | 收款、退款、关单;见 21.11 |\n| 事务提交后、写文件前中断 | 只在隔离环境开启的测试钩子:业务事务提交后、追加状态行(和第③段报文)进文件前让进程退出;生产配置里没有这个钩子,开启开关只认测试环境 | 报文双写、补写和重建;L-5、L-5b、L-5c |\n\n两类夹具必须分开(Jim C):\n- 夹具 ① 只验证“坏签被验签拦下”,不能当作金额、身份检查的证据。\n- 夹具 ② 在**完全隔离的配置**里用临时生成的测试平台密钥对(不是易宝密钥,也不向任何人要易宝密钥)对改过字段的应答或通知**重新签名 / 封装**,本服务的验签代码照常运行、不绕过,验签通过后由金额 / 身份检查拒绝。\n- 每例证据记录:实际到达的检查(`signature_result`、`match_result` 等字段)和拒绝原因;结果标“隔离模拟”,不冒充易宝沙箱业务实证。沙箱里因为没有易宝私钥,造不出夹具 ②。"
},
{
"id": "21.10",
"title": "部署路径与来源(部署清单 A3,Jim 第 6 条)",
"body": "| 路径 | 方法 | 允许来源 |\n| --- | --- | --- |\n| `/api/v1/notify/yeepay` | POST | 公网 443,易宝回调来源(按《回调网络配置》用域名 `out.yeepay.com` 解析同步,不写死 IP) |\n| `/api/v1/notify/yeepay/refund` | POST | 同上 |\n| `/rest/v1.0/*`、`/api/v1/payments/*`(旧接口并行期) | 按各接口 | 私网,或已核实的业务后端出口 IP |\n| `/api/v1/collections/*`、`/api/v1/internal/*` | POST | 私网 |\n| `/ready`、`/up` | GET | 负载均衡和监控所在私网 |\n\n- 只放行上面两条回调的**精确路径**,不放宽整个 `/api/*`。\n- 验收:两条回调从公网可达;其余路径从未授权公网来源探测必须被拒(拿实际探测结果,不只看安全组 443 截图);业务调用只从私网或已核实出口成功。"
},
{
"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": [],
"responseFields": [],
"uncertainty": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。"
],
"displayFields": [],
"keyRules": [],
"authDescription": "只对负载均衡和监控所在私网开放,不对公网开放(第15、21.10节);具体请求鉴权头未明确。"
}
},
"diagnostics": {
"networkEnabled": false,
"documentationOnly": true
},
"businessRules": [
"本服务自有协议,易宝没有对应接口。"
],
"issues": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。"
]
}