更新商户进件spec

yeg

2026-09-15 e7422af834e7751e02a432ec3c32b25540d4e51f

更新商户进件spec

 .scratch/merchant-wechat-onboarding/issues/01-onboarding-wechat-delay-closure.md

@@ -17,17 +17,30 @@

## 实施顺序

1. 核实规格中列出的汇付接口、场景与状态语义，形成与控台参考配置对应的字段依据；只读核对指定存量商户现状。
2. 复用现有应用服务和通道适配边界，实现分阶段结果收敛、显式刷新、未知结果查询与失败步骤重试。
3. 对接商户端与后台进度和操作入口，落实权限边界。
4. 按已确认测试边界验证无回调推进、幂等、部分失败、能力缺失及现有资金语义。
5. 对指定存量商户制定并执行范围内恢复流程，记录通道证据、未完成的人工办理事项及真实验收结果。
严格先完成阶段一，再进入阶段二。不得以新商户进件试错代替恢复指定存量商户。

### 阶段一：先开通既有商户

1. 核实官方接口、场景和状态语义，只读核对 6666000241335656 的本地申请、汇付审核与实际配置。
2. 仅实现恢复该商户所需的查询、补开、状态同步、局部重试与操作入口，复用原商户号和银行卡。
3. 使用模拟汇付响应和真实测试库验证上述公共能力；不得调用真实新商户进件接口。
4. 对指定商户执行缺失能力补开，完成适用实名/授权及人才端绑定，核实延迟入账和自动结算，记录汇付侧成功证据与核验时间。

阶段一通过条件：规格中所有必要能力取得有效成功证据。受理成功、处理中、待实名、查询超时或仅本地标记成功均不算通过。未通过时停留在该商户的查询和恢复，不创建新商户绕过。

### 阶段二：再完成新商户完整流程

5. 阶段一通过后，将已验证的公共能力接入新企业商户“一次进件 + 微信开通”的完整流程，对接商户端与后台。
6. 先完成模拟测试及页面验收，再开展实际需要的新企业商户联调；失败时查原申请并局部修复，不反复新进件制造测试记录。
7. 记录完整流程验收及现有资金语义回归结果。

## 验收

- 满足规格 Testing Decisions 中全部适用验收场景；以外部行为及业务结果判定，不仅验证内部方法。
- 业务未真正生效或必要能力尚无证据时，不显示全部完成。
- 复用原商户号和银行卡，仅补齐缺失能力；不处理其他已关闭小微商户。
- 阶段一成功之前没有真实新进件；留存证据证明先恢复指定商户，再实施和联调新商户完整流程。
- 普通自动化测试不创建汇付商户；联调不得将创建或关闭重建商户作为失败重试手段。
- 本次进件不增加定时查询或页面自动轮询；保留已有回调，不修改其他支付补偿任务。
- 人才端是唯一付款端，商户端仅创建到店订单和核销。
- 遵守单 checkout 单 Maven、只追加迁移、共享文件最小增量和开发库保护约定。
@@ -38,5 +51,7 @@

## Comments

- 2026-09-15：用户补充执行顺序：先给 6666000241335656 开通微信并确认成功，再做新商户进件与微信开通。原因是每次新进件会增加控台记录且只能关闭、不能删除；已将阶段切换条件与防止真实测试数据积累的要求写入规格和本 Issue。

- 2026-09-15：按用户指定的 to-spec 技能从本会话合成并发布，应用 ready-for-agent 标签。用户已确认以进件服务为主要测试入口，使用真实测试库、模拟汇付响应，并补充接口权限与页面验收。
- 2026-09-15：此次交付为规格和执行 Issue，尚未实施业务代码或恢复真实商户。未验证的通道字段、状态语义及存量实时情况已明确列为实施前核查任务。

 .scratch/merchant-wechat-onboarding/spec.md

@@ -11,6 +11,8 @@

