Domů Procházet Nápověda
Registrovat se Přihlásit se
gatsby
/
payment-platform
1
0
Rozštěpit 0
Soubory Úkoly 0 Pull Requesty 0 Wiki
Strom: 262e452f04
Větve Značky
payment-platfor...
/
.claude
/
plan
/
2026-10-08-har-shop-region-交付说明.md

2026-10-08-har-shop-region-交付说明.md 11 KB
Historie Surový

汇安融「门店地区 + 按顾客 IP 挑店」交付说明（2026-10-08）

需求原文（用户，指向《支付宝支付接口接入规范261008(1).docx》）： 「门店新增了地区相关的字段，需要接上，因为支付宝异地收款会有风控，我们的 checkout 也要做一个调整， 在调起支付时要根据请求者 ip 自动选择对应地区的门店 id，这样才不会风控」

设计裁定（本批开工前已与你确认，未改）：IP 归属地取 ipwho.is（进程内缓存，失败⇒空）； 粒度 = 城市精确匹配、省作回退；匹配不上拒收（顾客语，不打上游、不落单）；同城多店按 IP 稳定散列挑一家；城市未匹配则该省随机一家。

★ 这一批没有写计划文件（前几批是 .claude/plan/<日期>-<主题>.md），需求以 docx + 上述裁定 为准，落地过程与读数都在 logs/ 下的日志里 —— 这点与既有批次不同，先说明。

一、提交清单（全部未 push）

origin/java 停在 ed24480f。本地领先的提交 = 下表 6 个功能/文档刀 + 本说明自身的提交 （0a07a456 首次提交，以及本文件每次订正各一刀）—— 不写死总数：本说明自己也在数里， 写完再提交一次就 +1（要读数就现量 git rev-list --count origin/java..java）。

提交 内容
b1c8f6fb （一）目录快照 har-region-cn.json（31 省 / 342 地级 / 166 繁简对）+ HarRegionCatalog + HarIpRegionResolver + HarShopService#pickForRegion + 门店/创建请求带地区
32384b2b （二）结账腿接线：HarCheckoutController 按顾客 IP 挑店填 third_shop_code；挑不出来 400 拒收（两种文案）；clientIp 四个头 + unknown 兜底
c47b0c63 （三）省市目录只读端点 GET /payment/har/region/provinces｜cities + db/har-shop-region.sql
8e352e7e （四）前端：门店表单省→市选择器、列表「地区」列、详情一行；开放 API 文档 §10.1 同步
ccc34414 文档 markdown 空行修正（引用块贴着 --- 会被当成懒惰续行）
300a27f9 （五）编码填错统一 400：HarShopService#requireKnownCity 两处单参 BusinessException（默认码 500）改显式 400；两条地区拒收用例补码断言（先红后绿）；开放文档 §10.1 补码值

★ b1c8f6fb 里夹带了一份 支付宝支付接口接入规范261008(1).docx（87512 字节） —— 那是开工时会话开始前就已经 git add 进索引的文件，提交时没有指定路径，于是跟着这一刀进去了。 我没有改写历史（改写会动到你已经能看到的提交）。你的裁定是保持现状（2026-10-08）， 本批不再动它：留着无功能影响，摘掉需要 rebase/改写。后续提交都改成 「显式路径 git add + git commit -F <msg> -- <显式路径>」。

二、验证读数（本机实测，不是推断）

  • 整包 mvn test：1212 条，0 失败 0 错误 0 跳过，BUILD SUCCESS （★ 两条读数：第一条 12:44:08 在 300a27f9 之前；400 订正后 12:47 复跑同数 = 1212/0/0/0，21.4s，日志 logs/_mvn-full-region-code-400.txt； HarCheckoutControllerTest 24 + HarRegionControllerTest 5 都在内）
  • 两向变异（每条都先确认变异体生效，还原后 sha256 复核回基线）：
