商城BUG修复（前台+后台）

介绍

把系统自带的一堆小毛病集中修掉：8 项你直接能看到的修复 + 33 项框架补丁 + 1 项后台排版修正，每项独立开关，插件页有常驻体检清单。

功能清单

你直接能感觉到的 8 项修复

1. 客户地址保存/删除：官方把保存请求发到了需要前台客户登录的接口，后台点了提交一直转圈、存不上。修复后地址的新增/编辑/删除走后台接口，正常保存，弹窗用法不变。
2. SKU 图片预览破图：图片地址 http/https 混用、路径缺前缀或文件已删时不再显示裂图——能修就自动重试修复，实在加载不了降级成「点击选择图片」占位。另给一个「SKU 图片诊断」按钮，一键列出可疑的图片数据。
3. 媒体库图片显示成 media://6 这类乱码地址：前后台自动把内部引用解析成真实图片地址。
4. 规格值重复也能保存：官方允许同一规格下填重名的值（A、A 甚至 A 和 a），保存后前台选项错乱。修复后同一规格下不允许重名（大小写也算重复），输入时实时红框提醒，保存直接拦截并说明「规格值不能重复：xx」。
5. SEO 别名（网址）出问题：① AI 生成的别名常是一长串分析文字 ② 别名留空保存，该商品前台直接 404。修复后自动把脏数据净化成干净的英文短网址，留空保存时自动补一个不重复的别名。
6. 图片格式统一：webp / avif 是新一代格式（1688 等平台常见），官方服务不认识，进媒体库后日志反复报「Image resize failed」、缩略图裂开。修复后不管图片从哪来（采集、上传、编辑器粘贴），进库前自动把 webp 转成通用 jpg（透明铺白底），转不了的按原样入库，绝不阻断上传。
7. sitemap 丢失全部单页地址：官方按「page-单页别名」去拼一个不存在的路由名，结果 sitemap 里关于 / 服务 / 隐私政策这些单页地址全部消失，日志还刷一堆「Route [...] not defined」。修复后每个已启用单页都补上正确地址，新加的单页最迟 10 分钟内自动纳入。
8. 中文等非英文图片路径缩略图全裂：上游图像库判断「这是路径还是图片数据」的正则只认英文字符，文件名或目录名带中文/日文/韩文/阿拉伯语的图片会被误判。修复后任何语言的文件名都能正常生成缩略图（只对「字符串确实是一个存在的文件」生效，对真图片数据、英文路径零影响）；系统升级把补丁冲掉会自动补回。

框架补丁 · 登录态与前台接口（7 项）

1. 插件前台 API 路由组 + 登录接口路由组：官方缺陷是插件前台接口不带登录态，客户在网站登录后，前台插件功能认不出人、消息归属错乱。
2. 跨域登录态域名（.env 一行）：让 www 与裸域名共用一份登录态，客户在 www 登录后跳裸域名不会被当游客。
3. 登录态跨域名（www 与裸域名）：同上的写入与校验，防止升级后被覆盖。
4. 找回密码页选择器：补上作用域，避免前端脚本抓错元素。
5. 读取插件设置：官方只认小写插件名，CamelCase 名字的插件读不到自己的设置，已修正。
6. 找回密码页选择器：补上作用域，避免前端脚本抓错元素导致找回密码页表现异常。
7. 插件开关字段模板（说明文字渲染）：每个开关下方的灰字说明能正常显示。

框架补丁 · 会让页面直接 500 的系统 BUG（9 项）

