From bcb5fbe3249d9fcfe8efab90b09dc47f1d0b5f3a Mon Sep 17 00:00:00 2001
From: yeg <1347747024@qq.com>
Date: 星期四, 17 九月 2026 13:42:22 +0800
Subject: [PATCH] docs(scratch): 补人工验收步骤与开发库样本

---
 .scratch/merchant-capability-visibility/spec.md |   71 +++++++++++++++++++++++++++++++++++
 1 files changed, 71 insertions(+), 0 deletions(-)

diff --git a/.scratch/merchant-capability-visibility/spec.md b/.scratch/merchant-capability-visibility/spec.md
index eb90d79..bca3c70 100644
--- a/.scratch/merchant-capability-visibility/spec.md
+++ b/.scratch/merchant-capability-visibility/spec.md
@@ -55,6 +55,77 @@
 - 跑测试用 `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` → 申请）：
+
+| 账号 | merchant / store | 申请 | 当前状态 |
+| --- | --- | --- | --- |
+| `yangye134`（个人进件验证商户） | 632 / 573 | `application 452` | approved，能力快照 NORMAL／取现 1／自动结算 1，六项阶段全 confirmed → 收款就绪 |
+| `verify_merchant`（存量商户验证专用） | 631 / 572 | `application 448` | approved 且快照正常，但**没有进度记录** → 卡在微信开通与实名 |
+| `onboarde001`（企业进件验证商户） | 633 / 574 | `application 449` | pending（`wechat=missing`）→ 用于"进件未通过"那一类 |
+
+### A. 进件页不再自相矛盾（票 01、04）
+
+```sql
+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 的核心）
+
+```sql
+update merchant_onboarding_application set merchant_stat = 'CLOSED' where id = 452;
+```
+
+1. 「收款能力」页应显示「暂时无法收款 · 斗拱子商户状态异常（CLOSED），暂时无法收款」。
+2. 用同一商户在商户端扫码下一笔到店消费单（首页扫码 → 提交）：被拒的 toast 应与上面那句**逐字一致**。
+   （等价性另有集成测试 `merchantViewReusesTheGateMessage` 直接拿闸门抛出的异常消息比对，人工这步是端到端确认。）
+3. 再点一次「立即核实」：汇付侧其实没关这家商户，快照会被真实查询纠正回 `NORMAL`，页面回到可收款。
+
+### E. 还原
+
+```sql
+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 小时窗口、下单前实时校验、提高定时核实频率。

--
Gitblit v1.7.1