交付出件箱

云机会话交接 · 2026-08-16（批 B 微信支付 · 后端全通 · 待发 test）

新会话读完本文即可接手，不需回溯对话。 取代 CLOUD-SESSION-HANDOFF-20260815.md。

🔴 第 0 节必须先读——那是防止"换了会话就变傻"的部分，比进度更重要。

0. 🔴 新会话最容易犯的错（长官原话：每次换新会话就会变傻、经常犯错）

上一会话 15 小时里，我犯的错 90% 是同一类：没查就说、没查就做。逐条列出来，照着防。

0.1 铁律：说任何关于现网行为的话之前，先把代码从入口读到落库

我犯过的	后果
猜"签约链接一条对应一家机构"	长官纠正 3 次，浪费半小时
猜服务层文件在 `services/` 实际在 `api/`	测试 import 失败
猜 `core_client` 路径不带 `/internal/settlement` 前缀	单测测不出来，联调才会 404
猜 `opening-result` 走 `serialize_store_signup`	差点改了没效果的地方

做法：grep -rn "def 函数名" app/ 找到真实位置 → 读完整函数 → 再开口。
说不准的直接说"我没查"，不要用推测冒充事实。

0.2 铁律：判据要硬，"看起来成功"不算成功

上一会话犯的错全是判据选错：

我以为的判据	真判据
发版脚本 exit 0 = 发成功	流水线出现新 run 才算（脚本非交互会静默取消）
`cp` 失败 = 没权限	试过 `sg devshare -c` 才算
文件字节相同 = 内容一致	md 会被服务端渲染成 HTML，要看内容在不在
测试跑绿 = 功能对	要拆掉保护看它是否真会红（反证）
断言写了 = 拦得住	我写过 `assert A or B` 而 B 恒真 = 形同虚设

0.3 已固化成命令的，别再手工做（做了就会错）

status                    # 开局：分支/工作区/其他 worktree/流水线/当前卡点，一条命令看全
release-test "标题"        # 发版：自动喂 y + 判据内置（MR号/merged/新 run 三重校验）
deliver 文件名             # 交付：类型白名单 + 密码泄露拦截 + URL 编码 + 出公网链接

🔴 sudo release-to-test 不要直接用 —— 它有 read -p y/N 交互，非交互环境会静默取消却 exit 0。
上一会话为此白发了两次版，是查流水线时间戳才识破的。

0.4 测试偶发不是你改坏的（三条判据，别重跑掩盖）

结算套件有既有的偶发失败，全量跑会随机红 1~2 条。判断方法（避坑指南 C30）：

失败用例跟本次改动有关吗？（无关 → 大概率既有）
单独跑那个文件通过吗？（通过 → 并跑串扰）
🔴 在 origin/test 基线上跑同一个用例，也失败吗？（失败 → 铁证不是你引入的）

判据③ 是唯一铁证。已实测：test_channel_store_profile_view 在基线上单独连跑 4 次红 2 次、
test_revenue_ledger_period_range::test_month_filter... 基线 4 次红 1 次。
基线全量抖动区间：17~18 failed。

0.5 改现网在跑的代码时

改共用件先 grep 调用方（上一会话差点误伤 page_platform_mobile_payment_vouchers）
契约钉子失败时不要删它——按新行为更新（避坑指南第 12 条）。上一会话更新了 5 处钉子
改完 .tsx 必须真编译：~/.npm-global/bin/esbuild <文件> --loader:.tsx=tsx --outfile=/dev/null
UI 配色必须扒现网令牌（主色 #0b9a7a、错误色 #b42318），禁自造
加图片必须照现网写法：微信头像要 referrerPolicy="no-referrer"（有防盗链，不加 PC 端裂图）

0.6 长官交互（详见记忆 `changguan-rules`）

称呼长官（简体）· 回复先结论 + ≤15 行 + 带表情 · 细节进文档
🔴 干得越细，汇报越要短——"认真仔细精准"是对干活的要求，不是对汇报的要求
🔴 发版必须长官现场令，一次一用不外推
交付物做完主动附链接，链接裸写不进代码块（进了点不动）

1. 一页速览