1. 订单号类型：字母订单号会 500，已修正。
2. 退款状态机：退款后订单状态不联动，已修正。
3. 发货不推进订单状态：填了单号后订单自动变「已发货」。
4. 退货单新建页 500：官方类型声明过严，已放宽。
5. 支付方式可用端：支付设置里的脏数据会让结账页整页崩掉，已兜底。
6. 官方路由注册了不存在的方法：23 条死路由访问即 500，已裁剪，访问返回 404。
7. 官方 catch 缺 use Throwable：有 catch 却永远不匹配，发货接口异常直接裸奔 500，已补上。
8. 支付页缺键兜底（PayPal 视图）：支付页少任何一个键都不会再 500。
9. 访问统计写入超长 URL 失败：超长 URL 自动截断到列宽，不再写库失败。

框架补丁 · 后台顺手（7 项）

1. 返回按钮只需按一次：保存后历史里多出一条重复记录，导致要点两次才回上一页，已去重。
2. 插件页表头不重复显示标题（官方会出双标题）。
3. 后台打开先亮出没样式的裸页（FOUC）：样式到齐前不显示、之后淡入，不再白闪。
4. 表单行栅格负边距导致横向溢出 12px，已修正。
5. 未启用插件也注册后台路由：停用后设置页仍可访问，已按正确逻辑处理。
6. 上传保留原文件名：不再自动哈希成一串看不懂的名字。
7. 设置快照重载：后台已配项能正常读取。

框架补丁 · 多语言与文案（3 项）

1. 框架语言包完整性：补齐缺失的语言键，避免界面露出 xxx.yyy 这种裸键。
2. 订单「确认」按钮裸翻译键：按钮显示为翻译后的文字。
3. 邮件发件人名称：官方写死 app.name，已改回读系统配置。

框架补丁 · 图片与地理（3 项）

1. GeoLite2 路径写入 .env：数据库文件在但 .env 没配时，访客地区识别会失效，已自动补上。
2. GeoLite2 下载保护：下载先写临时文件、验证通过才替换现有数据库；下载源异常时不再把本地库删掉。
3. 访客地名与地图同语言：隐身的国家回到地图上，地名不再半中半英。

框架补丁 · 运费 / 设置 / 安全（4 项）

1. 固定运费：后台填的金额不生效（官方读错设置键），已改为读插件真实 code。
2. 固定运费「运费值」输入框没写货币单位，已注明「按设置 → 本地设置 → 默认货币计」。
3. 后台「账户」页打不开：官方拼首页链接时漏了语言前缀，缺的路由名已补上（当前版本已用正确写法时不重复修补）。
4. 后台「页面」里填的内容会被当成模板编译执行——这可以被人用来远程控制服务器。修复后后台填的内容原样输出，不再被当成代码跑。

后台排版修正（1 项）

1. 阿语等 RTL 语言后台排版修正：后台语言为阿拉伯语这类从右向左的语言时，说明文字贴错边、和字段分家（官方没提供 RTL 样式）。可修正为镜像排版，也可选择保持官方原样。

常驻体检清单

1. 后台右下角常驻一张体检卡：逐项列出「已就位 / 被覆盖需重装 / 文件不存在」，全部正常是绿的，缺项是红的。
2. 「一键重装」：服务器文件可写时点一下自动补齐，不用找服务器管理员。
3. 登录态补丁每次启动自动体检，缺项直接弹提示卡；系统升级覆盖后也能自动发现并补回。
4. 可以「本次会话不再显示」收起，也能随时点右下角重新显示。

需要的工具

• 不需要任何第三方账号。
• 注意：本插件的部分是「框架补丁」，会改到系统文件（登录态路由、.env、几个官方视图），这是修复官方缺陷的必要代价；补丁全部登记在册，系统升级若覆盖会自动体检并提示一键重装。业务数据（商品、订单、客户）一个字节都不动。
• 关掉某一项就是恢复官方行为，可以逐项开关、互不影响。

兼容环境

纯插件实现，不改系统任何文件，卸载后网站自动恢复原样。

展示位置

后台全部页面（右下角常驻体检卡 + 顶部状态行）；前台图片、地址、规格、SEO 别名、sitemap 等受影响位置；插件配置页。

更新版本

v1.9.30（2026-10-31 更新）