变异体 结果
结账腿：4 个（挑到不填 third_shop_code / 两句拒收文案合并 / 不取 XFF 第一跳 / 去掉 unknown 兜底） 预测红集 6，实测恰为那 6 条，其余 18 条作正对照仍绿；还原后 sha256 与变异前一致（24/0）
目录端点：3 个（省码不校验 / 用空表代替 400 / 权限串只留 :create） 预测红集 3，实测 cities_returnsOnlyThatProvincesCities、cities_unknownProvinceCode_400_notAnEmptyList、contract_pathAndPermissionAreTheOnesTheFrontendCalls；2 条对照仍绿；还原后 sha256 一致（5/0）

  • 前端（本仓无测试框架，ts:check 基线本就非零 ⇒ 只能同机差分）：

    • pnpm ts:check：基线 289 条 error TS（exit 2）→ 改动后 289 条，逐条集合比对 新增 0、消失 0；
    • pnpm build：exit 0（两次，12:42 与 12:46，各约 57s）；已回读产物确认新代码真进了包： dist/js/index.x_9MozyF.js 含 region/provinces、dist/js/index.SNmFzXAj.js 含文档新句 「城市编码不属于该省」、province_code 出现在 3 个 chunk（注意：一开始我按 dist/assets/*.js 搜，3 个都查成 0 —— 是本仓产物在 dist/js/，是检索式错不是文件缺失，换路径后同一条搜索命中）；
    • Element Plus 用法对着装好的包核过（2.14.0 select.mjs）：loading: Boolean 「whether Select is loading data from server」、disabled: Boolean —— 不是凭记忆。

  • 产物指纹（★ 下面这版是要部署的，12:51/12:53 在 300a27f9 之后重打）：

    • java/target/payment-platform-1.0.0.jar，143,146,853 字节，sha256 b6b64c8ad8455d4e1e0639d7d8ad04ea9db347292ec75bb81cb384213379068d， 重打于 12:51:49；开包验的是产物本身：从 jar 里取 HarShopService.class 反汇编 （javap -p -c），两处拒收都是 sipush 400 → BusinessException.<init>:(ILjava/lang/String;)V
    • frontend/dist.zip，9,375,214 字节，sha256 80038a66ef9dd73678ec5d9158f66763eef6f4451feb9f3fd9b92d50a2468fa6， 12:53:49；281 个条目 = 277 文件 + 4 个目录条目（dist/、dist/css/、dist/img/、dist/js/， 与上一版同形：全为正斜杠、testzip() 无坏成员）
    • 这两版之前的旧件已被取代，别再照旧指纹核产物： jar 977da280…（143,146,829 字节，12:45:02）、dist.zip dd4cf524…（9,375,221 字节）
    • 文档改了一行 ⇒ dist 里 103 个 chunk 的文件名哈希跟着变了（Rollup 的 [hash] 含依赖哈希， 一处内容改动脉冲式传播），条目数没变（前后各 277 个文件）。两向读数：旧包里只有旧句 不属于该省的编码会被拒（在 js/index.SNmFzXAj.js），新包里只有新句 编码填错一律 （在 js/index.ruVK6GJ7.js），互不相见 —— 不是「重建后一律变」的空话

三、部署要求（按顺序，第 1 步不做就没有后面）

  1. 先执行 java/src/main/resources/db/har-shop-region.sql（本工程未接 Flyway，只能你执行）。 ★ 反了不是静默降级而是直接报错：实体带上 province_code/city_code 后，门店列表与 挑店的每一句 SELECT 都会取这两列 ⇒ 门店列表 500，且每一笔收款链接下单都失败。
  2. 重新部署：上面的 jar + frontend/dist.zip。
  3. 不需要新菜单 SQL、不需要重登：目录端点复用门店既有的 module_payment:har:shop:list / :create 权限串（@perm.hasAny 两条），菜单不动。
  4. 跑脚本末尾那三条只读核对，尤其第 ③ 条 —— 它给出的数字就是要重开的店数： province_code/city_code 为空的门店（2026-10-08 之前建的）在挑店时必然落选。 上游没有门店更新接口，补不上，要收款只能换新的 third_shop_id 重开。
  5. 验收路径：门店管理 → 创建门店 → 省/市两级下拉能出目录 → 提交 → 列表「地区」列显示 「江苏省 / 南京市」→ 从另一个地区的网络打开该商户的收款链接 → 应当拒收 （「无法确定您当前所在地区…」或「收款方暂未开通您所在地区的收款…」），而不是跑到异地门店。

四、未验项（如实列，别当已验）

  1. 前端页面没有执行级验证：本仓前端没有测试框架、也没有能起真 SFC 的台子，页面还要登录态 才能打开。「选择器真的拉到 31 个省」「换省真的换了市」「列表把码显示成了名」这几步 一次都没被真跑过 —— 我只能给到「类型零新增 + 构建通过 + 产物里确有这段代码」。
  2. pay_url 仍然没有被真机扫过（上一批就挂着的问题，本批没变）；挑店在真实顾客 IP 下的表现（真挑到哪个地区的哪家店）没有端到端跑过，只跑到「挑店逻辑 + 端口」这一层。
  3. 上游是否真的按地区风控未知：本批保证的是「我们把对的码发上去、按地区挑店」， 上游收了这两个码之后怎么用，没有可观测的读数。
  4. X-Forwarded-For 可伪造：除非前置代理覆写它（写在 HarCheckoutController 的类 javadoc 「已知的边界」里）。后果是把顾客导到收款方自己的另一家门店，不涉资金与租户边界， 要堵得在网关上 —— 本批不动。
  5. HarCheckoutController 三个偏差未改（都在代码注释里标了，属规范与现状不一致， 不是本次引入）：shopName 我方 @Size(128) vs 规范 varchar(16)；thirdShopCode 32 vs 30； 实体列宽按规范 16 建。

五、两件拍板（你已裁定：① 我解决、② 保持现状）

  1. 同类错误码两处不一致 —— 已按裁定修掉（300a27f9）：编码不认识时， HarRegionController 返回 code=400（两参构造）， 而 HarShopService#requireKnownCity 返回 code=500（单参 BusinessException 的默认码）。 后者是对外开放 API 也会走到的路径 ⇒ 外部调用方传错码会看到「服务器错误」。 现在两处都是显式 400，文案一字未动。读数：给两条地区拒收用例各加一条 assertEquals(400, e.getCode()) 后实测红（expected: <400> but was: <500>，两条都红， 同类其余 16 条绿）→ 改完该件 18/18 绿 → 整包 1212/0/0/0（21.4s）。 开放文档 §10.1 那句从「只写 msg 形状、不写码值」改成写死 code=400（按上面的实测口径）。
  2. b1c8f6fb 里的 docx：保持现状（按裁定未动，历史未改写）。
  3. 顺带说明（不在本次裁定范围，仍未动）：third_shop_id 重复仍是 code=500 —— 它与上面同类，但只有一处入口、且开放文档第 82 行已按 500 写给外部调用方， 改它等于动一条既有对外契约。要统一请单独说。

另：probe 结论提醒 —— 顾客端拒收文案能上屏，是因为 GlobalExceptionHandler 对 BusinessException 不带 @ResponseStatus（HTTP 200 + body code），顾客页自建实例 读的是 res.data.msg；如果哪天有人把它改成真 4xx/5xx，顾客页会 fallback 成 「网络异常，请检查网络后重试」，那句「你所在地区未开通」就再也到不了顾客眼前。