项	状态
主线	门店签约并行化 v2 · 微信支付版（批 B）
待发 test	🔴 20 个 commit · 45 文件 · +4386 行 · 工作区干净
分支	`feature/wechatpay-pay-core`（worktree: `.claude/worktrees/bridge-cse_01AcGpTe1nKXvLXiYNPAGF53`）
后端	✅ 全通（授权/下单/支付/回调/资金链/退款/台账/详情/列表）
前端	✅ 授权页、支付页、详情支付块、列表状态列 ⬜ 支付记录页、老档案临时授权
全量测试	619 passed / 17 failed，与基线逐条一致
联调	⏸️ 等发版 + 长官手机付 0.01 元（⚠️ 真扣钱，微信无沙箱）

2. 批 B 已完成（20 commit 逐条）

2.1 基础设施

66fc5d4c 密钥挂载改仓外绝对路径 —— deploy/ 是 CI 同步区，rsync --delete 每次发版清掉密钥（已在 test 实际发生过，root 定位）

2.2 支付链路

86ffc0dd JSAPI 调起支付签名（官方黄金向量逐字校验）+ 建支付订单
13694d1b 门店支付页改造 + 门店端取价接口
9bb8a892 下单端点 + 回调端点（验签/解密/幂等）
8d9c0b94 未支付订单复用不是拒绝（方案 §89）

2.3 资金链

580685aa 资金链 7 步 + 下游 4 处凭证连接改外连接（路 B）
2e0a028e 退款标记 + 收益三分支冲销（方案 §260）
e34b5304 记录「当前不做微信原路退」+ 防线测试

2.4 授权

d72946bc 核心内部端点 + 结算换身份 + 授权落地页
ae2d7d6c 授权接入签约流程（闸门/取号/带身份提交/落库）
563d29e8 支付页身份改由后端回传（只靠浏览器缓存的话，换个会话就付不了钱）

2.5 平台侧

606ba688 支付记录接口（历史凭证 ∪ 微信订单，两类拼接不重复计数）
93a712fc 支付记录分页（1492 KB → 9 KB）+ 稳定排序防串页
d64764c7 00c062fb 机构详情支付信息块（列出全部支付 + 开通席位数带出订单数量）
434865cf 机构列表付款状态列 + 独立筛选

2.6 测试治理

3e7ec515 f00e2e57 治随机 org_id 撞号 + 加渠道隔离（部分缓解，非根治）

3. 长官在本会话拍板的事（别再问）

#	拍板内容
1	付款人昵称 + 头像 + openid 三项都要存（头像是长官特别追加的）
2	付款人信息存快照 —— 用户日后改微信昵称，历史订单不变
3	审计 `actor_role` 存 `system`（沿用现网口径），展示层渲染成「微信支付」
4	当前不做微信原路退（现在不做，后续可能做，不是永久否定）；退款=线下退钱+系统标记
5	授权时机 = A 方案：点签约链接/扫码进来第一步就授权
6	拒绝授权 → 不让往下走；只允许微信内打开，其他浏览器给提示
7	一人一份档案：A 发给 B，B 打开就是全新一份，重新授权重新填
8	机构详情列出全部支付记录（不是只显示最近一笔）
9	开通账号时席位数默认带出支付订单 quantity（方案 §124）

4. 还没做的（按优先级）

4.1 前端剩余 2 项

⬜ 支付记录页前端（后端 /api/admin/payment-vouchers/records 已就绪，分页也有了）
⬜ 老档案临时授权：批 B 之前的档案没 openid，付款前要弹一次授权补录（组件可复用 store-wx-auth-landing）

4.2 联调（凑齐后一次性验）

⬜ 发 test（release-test "标题"，等长官现场令）
⬜ 长官手机：扫码 → 授权 → 填资料 → 提交 → 付 0.01 元 ⚠️ 真扣钱
⬜ 验：收款管理看到微信昵称+头像+openid → 收益台账查得到 → 结算单明细与总额对得上
⬜ 验：标记退款 → 三种冲销情形各走一次
⬜ 验：重复推送同一笔回调，只产出一份快照

4.3 收尾

⬜ 删两个无鉴权临时件：app/api/wx_openid_probe.py、/api/wxpay/self-check
（删后 grep -rn "wx-probe\|self-check" 确认零残留）
⬜ 🔴 上生产前必须先切结算生产流水线源（详见 ~/reports/batch-b-production-checklist.md）

5. 🔴 上生产前的拦路虎（实查结果，不是转抄）

