交付出件箱

云机会话交接 · 2026-08-17 v2（批 B 全量在 test · 待长官验收）

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

🔴 第 0 节必须先读完再动手 —— 长官原话：「每次换新会话就会变傻就会经常犯错，这个一定要教好。」

0. 🔴 怎么不变傻（比进度重要，读完再往下）

0.1 变傻的真因：没查就说 · 判据选错 · 拿"没报错"当"对了"

你不是不知道，是手边没有上一会话查过的事实，于是用推测填空 ——
推测听起来跟事实一模一样，长官分不出来，只能等踩坑才发现。

0.2 判据表（"看起来成功"不算成功）

每一行右边那列，都是拿真事故换来的。带 🆕 的是 8-16/17 这一夜新交的学费。

事情	❌ 假判据	✅ 真判据
后端改动没问题	静态检查 / import ok / py_compile	本地真库真跑（🔴 CI 不跑 pytest）
🆕 migration 没问题	本地 `alembic upgrade` 成功	本地是 postgres 超级用户，权限比 test 大。碰核心表（users/organizations）的操作先停 —— 8-17 加个 FK 就把 test 部署干失败了
🆕 判据本身有效	我跑了对比	先证明"撤掉修复会红"。8-17 用 `git stash` 做基线，可工作区本来就干净 → stash 是空操作，那次"基线"其实带着改动，结论无效
🆕 我 grep 到了/没到	`grep -c` 返回数字	对照组 + 查法本身要验：`sed -n '/^function X/,/^}/p'` 在多行函数签名上会截断；用文案当锚会命中自己写的注释
降级保护有效	写了 try/except	注入必错 SQL，看主流程还活不活（PG 里语句失败会让整个事务 aborted，不 rollback = 假降级）
🆕 外部系统的状态	拿本地字段推测	对着外部系统的真实反应做。8-16 拿"本地金额变没变"猜微信记着多少 → 治不了脱节的存量单，白发一版
接口能用	service 层单测全绿	真打 HTTP
前端改动生效	页面返回 200	抓 JS chunk 比对指纹 / 真渲染
🆕 测试红了是不是我干的	看名字像不像	单跑 + 撤改动再跑。本套件在全量下天然不稳（共享真库、顺序相关），同代码连跑结果都不同
🆕 效果图没问题	我渲染出来了	用 Read 把图看一遍。8-17 表格并排半栏 → 列被挤窄、文字全换行，与真实页面不符 = 失真
🆕 溢出自查 0	脚本报 0	先把绝对定位装饰藏起来再量 —— 「新增」标签这类会把父容器 scrollWidth 顶大，报假阳性
长官能打开链接	我自己 curl 通了	给公网域名
数据是真实的	库里有 N 行	看创建时间 / 是不是测试渠道（🆕 本地库 8-17 已清空，现在要自己造数据）
功能做完了	后端接口+测试都绿	前端有没有渲染
发版成功	脚本 exit 0	流水线出现新 run + SUCCESS（🆕 8-17 run#167 就是 FAIL）
没破坏别的	全量跑绿	与基线逐条比对失败清单

0.3 🔴 8-16/17 这一夜最贵的三次

判据打在错的一侧：微信下单撞「订单号重复但金额不一致」，我用"本地金额有没有变"当换号判据 —— 可本地金额早被上一版脏刷过，根本看不出微信那边记着多少。白发一版（MR #412 没治住），改成对着微信的真实反应兜底（#413）才好。
👉 判据要打在出问题的那一侧，别拿本地状态推测外部系统。
本地能跑 ≠ test 能跑：migration 给 closed_by 加了指向 users 的外键。本地超级用户跑得通，test 上 permission denied → 整支回滚 → 三列一个没加，而新代码已上线 → 机构详情 500。
👉 写 migration 前先问：这支碰的是不是结算自己的表？
验证手段本身是坏的：用 git stash 撤改动做基线对比，但工作区干净时 stash 是空操作 —— 那次比对完全无效，差点把自己打穿的测试当成"既有红灯"。
👉 每次做"撤掉改动看会不会红"，先 grep 确认真的撤掉了。

0.4 云机能力（现状，别用过期印象）

