交付出件箱

批 B 微信支付 · 方案定稿与后续待办（2026-08-15）

本文所有「现网行为」均读代码得出，标了文件行号可逐条核。不含推测。

一、已完成（后端，5 个 commit 待发 test）

#	内容	关键验证
1	密钥挂载改仓外绝对路径	已发 test（MR #393），发版后复验密钥没被清
2	JSAPI 调起支付签名	官方黄金向量逐字比对
3	建支付订单	服务端算钱 / 身份快照 / 并发兜底（拆掉索引反证过真会红）
4	回调验签 + 解密	篡改密文、错 AAD、错密钥、错算法四种拒绝路径
5	资金链 7 步	三种比例列 / 两级锁 / 半月账期 / 幂等双保险
6	下游 4 处内连接改外连接	反证：内连接下微信收入 count=0（被整行滤掉）
7	下单端点 + 回调端点	真打伪造签名（含微信探测流量格式），返 401
8	退款标记 + 三分支冲销	情形 2 断言两条快照相加 == 0

结算全量 591 passed / 17 failed，与 origin/test 基线逐条一致，零新增故障。

二、现网签约机制（读码结论 · 后续都基于这个）

2.1 只有一条链接

store_signup.py:236 — 签约 token 里装的是 channel_id（渠道），不是机构。
一条链接 = 该渠道的通用签约入口，不认人，谁打开都能开新的一份。

2.2 草稿不保存

signup/page.tsx:84-88 — localStorage 只在提交成功后写入
{orgId, storeName, contactPhone, status, reviewToken}。
⇒ 填一半退出，什么都不留。

2.3 重复打开靠本机缓存

signup/page.tsx:70 — 再次打开同一条链接，从 localStorage 读出「已提交机构」列表，
页面给「继续查看状态」按钮（:480）跳进行中流程；同一页也可直接再填一份新的。
⇒ 用户手上永远只有那一条链接，一条链接同时承载「新建」与「继续」。

2.4 提交即新建

services/settlement/store_signup.py:706 — 无条件 OrgSignupProfile(...) 新建，
没有任何「查已有档案」逻辑。同一个人重复提交就是多条档案，靠平台审核人工判重。

三、授权方案（长官 2026-08-15 拍板 · 定稿）

3.1 触发时机

点签约链接 / 扫签约二维码进来的第一步（方案 §W.1 的 A 方案）。

点链接/扫码
  ↓
【授权落地页】"赵阳智脑官方授权微信登录" [确认]   ← 🔴 必须用户点击才发起
  ↓
微信授权 → 拿 openid / unionid / 昵称 / 头像
  ↓
资料填写页 → 提交（授权信息随这份档案落库）
  ↓
点"去支付" → 直接用已存 openid 下单，不再授权

🔴 绝不自动跳：微信 2022-07-12 起对无用户交互的 snsapi_userinfo 打开快照页模式，
返回的是虚拟 openid，拿它下单会绑到假身份。项目已踩过一次
（web/app/h5/chat/components/seat-wx-auth-landing.tsx 同目录测试钉着这条）。

3.2 各场景行为（全部有代码依据）

场景	行为	依据
点链接进来	授权落地页，点击才发起	方案 §W.1
填一半退出，再进来	重新授权（草稿没存，openid 也没落库）	§2.2
提交成功	openid/unionid/昵称/头像随这份档案落库	§2.4
再签一家	用同一次授权的 openid，不再弹（同人同微信=同 openid）	§2.3
已提交的进"进行中"付款	档案里已有 openid，不授权	§2.3
老档案付款（批 B 之前的）	档案无 openid → 弹一次临时授权页，授权完回填档案，之后不再弹	长官定
拒绝授权	停在落地页可重试，不让往下走（没 openid 也付不了钱）	长官定
微信外打开	提示「请在微信中打开」，不让继续	长官定

3.3 页面文案

页面不解释任何机制（不提 openid、不提快照页）：

      赵阳智脑官方授权微信登录
            [ 确认 ]          ← 点击中显示「正在跳转微信授权…」
      点击后将跳转微信授权页确认

样式照抄现网 seat-wx-auth-landing.tsx（2778 字节，已验证可用）。

四、后续待做

4.1 授权（批 C 的活提前到批 B 做，批 C 直接复用）

[ ] org_signup_profiles 加 4 列：payer_openid / unionid / payer_nickname / payer_avatar（迁移）
[ ] 结算侧换 openid 接口 —— 走 core_client 调核心（appsecret 只在核心侧，
现成实现见 app/api/wx_openid_probe.py 的 exchange_code()，已实测跑通）
[ ] 授权落地页（照抄现网样式 · 点击才发起 · 拒绝不放行 · 微信外提示）
[ ] 老档案付款前的临时授权页（同一套组件复用）

4.2 前端（方案明写的 4 处，目前一行未动）

[ ] 门店端支付页：点"去支付"拉起微信收银台（没有它一分钱也付不了）
[ ] 支付记录页 → 详情弹窗 → 标记退款入口（后端接口已就绪）
[ ] 机构列表加付款状态列：已支付(绿) / 未支付(黄) / 已退款(蓝) + 筛选
[ ] 机构详情支付信息块：商品/单价/数量/合计/微信交易号/支付时间/付款微信(昵称+头像+openid)/退款留痕

4.3 联调（凑成完整链路后一次性验）

[ ] 发 test
[ ] 长官手机走完整流程：扫码 → 授权 → 填资料 → 提交 → 付 0.01 元
⚠️ 微信没有沙箱，test 用真实商户号，就是真扣钱
[ ] 验：收款管理能看到微信昵称 + 头像 + openid
[ ] 验：收益台账查得到这笔 → 生成结算单 → 明细有这行且总额对得上
[ ] 验：标记退款 → 三种冲销情形各走一次
[ ] 验：重复推送同一笔回调，只产出一份快照

4.3.5 明确排除在本批之外（长官 2026-08-15 定）

微信原路退款：现在不做，后续可能做。当前退款＝平台线下退钱 + 系统打标记做平账。
⚠️ 已知风险：「标记了退款但钱没真退」系统发现不了，靠人工流程保证。
📌 日后要做，先找长官确认；届时注意与线下标记并存时冲销逻辑不能重复执行。

4.4 收尾

[ ] 删两个临时件：app/api/wx_openid_probe.py、/api/wxpay/self-check
（删后各跑一次 grep -rn "wx-probe\|self-check" 确认零残留）
[ ] 🔴 上生产前必须先切结算生产流水线源：settle-prod 最新 run 的仓库仍是
tongban-settlement.git，而 settle-test 是 doctor-ai-brain.git
⇒ 批 B 代码进统一仓后，生产不会构建到它

五、需要长官知情的一处不可逆变更

迁移 phase68_001 动了资金表约束（为支持退款红字冲销）：

received_amount > 0 → <> 0（负数插不进去就做不了冲销；仍禁止 0）
去掉 channel_amount >= 0
UNIQUE(payment_confirmation_id) → 部分唯一（WHERE received_amount > 0）
—— 该约束是防重复入账的关键保护，没有简单删掉，改成只约束正数快照后保护不减

已真跑 downgrade → upgrade 验证可回滚。不认可的话回滚这一个迁移即可。