settle-prod 流水线仍指向旧仓 tongban-settlement.git，而 settle-test 是 doctor-ai-brain.git
⇒ 批 B 代码进统一仓后生产不会构建到它，发了也是白发
统一仓 main 流水线连续全红：根因是孤儿容器占着 doctor-web 名字
（镜像和 doctor-api 都成功了）；且 api 已换新、web 没换 = 生产新旧混跑
origin/main alembic 2 个头（phase70_001 / store_poster_demo_flag）

完整清单：~/reports/batch-b-production-checklist.md（7 节，发版前逐条过）

6. 关键技术事实（动代码前必读）

6.1 微信支付反直觉点

🔴 请求头 Wechatpay-Serial 放微信支付公钥 ID，商户证书序列号放 Authorization 的 serial_no
—— 搞反直接拒签，微信只回"签名错误"不说错在哪
🔴 回调只返 openid，不返昵称头像 —— 那两项只能在网页授权环节拿到
🔴 微信会故意发错误签名探测（WECHATPAY/SIGNTEST/ 前缀），验签失败必须返 4xx/5xx
🔴 snsapi_userinfo 必须用户点击才发起 —— 自动跳会进快照页，拿到虚拟 openid
接口签名 5 行、调起支付签名 4 行，是两套东西
金额单位是分，元→分只能用 Decimal（8.70*100 浮点会得 869.999…）

6.2 资金链

三种业务取三个不同的比例列：首开 rate_percent / 增购 expansion_rate_percent / 续费 renewal_rate_percent
账期是半月（H1=1~15、H2=16~月末），且按北京时间切分（UTC 判会差 8 小时）
退款冲销三分支：未进结算单→作废 / 已进未打款→负数红字冲销 / 已打款→只标记不追

6.3 本批动过的资金表约束（迁移 `phase68_001`）

received_amount > 0 → <> 0（负数冲销要用）
去掉 channel_amount >= 0
UNIQUE(payment_confirmation_id) → 部分唯一（WHERE received_amount > 0）
—— 保护不减，只给冲销开口
已实测可 downgrade → upgrade

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

没查就说：猜签约链接机制，被长官纠正 3 次
判据写松：assert A or B 而 B 恒真，等于没断言
字符串断言误报：注释里写"不该有 appsecret"，被自己的字面匹配判成违规 → 改用 AST
split 切不干净：split("\n@router") 把后面的函数也包进来 → 改用 AST
漏抄现网写法：微信头像漏 referrerPolicy="no-referrer"，PC 端会裂图
说"根治"过头：偶发只是缓解，全量再跑仍有 → 已修正措辞并记 C30
造数据留脏：一次失败后没清，自检时才发现（已清干净）

8. 交付物位置

件	路径
本交接件	`~/reports/CLOUD-SESSION-HANDOFF-20260816.md`
生产准备清单	`~/reports/batch-b-production-checklist.md`
批 B 方案与待办	`~/reports/batch-b-plan-and-todo-20260815.md`
B-后施工图	`~/reports/funds-chain-port-checklist.md`
运维手册	`~/reports/wxpay-ops-runbook.md`
方案正本	`~/reports/门店签约并行化方案v2-微信支付版-20260813.md`
台账	`~/zyai-handbook/CLOUD-WORKLOG-SETTLEMENT.md`

公网取件：deliver <文件> 或 https://dev-tokyo.tail3912a6.ts.net/<文件名>

9. 环境速查

# 跑结算测试（4 个环境变量缺一不可）
cd settlement/backend
DATABASE_URL="postgresql+asyncpg://postgres@127.0.0.1:5432/doctor_ai_brain" \
SETTLEMENT_SERVICE_TOKEN=t SETTLEMENT_JWT_SECRET=s CORE_API_BASE="http://127.0.0.1:8001" \
~/venvs/dab/bin/python -m pytest tests/ -q

# 基线对比（判断"是不是我改坏的"唯一铁证）
cd /home/dev2/doctor-ai-brain && git worktree add /tmp/base origin/test --detach
# ...跑同一个用例... 完了 git worktree remove /tmp/base --force

# 前端编译
~/.npm-global/bin/esbuild <文件>.tsx --loader:.tsx=tsx --outfile=/dev/null

# 微信支付官方文档（本地知识库）
~/.claude/skills/wechatpay-payment-integration/assets/微信支付官网文档/APIv3/普通商户/

⚠️ 云机测试结果汇报必带标签「云机环境·非验收证据」，验收去 test.tongban.love。