商户端可见「我现在能不能收款」

Status: ready-for-agent
更新日期：2026-09-17
规格来源：本会话 grilling 已确认的决策，以及只读代码核查（MerchantOnboardingProgressService、MerchantPaymentReadinessService、MerchantPaymentCapabilityScheduler、两端页面）。
相关留档：汇付控台关闭商户后我们这边会怎样（结论证据不变，其中「遗留一／遗留二」由本规格落实）。
术语：见根 CONTEXT.md 的「商户进件／收款能力／收款就绪」三词；判定依据见 ADR 0002 与 ADR 0001。

Problem Statement

汇付控台关闭商户后，我们的进件申请仍是 approved，进件页读的是本地快照、approved 之后商户又点不到「刷新进度」，于是页面一直显示「商户进件已完成 + 六项全已确认」，而商户其实已经收不了款。商户对环境变化的感知完全依赖「下一次下单被拒」。

同时存在一个已确认的矛盾态：一旦某次刷新发现通道商户状态异常，complete() 不成立、申请回到 pending，页面标题变成「请刷新进度核实各项能力，并按待办理项补齐缺失能力」，可展示的六项却全是「已确认」——因为完成判定还要求结算银行卡核实与通道商户状态这两项，而它们既不在 LABELS 里、view() 也不返回，商户看不到究竟缺什么，只会以为页面出错。

Solution

1. 进件页只讲进件：补出完成判定里此前不可见的两项核实结果（结算银行卡核实、通道商户状态），让「为什么还没完成」永远有对应的可见原因；stages 保持六项、complete() 不动。
2. 收款状态另有入口：商户中心新增只读「收款能力」页，展示与下单闸门同源、同文案的判定结果与最近核实时间，并提供一次受冷却保护的手动核实。
3. 术语收敛：区分「商户进件」（一次性流程）、「收款能力」（通道侧事实）、「收款就绪」（某一时点的判定结果），两端文案按此对齐。

Implementation Decisions（本会话已确认）

关键事实（实现时必须遵守）

• LABELS 同时是展示列表与完成判定的键集：MerchantOnboardingProgressService.complete() 用 LABELS.keySet().stream().allMatch(...)，且 bank／merchantNormal 是**布尔值**而其余六项必须是字符串 "confirmed"。把它们加进 LABELS 会两次破坏完成判定。
• view() 已经读入整份 stages_json（其中就有 bank、merchantNormal、realnameQr），只是只把 LABELS 的键映射进响应。
• stages_json 里除六个阶段外还住着三样**证据**：bank／merchantNormal（完成条件本身）、realnameQr（实名阶段的二维码）、以及本轮新增的 merchantStat（merchantNormal 的通道原值，用于写出「状态异常（CLOSED）」）。它们不是阶段：响应里的 stages 列表由 LABELS 生成，非 LABELS 的键不会进列表，完成判定也只认 LABELS 的六个键。旧记录没有 merchantStat 时回落到申请行的 merchant_stat 快照列。
• 能力刷新**没有任何去重或冷却**：refresh(Long) 无条件查通道，capability(Long) 只在 capability_verified_at 为空时查（不看多旧）；唯一的新鲜度闸门是定时任务那条 SQL。
• merchant_onboarding_application.updated_at 是 MySQL on update current_timestamp，代码从不手写它。
• 迁移当前最大版本 147，下一个是 V148；本地/开发 Flyway 关闭（application.yml），只有测试 profile 打开，**新增列必须同时写迁移与 MerchantOnboardingSchemaInitializer**。
• 全仓没有任何限流/节流工具；唯一的窗口模式是 merchant_onboarding_progress 的 sync_owner/sync_until 5 分钟租约。
• 商户端接口约定：ApiResponse<Map<String,Object>>、principal 经 @RequestAttribute 注入、门店取自 principal（X-Merchant-Store-Id 可选，缺省回落第一个门店）。
• 共享文件（CONTEXT.md、application.yml、AdminManagementController 等）只做增量小改。

Testing Decisions

• 后端沿用 MerchantPaymentReadinessServiceTests 的既有风格：@SpringBootTest + @ActiveProfiles("test") + @MockitoBean 通道 + 原始 SQL 造商户/门店/申请/银行卡，断言服务行为；本规格新增的派生判定与冷却都在这条边界上测，不新开测试专用接口。
• 需要断言「冷却期内不产生通道查询」时，用 mock 通道的调用次数断言，不锁内部方法顺序。
• 前端不新增自动化：仓库目前没有商户端测试基建，页面验收走人工。
• 跑测试用 talent-card-server/scripts/run-server-tests.ps1，遵守 docs/agents/testing.md（已执行迁移只追加、不 drop database、同一 checkout 一次只跑一个 Maven 构建、3 项基线失败不重复验证）。
• 人工验收：改测试库把 merchant_stat 从 NORMAL 改成别的值（以及改回），走 GET /api/merchant/onboarding/status、商户中心自查页、以及一次扫码下单，确认三处口径一致。