已有企业商户 6666000241335656 已进件，但微信能力未完成，需要保留原商户号恢复。后续新增企业商户应直接走完整流程。商户还必须开通延迟入账，使人才用户预购订单的资金在核销并完成交易确认之前不可结算到商户银行卡。

用户补充：每次真实新商户进件都会在汇付合作伙伴控台增加商户记录，这些记录只能关闭、不能删除。先用新商户反复试错会留下难以清理的测试记录，因此必须先把指定存量商户的微信业务开通成功，再进入新商户完整流程的实施与联调。

付款始终发生在人才端。商户端扫描人才码创建到店消费订单、或扫描已购买订单进行核销，并不承担付款。实现不得将该需求误解为多个小程序的支付接入。

## Solution
@@ -24,6 +26,8 @@
开通延迟入账但不开启强制延迟。预购订单支付后进入延迟户，核销并完成交易确认后进入可结算资金，再按 D1 自动结算到银行卡；到店消费订单支付即核销，不走延迟。核销成功不等于银行卡实时到账。

## User Stories

实施顺序为先完成指定存量商户的真实微信业务开通，再扩展新商户完整流程；下面的故事编号不代表执行顺序。

1. 作为新入驻企业商户，我希望在商户端完成企业进件，以便获得平台收款资格。
2. 作为企业商户，我希望一次提交主体、经营、联系人和结算资料，以便不用为微信开通重复填写相同内容。
@@ -63,6 +67,9 @@
36. 作为平台运营人员，我希望重复通知、并发刷新和重复提交不会重复开通，以便进度和通道申请保持一致。
37. 作为平台运营人员，我希望同步及恢复记录保留必要证据并保护敏感资料，以便排查时不会泄露证照、银行卡和密钥。
38. 作为平台负责人，我希望无需运行进件定时查询，以便进度由现有回调和人工刷新控制，并接受无回调且无人刷新时保留最后已知状态。
39. 作为平台负责人，我希望先开通 6666000241335656 的微信业务并确认成功，再实施和联调新商户完整流程，以便先用已有商户验证通道能力。
40. 作为平台负责人，我希望自动化测试使用模拟汇付响应，以便不会在合作伙伴控台创建无法删除的测试商户。
41. 作为平台运营人员，我希望联调失败时继续查询和修复原商户及原申请，以便不会通过反复新进件制造多余商户记录。

## Implementation Decisions

@@ -86,6 +93,9 @@
- **权限与信息展示**：商户入口按登录商户和门店权限定位申请，不信任前端传入的任意汇付商户号；后台沿用既有运营权限。对商户展示可处理的业务提示，对运营提供必要的脱敏诊断信息。
- **实名/签约**：需要商户本人完成的实名、授权或签署通过通道提供的指引办理，不能将本地状态改写为通道已授权。接口能否发起实名及所需材料属于实施前核查事项。
- **存量恢复**：仅恢复 6666000241335656。先只读核对本地关联、汇付审核和实际配置，再复用原商户号补齐缺失能力。保留已成功步骤与银行卡，不批量修复或重新打开其他小微商户。
- **阶段一优先且阻塞阶段二**：先完成指定存量商户微信开通所需的查询、补开、实名/授权衔接及必要能力核验，并取得汇付侧成功证据；阶段一只实现和验证这些工作所需的公共能力，不先扩展新商户完整进件流程，不调用真实新商户进件接口。
- **阶段切换条件**：指定商户的微信业务、人才端 AppID 和适用实名/授权已确认成功，并核实延迟入账及自动结算满足本规格。受理成功、处理中、等待实名、超时或仅本地成功都不能通过该条件。记录真实结果和时间后，再进入新增企业商户“进件 + 微信业务开通”流程的实现与联调。
- **真实测试数据约束**：普通自动化测试全部模拟汇付，不创建真实商户。阶段二也不能把反复真实新进件当作排错手段；复用既有请求关联，先查再重试，不通过“再开一家商户”或“关闭后重建”绕过故障。关闭控台商户不等于清除测试记录。
- **共享文件**：只在授权业务区域做必要增量改动，不顺手重构共享服务、路由或公共配置。

