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批次暂定;对账只记录差错和告警,不自动改资金状态。

C5 · 对应易宝接口

易宝名称易宝没有
接口标识易宝没有
易宝路径 / 事件易宝没有
谁调谁验收账号(内网)→ 支付服务
基线现状计划提供,内部只读;不对 POS
开发批次(计划)P1b(暂定,独立PR紧跟P1)

和易宝不一样的地方

  • 本服务自有协议,易宝没有对应接口。
  • payerInfo 整个对象及其 bankId、accountName、bankCardNo、mobilePhoneNo、cardType、userID、buyerLogonId、ypAccountBookNo、appID、channelTrxId、bankPostscript 全部子字段不落日志、不推第二跳;顶层 userId、buyerLogonId、yeepayOpenId、bankCardNo 以及 enterprisePayInfo.enterpriseId 同样删除。channelTrxId 只保留后 4 位,完整值不落、不推。

报文、补写与恢复边界

  • 收款、退款记录长期保存;`payment_exchange_logs` 和报文文件都长期保留,不设保留期限,都纳入备份范围;不设清理任务。
  • 应用数据库账号对 `payment_exchange_logs`、`payment_state_events` 只给 INSERT、SELECT,没有 UPDATE、DELETE(部署时配置,部署清单 B3、D2)。
  • 现有 `payment_state_events` 继续只追加,和报文记录互补(前者是状态事实,后者是报文)。
  • 状态事件也写进文件(评估后采纳):只有报文没有状态事实,数据库丢了就算不出每笔最终状态,所以 `payment_state_events` 的每条也写进同一份文件(`segment=state` 一行一条,带 `payment_ref`、`object_version`、`node`)。状态行的稳定标识是 `payment_ref`+`object_version`(现有唯一键 `payment_event_version_unique`;P4 的退款状态事件同样用“退款对象号+版本号”),不用数据库自增 `id`:数据库从备份恢复后自增号会重新用到,不能拿来去重和比对。状态事件属于业务事务,文件写入放在事务提交之后(afterCommit),避免把回滚了的状态写进文件;进程恰好在提交后、写文件前中断会漏写,由下面的补写任务补上。`payment_state_events` 加一列 `node`(写入节点),只加列、不改已有行。
  • 入口:定时任务 `payment:exchange-log-backfill`(名字以 P1b 为准),也能手工带 `--node=<节点> --from=<时间>` 运行。
  • 周期:每 5 分钟;每次检查范围是上次检查点往前多看 1 小时,到当前时间 −1 分钟(留给正在提交的事务)。最大延迟:节点在线时,漏写的行在中断后 10 分钟内补上(一个周期+运行时间)。
  • 每个节点都跑:这是第 21.2 节“定时任务加 `onOneServer()`”的例外,补写任务不加 `onOneServer()`;防重叠锁的锁名带节点标识(如 `exchange-log-backfill:<node>`),只防同一节点两次同时运行。
  • 两个方向:(a) 数据库有、文件缺:报文按 `log_uid`、状态行按 `payment_ref`+`object_version` 补写进文件,补的行标 `backfilled=true`;(b) 文件有、数据库缺(L-4 的情形):只对报文按 `log_uid` 补插进数据库,标 `source=file_backfill`;状态事件从不由文件写回数据库,补写不产生新状态。
  • 多节点去重:每个节点只补 `node` 等于自己的记录、只写自己的文件,两个节点不碰同一批记录;补插数据库靠 `log_uid` 唯一索引(重复插入直接忽略)。补写文件前,查检查范围覆盖到的每一天的本节点文件(不只查当天),已有就跳过;状态行“已有”要求标识相同且 `created_at` 相同,同标识不同 `created_at` 不算已有,照写(数据库从备份恢复后版本号会重号,见下面“恢复边界”);手工带 `--from` 时同样按覆盖到的每一天查。所以零点前后、同一任务重跑、并发跑都不会出现重复行。
  • 切天和写到哪天:文件按 `Asia/Shanghai`(和第 3 节时间口径一致)的日期切天;补写的行一律追加进运行当天的本节点文件,行里的 `created_at` 仍是原时间。节点永久下线:下线前跑一次;没跑成的,在别的节点手工带 `--node=<下线节点>` 跑,补写的行写进当前节点文件并标 `backfilled_for=<下线节点>`;这时去重要查下线节点自己的文件(或它在服务器外的副本),再加当前节点文件里标了 `backfilled_for=<下线节点>` 的行,不能只查当前节点文件。
  • 顺序:补写的行不在原来那一天的文件里,文件行序也不代表发生顺序;重建和比对一律读全部日期的文件,按 `created_at`+`log_uid`(报文)、`payment_ref`+`object_version`(状态)排序和比较集合,不按文件和行号。
  • 每次补到缺口都告警(第 14.1 节“报文记录”),带补了几条、哪个节点。
  • 文件的用途是查清每一笔和易宝之间发生过什么(四段报文),以及补写过来的状态事件。
  • 数据库还在(没有回退):补写任务把文件补齐;比对时数据库是准的,补写不产生新状态。
  • 数据库丢失且无法恢复,或数据库从备份恢复回来(比文件旧):两种按同一口径处理。备份恢复时,备份点之后文件里有、库里没有的状态行不写回库,这些单进下面的比对清单;算不算证据不足,另按文件判定。
  • 备份恢复后的比对和重新开放(产品负责人 11/11 14:11 亚利桑那已定:先停后开):数据库从备份恢复后,当时所有在用收款入口(A1 付款码、A2 本单二维码,以及并行期仍在用的旧付款码接口 E1)先不开放;带 `--compare-db` 跑一遍比对,把清单交到人手里,由人通知门店哪些账单核实前先不要再收,清单交出去以后再开放收款;停的这段时间门店收现金。支付服务不按账单拦截(不做),这一步靠人,谁通知门店、怎么通知写进部署方案的恢复手册。比对只读,不写库。清单单列,不算“证据不足”的原因,分两种:
  • 库里整笔没有(`db_missing`):备份点之后才建的单。支付服务认不到它,查单回 404,进行中保护和已付保护对它不起作用,之后的易宝通知也只按“不认识的订单”记一笔。易宝侧结果到易宝商户后台或对账单上查。
  • 库里有、缺后面几条状态行(`db_behind`):库里这笔还在进行中的,后台查单会照常追上,两道保护照常有效,列出来供核对。库里已经是失败或已关闭、文件里后面记了成功的,后台查单不会再查,不能依赖进行中保护或已付保护防止重复收款;和 `db_missing` 一样交人核实、通知门店哪些账单核实前先不要再收,具体处理和通知回执留到恢复手册验收。
  • “已证明”的判定:① 最后一条状态行(按 `object_version` 最大)是终态;② 文件里这笔最晚一条渠道终态报文(第②③段的收款成功、失败、已关闭,退款成功、失败;有的话)和它对得上;③ 同一个 `payment_ref`+`object_version` 没有两条内容不同的行。
  • 其余进“证据不足”,一笔可以带多个原因:`terminal_message_without_state`(有渠道终态报文、最后状态行不是对应终态,包括没有状态行)、`not_terminal`(最后可见状态不是终态)、`version_conflict`(违反③,备份恢复后版本号重号造成)。报告对这些单只给“最后可见状态”。`not_terminal` 的单,库里有这笔并且还在进行中的,照常由后台查单追上,不用人工(满 30 分钟、24 小时按原规则转待核);数据库整体丢失,或这笔同时在 `db_missing` 清单里,才逐笔到易宝侧查。
  • 为什么文件证明不了(Jim 11/11):第③段通知报文在给易宝应答前写,状态行在业务事务提交后写;现有代码把回执、成功事实、版本和事件放在同一个事务里(`ReceivePaymentNotification.php`、`ConfirmPayment.php`)。进程在事务提交后、两行都还没追加进文件时中断,文件里留下的内容和“事务提交前就中断”完全一样,本地是否已提交,文件证明不了。第一阶段不做事务前预写,不靠写入顺序排除这个时序。
  • 边界:“已证明”只说明文件前后对得上。进程在事务提交后、写文件前中断造成的缺行,文件自己看不出来(包括失败、已关闭的单后来又收到晚到成功),靠补写任务和每日对账发现。
  • 重建报告对证据不足的单和比对清单上的单不写回、不推送、不发起任何资金写调用;人工核实的结果另记处理人和依据。
  • 所以 L-6 的“只靠文件重建”只对“已证明”的单宣称完整(在上面“边界”之内);其余必须出现在“证据不足”清单里,不能算重建成功。这是恢复演练(部署清单 B5)的判定口径,不是零丢失承诺。
  • 各自独立:两处分别写,一处失败不影响另一处,也不改变资金判定;任何一处写失败都发告警(第 14.1 节)。
  • 不随业务事务回滚:报文记录用独立的数据库连接写入并立即提交,不放在业务事务里;业务事务回滚(`persist_result=rolled_back` 等)时,这条报文在数据库和文件里都保留。
  • 按文件重建(只读核对,P1b 交付):命令 `payment:rebuild-from-files`(名字以 P1b 为准),按记录的 `created_at` 筛日期范围,但文件从范围起点那天一直读到运行当天(补写的行可能在后面几天的文件里),读全部节点的报文文件(含外部副本);产出一份报告文件:每单重建出的状态序列、最后可见状态、是否“已证明”,以及“证据不足”清单(每单带原因代码);带 `--compare-db` 时再和当前数据库只读比对(见下面备份恢复);只读,不写数据库、不推送、不改任何状态。部署验收的恢复演练(部署清单 B5)和 L-5b、L-6 都验它的产出。

每日对账(P8暂定)

  • 收款按商编+orderId、退款按商编+refundRequestId分别关联,不跨商户或类型。
  • 同交易日运行加锁;差错按交易日+类型+商编+单号+差错种类去重,重跑保留既有处理记录,不调用资金写接口。
  • HTTP成功但文件截断、解析失败或CRC64不符,整批失败并告警,本批零差错,按规则重下;字段映射和样例待易宝提供,不猜测。
  • 对账只记录差错和告警,不自动改状态、金额或退款占额。

付款人信息不进日志

  • 脱敏:`authCode` 只留后四位(日志里写 `****1234`);签名(`X-SP-Signature`、`x-yop-sign`、`Authorization`)、密钥、证书、数字信封密文不记;付款人信息不落日志(Q11 已定):付款人标识:顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),以及 `enterprisePayInfo.enterpriseId`,在写日志前删除(判断标准同第 3.3 节);`channelTrxId` 只留后 4 位;只留对账需要的金额、支付方式、时间、渠道交易号后 4 位。注意区分:禁止出现在对外返回里的是付款码尾号;渠道交易号后 4 位(`channel_trade_no_last4`,GPAY02-07)是允许返回的,不要一起删掉。

