docs(user): 分享到小程序 url-link/url-scheme 404 已修 (PR #1488)

changelogs/2026-04/27_fix_admin-wxapp-share_endpoints-404.md

@@ -0,0 +1,100 @@
+# fix: 分享到小程序 URL Link / URL Scheme 404 已修复
+
+**日期**: 2026-04-27
+**PR**: #1488 (Closes #1481)
+**类型**: BUG 修复 — **前端零改动**, 自动生效
+**影响端**: 管理后台 (admin) — 产品列表「分享到小程序」对话框
+
+---
+
+## 修复内容
+
+### 之前的问题
+
+蒋雨莲 (橙子) 在产品列表点「分享到小程序」 → 弹对话框 → 点「URL Link 生成」或「URL Scheme 生成」按钮:
+
+- 顶部弹红色 toast: **请求的资源不存在**(HTTP 404)
+- DevTools Network 面板: 两次 `url-link` 请求 status=404
+
+### 根因
+
+后端**完全没实现 admin 端点**, 前端 `MiniappShareModal.vue` 已上线但从未与后端联调。与 #1477 cost-item 同款「前端先发后端漏跟」模式。
+
+### 修复
+
+后端补齐 2 个端点 + hl-gateway 加路由:
+
+```
+POST /admin/wxapp/share/url-link
+POST /admin/wxapp/share/url-scheme
+
+Request body (两端点一致):
+{
+  "path": "pages/product/detail/detail",   // 必填
+  "query": "id=20457...",                   // 选填
+  "envVersion": "trial" | "release",        // 选填, 默认 release
+  "expireDays": 30                          // 选填, 默认 30 天
+}
+
+Response:
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "link": "https://wxaurl.cn/..." | "weixin://...",   // URL Link 是 https, URL Scheme 是 weixin://
+    "expireTime": 1735689600                            // 过期 Unix 时间戳
+  }
+}
+```
+
+### 字段统一
+
+URL Link 和 URL Scheme **响应字段都叫 `link`**(微信原始 `urlLink`/`openlink` 已在后端归一化), 前端 `MiniappShareModal.vue:223,242` 取值 `res.link || res` 完全兼容。
+
+## 前端动作
+
+### 必须 ✅
+
+**无**。`hl-ui/src/api/wxapp.js` 中 `generateUrlLink` / `generateUrlScheme` 调用方式不变, 后端补齐端点 + 网关路由后自动工作。
+
+### 验收 ✅
+
+测试服管理后台:
+
+1. 用 SUPER_ADMIN 登录(或任意 admin token)
+2. 进「产品线管理」→ 任一产品列表
+3. 点产品上的「分享到小程序」按钮
+4. 在弹窗里点「URL Link 生成」 → 应填充 `https://wxaurl.cn/...` 类链接
+5. 点「URL Scheme 生成」 → 应填充 `weixin://...` 类链接
+
+测试服已部署 hl-user-service + hl-gateway 完成 (2026-04-27 16:51)。
+
+### ⚠️ 测试服可能仍报 230506 (errcode=40001)
+
+后端代码 + 路由 + 调用链已就绪, 但**测试服微信 appid 鉴权**可能未配齐(测试小程序 IP 白名单 / 接口权限 / appid-secret 不匹配)。如测试服仍报错:
+
+```
+{"code":230506, "message":"生成分享链接失败(错误码:40,001)"}
+```
+
+**这不是代码 bug**, 是微信开放平台账号配置侧。运维需确认:
+1. nacos `wechat.miniapp.appid` / `secret` 与测试小程序后台一致
+2. 测试服出口 IP `116.117.149.79` 在小程序后台 IP 白名单
+3. 测试小程序已开通 `generate_urllink` + `generatescheme` 接口权限
+
+正式服 appid/secret/IP 白名单配置正确即可工作。
+
+## 参考路径
+
+| 端 | 文件 | 行 |
+|---|---|---|
+| 前端 API | `hl-ui/src/api/wxapp.js` | 3-18 |
+| 前端组件 | `hl-ui/src/views/product/list/components/MiniappShareModal.vue` | 213, 232 |
+| 后端 (新) | `hl-user-service/.../controller/AdminWxappShareController.java` | `@RequestMapping("/admin/wxapp/share")` |
+| 后端 wxa 客户端 | `hl-user-service/.../service/WechatMiniAppClient.java` | generateUrlLink + generateUrlScheme |
+| 网关路由 (新) | `hl-gateway/src/main/resources/application.yml` | `Path=/admin/wxapp/**` → `lb://hl-user-service` |
+
+## 关联
+
+- 反馈人: 蒋雨莲 (橙子) 2026-04-27
+- 后端 changelog: `hl-backend-changelog/changelogs/2026-04/2026-04-27_user_admin-wxapp-share-endpoints.md`