From cc3452d4a6cec4a6b9742d6d9589737c7bb93cfe Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 9 May 2026 15:50:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(frontend-notice):=20admin=20=E4=BA=A7?= =?UTF-8?q?=E5=93=81=E5=88=86=E4=BA=AB=E5=8E=BB=E6=8E=89=E9=80=89=E7=9B=AE?= =?UTF-8?q?=E6=A0=87=E7=94=A8=E6=88=B7=E6=AD=A5=E9=AA=A4,=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E6=97=A0=E6=94=B9=E5=8A=A8=20(=E5=89=8D=E7=AB=AF?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...n_product-share-remove-target-user-step.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md diff --git a/changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md b/changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md new file mode 100644 index 0000000..d39aa7d --- /dev/null +++ b/changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md @@ -0,0 +1,155 @@ +# 前端 BUG 通知 — admin 产品分享去掉"选目标用户"步骤,直接生成 URL Scheme + +**日期**: 2026-05-09 +**类型**: 前端 BUG (admin 后台 hl-ui) +**模块**: 产品管理 → 产品列表 → 分享按钮 (MiniappShareModal) +**通知**: @mmg +**后端是否需改动**: 否(后端接口契约自 PR #1488 上线起从未变,不需要、也不应该加 targetUserId 字段) +**严重性**: 中 — 多余步骤,影响 admin 操作效率 + +--- + +## 现象 + +入口: admin 后台 → 产品列表 → 列表行「分享」按钮 (`hl-ui/src/views/product/list/components/MiniappShareModal.vue`) + +**期望流程**: +点「分享」→ 前端组装 `path` + `query` → 直接调后端接口 → 拿到 `weixin://dl/business/?t=xxx` URL Scheme 短链 → 弹窗里展示给 admin 拷贝/转发 + +**当前流程 (bug)**: +点「分享」→ 弹出"选目标用户"列表/搜索框 → admin 选完一个用户后才生成链接 + +→ "选目标用户"这一步是**多余的**,后端接口里完全没有"目标用户"概念,该步骤可直接删掉。 + +--- + +## 根因 (后端代码反推) + +后端接口 `POST /admin/wxapp/share/url-scheme` 自 PR #1488 (2026-04-27) 上线以来,代码从未改过 — 见 `hl-user-service/src/main/java/com/hulalv/user/controller/AdminWxappShareController.java:61-72`。 + +入参 VO `WxappUrlSchemeReqVO` (`hl-user-service/src/main/java/com/hulalv/user/vo/admin/WxappUrlSchemeReqVO.java`) **完整字段清单**: + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | String | ✅ | 小程序页面路径(不带前导 `/`) | +| `query` | String | ❌ | querystring,如 `id=123&sharerId=456` | +| `envVersion` | String | ❌ | release / trial / develop,不传走配置默认 | +| `expireDays` | Integer | ❌ | 1-365 天,默认 30 | + +**注意**: 完全没有 `targetUserId` / `receiverId` / `userId` / `shareTo` 等"目标用户"字段。 + +后端 Service 实现 (`WechatMiniAppClient.generateUrlScheme`) 是对微信开放平台 `wxa/generatescheme` API 的纯翻译调用,接口语义上与"分享给谁"无关 — 生成的是一条**任何人**点开都能进对应小程序页面的 scheme 短链。 + +→ "选目标用户"步骤是前端 UI 单方面加的,后端**没有任何对应字段或逻辑**。即便前端额外传了 `targetUserId`,后端 VO 没声明,Spring 反序列化会忽略,最终不会进入业务逻辑。 + +--- + +## 期望前端做的事 + +修改文件: `hl-ui/src/views/product/list/components/MiniappShareModal.vue` + +**优先级 1**: 去掉"选目标用户"那一步弹窗 / 用户列表 / 搜索逻辑(以及对应的状态变量、watch、API 调用) + +**优先级 2**: 改回直接组装 `path` + `query` 调后端接口,拿到 `link` 字段后展示给 admin 拷贝/转发 + +--- + +## 后端接口契约 (前端复核用) + +### `POST /admin/wxapp/share/url-scheme` + +**Headers**: +- `Content-Type: application/json` +- `Authorization: Bearer ` + +**Request body**: + +```json +{ + "path": "pages/product/detail/detail", + "query": "id=123&sharerId=456", + "envVersion": "release", + "expireDays": 30 +} +``` + +> ⚠️ 字段约束: +> - `path` 必填,**不带前导 `/`**,长度 ≤ 256 +> - `query` 可选,长度 ≤ 1024 +> - `envVersion` 可选,仅接受 `release` / `trial` / `develop`,不传走配置默认 +> - `expireDays` 可选,范围 1-365,不传默认 30 + +**Response** `Result`: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "link": "weixin://dl/business/?t=abc123", + "expireTime": 1735689600 + } +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `data.link` | String | scheme 短链,直接给 admin 拷贝 | +| `data.expireTime` | Long | Unix 秒级过期时间戳,微信未返回时为 null | + +**响应结构与现有前端调用完全一致,前端无需改取值代码。** + +--- + +## 后端为什么不需要(也不应该)加 `targetUserId` + +有人可能会想:既然 UI 上有"选目标用户"步骤,要不要后端也加个 `targetUserId` 字段记录一下?**不行**: + +1. 微信 `wxa/generatescheme` API 本身不接受"目标用户"参数 — scheme 短链是公开的,任何人点开都能进同一个小程序页面 +2. 如果业务需要"哪个用户分享给哪个用户"的归属关系,应该在 `query` 里塞 `sharerId` / `targetUserId` 当作小程序页面参数(前端组装 query 时自定),而不是后端 VO 加字段 +3. 加字段反而会带来"前端必传 → 不传 400"的破坏性变更 + +→ 后端接口契约保持原样,**零改动**。 + +--- + +## 复现取证 (mmg 在 DevTools 验证) + +1. **Network**: 抓「分享」按钮触发的请求,确认目标接口 `POST /admin/wxapp/share/url-scheme` +2. **Payload**: 看请求 body 里是否多塞了 `targetUserId` / `receiverId` 之类后端 VO 不存在的字段(后端会忽略,但是冗余) +3. **Sources**: 搜 `MiniappShareModal.vue`,定位"选目标用户"那段 UI 与逻辑代码,整段移除 + +--- + +## 验收 + +mmg 修完前端后,验收点: +1. admin 产品列表点「分享」按钮 → 弹窗里**直接**显示 scheme 链接(`weixin://dl/business/?t=xxx`),不再有"选目标用户"那一步 +2. 弹窗加载完成后,链接可一键拷贝 +3. 不同产品行点分享,生成的 link 携带不同 productId(`query` 字段里的 `id` 正确) +4. 后端接口 round-trip 状态码 200,响应结构与上方契约一致 + +--- + +## 涉及文件 + +**前端 (mmg 修改)**: +- `hl-ui/src/views/product/list/components/MiniappShareModal.vue` + +**后端 (零改动,仅供前端复核)**: +- `hl-user-service/src/main/java/com/hulalv/user/controller/AdminWxappShareController.java:61-72` +- `hl-user-service/src/main/java/com/hulalv/user/vo/admin/WxappUrlSchemeReqVO.java` +- `hl-user-service/src/main/java/com/hulalv/user/vo/admin/WxappUrlSchemeRespVO.java` + +--- + +## 相关历史 PR + +| PR | 说明 | 是否仍有效 | +|----|------|------------| +| #1488 | 补齐 admin 端点 `url-link` / `url-scheme` 首次上线 | ✅ 有效,本通知未改任何后端字段 | + +--- + +**联系人**: wx