未完整定义的字段说明

以下为来源点名的内容或脱敏规则,不补造协议字段名、返回位置、类型或媒体格式。

位置来源内容 / 中性标签说明
请求 / 推送正文order_id三者之一,具体校验未明确;第21.1节:order_id 或 bill_no 或 trace_id
请求 / 推送正文bill_no三者之一,具体校验未明确;第21.1节:order_id 或 bill_no 或 trace_id
请求 / 推送正文trace_id三者之一,具体校验未明确;第21.1节:order_id 或 bill_no 或 trace_id
返回log_uid日志记录字段;查询外层和协议类型未明确。记录的稳定标识:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应
返回node日志记录字段;查询外层和协议类型未明确。写这条记录的节点标识(和文件名里的一致)
返回id日志记录字段;查询外层和协议类型未明确。`id` 是数据库自增主键,只在库内用,不写进文件、不作为两份之间的关联号;`created_at` 写入时间(毫秒,应用生成,两份相同)
返回created_at日志记录字段;查询外层和协议类型未明确。`id` 是数据库自增主键,只在库内用,不写进文件、不作为两份之间的关联号;`created_at` 写入时间(毫秒,应用生成,两份相同)
返回trace_id日志记录字段;查询外层和协议类型未明确。一次调用方请求贯穿三段的关联号;后台任务自己生成
返回segment日志记录字段;查询外层和协议类型未明确。`caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);以上是报文表四段;segment=state是文件中的状态事件行,不并入报文表segment枚举。
返回operation日志记录字段;查询外层和协议类型未明确。`aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等
返回app_ref日志记录字段;查询外层和协议类型未明确。调用方和授权范围
返回brand_ref日志记录字段;查询外层和协议类型未明确。调用方和授权范围
返回store_ref日志记录字段;查询外层和协议类型未明确。调用方和授权范围
返回bill_no日志记录字段;查询外层和协议类型未明确。查整条链路用的号码
返回order_id日志记录字段;查询外层和协议类型未明确。查整条链路用的号码
返回payment_ref日志记录字段;查询外层和协议类型未明确。查整条链路用的号码
返回refund_request_id日志记录字段;查询外层和协议类型未明确。查整条链路用的号码
返回http_method日志记录字段;查询外层和协议类型未明确。
返回path日志记录字段;查询外层和协议类型未明确。
返回http_status日志记录字段;查询外层和协议类型未明确。
返回result_code日志记录字段;查询外层和协议类型未明确。易宝 `code` / `status` 或本服务 `error.code`
返回result_status日志记录字段;查询外层和协议类型未明确。易宝 `code` / `status` 或本服务 `error.code`
返回outcome日志记录字段;查询外层和协议类型未明确。本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等
返回latency_ms日志记录字段;查询外层和协议类型未明确。耗时
返回request_body日志记录字段;查询外层和协议类型未明确。脱敏后的完整请求和返回(JSON 文本)
返回response_body日志记录字段;查询外层和协议类型未明确。脱敏后的完整请求和返回(JSON 文本)
返回body_sha256日志记录字段;查询外层和协议类型未明确。原始字节摘要(脱敏前),用于核对
返回related_trace_id日志记录字段;查询外层和协议类型未明确。回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串
返回auth_result第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节)
返回dispatch_stage日志记录字段;查询外层和协议类型未明确。第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send`
返回signature_result日志记录字段;查询外层和协议类型未明确。第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing`
返回notification_key日志记录字段;查询外层和协议类型未明确。第③段:通知去重键(现有 `channel_notifications.notification_key`)
返回match_result日志记录字段;查询外层和协议类型未明确。第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch`
返回dedupe_result日志记录字段;查询外层和协议类型未明确。第③段:`first` / `duplicate`
返回persist_result日志记录字段;查询外层和协议类型未明确。第③段:`committed` / `rolled_back`
返回ack日志记录字段;查询外层和协议类型未明确。第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL`
返回source只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插)
返回backfilled、backfilled_for只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>`

后续范围(第22节)

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

待定问题与有条件决定

编号 / 问题方案状态与条件影响
Q11 付款人信息不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节)产品负责人已定 11/11P1b(日志脱敏)、P7(推送)
Q12 告警接收专门的 Slack 频道;接收人产品负责人、Lihao;资金类 15 分钟内响应,其他当天;webhook 只放 `.env`,P6 前提供(第 14.2 节)产品负责人已定 11/11P6
Q17 通过标准数值按第 21.3 节产品负责人已定 11/11验收
报文存储 报文怎么存、存多久数据库+文件双写,两份都长期保留,不设清理;文件和库不同盘、每天复制到服务器外(第 13.2、13.3 节)产品负责人已定 11/11P1b、部署
报文记录批次 报文记录何时做从 P6 提到 P1b,内部只读查询一起提前(第 17 节)产品负责人暂定 11/11P1b
每日对账 上线前是否加对账加 P8 每日对账,收真钱前置;差错只记录告警、不自动改资金状态(第 13.5 节)批次暂定;“不自动改状态”已定 11/11P8
备份恢复后收款怎么重新开放 恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节)产品负责人已定 11/11 14:11(亚利桑那)P1b、部署方案
  • 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
  • 设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。
  • 第13.1节是日志存储字段表;响应展示仅描述可查询的日志记录,API返回分页、封装、字段必填性未定义。
  • 设计稿未明确请求正文的媒体格式,不根据业务字段推导 Content-Type。
逐条来源规则与上下文

报文记录(三段式日志;11/06 22:28,11/11 改为数据库+文件双写,提到 P1b)

### 13.1 记什么

新表 `payment_exchange_logs`,只追加:

| 字段 | 说明 |
| --- | --- |
| `log_uid` | **记录的稳定标识**:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应 |
| `node` | 写这条记录的节点标识(和文件名里的一致) |
| `id`、`created_at` | `id` 是数据库自增主键,只在库内用,**不写进文件、不作为两份之间的关联号**;`created_at` 写入时间(毫秒,应用生成,两份相同) |
| `trace_id` | 一次调用方请求贯穿三段的关联号;后台任务自己生成 |
| `segment` | `caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);**只在文件里**另有 `state`(状态事件行,第 13.3 节) |
| `source` | 只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插) |
| `backfilled`、`backfilled_for` | 只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>` |
| `operation` | `aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等 |
| `app_ref`、`brand_ref`、`store_ref` | 调用方和授权范围 |
| `bill_no`、`order_id`、`payment_ref`、`refund_request_id` | 查整条链路用的号码 |
| `http_method`、`path`、`http_status` | |
| `result_code`、`result_status` | 易宝 `code` / `status` 或本服务 `error.code` |
| `outcome` | 本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等 |
| `latency_ms` | 耗时 |
| `request_body`、`response_body` | 脱敏后的完整请求和返回(JSON 文本) |
| `body_sha256` | 原始字节摘要(脱敏前),用于核对 |
| `related_trace_id` | 回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串 |
| `auth_result` | 第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节) |
| `dispatch_stage` | 第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send` |
| `signature_result` | 第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing` |
| `notification_key` | 第③段:通知去重键(现有 `channel_notifications.notification_key`) |
| `match_result` | 第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch` |
| `dedupe_result` | 第③段:`first` / `duplicate` |
| `persist_result` | 第③段:`committed` / `rolled_back` |
| `ack` | 第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL` |

部署清单 C1—C3 的逐项对应:C1 调用方→支付 = 第①段(`auth_result`、`request_body`、`response_body`、`app_ref`、`latency_ms`、`trace_id`);C2 支付→易宝 = 第②段(`operation`、`order_id`、`dispatch_stage`、`result_code`、`signature_result`、`latency_ms`、`outcome=unknown` 表示未明);C3 易宝→支付 = 第③段(`notification_key`、`signature_result`、`match_result`、`dedupe_result`、`persist_result`、`ack`、`latency_ms`)。

脱敏样例(合成数据,非真实订单):

```text
segment=caller  operation=aggpay.pay  trace_id=t-01  order_id=100000000000000123_1  auth_result=ok
  request_body={"merchantNo":"<商编>","orderId":"100000000000000123_1","orderAmount":"30.00","authCode":"****1234",...}
  response_body={"code":"00000","status":"PROCESSING",...}  http_status=200  outcome=unknown  latency_ms=4120
segment=channel operation=aggpay.pay  trace_id=t-01  dispatch_stage=response_received  signature_result=ok  result_code=00000  result_status=PROCESSING
segment=channel operation=order.query trace_id=t-07  related_trace_id=t-01  result_code=OPR00000  result_status=SUCCESS  signature_result=ok
segment=notify  operation=pay-result  trace_id=t-09  order_id=100000000000000123_1  notification_key=<摘要>  signature_result=ok
  match_result=matched  dedupe_result=first  persist_result=committed  ack=200 SUCCESS
```

- “所有请求和返回的数据都要记录”:按上表记完整报文,只做下面的脱敏。鉴权失败的请求也记(不认领 nonce、不进业务),但不记请求体;为防刷请求撑爆表,鉴权失败的写入按来源 IP + `app_ref` 限速(建议每分钟每来源前 60 条全记,之后每分钟只记 1 条汇总并带计数),超过阈值发告警(第 14 节“鉴权失败激增”)。
- 脱敏:`authCode` 只留后四位(日志里写 `****1234`);签名(`X-SP-Signature`、`x-yop-sign`、`Authorization`)、密钥、证书、数字信封密文不记;**付款人信息不落日志**(Q11 已定):付款人标识:顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),以及 `enterprisePayInfo.enterpriseId`,在写日志前删除(判断标准同第 3.3 节);`channelTrxId` 只留后 4 位;只留对账需要的金额、支付方式、时间、渠道交易号后 4 位。注意区分:禁止出现在对外返回里的是**付款码**尾号;**渠道交易号后 4 位**(`channel_trade_no_last4`,GPAY02-07)是允许返回的,不要一起删掉。
- 写入时机:第①段在返回前写;第②段在渠道调用返回或超时后写;第③段在应答前写;写日志失败不改变资金判定,但要告警(不能因为日志写不进去就把成功说成失败)。

### 13.2 双写:数据库和文件(产品负责人 11/11 定)

