wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

文档(mp): 活动是否收费字段变更通知（小程序端）— PR #3334 Issue #3331

浏览代码
这个提交包含在：
yaosutu 2026-06-01 22:42:51 +08:00
父节点 6f56b950fa
当前提交 0fda85a6f8
共有 1 个文件被更改，包括 239 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

239
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）