From 0fda85a6f8411078fb72169ce16cdcb4ec635e67 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 1 Jun 2026 22:42:51 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3(mp):=20=E6=B4=BB=E5=8A=A8?= =?UTF-8?q?=E6=98=AF=E5=90=A6=E6=94=B6=E8=B4=B9=E5=AD=97=E6=AE=B5=E5=8F=98?= =?UTF-8?q?=E6=9B=B4=E9=80=9A=E7=9F=A5=EF=BC=88=E5=B0=8F=E7=A8=8B=E5=BA=8F?= =?UTF-8?q?=E7=AB=AF=EF=BC=89=E2=80=94=20PR=20#3334=20Issue=20#3331?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../01_3331_活动是否收费-修改接口-小程序端.md | 239 ++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 changelogs-v2-mp/2026-06/01_3331_活动是否收费-修改接口-小程序端.md diff --git a/changelogs-v2-mp/2026-06/01_3331_活动是否收费-修改接口-小程序端.md b/changelogs-v2-mp/2026-06/01_3331_活动是否收费-修改接口-小程序端.md new file mode 100644 index 0000000..699beb7 --- /dev/null +++ b/changelogs-v2-mp/2026-06/01_3331_活动是否收费-修改接口-小程序端.md @@ -0,0 +1,239 @@ +# 游玩项目（活动）新增「是否收费」字段（小程序端） + +- **端类型**：小程序端 +- **变更类型**：修改接口 +- **日期**：2026-06-01 +- **Issue**：[#3331](https://git.1814.love:8443/wx/HL/issues/3331) +- **PR**：[#3334](https://git.1814.love:8443/wx/HL/pulls/3334) +- **Commit**：[5da05a3](https://git.1814.love:8443/wx/HL/commit/5da05a324813cf8109d35c521c5e7bb9719627be) +- **后端负责人**：腰苏图（yst@1814.love） + +--- + +## ① 接口背景 + +游玩项目（活动）资源新增「是否收费」属性。小程序端的活动详情接口和活动列表接口均已同步透传该字段，供小程序展示活动是否需要游客付费。字典来源 `sys_yes_no`，后端已配置并完成翻译，小程序无需任何字典配置。备品（物资）域不涉及小程序端接口，本文档不包含备品。 + +--- + +## ② 变更清单 + +| 接口 | 方法 | 路径 | 变更内容 | +|------|------|------|----------| +| 活动详情 | GET | `/mp/activity/{activityId}` | 出参新增 `isCharged` + `isChargedLabel` | +| 活动列表 | GET | `/mp/activity/list` | 出参新增 `isCharged` + `isChargedLabel` | + +所有变更均为**向后兼容新增字段**，小程序现有调用代码无需修改。 + +--- + +## ③ 接口详情 + +| 项目 | 说明 | +|------|------| +| **认证方式** | 小程序 JWT Token，请求头 `Authorization: Bearer {mp_token}` | +| **幂等性** | GET 查询，天然幂等 | +| **限流** | 无单独限流配置，走网关全局限流 | +| **权限** | 小程序用户，已登录状态 | + +--- + +## ④ 接口入参 + +### GET `/mp/activity/{activityId}` 详情 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| activityId | Long | 是 | 游玩项目 ID（路径参数） | + +### GET `/mp/activity/list` 列表 + +| 参数名 | 类型 | 必填 | 默认值 | 说明 | +|--------|------|------|--------|------| +| keyword | String | 否 | - | 关键词搜索 | +| categoryCode | String | 否 | - | 分类筛选（字典: activity_category） | +| page | Integer | 否 | 1 | 页码 | +| pageSize | Integer | 否 | 20 | 每页条数 | + +> 入参无变化，以上为完整入参文档。 + +--- + +## ⑤ 出参字段 + +### GET `/mp/activity/{activityId}` 详情（`MpActivityDetailVO`，新增字段） + +| 字段名 | 类型 | 说明 | 可能为 null | +|--------|------|------|-------------| +| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | +| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | + +### GET `/mp/activity/list` 列表（`MpActivityListItemVO`，新增字段） + +| 字段名 | 类型 | 说明 | 可能为 null | +|--------|------|------|-------------| +| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | +| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | + +--- + +## ⑥ 枚举 / 数据字典 + +### sys_yes_no 字典（后端已配置，小程序无需维护） + +| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 | +|--------------------|-----------------------------|------| +| 1 | 是 | 该活动收费 | +| 0 | 否 | 该活动免费 | + +> `isChargedLabel` 由后端查字典自动翻译并返回，小程序可直接展示。若字典配置异常（不正常情况），该字段返回 null。 + +--- + +## ⑦ 错误码 + +| 错误码 | HTTP 状态 | 场景 | +|--------|-----------|------| +| 401 | 401 | 未登录或 Token 失效 | +| 404 | 404 | 活动 ID 不存在、已删除或已下架 | + +--- + +## ⑧ 示例 + +### 8.1 典型成功 — 获取收费活动详情 + +**请求** +``` +GET /mp/activity/1929000000000001 +Authorization: Bearer {mp_token} +``` + +**响应** +```json +{ + "code": 200, + "msg": "成功", + "data": { + "activityId": "1929000000000001", + "name": "高原骑马体验", + "categoryCode": "OUTDOOR", + "isCharged": 1, + "isChargedLabel": "是", + "status": 1 + } +} +``` + +### 8.2 边界情况 — 列表中混合收费/免费活动（均返回 isCharged + isChargedLabel） + +**请求** +``` +GET /mp/activity/list?categoryCode=OUTDOOR&page=1&pageSize=20 +Authorization: Bearer {mp_token} +``` + +**响应** +```json +{ + "code": 200, + "msg": "成功", + "data": { + "total": 2, + "list": [ + { + "activityId": "1929000000000001", + "name": "高原骑马体验", + "isCharged": 1, + "isChargedLabel": "是" + }, + { + "activityId": "1929000000000002", + "name": "免费篝火晚会", + "isCharged": 0, + "isChargedLabel": "否" + } + ] + } +} +``` + +### 8.3 业务失败 — 访问已下架活动 + +**请求** +``` +GET /mp/activity/1929000000000099 +Authorization: Bearer {mp_token} +``` + +**响应**（404，活动不存在或下架） +```json +{ + "code": 404, + "msg": "活动不存在", + "data": null +} +``` + +--- + +## ⑨ 业务边界 + +**适用场景**： +- 小程序活动详情页展示"是否收费"信息 +- 小程序活动列表卡片可展示收费状态，帮助用户快速识别 + +**不适用场景**： +- `isCharged` 仅为展示属性，不影响小程序下单流程或费用计算 +- 列表接口不支持按 `isCharged` 筛选 + +**特殊边界**： +- 历史存量活动（PR #3334 上线前创建）`isCharged` 默认为 0，`isChargedLabel` 返回 "否" +- 备品（物资）域无小程序端接口，本次不涉及 + +--- + +## ⑩ 修改前后对比 + +### 字段级对比 + +**出参（详情 + 列表）** + +| 字段名 | 变更前 | 变更后 | +|--------|--------|--------| +| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 | +| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null | + +### 行为级对比 + +| 行为 | 变更前 | 变更后 | +|------|--------|--------| +| 活动详情接口 | 无收费信息 | 新增 isCharged + isChargedLabel | +| 活动列表接口 | 无收费信息 | 新增 isCharged + isChargedLabel | + +--- + +## ⑪ 影响评估 / 回滚 + +**破坏兼容性**：无，新增字段，现有小程序代码可忽略不用。 + +**前端同步上线**：无强制要求，可选接入展示。 + +**回滚方案**：若后端回滚，`isCharged` 和 `isChargedLabel` 字段会从响应中消失，小程序侧无感（原本不存在该字段）。 + +--- + +## ⑫ 注意事项 + +1. 小程序**无需**配置 `sys_yes_no` 字典，后端已完成翻译并在 `isChargedLabel` 中直接返回中文 +2. 若不需要展示该字段，忽略即可，不影响任何现有功能 +3. 本次仅活动有小程序端接口变更，备品（物资）无小程序端接口，不在本文档范围内 + +--- + +## ⑬ 关联 / 联系人 + +- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3331](https://git.1814.love:8443/wx/HL/issues/3331) +- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3334](https://git.1814.love:8443/wx/HL/pulls/3334) +- **Commit**：[https://git.1814.love:8443/wx/HL/commit/5da05a324813cf8109d35c521c5e7bb9719627be](https://git.1814.love:8443/wx/HL/commit/5da05a324813cf8109d35c521c5e7bb9719627be) +- **后端负责人**：腰苏图（企微 / yst@1814.love）