- **同时写两份**:每条报文(①②③④段)写入数据库表 `payment_exchange_logs`,同时追加写入报文文件。写的时候同步写两份,不是事后导出。目的:数据库损坏且无法恢复时,靠文件也能查清每一笔。
- **内容相同**:文件里是同一条记录(同一 `log_uid` / `trace_id`、同样字段,JSON 一行一条;数据库自增 `id` 不进文件),脱敏规则完全相同:付款码只留后 4 位、付款人信息删除、`channelTrxId` 只留后 4 位、签名 / 密钥 / 证书 / 信封密文不记。
- **各自独立**:两处分别写,一处失败不影响另一处,也不改变资金判定;任何一处写失败都发告警(第 14.1 节)。
- **不随业务事务回滚**:报文记录用**独立的数据库连接**写入并立即提交,不放在业务事务里;业务事务回滚(`persist_result=rolled_back` 等)时,这条报文在数据库和文件里都保留。
- **文件要求**:只追加;按天分文件;多节点时文件名带节点标识(如 `exchange-<node>-<yyyy-mm-dd>.log`);放在站点目录以外,只有应用用户能写;不进代码仓库。
- **部署前置条件**(属于部署方案,部署清单 B、D 组验收):报文文件和数据库不在同一块盘;每天把前一天的文件复制到这台服务器以外的地方。

### 13.3 保留和不可改

- 收款、退款记录长期保存;`payment_exchange_logs` 和报文文件**都长期保留,不设保留期限**,都纳入备份范围;不设清理任务。
- 应用数据库账号对 `payment_exchange_logs`、`payment_state_events` 只给 INSERT、SELECT,**没有 UPDATE、DELETE**(部署时配置,部署清单 B3、D2)。
- 现有 `payment_state_events` 继续只追加,和报文记录互补(前者是状态事实,后者是报文)。
- **状态事件也写进文件(评估后采纳)**:只有报文没有状态事实,数据库丢了就算不出每笔最终状态,所以 `payment_state_events` 的每条也写进同一份文件(`segment=state` 一行一条,带 `payment_ref`、`object_version`、`node`)。状态行的**稳定标识是 `payment_ref`+`object_version`**(现有唯一键 `payment_event_version_unique`;P4 的退款状态事件同样用“退款对象号+版本号”),不用数据库自增 `id`:数据库从备份恢复后自增号会重新用到,不能拿来去重和比对。状态事件属于业务事务,文件写入放在事务**提交之后**(afterCommit),避免把回滚了的状态写进文件;进程恰好在提交后、写文件前中断会漏写,由下面的补写任务补上。`payment_state_events` 加一列 `node`(写入节点),只加列、不改已有行。

**补写任务**(P1b):
- 入口:定时任务 `payment:exchange-log-backfill`(名字以 P1b 为准),也能手工带 `--node=<节点> --from=<时间>` 运行。
- 周期:每 5 分钟;每次检查范围是上次检查点往前多看 1 小时,到当前时间 −1 分钟(留给正在提交的事务)。**最大延迟**:节点在线时,漏写的行在中断后 10 分钟内补上(一个周期+运行时间)。
- **每个节点都跑**:这是第 21.2 节“定时任务加 `onOneServer()`”的例外,补写任务不加 `onOneServer()`;防重叠锁的锁名带节点标识(如 `exchange-log-backfill:<node>`),只防同一节点两次同时运行。
- 两个方向:(a) 数据库有、文件缺:报文按 `log_uid`、状态行按 `payment_ref`+`object_version` 补写进文件,补的行标 `backfilled=true`;(b) 文件有、数据库缺(L-4 的情形):只对**报文**按 `log_uid` 补插进数据库,标 `source=file_backfill`;**状态事件从不由文件写回数据库**,补写不产生新状态。
- 多节点去重:每个节点只补 `node` 等于自己的记录、只写自己的文件,两个节点不碰同一批记录;补插数据库靠 `log_uid` 唯一索引(重复插入直接忽略)。补写文件前,查**检查范围覆盖到的每一天**的本节点文件(不只查当天),已有就跳过;状态行“已有”要求标识相同**且** `created_at` 相同,同标识不同 `created_at` 不算已有,照写(数据库从备份恢复后版本号会重号,见下面“恢复边界”);手工带 `--from` 时同样按覆盖到的每一天查。所以零点前后、同一任务重跑、并发跑都不会出现重复行。
- 切天和写到哪天:文件按 `Asia/Shanghai`(和第 3 节时间口径一致)的日期切天;补写的行一律追加进**运行当天**的本节点文件,行里的 `created_at` 仍是原时间。节点永久下线:下线前跑一次;没跑成的,在别的节点手工带 `--node=<下线节点>` 跑,补写的行写进当前节点文件并标 `backfilled_for=<下线节点>`;这时去重要查下线节点自己的文件(或它在服务器外的副本),再加当前节点文件里标了 `backfilled_for=<下线节点>` 的行,不能只查当前节点文件。
- 顺序:补写的行不在原来那一天的文件里,文件行序也不代表发生顺序;重建和比对一律读全部日期的文件,按 `created_at`+`log_uid`(报文)、`payment_ref`+`object_version`(状态)排序和比较集合,不按文件和行号。
- 每次补到缺口都告警(第 14.1 节“报文记录”),带补了几条、哪个节点。

**按文件重建(只读核对,P1b 交付)**:命令 `payment:rebuild-from-files`(名字以 P1b 为准),按记录的 `created_at` 筛日期范围,但文件从范围起点那天一直读到运行当天(补写的行可能在后面几天的文件里),读全部节点的报文文件(含外部副本);产出一份报告文件:每单重建出的状态序列、**最后可见状态**、是否“已证明”,以及“证据不足”清单(每单带原因代码);带 `--compare-db` 时再和当前数据库只读比对(见下面备份恢复);**只读,不写数据库、不推送、不改任何状态**。部署验收的恢复演练(部署清单 B5)和 L-5b、L-6 都验它的产出。

**文件能证明什么(恢复边界)**:
- 文件的用途是查清每一笔和易宝之间发生过什么(四段报文),以及补写过来的状态事件。
- **数据库还在(没有回退)**:补写任务把文件补齐;比对时数据库是准的,补写不产生新状态。
- **数据库丢失且无法恢复**,或**数据库从备份恢复回来(比文件旧)**:两种按同一口径处理。备份恢复时,备份点之后文件里有、库里没有的状态行不写回库,这些单进下面的比对清单;算不算证据不足,另按文件判定。
- **备份恢复后的比对和重新开放(产品负责人 11/11 14:11 亚利桑那已定:先停后开)**:数据库从备份恢复后,当时所有在用收款入口(A1 付款码、A2 本单二维码,以及并行期仍在用的旧付款码接口 E1)**先不开放**;带 `--compare-db` 跑一遍比对,把清单交到人手里,由人通知门店哪些账单核实前先不要再收,清单交出去以后再开放收款;停的这段时间门店收现金。**支付服务不按账单拦截**(不做),这一步靠人,谁通知门店、怎么通知写进部署方案的恢复手册。比对只读,不写库。清单单列,不算“证据不足”的原因,分两种:
  - **库里整笔没有**(`db_missing`):备份点之后才建的单。支付服务认不到它,查单回 404,进行中保护和已付保护对它不起作用,之后的易宝通知也只按“不认识的订单”记一笔。易宝侧结果到易宝商户后台或对账单上查。
  - **库里有、缺后面几条状态行**(`db_behind`):库里这笔还在进行中的,后台查单会照常追上,两道保护照常有效,列出来供核对。库里已经是失败或已关闭、文件里后面记了成功的,后台查单不会再查,不能依赖进行中保护或已付保护防止重复收款;和 `db_missing` 一样交人核实、通知门店哪些账单核实前先不要再收,具体处理和通知回执留到恢复手册验收。
- **“已证明”的判定**:① 最后一条状态行(按 `object_version` 最大)是终态;② 文件里这笔**最晚一条**渠道终态报文(第②③段的收款成功、失败、已关闭,退款成功、失败;有的话)和它对得上;③ 同一个 `payment_ref`+`object_version` 没有两条内容不同的行。
- **其余进“证据不足”**,一笔可以带多个原因:`terminal_message_without_state`(有渠道终态报文、最后状态行不是对应终态,包括没有状态行)、`not_terminal`(最后可见状态不是终态)、`version_conflict`(违反③,备份恢复后版本号重号造成)。报告对这些单只给“最后可见状态”。`not_terminal` 的单,库里有这笔并且还在进行中的,照常由后台查单追上,不用人工(满 30 分钟、24 小时按原规则转待核);数据库整体丢失,或这笔同时在 `db_missing` 清单里,才逐笔到易宝侧查。
- **为什么文件证明不了(Jim 11/11)**:第③段通知报文在给易宝应答前写,状态行在业务事务提交后写;现有代码把回执、成功事实、版本和事件放在同一个事务里(`ReceivePaymentNotification.php`、`ConfirmPayment.php`)。进程在事务提交后、两行都还没追加进文件时中断,文件里留下的内容和“事务提交前就中断”完全一样,本地是否已提交,文件证明不了。第一阶段**不做**事务前预写,不靠写入顺序排除这个时序。
- **边界**:“已证明”只说明文件前后对得上。进程在事务提交后、写文件前中断造成的缺行,文件自己看不出来(包括失败、已关闭的单后来又收到晚到成功),靠补写任务和每日对账发现。
- 重建报告对证据不足的单和比对清单上的单不写回、不推送、不发起任何资金写调用;人工核实的结果另记处理人和依据。
- 所以 L-6 的“只靠文件重建”只对“已证明”的单宣称完整(在上面“边界”之内);其余必须出现在“证据不足”清单里,不能算重建成功。这是恢复演练(部署清单 B5)的判定口径,不是零丢失承诺。

### 13.4 怎么查

- 按 `order_id`、`bill_no`、`payment_ref`、`trace_id`、`related_trace_id` 建索引;P1b 提供内部只读查询接口 `POST /api/v1/internal/exchange-logs`(和报文记录一起提前,Jim 从 P2 起验收要用)(只对私网和验收账号开放,不对 POS),按单号串出①②③④段。

### 13.5 每日对账(P8,产品负责人 11/11 暂定;“不自动改状态”已定)

- 每天下载易宝交易日账单(`bill-trade-day-download`,`/yos/v1.0/std/bill/tradedaydownload`,走 `yos` 网关),和本服务的收款单、退款单逐笔核对。门店是入驻商户,按品牌总部平台商编下载一份(`dataType=platform`),包含下面全部门店(第 7.1 节)。
- 差错至少分四种:易宝有本服务没有、本服务成功易宝没有、金额不符(含手续费不符)、状态不符。跨日的(如 23:59 下单、次日成功)先放缓冲,第二天再对一次仍不符才算差错(沿用 GPAY-15 第 4 条)。
- **只记差错、发告警,不自动改收款单、退款单的资金状态**,差错由人处理(产品负责人 11/11 已定)。
- 账单下载时间、空账单重试、可下载多久以前的:仍待易宝确认(Q21);确认前按 GPAY-15 的推荐(T+1 10:00 下载,空账单每小时重试到 18:00)配置,可改。
- **关联方式**:收款按“商编+orderId”、退款按“商编+退款请求号”(`merchantNo`+`refundRequestId`)关联,收款和退款分两张清单分别核对,不跨类型匹配;orderId 和退款号只在商户内唯一,所以不允许只按单号关联。
- **重跑不重复**:同一交易日可以重跑、两个节点也可能同时跑。同一交易日同一时刻只允许一次运行(锁);差错按“交易日+类型(收款 / 退款)+商编+单号+差错种类”去重,已有同一条差错时不再新增,只记一次“本次运行再次发现”;已有的处理记录保留不动。对平时零差错。对账全程不调用任何资金写接口,前后收款单、退款单的状态、金额和退款占额不变。
- **账单文件不完整**:易宝交易日账单返回文件流并带 CRC64 校验值(API ID `bf91e77fac2b4d6aa7a827bc5bcbcb38`)。HTTP 成功但文件截断、解析失败、CRC64 不符,**整批判失败**并告警,本批不产生任何差错(不把没读到的行记成“易宝没有”),按下载重试规则重下。账单字段映射和样例待易宝提供后补,未确认前不凭猜测写字段(Q21)。
- 差错表只追加;处理记录(处理人、原因、时间)另记,不改原差错行。