✅ 能跑后端真验：已装 sqlalchemy asyncpg greenlet fastapi httpx pytest alembic dotenv reportlab apscheduler passlib；本地 PG 在 127.0.0.1:5432/doctor_ai_brain
跑测试：cd settlement/backend && SETTLEMENT_JWT_SECRET=local-test-secret python3 -m pytest tests/contract/settlement -q
跑 migration：DATABASE_URL='postgresql+asyncpg://postgres:postgres@127.0.0.1:5432/doctor_ai_brain' python3 -m alembic upgrade head
⚠️ 本地库 8-17 已清空（原来被测试数据撑到 3.3 万渠道、越过 asyncpg 32767 参数上限）。要验支付/渠道得自己造数据，用完删。备份在 ~/backups/db-20260817-0303/
✅ 能看 test 的异常（root 8-17 新给的）：sudo test-inspect ps|health|trace|ls|envkeys
trace settlement-api = 异常类型/消息/出错位置（源码行已剥离）。刻意不给 logs
这是今天最大的能力补齐 —— 出 500 先 trace，别再让长官刷页面帮你试
✅ 有浏览器：~/render-env/browse.js（--script 要 module.exports = async (page, log) => {}，URL 要 file://）
✅ 能连 test（走代理，别加 --noproxy）
❌ 仍不能：连 test/生产数据库、看完整应用日志、装 pg_dump（备份用 asyncpg copy_from_query 导 CSV）

0.5 别手工做已固化成命令的事

status                 # 开局：分支/工作区/流水线/卡点
release-test "标题"     # 发版（判据内置）。🔴 不要用 sudo release-to-test
deliver 文件名          # 交付：公网链接
sudo test-inspect trace settlement-api   # 看 test 异常

⚠️ release-test 有个已知坑：推完只等 75 秒，桥没同步完会报「跟 test 一致·无需发版」。
发版前先确认：git ls-remote /srv/git/mirror.git refs/heads/<分支> 的 SHA == 本地 HEAD。

0.6 长官交互

称呼长官 · 先结论 + ≤15 行 + 带表情 · 细节进文档
🔴 干得越细，汇报越要短
🔴 发版必须长官现场令，一次一用不外推
链接裸写，别包反引号
长官问"你觉得 X 合适吗" = 他觉得不合适，先查证再表态，别附和也别硬顶

1. 一页速览

项	状态
主线	门店签约并行化 v2 · 微信支付（批 B）
test	✅ 已全量发（最新 MR #419 / settle-test run#168 SUCCESS，08-17 04:00）
待发	0（分支与 test 一致）
分支	`feature/wechatpay-pay-core`
worktree	`/home/dev2/doctor-ai-brain/.claude/worktrees/bridge-cse_01AcGpTe1nKXvLXiYNPAGF53`
生产	未动。发生产：`sudo release-to-prod --mr <编号>`
数据库	结算独立 alembic（`alembic_version_settlement`），head = phase68_003_store_closed

接手第一件事：等长官验收反馈，别自己发版。

2. 这一夜做完并已上 test 的（MR #411~#419）

支付链路

商品名恢复：收款管理 price_name / 机构详情 product_name（⚠️ 两个接口字段名不同，既有现状，统一要动前端，未做）
🔴 门店永久付不了钱（最严重的一个）：金额变了却复用同一个商户订单号 → 微信拒收 → 待支付单没有清理逻辑 → 这家店再也付不了。
修法：金额变了换新号、换号前先调微信关单、关单必须在 commit 之前；再撞上就关旧号换新号重试一次（is_out_trade_no_conflict）
支付成功屏补机构名：「机构名 · 商品名 × N 席」
收款管理/机构详情的附加字段全部套 SAVEPOINT 降级（读不了只留空，绝不带崩整页）

渠道

默认比例：一级 40→50、二级 25→30（首开+增购），续费不变（20/10）。落点 13 处，第一轮漏了 4 个页面 + 5 处文案，二次全仓 grep 才抓齐
比例守门双向：原来只守 2 个入口（新建二级/改二级资料），补齐另外 2 个（rate/update、service-rates/update，PC+手机端共用）；并加反方向 —— 一级不许调到比名下二级还低，报错一次列全所有踩线的二级
渠道管理报错不再甩原始 JSON（取 detail）

