第 6 批接口实现进度（设置模块 18 个接口）

目标：把后台「设置」菜单跑通——配送模板、物流公司、快递打印、支付设置、支付模板。验证方式：读接口双端逐字段对比（PHP 线上 vs Java 本地），写接口端到端断言（造数 → 调接口 → 查库 → 清理）。

一、本批接口清单（18 个）

分组	接口	说明
配送模板	`GET /store/setting.delivery/detail`	详情（含 rule 数组）
	`POST /store/setting.delivery/add`	新增模板 + 区域运费
	`POST /store/setting.delivery/edit`	编辑（区域整体替换）
	`POST /store/setting.delivery/delete`	软删除（被商品使用时拦截）
物流公司	`POST /store/setting.express/add`	新增
	`POST /store/setting.express/edit`	编辑
	`POST /store/setting.express/delete`	软删除
支付设置	`GET /store/setting.payment/options`	4 客户端 × 支付方式配置
	`POST /store/setting.payment/update`	全量覆盖写入
支付模板	`GET /store/setting.payment.template/list`	分页（15/页）
	`GET /store/setting.payment.template/all`	全部
	`GET /store/setting.payment.template/detail`	详情（config 合并默认）
	`POST /store/setting.payment.template/add`	multipart，含证书文件
	`POST /store/setting.payment.template/edit`	multipart
	`POST /store/setting.payment.template/delete`	被引用时拦截
打印机	`POST /store/setting.printer/add`	printer_config 存 JSON
	`POST /store/setting.printer/edit`
	`POST /store/setting.printer/delete`	软删除

进度：151 个接口已实现 122 个，剩余 29 个。

二、新增 / 修改文件

新增

实体：Payment、PaymentTemplate
Mapper：PaymentMapper、PaymentTemplateMapper
服务：PaymentSettingService（支付配置 + 支付模板）
工具：PaymentConfig（默认配置结构 + resetOptions 递归合并）
控制器：SettingPaymentController、SettingPaymentTemplateController

修改

Delivery：补 rule 关联（@JsonInclude(NON_NULL)，未装配时不输出该键）
DeliveryRule：region / region_text 库内 JSON 字符串 → 出参数组
Printer：printer_config 改为 JSON 解析后出参（原来直接吐字符串，列表页会错）
SettingService：配送模板/物流公司/打印机的新增、编辑、删除
SettingDeliveryController / SettingExpressController / SettingPrinterController：补充路由

三、本批踩到的对齐细节

rule 键的有无是有语义的 setting.delivery/all 的 PHP 输出没有 rule 键，而 list 和 detail 有。所以实体上加 @JsonInclude(NON_NULL)，只在 list/detail 里装配，all 保持不输出——不能用「一律返回空数组」糊过去。
@TableLogic 字段不能用 updateById 置位 MyBatis-Plus 更新时会跳过逻辑删除字段，setIsDelete(1) + updateById 结果是「接口返回成功、库里没删」。必须 lambdaUpdate().set(IsDelete, 1).set(UpdateTime, ts)。删除接口的 4 处均已改为显式 set。
支付模板 config 是「默认结构 + 已存值」的递归合并 PHP resetOptions($default, $data)：键并集、关联数组递归合并、索引数组后者整体覆盖。 add 只把 {method: config} 写库，读取时再补上另一种支付方式的默认块（所以 detail 里一定同时有 wechat 和 alipay）。
证书文件名规则 {字段名}-{md5(uuid) 前8位}.{pem|crt}，落盘目录 payment/{method}/{storeId}/（PHP 是 data/，Java 用 yoshop.upload-path 作 data 根）。编辑时前端会把 detail 拿到的文件名原样回传，所以「不传文件」时配置里的文件名要靠前端带上；若传空串则会被清空——这点与 PHP 一致。
支付设置是「全量覆盖」 update 先删当前商城的全部 yoshop_payment 记录再批量插入（每个客户端 × 每个支付方式一条，共 9 条）。不是增量更新。
payment_options 的 methods 是数组不是对象 默认数据里按 "client-method" 作键便于合并，输出前必须 array_values 转成索引数组，否则前端表格渲染不出来。

四、验证结果

项目	结果
读接口双端对比（`tools/compare_setting_batch.py`）	13 / 13 零差异
写接口端到端断言（`tools/test_setting_writes.py`）	66 / 66 通过
订单链路回归（`tools/compare_order_batch.py`）	10 / 10 PASS
既有接口回归（`tools/compare_batch.py`）	28 / 28 PASS

写测试覆盖：配送模板新增（含 2 条区域规则的 JSON 落库与回读）、空规则拦截、编辑时区域整体替换（旧 rule 物理删除）、删除（含「被 6 个商品使用」拦截）、物流公司增改删、打印机配置对象 ↔ JSON 互转、支付设置全量覆盖与读回、支付模板 multipart 上传证书（校验文件名规则与落盘）、编辑保留证书名、被引用时禁止删除、解除后删除成功。

测试数据已全部清理（yoshop_payment 恢复为空、TESTJ 记录物理删除、上传的证书文件已删）。

五、仍未接入（切流前必须补）

checkPrivilege 角色权限校验（当前只校验登录态）；
微信支付 V3「平台证书」自动下载（downloadPlatformCert）：需要商户证书 + 调微信接口，Java 侧目前显式报错「请改用公钥验签」，避免静默跳过；
小票打印机驱动（飞鹅 / 365 云打印）的实际出票调用——本批只做了打印机的增删改查；
微信小程序发货信息上报、第三方支付（微信/支付宝）退款、阿里云物流轨迹驱动。

接口实现进度-第6批.md 5.8 KB Vēsture Neapstrādāts