人工验收（在共享开发库上，样本值 2026-09-17 校对）

前置：后端重启到含本轮改动的版本；商户端在 HBuilderX 重新编译运行（开发者工具默认连
http://192.168.110.26:8080，与共享开发库 192.168.110.13:3306/talent_card 配套）。改库前记下原值，
验完按最后一节还原。

可用样本（merchant_operator.account → 申请）：

A. 进件页不再自相矛盾（票 01、04）

update merchant_onboarding_progress
   set stages_json = json_set(stages_json, '$.merchantNormal', false, '$.merchantStat', 'CLOSED')
 where application_id = 452;

用 yangye134 打开商户中心 →「商户进件」，应看到：标题「进件办理中」（原来是「收款能力开通中」）；
六项阶段仍全部「已确认」；多出一段「完成条件核实」，其中「通道商户状态」是「失败」+
「斗拱子商户状态异常（CLOSED），请联系汇付或后台处理」；顶部说明是「进件阶段已全部确认，但通道商户
状态未通过核实…」，**不再**是「请按待办理项补齐缺失能力」。把 $.bank 改成 false 可看到
「结算银行卡核实」那一条。

注意：此时点页面上的「刷新进度」会真去查通道、把 merchantNormal 写回真实值，这一页就恢复成
approved——想看这个场景就别点刷新，或看完再点（那也是"以通道为准"的正常表现）。

B. 收款能力自查（票 02、05）

yangye134 打开商户中心 →「收款能力」：显示「现在可以收款」+ 最近核实时间。

• 只读验证：记下 capability_verified_at，反复进出这个页面，该值不应变化（加载不查通道、不写库）。
• verify_merchant：显示「暂时无法收款 · 微信收款能力未就绪：微信支付业务开通、微信实名与授权，暂时无法收款」，
  按钮仍是可点的「立即核实」（它缺的是微信开通与实名，不是通道侧的事，所以允许重新核实）。
• onboarde001：显示「暂时无法收款 · 商户进件尚未审核通过，暂时无法收款」，按钮是「**暂不可核实**」，
  且没有「下次可核实」那一行——没有冷却，只是没有可核实的对象。

C. 手动核实与冷却（票 03）

yangye134：

1. 点「立即核实」→ 后端日志出现一次汇付能力查询，最近核实时间刷新，capability_verified_at 更新。
2. 立刻再点：按钮变成「4:5x 后可再次核实」并逐秒递减；此时强点会提示「刚核实过，请稍后再试」。
3. 留在页面上等倒计时归零：按钮应自己变回「立即核实」（本轮新加的行为，不必退出重进）。
4. 不想等：update merchant_onboarding_application set capability_sync_until = date_sub(now(), interval 1 minute) where id = 452;
   再点一次即可再查。

D. 页面文案 == 下单被拒文案（票 02 的核心）

update merchant_onboarding_application set merchant_stat = 'CLOSED' where id = 452;

1. 「收款能力」页应显示「暂时无法收款 · 斗拱子商户状态异常（CLOSED），暂时无法收款」。
2. 用同一商户在商户端扫码下一笔到店消费单（首页扫码 → 提交）：被拒的 toast 应与上面那句**逐字一致**。
   （等价性另有集成测试 merchantViewReusesTheGateMessage 直接拿闸门抛出的异常消息比对，人工这步是端到端确认。）
3. 再点一次「立即核实」：汇付侧其实没关这家商户，快照会被真实查询纠正回 NORMAL，页面回到可收款。

E. 还原

update merchant_onboarding_application set merchant_stat = 'NORMAL', capability_sync_until = null where id = 452;
update merchant_onboarding_progress
   set stages_json = json_remove(json_set(stages_json, '$.merchantNormal', true), '$.merchantStat')
 where application_id = 452;

Out of Scope

• 缩短能力快照 6 小时窗口、下单前实时校验、提高定时核实频率。
• 下游「下单被拒」的 toast 文案改动（人才端与商户端）。
• 核销后交易确认在关闭商户下能否成功（属支付链路，需实测）。
• 商户端/人才端的任何前端自动化测试基建。
• 人才端（rencaika）页面改动、核销实现、交易下单与退款实现。
• 给进件进度新增定时轮询或页面自动轮询（ADR-0001 已由用户选择不做）。

Further Notes

• 留档文档里「怎么验」的第 1、3 步（控台关户 → 后台点能力刷新 → 查库看通道把哪些字段改成了什么）仍然有效，只是本轮不依赖真实控台操作也能验收：直接改测试库即可造出同样的快照。
• MerchantPaymentReadinessService 里那句「微信收款能力未就绪：…」在术语上指的是**收款就绪**的前提，属存量措辞；本轮不改这段文案（会牵动既有测试断言），仅在此记录，留待下次收口。
• AGENTS.md 指向 CONTEXT.md 查「各业务域的代码位置」，而 CONTEXT.md 里没有代码位置（该指针悬空）。这是仓库级的小缺口，涉及所有业务域，本轮不动，另行提请。