告警(P6)

### 14.1 触发

| 类别 | 事件 | 现状 |
| --- | --- | --- |
| 资金 | UNKNOWN 满 30 分钟待核、24 小时停止自动查单、晚到成功、unknown 后成功、金额 / 身份矛盾、terminal_conflict、existence_conflict、退款 FAILED / CANCEL / SUSPEND / 结果不明(Q9) | 代码里已有 `Log::warning`(提交后、去重),未外发 |
| 回调 / 入口 | 验签失败激增、通知持久化失败、第二跳投递失败、调用方鉴权失败激增 | 部分有日志 |
| 报文记录 | 报文写数据库失败、写文件失败(任一处)、补写任务发现缺口 | 新增(P1b 只记失败日志,P6 起外发) |
| 对账 | 每日对账发现差错、账单下载失败、账单校验不过(截断、损坏、CRC64 不符)(P8) | 新增 |
| 任务 | `payment:poll`、`payment:prune-nonces`、关单 worker、报文补写任务(按节点,任一节点超过 15 分钟没跑完一次)停跑或报错、锁争用、数据库连接耗尽 | 只有错误日志 |
| 基础设施 | 备份失败、复制延迟、磁盘、证书到期、WAF / DDoS、费用异常 | 部署侧,不在本仓 |

### 14.2 怎么发

- 新表 `payment_alerts`:`alert_key`(同一笔同一原因唯一,去重)、级别、原因、关联号码、`created_at`、投递状态。资金类告警和状态变更同事务写入,提交后投递。
- 投递适配器:HTTP webhook,发到专门的 Slack 告警频道,失败重试(Q12 已定)。接收人:产品负责人和 Lihao。响应时间:资金类 15 分钟内,其他当天处理。频道和 webhook 由产品负责人在 P6 前提供;webhook 地址只放服务器 `.env`,不进仓库、日志、频道。
- 保留现有 `Log::warning`,但它不再被当作“已通知”。

待定问题与决定

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、验收 |

不拿易宝密钥怎么验

- 发请求:Jim 用一个专门的测试接入应用(如 `qa-sandbox`)的**本服务签名密钥**签 v2 请求;这把密钥只能调沙箱部署,由产品负责人私下提供,不进频道、Issue、PR。易宝密钥只在服务器,Jim 不需要也拿不到。
- 看结果:
  - 三段日志:内部只读查询 `POST /api/v1/internal/exchange-logs`(入参 `order_id` 或 `bill_no` 或 `trace_id`,按时间返回①②③④段,已脱敏),只对内网和验收账号开放;
  - 业务事实:`POST /api/v1/collections/facts`(第 12 节);
  - 就绪:`GET /ready`(第 15 节);
  - 告警:沙箱部署把告警 webhook 指向一个测试接收端,Jim 看接收记录;
  - 渠道写调用次数:按第 21.11 节的独立计数,不按日志行数。
- 每例保存:脱敏请求和返回、②段调用序列和次数、facts 快照、告警接收记录。

渠道写调用怎么计数(Jim D)

- 每次派发(付款码、二维码、关单、退款各算一次写调用;查单、查退款是读调用另计)在**发出前**分配一个 `dispatch_id`,和 `order_id` / `refund_request_id`、`attempt_no` 一起写入派发记录;第②段日志都带 `dispatch_id`。一个 `dispatch_id` 只代表一次网络发送,前后两条日志、`not_sent` 记录都不增加次数。
- 验收计数**不依赖本服务日志**:隔离环境里通道地址指向一个**记录型测试通道**(只在隔离环境存在),它对每个收到的写请求记一行脱敏记录(时间、接口路径、orderId / refundRequestId;不存签名头、完整付款码、密钥),以这里的行数为准。易宝沙箱里没有这个通道,沙箱只核对状态和日志,不判写调用次数。
- 必测三种:

| 场景 | 记录型通道计数 | 本服务表现 |
| --- | --- | --- |
| 派发前预算耗尽 | 0 | 一条 `dispatch_stage=not_sent` 日志,UNKNOWN(未派发) |
| 正常派发,前后两条日志 | 1 | 两条日志同一个 `dispatch_id` |
| 派发后日志写失败,或进程被杀 | 1 | 恢复后按原单查询 / 查退款,不再次写调用(计数仍为 1);派发记录停在“已发出待结果”即视为结果不明 |

不在本设计范围