机构

到账已确认后也允许驳回资料（后端本来就放行，挡人的是前端一句）
退款后不许开通：判据从"有没有到账确认记录"改成"还有没有没被退掉的钱"；付款状态如实显示「已退款」
关闭机构：详情页「编辑资料」左边红按钮 → 弹框填原因 → 再点「确认关闭」（两步）；只能关还没开通的；列表整行置灰；留痕（原因/时间/操作人）落业务表并在详情顶部显示两行红条

服务管理

钱跟着订单走：机构详情「支付信息」整块撤掉 → 历史服务记录加「金额」列（实收，已退款划线、没收过显「-」）+「查看详情」里加支付明细块（排在合同下边）
⚠️ 首开单与微信订单没有外键（下单时没传 service_order_id，库里实查为 NULL）→ 走「同机构 + 首次开通」约定关联

交互

三处 DialogFrame 加限高 + 内容区滚动（标题栏和关闭按钮固定）

3. 待长官验收（我验不了的）

已过：① 老机构显示已支付 ② 修改资料收起付款卡 ③ 付款页价目/席位加减 ④ 渠道预填 50/30 + 409 拦截 ⑤ 退款操作人 ⑥ 商品名 ⑦ 微信支付能付成功

还剩（完整清单：~/reports/batchB-acceptance-checklist-20260817.md）：
1. 手机端机构列表筛选
2. 收款管理：筛选是全量筛、操作后有提示条
3. 机构详情：撤掉支付块后没别的问题
4. 服务管理：金额列 + 详情里支付明细（在合同下边）
5. 真付一笔 → 渠道收益按新口径（一级只拿差额）
6. 关闭机构全流程 + 详情顶部两行红条
7. 详情弹框内容长时能竖着滚

4. 悬着的待办

⬜ 长官验收反馈后的修补
⬜ 「商品名」字段命名双轨（price_name / product_name）统一
⬜ 契约测试 25 条老红灯（本地库清空后从 31 降到 25）：test_channel_management 13 条是最大头，都是基线就红，CI 不跑 pytest 所以长期没人管 → 建议专门清一天
⬜ 渠道列表 IN(全部 id) 没分批 —— 8-17 本地库撑爆时暴露的真隐患（生产渠道量远达不到，但值得单独立项）
⬜ 历史数据洗号（旧快照同时存了一级/二级比例，差额可直接算；连带洗 settlement_statements.total_amount 与红字冲销）
⬜ 上生产前：切 settle-prod 流水线源 + 支付授权目录填 https://chat.tongban.love/（必须 https）
⬜ 批 C/D/E 未动

5. 长官已拍板、别再问的

原价 ¥2,880 前端写死；现价/月折算取后端实际单价，月折算取整
支付详情值左对齐 + 标签定宽；标记退款保持独立弹窗
退款提示语两句都留（一句管钱、一句管流程）
分账先账面拆开（一级只拿差额）；打款分离与洗号「后面统一处理」
二级比例不得高于一级，且一级也不许调到比二级低（双向）
渠道默认比例 50/30，续费不变；只改默认值，存量渠道一律不动
关闭机构：手动（不自动）· 词统一叫「关闭」· 原因必填 · 只能关未开通 · 不做自助恢复
机构详情支付块整块撤掉，钱放服务管理；支付明细排在合同下边
已关闭红条：位置 A（顶部状态卡下方通栏）+ 版式 B（两行，实测三行会让笔记本多下拉 54px）

6. 本轮自伤记账（引以为戒）

判据打在错的一侧 → 白发一版（MR #412 没治住支付脱节）
本地能跑≠test 能跑 → migration 加 users 外键，test 部署 FAIL + 机构详情 500
git stash 对干净工作区是空操作 → 假基线，差点误判
sed 截取多行函数签名会截断 → 误报"没改到"
grep 锚点用文案 → 命中自己写的注释，位置量错
自己插按钮撑破了老测试的字符窗口断言（700→1400→又破）
效果图并排半栏 → 列挤窄换行失真，Read 看图才发现
溢出自查第一次报 2 处假阳性（绝对定位装饰）

📌 共同点：判据选错、或没查就说。第 0 节那张表就是这么来的。