## Testing Decisions
@@ -105,6 +115,7 @@
- 对外部请求可验证关键合同字段、请求关联和必要调用次数，因为它们决定是否重复办理；不锁死内部方法顺序、私有字段或实现分支。
- 使用按商户 ID/申请号隔离的数据，不依赖共享测试库全表数量或其他测试的执行顺序。
- 常规自动化测试模拟汇付，不对真实商户提交开通、授权或支付请求。指定存量商户的真实结果作为另外记录的验收证据。
- 真实联调严格分阶段：先验收 6666000241335656，再开展新商户完整流程；阶段一禁止真实新进件。阶段二先完成模拟测试，再以实际需要的企业进件作验收，不反复创建测试商户试错。

### 测试模块与先例

@@ -132,6 +143,9 @@
| 通道已经开启全部必要能力 | 两端显示一致的已完成结果与同步时间 |
| 资料或行业不匹配 | 给出具体补充/纠正项，不照搬平台服务类目 |
| 存量指定商户恢复 | 原汇付商户号、已成功步骤和银行卡保持关联 |
| 指定存量商户未取得真实开通成功证据 | 不进入新商户完整流程实施与真实新进件联调；明确记录仍待完成的条件 |
| 指定存量商户满足阶段切换条件 | 留存汇付结果及核验时间，随后进入新商户完整流程 |
| 自动化测试或联调失败 | 自动化测试不调用真实新进件；联调先查原申请，不能反复创建新商户绕过失败 |
| 其他已关闭小微商户 | 不被本次恢复扫描、补开或更改状态 |
| 商户尝试访问其他商户申请 | 请求被权限边界拒绝，不能泄露或推进他人资料 |
| 到店消费和预购订单相关回归 | 前者支付即核销且不延迟；后者核销和确认前资金保持延迟 |
@@ -143,6 +157,7 @@

- 个人/小微商户的新功能，以及已关闭小微商户的恢复、批量重新进件。
- 指定存量商户以外的历史数据批量修复。
- 在指定存量商户开通成功之前开展真实新商户进件，或为排错反复创建、关闭再重建汇付测试商户。
- 商户端付款、多 AppID 微信登录和多支付端改造。
- 微信直连、微信预授权、支付宝或其他新增支付产品。
- 对参考商户本身做配置修改，或复制其企业身份、银行卡、子商户号和实名结果。
@@ -162,6 +177,7 @@
- 当前本地状态读取不会向汇付同步；后台能力刷新限于整体通过申请，不能救活卡在进件阶段的记录；旧重试会重新提交整份进件。
- 已有商户能力定时刷新和交易确认补偿任务，与本次“手动推进进件”的需求分开；不得将进件推进挂入这些任务。
- 本次只读核查尚未查询 6666000241335656 的实际数据库及汇付最新状态，不能将用户报告的卡住现象直接归因于某一通道错误。
- “汇付商户记录不能删除、只能关闭”由用户说明，是本次严格先存量后新增的实施约束；本轮没有尝试删除或关闭商户来验证该事实。
- 领域术语沿用根领域文档；执行已有“商户进件与微信支付开通分别判定”ADR。

### 技术核查任务
@@ -179,4 +195,6 @@

商户端与后台可完成受权限约束的刷新及局部重试；无回调场景能按人工操作推进到真实已完成或明确待办理状态；指定存量商户复用原身份恢复缺项，新企业商户可走同一闭环；必要能力以通道证据确认，测试与无法验证的外部条件均有记录。

交付证据必须体现先后顺序：先记录指定存量商户满足阶段切换条件的通道证据，再记录新商户流程实施与验收结果。指定商户尚未开通成功时，阶段一尚未完成，不能用“新商户能进件”替代其验收。

Status 表示规格已按技能发布并可由代理执行技术核查与实现，不表示功能已经实现或真实商户已经恢复。