- 分账、归集、资金方案、循环收款池、提现、余额(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.5.1payment-service-C5

C5 内部日志查询支付设计

按单号查这笔单和易宝之间来回发过的全部数据(敏感信息已打码),给验收和排查问题用,收银台不能调。

契约状态:设计稿实现状态:设计未实现;基线:计划提供,内部只读;不对 POS真实接口验收:未经沙箱验收
POST/api/v1/internal/exchange-logsDESIGN ONLY · NO LIVE CALL
i
设计稿,未实现,未经沙箱验收

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

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

01接口说明

业务端 / 模块支付服务(易宝同款) / C 自有接口
请求格式来源未定义
鉴权与权限仅私网和验收账号开放,不对POS;鉴权头和正文媒体格式设计稿未明确(第13.4节)。 · 设计展示,禁止网络请求
技术服务归属(元信息)支付服务

验收账号(内网)→ 支付服务目录引用不授予调用权限。

来源业务约束
  • 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
  • 设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。
  • 第13.1节是日志存储字段表;响应展示仅描述可查询的日志记录,API返回分页、封装、字段必填性未定义。
  • 设计稿未明确请求正文的媒体格式,不根据业务字段推导 Content-Type。

02请求头 0 个字段

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

03请求参数 按来源列示,未明确部分不补造

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

04响应参数

只列来源点名的业务字段;完整外层、类型、HTTP状态未明确。

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

05错误码 沿用来源定义

设计稿未明确错误响应,保留待确认,不补造错误码。

06来源与状态

契约状态:设计稿实现状态:设计未实现;基线:计划提供,内部只读;不对 POS真实接口验收:未经沙箱验收
sourceCommit7d2ae11e91ecd073944f98473ef41a67cd0f6146
查看原始契约、引用与状态记录
{
  "contract": {
    "parameters": [],
    "responses": {
      "default": {
        "description": "只列来源点名的业务字段;完整外层、类型、HTTP状态未明确。"
      }
    },
    "sourceExtensions": {
      "x-permission": "设计展示,禁止网络请求",
      "x-source-sections": [
        "13",
        "14",
        "19",
        "21.1",
        "21.11",
        "22"
      ]
    }
  },
  "status": {
    "contract": "设计稿",
    "implementation": "设计未实现;基线:计划提供,内部只读;不对 POS",
    "realApiAcceptance": "未经沙箱验收"
  },
  "provenance": {
    "sourceCommit": "7d2ae11e91ecd073944f98473ef41a67cd0f6146",
    "sourceBlob": "74501663abc0df79dd867f39057b29e7cd1345b3",
    "sourceUrl": "https://github.com/SmartPool-Dev/smartpool-payment-service/pull/17",
    "paymentService": {
      "code": "C5",
      "group": "本服务内部与推送",
      "purpose": "按单号查这笔单和易宝之间来回发过的全部数据(敏感信息已打码),给验收和排查问题用,收银台不能调。",
      "direction": "验收账号(内网)→ 支付服务",
      "supplier": {
        "name": "易宝没有",
        "id": "易宝没有",
        "path": "易宝没有"
      },
      "phase": "P1b(暂定,独立PR紧跟P1)",
      "baselineStatus": "计划提供,内部只读;不对 POS",
      "differences": [
        "本服务自有协议,易宝没有对应接口。",
        "payerInfo 整个对象及其 bankId、accountName、bankCardNo、mobilePhoneNo、cardType、userID、buyerLogonId、ypAccountBookNo、appID、channelTrxId、bankPostscript 全部子字段不落日志、不推第二跳;顶层 userId、buyerLogonId、yeepayOpenId、bankCardNo 以及 enterprisePayInfo.enterpriseId 同样删除。channelTrxId 只保留后 4 位,完整值不落、不推。"
      ],
      "openQuestions": [
        {
          "id": "Q11",
          "question": "付款人信息",
          "decision": "不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节)",
          "status": "产品负责人已定 11/11",
          "impact": "P1b(日志脱敏)、P7(推送)"
        },
        {
          "id": "Q12",
          "question": "告警接收",
          "decision": "专门的 Slack 频道;接收人产品负责人、Lihao;资金类 15 分钟内响应,其他当天;webhook 只放 `.env`,P6 前提供(第 14.2 节)",
          "status": "产品负责人已定 11/11",
          "impact": "P6"
        },
        {
          "id": "Q17",
          "question": "通过标准数值",
          "decision": "按第 21.3 节",
          "status": "产品负责人已定 11/11",
          "impact": "验收"
        },
        {
          "id": "报文存储",
          "question": "报文怎么存、存多久",
          "decision": "数据库+文件双写,两份都长期保留,不设清理;文件和库不同盘、每天复制到服务器外(第 13.2、13.3 节)",
          "status": "产品负责人已定 11/11",
          "impact": "P1b、部署"
        },
        {
          "id": "报文记录批次",
          "question": "报文记录何时做",
          "decision": "从 P6 提到 P1b,内部只读查询一起提前(第 17 节)",
          "status": "产品负责人暂定 11/11",
          "impact": "P1b"
        },
        {
          "id": "每日对账",
          "question": "上线前是否加对账",
          "decision": "加 P8 每日对账,收真钱前置;差错只记录告警、不自动改资金状态(第 13.5 节)",
          "status": "批次暂定;“不自动改状态”已定 11/11",
          "impact": "P8"
        },
        {
          "id": "备份恢复后收款怎么重新开放",
          "question": "恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦",
          "decision": "先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节)",
          "status": "产品负责人已定 11/11 14:11(亚利桑那)",
          "impact": "P1b、部署方案"
        }
      ],
      "sourceSections": [
        {
          "id": "13",
          "title": "报文记录(三段式日志;11/06 22:28,11/11 改为数据库+文件双写,提到 P1b)",
          "body": "### 13.1 记什么\n\n新表 `payment_exchange_logs`,只追加:\n\n| 字段 | 说明 |\n| --- | --- |\n| `log_uid` | **记录的稳定标识**:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应 |\n| `node` | 写这条记录的节点标识(和文件名里的一致) |\n| `id`、`created_at` | `id` 是数据库自增主键,只在库内用,**不写进文件、不作为两份之间的关联号**;`created_at` 写入时间(毫秒,应用生成,两份相同) |\n| `trace_id` | 一次调用方请求贯穿三段的关联号;后台任务自己生成 |\n| `segment` | `caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);**只在文件里**另有 `state`(状态事件行,第 13.3 节) |\n| `source` | 只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插) |\n| `backfilled`、`backfilled_for` | 只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>` |\n| `operation` | `aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等 |\n| `app_ref`、`brand_ref`、`store_ref` | 调用方和授权范围 |\n| `bill_no`、`order_id`、`payment_ref`、`refund_request_id` | 查整条链路用的号码 |\n| `http_method`、`path`、`http_status` | |\n| `result_code`、`result_status` | 易宝 `code` / `status` 或本服务 `error.code` |\n| `outcome` | 本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等 |\n| `latency_ms` | 耗时 |\n| `request_body`、`response_body` | 脱敏后的完整请求和返回(JSON 文本) |\n| `body_sha256` | 原始字节摘要(脱敏前),用于核对 |\n| `related_trace_id` | 回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串 |\n| `auth_result` | 第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节) |\n| `dispatch_stage` | 第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send` |\n| `signature_result` | 第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing` |\n| `notification_key` | 第③段:通知去重键(现有 `channel_notifications.notification_key`) |\n| `match_result` | 第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch` |\n| `dedupe_result` | 第③段:`first` / `duplicate` |\n| `persist_result` | 第③段:`committed` / `rolled_back` |\n| `ack` | 第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL` |\n\n部署清单 C1—C3 的逐项对应:C1 调用方→支付 = 第①段(`auth_result`、`request_body`、`response_body`、`app_ref`、`latency_ms`、`trace_id`);C2 支付→易宝 = 第②段(`operation`、`order_id`、`dispatch_stage`、`result_code`、`signature_result`、`latency_ms`、`outcome=unknown` 表示未明);C3 易宝→支付 = 第③段(`notification_key`、`signature_result`、`match_result`、`dedupe_result`、`persist_result`、`ack`、`latency_ms`)。\n\n脱敏样例(合成数据,非真实订单):\n\n```text\nsegment=caller  operation=aggpay.pay  trace_id=t-01  order_id=100000000000000123_1  auth_result=ok\n  request_body={\"merchantNo\":\"<商编>\",\"orderId\":\"100000000000000123_1\",\"orderAmount\":\"30.00\",\"authCode\":\"****1234\",...}\n  response_body={\"code\":\"00000\",\"status\":\"PROCESSING\",...}  http_status=200  outcome=unknown  latency_ms=4120\nsegment=channel operation=aggpay.pay  trace_id=t-01  dispatch_stage=response_received  signature_result=ok  result_code=00000  result_status=PROCESSING\nsegment=channel operation=order.query trace_id=t-07  related_trace_id=t-01  result_code=OPR00000  result_status=SUCCESS  signature_result=ok\nsegment=notify  operation=pay-result  trace_id=t-09  order_id=100000000000000123_1  notification_key=<摘要>  signature_result=ok\n  match_result=matched  dedupe_result=first  persist_result=committed  ack=200 SUCCESS\n```\n\n- “所有请求和返回的数据都要记录”:按上表记完整报文,只做下面的脱敏。鉴权失败的请求也记(不认领 nonce、不进业务),但不记请求体;为防刷请求撑爆表,鉴权失败的写入按来源 IP + `app_ref` 限速(建议每分钟每来源前 60 条全记,之后每分钟只记 1 条汇总并带计数),超过阈值发告警(第 14 节“鉴权失败激增”)。\n- 脱敏:`authCode` 只留后四位(日志里写 `****1234`);签名(`X-SP-Signature`、`x-yop-sign`、`Authorization`)、密钥、证书、数字信封密文不记;**付款人信息不落日志**(Q11 已定):付款人标识:顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),以及 `enterprisePayInfo.enterpriseId`,在写日志前删除(判断标准同第 3.3 节);`channelTrxId` 只留后 4 位;只留对账需要的金额、支付方式、时间、渠道交易号后 4 位。注意区分:禁止出现在对外返回里的是**付款码**尾号;**渠道交易号后 4 位**(`channel_trade_no_last4`,GPAY02-07)是允许返回的,不要一起删掉。\n- 写入时机:第①段在返回前写;第②段在渠道调用返回或超时后写;第③段在应答前写;写日志失败不改变资金判定,但要告警(不能因为日志写不进去就把成功说成失败)。\n\n### 13.2 双写:数据库和文件(产品负责人 11/11 定)\n\n- **同时写两份**:每条报文(①②③④段)写入数据库表 `payment_exchange_logs`,同时追加写入报文文件。写的时候同步写两份,不是事后导出。目的:数据库损坏且无法恢复时,靠文件也能查清每一笔。\n- **内容相同**:文件里是同一条记录(同一 `log_uid` / `trace_id`、同样字段,JSON 一行一条;数据库自增 `id` 不进文件),脱敏规则完全相同:付款码只留后 4 位、付款人信息删除、`channelTrxId` 只留后 4 位、签名 / 密钥 / 证书 / 信封密文不记。\n- **各自独立**:两处分别写,一处失败不影响另一处,也不改变资金判定;任何一处写失败都发告警(第 14.1 节)。\n- **不随业务事务回滚**:报文记录用**独立的数据库连接**写入并立即提交,不放在业务事务里;业务事务回滚(`persist_result=rolled_back` 等)时,这条报文在数据库和文件里都保留。\n- **文件要求**:只追加;按天分文件;多节点时文件名带节点标识(如 `exchange-<node>-<yyyy-mm-dd>.log`);放在站点目录以外,只有应用用户能写;不进代码仓库。\n- **部署前置条件**(属于部署方案,部署清单 B、D 组验收):报文文件和数据库不在同一块盘;每天把前一天的文件复制到这台服务器以外的地方。\n\n### 13.3 保留和不可改\n\n- 收款、退款记录长期保存;`payment_exchange_logs` 和报文文件**都长期保留,不设保留期限**,都纳入备份范围;不设清理任务。\n- 应用数据库账号对 `payment_exchange_logs`、`payment_state_events` 只给 INSERT、SELECT,**没有 UPDATE、DELETE**(部署时配置,部署清单 B3、D2)。\n- 现有 `payment_state_events` 继续只追加,和报文记录互补(前者是状态事实,后者是报文)。\n- **状态事件也写进文件(评估后采纳)**:只有报文没有状态事实,数据库丢了就算不出每笔最终状态,所以 `payment_state_events` 的每条也写进同一份文件(`segment=state` 一行一条,带 `payment_ref`、`object_version`、`node`)。状态行的**稳定标识是 `payment_ref`+`object_version`**(现有唯一键 `payment_event_version_unique`;P4 的退款状态事件同样用“退款对象号+版本号”),不用数据库自增 `id`:数据库从备份恢复后自增号会重新用到,不能拿来去重和比对。状态事件属于业务事务,文件写入放在事务**提交之后**(afterCommit),避免把回滚了的状态写进文件;进程恰好在提交后、写文件前中断会漏写,由下面的补写任务补上。`payment_state_events` 加一列 `node`(写入节点),只加列、不改已有行。\n\n**补写任务**(P1b):\n- 入口:定时任务 `payment:exchange-log-backfill`(名字以 P1b 为准),也能手工带 `--node=<节点> --from=<时间>` 运行。\n- 周期:每 5 分钟;每次检查范围是上次检查点往前多看 1 小时,到当前时间 −1 分钟(留给正在提交的事务)。**最大延迟**:节点在线时,漏写的行在中断后 10 分钟内补上(一个周期+运行时间)。\n- **每个节点都跑**:这是第 21.2 节“定时任务加 `onOneServer()`”的例外,补写任务不加 `onOneServer()`;防重叠锁的锁名带节点标识(如 `exchange-log-backfill:<node>`),只防同一节点两次同时运行。\n- 两个方向:(a) 数据库有、文件缺:报文按 `log_uid`、状态行按 `payment_ref`+`object_version` 补写进文件,补的行标 `backfilled=true`;(b) 文件有、数据库缺(L-4 的情形):只对**报文**按 `log_uid` 补插进数据库,标 `source=file_backfill`;**状态事件从不由文件写回数据库**,补写不产生新状态。\n- 多节点去重:每个节点只补 `node` 等于自己的记录、只写自己的文件,两个节点不碰同一批记录;补插数据库靠 `log_uid` 唯一索引(重复插入直接忽略)。补写文件前,查**检查范围覆盖到的每一天**的本节点文件(不只查当天),已有就跳过;状态行“已有”要求标识相同**且** `created_at` 相同,同标识不同 `created_at` 不算已有,照写(数据库从备份恢复后版本号会重号,见下面“恢复边界”);手工带 `--from` 时同样按覆盖到的每一天查。所以零点前后、同一任务重跑、并发跑都不会出现重复行。\n- 切天和写到哪天:文件按 `Asia/Shanghai`(和第 3 节时间口径一致)的日期切天;补写的行一律追加进**运行当天**的本节点文件,行里的 `created_at` 仍是原时间。节点永久下线:下线前跑一次;没跑成的,在别的节点手工带 `--node=<下线节点>` 跑,补写的行写进当前节点文件并标 `backfilled_for=<下线节点>`;这时去重要查下线节点自己的文件(或它在服务器外的副本),再加当前节点文件里标了 `backfilled_for=<下线节点>` 的行,不能只查当前节点文件。\n- 顺序:补写的行不在原来那一天的文件里,文件行序也不代表发生顺序;重建和比对一律读全部日期的文件,按 `created_at`+`log_uid`(报文)、`payment_ref`+`object_version`(状态)排序和比较集合,不按文件和行号。\n- 每次补到缺口都告警(第 14.1 节“报文记录”),带补了几条、哪个节点。\n\n**按文件重建(只读核对,P1b 交付)**:命令 `payment:rebuild-from-files`(名字以 P1b 为准),按记录的 `created_at` 筛日期范围,但文件从范围起点那天一直读到运行当天(补写的行可能在后面几天的文件里),读全部节点的报文文件(含外部副本);产出一份报告文件:每单重建出的状态序列、**最后可见状态**、是否“已证明”,以及“证据不足”清单(每单带原因代码);带 `--compare-db` 时再和当前数据库只读比对(见下面备份恢复);**只读,不写数据库、不推送、不改任何状态**。部署验收的恢复演练(部署清单 B5)和 L-5b、L-6 都验它的产出。\n\n**文件能证明什么(恢复边界)**:\n- 文件的用途是查清每一笔和易宝之间发生过什么(四段报文),以及补写过来的状态事件。\n- **数据库还在(没有回退)**:补写任务把文件补齐;比对时数据库是准的,补写不产生新状态。\n- **数据库丢失且无法恢复**,或**数据库从备份恢复回来(比文件旧)**:两种按同一口径处理。备份恢复时,备份点之后文件里有、库里没有的状态行不写回库,这些单进下面的比对清单;算不算证据不足,另按文件判定。\n- **备份恢复后的比对和重新开放(产品负责人 11/11 14:11 亚利桑那已定:先停后开)**:数据库从备份恢复后,当时所有在用收款入口(A1 付款码、A2 本单二维码,以及并行期仍在用的旧付款码接口 E1)**先不开放**;带 `--compare-db` 跑一遍比对,把清单交到人手里,由人通知门店哪些账单核实前先不要再收,清单交出去以后再开放收款;停的这段时间门店收现金。**支付服务不按账单拦截**(不做),这一步靠人,谁通知门店、怎么通知写进部署方案的恢复手册。比对只读,不写库。清单单列,不算“证据不足”的原因,分两种:\n  - **库里整笔没有**(`db_missing`):备份点之后才建的单。支付服务认不到它,查单回 404,进行中保护和已付保护对它不起作用,之后的易宝通知也只按“不认识的订单”记一笔。易宝侧结果到易宝商户后台或对账单上查。\n  - **库里有、缺后面几条状态行**(`db_behind`):库里这笔还在进行中的,后台查单会照常追上,两道保护照常有效,列出来供核对。库里已经是失败或已关闭、文件里后面记了成功的,后台查单不会再查,不能依赖进行中保护或已付保护防止重复收款;和 `db_missing` 一样交人核实、通知门店哪些账单核实前先不要再收,具体处理和通知回执留到恢复手册验收。\n- **“已证明”的判定**:① 最后一条状态行(按 `object_version` 最大)是终态;② 文件里这笔**最晚一条**渠道终态报文(第②③段的收款成功、失败、已关闭,退款成功、失败;有的话)和它对得上;③ 同一个 `payment_ref`+`object_version` 没有两条内容不同的行。\n- **其余进“证据不足”**,一笔可以带多个原因:`terminal_message_without_state`(有渠道终态报文、最后状态行不是对应终态,包括没有状态行)、`not_terminal`(最后可见状态不是终态)、`version_conflict`(违反③,备份恢复后版本号重号造成)。报告对这些单只给“最后可见状态”。`not_terminal` 的单,库里有这笔并且还在进行中的,照常由后台查单追上,不用人工(满 30 分钟、24 小时按原规则转待核);数据库整体丢失,或这笔同时在 `db_missing` 清单里,才逐笔到易宝侧查。\n- **为什么文件证明不了(Jim 11/11)**:第③段通知报文在给易宝应答前写,状态行在业务事务提交后写;现有代码把回执、成功事实、版本和事件放在同一个事务里(`ReceivePaymentNotification.php`、`ConfirmPayment.php`)。进程在事务提交后、两行都还没追加进文件时中断,文件里留下的内容和“事务提交前就中断”完全一样,本地是否已提交,文件证明不了。第一阶段**不做**事务前预写,不靠写入顺序排除这个时序。\n- **边界**:“已证明”只说明文件前后对得上。进程在事务提交后、写文件前中断造成的缺行,文件自己看不出来(包括失败、已关闭的单后来又收到晚到成功),靠补写任务和每日对账发现。\n- 重建报告对证据不足的单和比对清单上的单不写回、不推送、不发起任何资金写调用;人工核实的结果另记处理人和依据。\n- 所以 L-6 的“只靠文件重建”只对“已证明”的单宣称完整(在上面“边界”之内);其余必须出现在“证据不足”清单里,不能算重建成功。这是恢复演练(部署清单 B5)的判定口径,不是零丢失承诺。\n\n### 13.4 怎么查\n\n- 按 `order_id`、`bill_no`、`payment_ref`、`trace_id`、`related_trace_id` 建索引;P1b 提供内部只读查询接口 `POST /api/v1/internal/exchange-logs`(和报文记录一起提前,Jim 从 P2 起验收要用)(只对私网和验收账号开放,不对 POS),按单号串出①②③④段。\n\n### 13.5 每日对账(P8,产品负责人 11/11 暂定;“不自动改状态”已定)\n\n- 每天下载易宝交易日账单(`bill-trade-day-download`,`/yos/v1.0/std/bill/tradedaydownload`,走 `yos` 网关),和本服务的收款单、退款单逐笔核对。门店是入驻商户,按品牌总部平台商编下载一份(`dataType=platform`),包含下面全部门店(第 7.1 节)。\n- 差错至少分四种:易宝有本服务没有、本服务成功易宝没有、金额不符(含手续费不符)、状态不符。跨日的(如 23:59 下单、次日成功)先放缓冲,第二天再对一次仍不符才算差错(沿用 GPAY-15 第 4 条)。\n- **只记差错、发告警,不自动改收款单、退款单的资金状态**,差错由人处理(产品负责人 11/11 已定)。\n- 账单下载时间、空账单重试、可下载多久以前的:仍待易宝确认(Q21);确认前按 GPAY-15 的推荐(T+1 10:00 下载,空账单每小时重试到 18:00)配置,可改。\n- **关联方式**:收款按“商编+orderId”、退款按“商编+退款请求号”(`merchantNo`+`refundRequestId`)关联,收款和退款分两张清单分别核对,不跨类型匹配;orderId 和退款号只在商户内唯一,所以不允许只按单号关联。\n- **重跑不重复**:同一交易日可以重跑、两个节点也可能同时跑。同一交易日同一时刻只允许一次运行(锁);差错按“交易日+类型(收款 / 退款)+商编+单号+差错种类”去重,已有同一条差错时不再新增,只记一次“本次运行再次发现”;已有的处理记录保留不动。对平时零差错。对账全程不调用任何资金写接口,前后收款单、退款单的状态、金额和退款占额不变。\n- **账单文件不完整**:易宝交易日账单返回文件流并带 CRC64 校验值(API ID `bf91e77fac2b4d6aa7a827bc5bcbcb38`)。HTTP 成功但文件截断、解析失败、CRC64 不符,**整批判失败**并告警,本批不产生任何差错(不把没读到的行记成“易宝没有”),按下载重试规则重下。账单字段映射和样例待易宝提供后补,未确认前不凭猜测写字段(Q21)。\n- 差错表只追加;处理记录(处理人、原因、时间)另记,不改原差错行。"
        },
        {
          "id": "14",
          "title": "告警(P6)",
          "body": "### 14.1 触发\n\n| 类别 | 事件 | 现状 |\n| --- | --- | --- |\n| 资金 | UNKNOWN 满 30 分钟待核、24 小时停止自动查单、晚到成功、unknown 后成功、金额 / 身份矛盾、terminal_conflict、existence_conflict、退款 FAILED / CANCEL / SUSPEND / 结果不明(Q9) | 代码里已有 `Log::warning`(提交后、去重),未外发 |\n| 回调 / 入口 | 验签失败激增、通知持久化失败、第二跳投递失败、调用方鉴权失败激增 | 部分有日志 |\n| 报文记录 | 报文写数据库失败、写文件失败(任一处)、补写任务发现缺口 | 新增(P1b 只记失败日志,P6 起外发) |\n| 对账 | 每日对账发现差错、账单下载失败、账单校验不过(截断、损坏、CRC64 不符)(P8) | 新增 |\n| 任务 | `payment:poll`、`payment:prune-nonces`、关单 worker、报文补写任务(按节点,任一节点超过 15 分钟没跑完一次)停跑或报错、锁争用、数据库连接耗尽 | 只有错误日志 |\n| 基础设施 | 备份失败、复制延迟、磁盘、证书到期、WAF / DDoS、费用异常 | 部署侧,不在本仓 |\n\n### 14.2 怎么发\n\n- 新表 `payment_alerts`:`alert_key`(同一笔同一原因唯一,去重)、级别、原因、关联号码、`created_at`、投递状态。资金类告警和状态变更同事务写入,提交后投递。\n- 投递适配器:HTTP webhook,发到专门的 Slack 告警频道,失败重试(Q12 已定)。接收人:产品负责人和 Lihao。响应时间:资金类 15 分钟内,其他当天处理。频道和 webhook 由产品负责人在 P6 前提供;webhook 地址只放服务器 `.env`,不进仓库、日志、频道。\n- 保留现有 `Log::warning`,但它不再被当作“已通知”。"
        },
        {
          "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.1",
          "title": "不拿易宝密钥怎么验",
          "body": "- 发请求:Jim 用一个专门的测试接入应用(如 `qa-sandbox`)的**本服务签名密钥**签 v2 请求;这把密钥只能调沙箱部署,由产品负责人私下提供,不进频道、Issue、PR。易宝密钥只在服务器,Jim 不需要也拿不到。\n- 看结果:\n  - 三段日志:内部只读查询 `POST /api/v1/internal/exchange-logs`(入参 `order_id` 或 `bill_no` 或 `trace_id`,按时间返回①②③④段,已脱敏),只对内网和验收账号开放;\n  - 业务事实:`POST /api/v1/collections/facts`(第 12 节);\n  - 就绪:`GET /ready`(第 15 节);\n  - 告警:沙箱部署把告警 webhook 指向一个测试接收端,Jim 看接收记录;\n  - 渠道写调用次数:按第 21.11 节的独立计数,不按日志行数。\n- 每例保存:脱敏请求和返回、②段调用序列和次数、facts 快照、告警接收记录。"
        },
        {
          "id": "21.11",
          "title": "渠道写调用怎么计数(Jim D)",
          "body": "- 每次派发(付款码、二维码、关单、退款各算一次写调用;查单、查退款是读调用另计)在**发出前**分配一个 `dispatch_id`,和 `order_id` / `refund_request_id`、`attempt_no` 一起写入派发记录;第②段日志都带 `dispatch_id`。一个 `dispatch_id` 只代表一次网络发送,前后两条日志、`not_sent` 记录都不增加次数。\n- 验收计数**不依赖本服务日志**:隔离环境里通道地址指向一个**记录型测试通道**(只在隔离环境存在),它对每个收到的写请求记一行脱敏记录(时间、接口路径、orderId / refundRequestId;不存签名头、完整付款码、密钥),以这里的行数为准。易宝沙箱里没有这个通道,沙箱只核对状态和日志,不判写调用次数。\n- 必测三种:\n\n| 场景 | 记录型通道计数 | 本服务表现 |\n| --- | --- | --- |\n| 派发前预算耗尽 | 0 | 一条 `dispatch_stage=not_sent` 日志,UNKNOWN(未派发) |\n| 正常派发,前后两条日志 | 1 | 两条日志同一个 `dispatch_id` |\n| 派发后日志写失败,或进程被杀 | 1 | 恢复后按原单查询 / 查退款,不再次写调用(计数仍为 1);派发记录停在“已发出待结果”即视为结果不明 |"
        },
        {
          "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": "order_id",
          "supplierRequired": "未明确",
          "processing": "三者之一,具体校验未明确",
          "required": false,
          "description": "第21.1节:order_id 或 bill_no 或 trace_id"
        },
        {
          "name": "bill_no",
          "supplierRequired": "未明确",
          "processing": "三者之一,具体校验未明确",
          "required": false,
          "description": "第21.1节:order_id 或 bill_no 或 trace_id"
        },
        {
          "name": "trace_id",
          "supplierRequired": "未明确",
          "processing": "三者之一,具体校验未明确",
          "required": false,
          "description": "第21.1节:order_id 或 bill_no 或 trace_id"
        }
      ],
      "responseFields": [
        {
          "name": "log_uid",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。记录的稳定标识:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应"
        },
        {
          "name": "node",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。写这条记录的节点标识(和文件名里的一致)"
        },
        {
          "name": "id",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。`id` 是数据库自增主键,只在库内用,不写进文件、不作为两份之间的关联号;`created_at` 写入时间(毫秒,应用生成,两份相同)"
        },
        {
          "name": "created_at",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。`id` 是数据库自增主键,只在库内用,不写进文件、不作为两份之间的关联号;`created_at` 写入时间(毫秒,应用生成,两份相同)"
        },
        {
          "name": "trace_id",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。一次调用方请求贯穿三段的关联号;后台任务自己生成"
        },
        {
          "name": "segment",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。`caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);以上是报文表四段;segment=state是文件中的状态事件行,不并入报文表segment枚举。"
        },
        {
          "name": "operation",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。`aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等"
        },
        {
          "name": "app_ref",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。调用方和授权范围"
        },
        {
          "name": "brand_ref",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。调用方和授权范围"
        },
        {
          "name": "store_ref",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。调用方和授权范围"
        },
        {
          "name": "bill_no",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "name": "order_id",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "name": "payment_ref",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "name": "refund_request_id",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "name": "http_method",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。"
        },
        {
          "name": "path",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。"
        },
        {
          "name": "http_status",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。"
        },
        {
          "name": "result_code",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。易宝 `code` / `status` 或本服务 `error.code`"
        },
        {
          "name": "result_status",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。易宝 `code` / `status` 或本服务 `error.code`"
        },
        {
          "name": "outcome",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等"
        },
        {
          "name": "latency_ms",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。耗时"
        },
        {
          "name": "request_body",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。脱敏后的完整请求和返回(JSON 文本)"
        },
        {
          "name": "response_body",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。脱敏后的完整请求和返回(JSON 文本)"
        },
        {
          "name": "body_sha256",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。原始字节摘要(脱敏前),用于核对"
        },
        {
          "name": "related_trace_id",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串"
        },
        {
          "name": "auth_result",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节)"
        },
        {
          "name": "dispatch_stage",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send`"
        },
        {
          "name": "signature_result",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing`"
        },
        {
          "name": "notification_key",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:通知去重键(现有 `channel_notifications.notification_key`)"
        },
        {
          "name": "match_result",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch`"
        },
        {
          "name": "dedupe_result",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:`first` / `duplicate`"
        },
        {
          "name": "persist_result",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:`committed` / `rolled_back`"
        },
        {
          "name": "ack",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "日志记录字段;查询外层和协议类型未明确。第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL`"
        },
        {
          "name": "source",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插)"
        },
        {
          "name": "backfilled",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>`"
        },
        {
          "name": "backfilled_for",
          "supplierRequired": "未明确",
          "processing": "未明确",
          "required": false,
          "description": "只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>`"
        }
      ],
      "uncertainty": [
        "未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
        "设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。",
        "第13.1节是日志存储字段表;响应展示仅描述可查询的日志记录,API返回分页、封装、字段必填性未定义。",
        "设计稿未明确请求正文的媒体格式,不根据业务字段推导 Content-Type。"
      ],
      "displayFields": [
        {
          "location": "request",
          "label": "order_id",
          "description": "三者之一,具体校验未明确;第21.1节:order_id 或 bill_no 或 trace_id"
        },
        {
          "location": "request",
          "label": "bill_no",
          "description": "三者之一,具体校验未明确;第21.1节:order_id 或 bill_no 或 trace_id"
        },
        {
          "location": "request",
          "label": "trace_id",
          "description": "三者之一,具体校验未明确;第21.1节:order_id 或 bill_no 或 trace_id"
        },
        {
          "location": "response",
          "label": "log_uid",
          "description": "日志记录字段;查询外层和协议类型未明确。记录的稳定标识:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应"
        },
        {
          "location": "response",
          "label": "node",
          "description": "日志记录字段;查询外层和协议类型未明确。写这条记录的节点标识(和文件名里的一致)"
        },
        {
          "location": "response",
          "label": "id",
          "description": "日志记录字段;查询外层和协议类型未明确。`id` 是数据库自增主键,只在库内用,不写进文件、不作为两份之间的关联号;`created_at` 写入时间(毫秒,应用生成,两份相同)"
        },
        {
          "location": "response",
          "label": "created_at",
          "description": "日志记录字段;查询外层和协议类型未明确。`id` 是数据库自增主键,只在库内用,不写进文件、不作为两份之间的关联号;`created_at` 写入时间(毫秒,应用生成,两份相同)"
        },
        {
          "location": "response",
          "label": "trace_id",
          "description": "日志记录字段;查询外层和协议类型未明确。一次调用方请求贯穿三段的关联号;后台任务自己生成"
        },
        {
          "location": "response",
          "label": "segment",
          "description": "日志记录字段;查询外层和协议类型未明确。`caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);以上是报文表四段;segment=state是文件中的状态事件行,不并入报文表segment枚举。"
        },
        {
          "location": "response",
          "label": "operation",
          "description": "日志记录字段;查询外层和协议类型未明确。`aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等"
        },
        {
          "location": "response",
          "label": "app_ref",
          "description": "日志记录字段;查询外层和协议类型未明确。调用方和授权范围"
        },
        {
          "location": "response",
          "label": "brand_ref",
          "description": "日志记录字段;查询外层和协议类型未明确。调用方和授权范围"
        },
        {
          "location": "response",
          "label": "store_ref",
          "description": "日志记录字段;查询外层和协议类型未明确。调用方和授权范围"
        },
        {
          "location": "response",
          "label": "bill_no",
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "location": "response",
          "label": "order_id",
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "location": "response",
          "label": "payment_ref",
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "location": "response",
          "label": "refund_request_id",
          "description": "日志记录字段;查询外层和协议类型未明确。查整条链路用的号码"
        },
        {
          "location": "response",
          "label": "http_method",
          "description": "日志记录字段;查询外层和协议类型未明确。"
        },
        {
          "location": "response",
          "label": "path",
          "description": "日志记录字段;查询外层和协议类型未明确。"
        },
        {
          "location": "response",
          "label": "http_status",
          "description": "日志记录字段;查询外层和协议类型未明确。"
        },
        {
          "location": "response",
          "label": "result_code",
          "description": "日志记录字段;查询外层和协议类型未明确。易宝 `code` / `status` 或本服务 `error.code`"
        },
        {
          "location": "response",
          "label": "result_status",
          "description": "日志记录字段;查询外层和协议类型未明确。易宝 `code` / `status` 或本服务 `error.code`"
        },
        {
          "location": "response",
          "label": "outcome",
          "description": "日志记录字段;查询外层和协议类型未明确。本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等"
        },
        {
          "location": "response",
          "label": "latency_ms",
          "description": "日志记录字段;查询外层和协议类型未明确。耗时"
        },
        {
          "location": "response",
          "label": "request_body",
          "description": "日志记录字段;查询外层和协议类型未明确。脱敏后的完整请求和返回(JSON 文本)"
        },
        {
          "location": "response",
          "label": "response_body",
          "description": "日志记录字段;查询外层和协议类型未明确。脱敏后的完整请求和返回(JSON 文本)"
        },
        {
          "location": "response",
          "label": "body_sha256",
          "description": "日志记录字段;查询外层和协议类型未明确。原始字节摘要(脱敏前),用于核对"
        },
        {
          "location": "response",
          "label": "related_trace_id",
          "description": "日志记录字段;查询外层和协议类型未明确。回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串"
        },
        {
          "location": "response",
          "label": "auth_result",
          "description": "第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节)"
        },
        {
          "location": "response",
          "label": "dispatch_stage",
          "description": "日志记录字段;查询外层和协议类型未明确。第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send`"
        },
        {
          "location": "response",
          "label": "signature_result",
          "description": "日志记录字段;查询外层和协议类型未明确。第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing`"
        },
        {
          "location": "response",
          "label": "notification_key",
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:通知去重键(现有 `channel_notifications.notification_key`)"
        },
        {
          "location": "response",
          "label": "match_result",
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch`"
        },
        {
          "location": "response",
          "label": "dedupe_result",
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:`first` / `duplicate`"
        },
        {
          "location": "response",
          "label": "persist_result",
          "description": "日志记录字段;查询外层和协议类型未明确。第③段:`committed` / `rolled_back`"
        },
        {
          "location": "response",
          "label": "ack",
          "description": "日志记录字段;查询外层和协议类型未明确。第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL`"
        },
        {
          "location": "response",
          "label": "source",
          "description": "只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插)"
        },
        {
          "location": "response",
          "label": "backfilled、backfilled_for",
          "description": "只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>`"
        }
      ],
      "keyRules": [
        {
          "title": "报文、补写与恢复边界",
          "items": [
            "收款、退款记录长期保存;`payment_exchange_logs` 和报文文件都长期保留,不设保留期限,都纳入备份范围;不设清理任务。",
            "应用数据库账号对 `payment_exchange_logs`、`payment_state_events` 只给 INSERT、SELECT,没有 UPDATE、DELETE(部署时配置,部署清单 B3、D2)。",
            "现有 `payment_state_events` 继续只追加,和报文记录互补(前者是状态事实,后者是报文)。",
            "状态事件也写进文件(评估后采纳):只有报文没有状态事实,数据库丢了就算不出每笔最终状态,所以 `payment_state_events` 的每条也写进同一份文件(`segment=state` 一行一条,带 `payment_ref`、`object_version`、`node`)。状态行的稳定标识是 `payment_ref`+`object_version`(现有唯一键 `payment_event_version_unique`;P4 的退款状态事件同样用“退款对象号+版本号”),不用数据库自增 `id`:数据库从备份恢复后自增号会重新用到,不能拿来去重和比对。状态事件属于业务事务,文件写入放在事务提交之后(afterCommit),避免把回滚了的状态写进文件;进程恰好在提交后、写文件前中断会漏写,由下面的补写任务补上。`payment_state_events` 加一列 `node`(写入节点),只加列、不改已有行。",
            "入口:定时任务 `payment:exchange-log-backfill`(名字以 P1b 为准),也能手工带 `--node=<节点> --from=<时间>` 运行。",
            "周期:每 5 分钟;每次检查范围是上次检查点往前多看 1 小时,到当前时间 −1 分钟(留给正在提交的事务)。最大延迟:节点在线时,漏写的行在中断后 10 分钟内补上(一个周期+运行时间)。",
            "每个节点都跑:这是第 21.2 节“定时任务加 `onOneServer()`”的例外,补写任务不加 `onOneServer()`;防重叠锁的锁名带节点标识(如 `exchange-log-backfill:<node>`),只防同一节点两次同时运行。",
            "两个方向:(a) 数据库有、文件缺:报文按 `log_uid`、状态行按 `payment_ref`+`object_version` 补写进文件,补的行标 `backfilled=true`;(b) 文件有、数据库缺(L-4 的情形):只对报文按 `log_uid` 补插进数据库,标 `source=file_backfill`;状态事件从不由文件写回数据库,补写不产生新状态。",
            "多节点去重:每个节点只补 `node` 等于自己的记录、只写自己的文件,两个节点不碰同一批记录;补插数据库靠 `log_uid` 唯一索引(重复插入直接忽略)。补写文件前,查检查范围覆盖到的每一天的本节点文件(不只查当天),已有就跳过;状态行“已有”要求标识相同且 `created_at` 相同,同标识不同 `created_at` 不算已有,照写(数据库从备份恢复后版本号会重号,见下面“恢复边界”);手工带 `--from` 时同样按覆盖到的每一天查。所以零点前后、同一任务重跑、并发跑都不会出现重复行。",
            "切天和写到哪天:文件按 `Asia/Shanghai`(和第 3 节时间口径一致)的日期切天;补写的行一律追加进运行当天的本节点文件,行里的 `created_at` 仍是原时间。节点永久下线:下线前跑一次;没跑成的,在别的节点手工带 `--node=<下线节点>` 跑,补写的行写进当前节点文件并标 `backfilled_for=<下线节点>`;这时去重要查下线节点自己的文件(或它在服务器外的副本),再加当前节点文件里标了 `backfilled_for=<下线节点>` 的行,不能只查当前节点文件。",
            "顺序:补写的行不在原来那一天的文件里,文件行序也不代表发生顺序;重建和比对一律读全部日期的文件,按 `created_at`+`log_uid`(报文)、`payment_ref`+`object_version`(状态)排序和比较集合,不按文件和行号。",
            "每次补到缺口都告警(第 14.1 节“报文记录”),带补了几条、哪个节点。",
            "文件的用途是查清每一笔和易宝之间发生过什么(四段报文),以及补写过来的状态事件。",
            "数据库还在(没有回退):补写任务把文件补齐;比对时数据库是准的,补写不产生新状态。",
            "数据库丢失且无法恢复,或数据库从备份恢复回来(比文件旧):两种按同一口径处理。备份恢复时,备份点之后文件里有、库里没有的状态行不写回库,这些单进下面的比对清单;算不算证据不足,另按文件判定。",
            "备份恢复后的比对和重新开放(产品负责人 11/11 14:11 亚利桑那已定:先停后开):数据库从备份恢复后,当时所有在用收款入口(A1 付款码、A2 本单二维码,以及并行期仍在用的旧付款码接口 E1)先不开放;带 `--compare-db` 跑一遍比对,把清单交到人手里,由人通知门店哪些账单核实前先不要再收,清单交出去以后再开放收款;停的这段时间门店收现金。支付服务不按账单拦截(不做),这一步靠人,谁通知门店、怎么通知写进部署方案的恢复手册。比对只读,不写库。清单单列,不算“证据不足”的原因,分两种:",
            "库里整笔没有(`db_missing`):备份点之后才建的单。支付服务认不到它,查单回 404,进行中保护和已付保护对它不起作用,之后的易宝通知也只按“不认识的订单”记一笔。易宝侧结果到易宝商户后台或对账单上查。",
            "库里有、缺后面几条状态行(`db_behind`):库里这笔还在进行中的,后台查单会照常追上,两道保护照常有效,列出来供核对。库里已经是失败或已关闭、文件里后面记了成功的,后台查单不会再查,不能依赖进行中保护或已付保护防止重复收款;和 `db_missing` 一样交人核实、通知门店哪些账单核实前先不要再收,具体处理和通知回执留到恢复手册验收。",
            "“已证明”的判定:① 最后一条状态行(按 `object_version` 最大)是终态;② 文件里这笔最晚一条渠道终态报文(第②③段的收款成功、失败、已关闭,退款成功、失败;有的话)和它对得上;③ 同一个 `payment_ref`+`object_version` 没有两条内容不同的行。",
            "其余进“证据不足”,一笔可以带多个原因:`terminal_message_without_state`(有渠道终态报文、最后状态行不是对应终态,包括没有状态行)、`not_terminal`(最后可见状态不是终态)、`version_conflict`(违反③,备份恢复后版本号重号造成)。报告对这些单只给“最后可见状态”。`not_terminal` 的单,库里有这笔并且还在进行中的,照常由后台查单追上,不用人工(满 30 分钟、24 小时按原规则转待核);数据库整体丢失,或这笔同时在 `db_missing` 清单里,才逐笔到易宝侧查。",
            "为什么文件证明不了(Jim 11/11):第③段通知报文在给易宝应答前写,状态行在业务事务提交后写;现有代码把回执、成功事实、版本和事件放在同一个事务里(`ReceivePaymentNotification.php`、`ConfirmPayment.php`)。进程在事务提交后、两行都还没追加进文件时中断,文件里留下的内容和“事务提交前就中断”完全一样,本地是否已提交,文件证明不了。第一阶段不做事务前预写,不靠写入顺序排除这个时序。",
            "边界:“已证明”只说明文件前后对得上。进程在事务提交后、写文件前中断造成的缺行,文件自己看不出来(包括失败、已关闭的单后来又收到晚到成功),靠补写任务和每日对账发现。",
            "重建报告对证据不足的单和比对清单上的单不写回、不推送、不发起任何资金写调用;人工核实的结果另记处理人和依据。",
            "所以 L-6 的“只靠文件重建”只对“已证明”的单宣称完整(在上面“边界”之内);其余必须出现在“证据不足”清单里,不能算重建成功。这是恢复演练(部署清单 B5)的判定口径,不是零丢失承诺。",
            "各自独立:两处分别写,一处失败不影响另一处,也不改变资金判定;任何一处写失败都发告警(第 14.1 节)。",
            "不随业务事务回滚:报文记录用独立的数据库连接写入并立即提交,不放在业务事务里;业务事务回滚(`persist_result=rolled_back` 等)时,这条报文在数据库和文件里都保留。",
            "按文件重建(只读核对,P1b 交付):命令 `payment:rebuild-from-files`(名字以 P1b 为准),按记录的 `created_at` 筛日期范围,但文件从范围起点那天一直读到运行当天(补写的行可能在后面几天的文件里),读全部节点的报文文件(含外部副本);产出一份报告文件:每单重建出的状态序列、最后可见状态、是否“已证明”,以及“证据不足”清单(每单带原因代码);带 `--compare-db` 时再和当前数据库只读比对(见下面备份恢复);只读,不写数据库、不推送、不改任何状态。部署验收的恢复演练(部署清单 B5)和 L-5b、L-6 都验它的产出。"
          ]
        },
        {
          "title": "每日对账(P8暂定)",
          "items": [
            "收款按商编+orderId、退款按商编+refundRequestId分别关联,不跨商户或类型。",
            "同交易日运行加锁;差错按交易日+类型+商编+单号+差错种类去重,重跑保留既有处理记录,不调用资金写接口。",
            "HTTP成功但文件截断、解析失败或CRC64不符,整批失败并告警,本批零差错,按规则重下;字段映射和样例待易宝提供,不猜测。",
            "对账只记录差错和告警,不自动改状态、金额或退款占额。"
          ]
        },
        {
          "title": "付款人信息不进日志",
          "items": [
            "脱敏:`authCode` 只留后四位(日志里写 `****1234`);签名(`X-SP-Signature`、`x-yop-sign`、`Authorization`)、密钥、证书、数字信封密文不记;付款人信息不落日志(Q11 已定):付款人标识:顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),以及 `enterprisePayInfo.enterpriseId`,在写日志前删除(判断标准同第 3.3 节);`channelTrxId` 只留后 4 位;只留对账需要的金额、支付方式、时间、渠道交易号后 4 位。注意区分:禁止出现在对外返回里的是付款码尾号;渠道交易号后 4 位(`channel_trade_no_last4`,GPAY02-07)是允许返回的,不要一起删掉。"
          ]
        }
      ],
      "authDescription": "仅私网和验收账号开放,不对POS;鉴权头和正文媒体格式设计稿未明确(第13.4节)。"
    }
  },
  "diagnostics": {
    "networkEnabled": false,
    "documentationOnly": true
  },
  "businessRules": [
    "本服务自有协议,易宝没有对应接口。",
    "payerInfo 整个对象及其 bankId、accountName、bankCardNo、mobilePhoneNo、cardType、userID、buyerLogonId、ypAccountBookNo、appID、channelTrxId、bankPostscript 全部子字段不落日志、不推第二跳;顶层 userId、buyerLogonId、yeepayOpenId、bankCardNo 以及 enterprisePayInfo.enterpriseId 同样删除。channelTrxId 只保留后 4 位,完整值不落、不推。"
  ],
  "issues": [
    "未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
    "设计稿主要给出用途和规则;未命名的金额、原因、状态、游标、就绪项不补造协议字段名。",
    "第13.1节是日志存储字段表;响应展示仅描述可查询的日志记录,API返回分页、封装、字段必填性未定义。",
    "设计稿未明确请求正文的媒体格式,不根据业务字段推导 Content-Type。"
  ]
}
SmartPool 接口文档源码/候选文档 · 不可真实调用