交付出件箱

← 返回出件箱

云机会话交接 · 2026-08-15（dev2 · 微信支付批 B 进行中）

上一会话上下文将满。新会话读完本文即可无缝接手，不需回溯对话。
前一份交接件 CLOUD-SESSION-HANDOFF-20260813.md 讲的是方案冻结阶段，已被本文取代。

0. 一页速览

项 状态
主线 门店签约并行化 v2 · 微信支付版
批 A 价格管理 ✅ 完工，test 已验收通过，生产按长官令未发
批 B 微信支付 🔄 前半代码已写完，未发 test
当前分支 feature/wechatpay-pay-core（基线 origin/test@6ce34824）· 6 commit 待发
微信侧配置 ✅ 全齐（权限/绑定/密钥/证书/公钥/两个域名/授权目录）
test 服务器 ✅ 证书+配置+nginx 全部就位并验证
生产服务器 ⏸️ 按约定未配
下一动作 发 test → 我 curl 自检验密钥 → 长官点探针给 openid → 做 B-后

1. 立刻要知道的三件事

  1. 批 A 生产未发：test 已验收，长官明确"先不发生产"。要发是 sudo release-to-prod --mr 391。
  2. 批 B 分两步（原四步太碎，长官定合并）：
  3. B-前＝能发起支付：建表/取号/签名/下单/查单 ← 已写完，未发版
  4. B-后＝钱能正确入账：回调 + 资金链 7 步 + 下游 4 处 join 改造
  5. 两个临时件联调完必须删（已写进施工图清单）：
    app/api/wx_openid_probe.py、settlement/.../api/settlement/wechatpay.py 的 /self-check

2. 微信侧配置（已全部就绪，不用再折腾）

项 值 / 状态
商户号 1749330064
appid（服务号「瞳伴智能」） wx0bd8d0601bcc2d62 · 已与商户号已关联
JSAPI 支付权限 ✅ 已开通
APIv3 密钥 / 商户 API 证书 / 微信支付公钥 ✅ 均已办（走公钥模式，不是平台证书模式）
网页授权域名 ✅ test.tongban.love + chat.tongban.love
支付授权目录 ✅ 两个域名都配

⚠️ APIv3 密钥曾被长官贴进对话，长官决定不重设。风险边界已核实：单独泄露不能扣钱
（扣钱要商户私钥）、不能伪造回调（验签用微信支付公钥），只影响回调报文解密。

test 服务器（root 已完成）
- deploy/wxpay/ 下两个 PEM，权限 600；.env.production 8 个 WECHATPAY_ 变量齐
- WECHATPAY_NOTIFY_URL=https://test.tongban.love/api/wxpay/notify
- nginx location /api/wxpay → 127.0.0.1:8002 已 reload，用探针+双服务日志对照验证过*

生产服务器：按约定未配，等 test 联调过 + 长官点头。

3. 批 B 关键设计拍板

3.1 路 B（长官 2026-08-14 拍板）

微信支付照常产出「到账确认」记录，但它挂支付订单而不是凭证；下游只把「凭证」那一层改外连接。

否决路 A（影子凭证）的硬理由
1. 违反方案 §五C:215 自己定的「payment_vouchers 只读、payment_orders 只装微信订单」
2. 「支付记录」列表是「历史线下 ∪ 微信新单」两类拼接，影子凭证会重复计数
3. payment_vouchers.status CHECK 只有三值，填不出设计要的「已支付/已退款」
4. voucher_file_key NOT NULL，而效果图⑦明写「微信支付无凭证」

3.2 为什么必须走「到账确认」表

收益台账（PC/渠道/手机端）与结算单对账明细都是 快照 → 到账确认 → 凭证 的内连接
（revenue_ledger.py:109/228、platform_mobile_paging.py:603、settlement_statements.py:1081）。
微信若不产出确认记录，钱进库但台账查不到；而结算单总额由另一条不看凭证的查询算出
（settlement_statements.py:783）→ 总额有、明细无，结算单自己对不上账。

好消息：下游从凭证上只读 payment_no 一个字段（已逐处 grep 实证），改造面很小。

4. B-前 已完成的内容（6 commit，未发版）

分支 feature/wechatpay-pay-core，基线 origin/test@6ce34824。

文件 作用
settlement/backend/migrations/versions/phase68_000_payment_orders.py 建 payment_orders + payment_order_seq 序列 + 改造 payment_confirmations
settlement/backend/app/models/settlement.py PaymentOrder 模型 + PaymentConfirmation 路B改造
settlement/backend/app/services/settlement/wechatpay_client.py 签名 / 验签 / JSAPI 下单 / 查单
settlement/backend/app/services/settlement/payment_orders.py 订单号取号（序列）
settlement/backend/app/api/settlement/wechatpay.py /api/wxpay/self-check 配置自检（临时件）
app/api/wx_openid_probe.py /api/wx-probe openid 取号页（临时件）
migrations/env.py（核心） 登记 payment_orders 进 autogenerate 排除清单
settlement/backend/requirements.txt 显式钉 cryptography==50.0.0
settlement/deploy/docker-compose.prod.yml 加 ./wxpay:/app/wxpay:ro 只读挂载

新增测试 16 个（签名 7 + 取号 4 + 批A价格 5 已在 test）。结算全量 552 passed / 17 failed，与基线零新增。

关键实现细节（改动前务必知道）

5. 下一步（B-后）怎么做

施工图已备好：~/reports/funds-chain-port-checklist.md（含资金链 7 步逐条位置、
路 B 改造点、钱面验收清单、临时件删除清单）。

顺序
1. 发 B-前 到 test（等长官令）
2. 工程师从云机 curl https://test.tongban.love/api/wxpay/self-check
- 回 ok:true = 商户号/证书/序列号/公钥全对（不花钱、不需 openid）
- 回 stage:"sign" = 签名或证书配错，重点查 Wechatpay-Serial 那条
3. 长官手机微信打开 https://test.tongban.love/api/wx-probe → 点一次授权 → 把 openid 发来
（openid 不是密钥，可以直接贴；页面同时显示当前 appid）
4. 写 B-后：回调接口 + 资金链 7 步移植 + 下游 4 处 join 改造
5. 联调：长官手机付 0.01 元 → 查台账看得见 → 出结算单核明细与总额 → 标退款

⚠️ 微信没有沙箱：test 用的是同一套真实商户号，联调就是真扣钱。

6. 🔴 悬着的拦路虎（不卡 test，卡生产）

  1. 结算生产流水线指向旧仓：sudo release-pipeline-status settle-prod 实测最新 run#7
    的仓库是 tongban-settlement.git，而 settle-test 是 doctor-ai-brain.git。
    ⇒ 批 B 代码进统一仓后生产不会构建到它，上生产前必须先切流水线源。
  2. 统一仓 main 流水线最近全红，root 已定位两个病（要长官点头才能动生产）：
  3. run#131-135：alembic 多头。⚠️ 主会话复算后修正：origin/main 是 2 个头
    （phase70_001 / store_poster_demo_flag，均 fork 于 phase63_002），
    不是 root 说的 4 个 —— 他点名的两个 legacy 头早在 2026-04-14 就被
    d1de4b851a49（down_revision 是二元组）合并了。治本只需 merge 这两个头。
  4. run#136：doctor-web 容器名冲突，且那次 api 换了新的、web 没换，
    生产上可能留着孤儿 web 容器。

7. 本会话的自伤记账（新会话引以为戒）

  1. 🔴 假验证：改过已应用的迁移后没确认库重建，5 条"约束真打"全在无约束的库上通过。
    看到输出全是 INSERT 0 1 才发现。→ 跑断言前先查 pg_constraint 确认约束真在库里。
  2. 🔴 说了没做的话：手册里写"仓库里已经加好了 nginx 段"，其实只 commit 到功能分支
    没发版，误导 root 白找一轮。
  3. 🔴 给了错的验收判据：说"curl 返 404 就是转发对了"，实际对照组也返 404，区分不了
    （root 纠正）。正确判据是带唯一标记的探针 + 双服务日志对照。
  4. 文档两个 bug：APIv3 密钥生成命令 65% 概率不足 32 位；grep 字符类漏数字把
    WECHATPAY_APIV3_KEY 截成 WECHATPAY_APIV（均 root 抓出）。
  5. 批 A 漏登记新表到核心 autogenerate 排除清单，自检才发现（批 B 开工即补做）。

8. 交付物位置

件 路径
本交接件 ~/reports/CLOUD-SESSION-HANDOFF-20260815.md
B-后 施工图 ~/reports/funds-chain-port-checklist.md
运维操作手册 ~/reports/wxpay-ops-runbook.md
超管待办 + 密钥处理规范 ~/reports/wechatpay-superadmin-and-key-handling.md
批 A 范围梳理 ~/reports/batch-a-scope.md
方案正本（1017 行） ~/reports/门店签约并行化方案v2-微信支付版-20260813.md
效果图 ~/reports/signup-v2-mockup.html
台账 ~/zyai-handbook/CLOUD-WORKLOG-SETTLEMENT.md

公网取件：https://dev-tokyo.tail3912a6.ts.net/<文件名>（用户名 dev，密码见 ~/.claude/CLAUDE.md）

9. 长官交互要点（本会话被提醒过的）