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

docs(v2): 服务标准三篇 changelog 对齐团队样板格式 + 补详细用法与请求/响应示例

浏览代码
这个提交包含在：
API Changelog Bot 2026-06-03 11:57:56 +08:00
父节点 a38678b311
当前提交 d3e7e69489
共有 3 个文件被更改，包括 268 次插入 和 53 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

127
changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md
查看文件

@ -1,37 +1,118 @@
# 产品 Step5 服务标准 tab 只读预览接口 # 【新增接口·管理后台】产品 Step5 服务标准 tab 只读预览
端类型：管理后台 > PR: #3377 服务: hl-product-service-v2 | 更新时间: 2026-06-03
日期：2026-06-03 > 存放目录: changelogs-v2/2026-06/ 影响范围: 管理后台「产品编辑 / Step5 补充信息 / 服务标准 tab」
PR：#3377
Step5 补充信息新增服务标准 tab，一个接口返三块（都只读、实时拉取不冻快照）：当前绑定模板内容、各行程节点服务标准、各行程节点退费说明。模板的绑定（写）走 Step5 保存的 serviceStandardTemplateId（见另一篇《服务标准模板与产品关联说明》），本接口只负责只读预览。 ## ⚠️ 关键说明
## 接口 Step5 补充信息新增「服务标准」tab，**一个接口返三块**，均**只读、实时拉取不冻快照**：
GET /admin/product/item/{id}/service-standard-preview（admin token，产品数据权限与产品详情同口径） 1. 当前绑定模板内容
2. 各行程节点的服务标准（来自资源 `service_standard`）
3. 各行程节点的退费说明（来自资源退费说明）
返回 data： 模板的**绑定（写）**走 Step5 保存的 `serviceStandardTemplateId`（见同期《服务标准模板与产品的关联方式》），本接口只负责 tab 内的**只读预览展示**。
## 1. 接口背景
运营在 Step5 绑定模板后，希望一屏看到：当前模板内容、以及各行程节点从资源实时带出的服务标准与退费说明，而不必跳到资源页或下单后才看到。
## 2. 接口清单
| # | 方法 | 路径 | 变更类型 | 鉴权 |
|---|------|------|----------|------|
| 1 | GET | `/admin/product/item/{id}/service-standard-preview` | 新增 | admin token，产品数据权限（与产品详情同口径） |
## 3. 请求示例
```bash
curl -H "Authorization: Bearer <admin-token>" \
"https://api.test.1814.love:9443/admin/product/item/2056944461216100353/service-standard-preview"
```
## 4. 响应结构与字段说明
``` ```
{ {
templateId, // 当前绑定模板 ID，未绑定为 null "templateId": Long, // 当前绑定模板 ID，未绑定为 null
template, // 绑定模板完整内容(id/name/intro/applicableScope/sections[].items[6字段])，未绑定为 null "template": { ... }, // 绑定模板完整内容，结构同模板详情接口，未绑定为 null
nodes: [ // 行程节点的服务标准+退费说明，只含有内容的节点，皆空的节点不返回 "nodes": [ ... ] // 行程节点服务标准+退费说明，仅含有内容的节点，皆空节点不返回
{
dayNumber,
nodeName,
nodeType, // SCENIC/ACTIVITY/HOTEL/RESTAURANT...
serviceStandard, // 节点服务标准，无则 null
refundNote: { intro, items:[{title,amount,unitLabel,settleScope,settleScopeLabel,remark,effectiveFrom,effectiveTo}] } // 无则 null
}
]
} }
``` ```
## 测试服实测（dev-v3） nodes[] 字段：
12 个产品调用全 200。模板块、退费说明块用真数据验证通过；节点服务标准块在景区/游玩项目/服务各配一条 service_standard 后，三类节点均正确返回。 | 字段 | 类型 | 说明 |
|------|------|------|
| dayNumber | Integer | 第几天 |
| nodeName | String | 节点名称（如「呼和诺尔草原旅游区」） |
| nodeType | String | 节点类型：SCENIC / ACTIVITY / HOTEL / RESTAURANT / SERVICE ... |
| serviceStandard | String | 节点服务标准（来自资源），无则 null |
| refundNote | Object | 退费说明，无则 null |
## 前端动作 refundNote 结构：
在服务标准 tab 调本接口渲染三块，均只读。serviceStandard/refundNote 可能为 null，按需隐藏。绑定写走 supplement 的 serviceStandardTemplateId，预览读走本接口。 | 字段 | 类型 | 说明 |
|------|------|------|
| intro | String | 退费说明备注 |
| items[].title | String | 条目标题（如「成人未参加」） |
| items[].amount | BigDecimal | 退费金额 |
| items[].unitLabel | String | 单位文案（如「/人」「/团」） |
| items[].settleScope | String | 结算范围枚举：PER_PERSON / PER_TEAM |
| items[].settleScopeLabel | String | 结算范围中文（按人 / 按团） |
| items[].remark | String | 备注，可空 |
| items[].effectiveFrom / effectiveTo | Date | 生效区间，可空 |
## 5. 真实响应示例（测试服 dev-v3，产品 2056944461216100353）
```json
{
"code": 200,
"data": {
"templateId": null,
"template": null,
"nodes": [
{
"dayNumber": 1,
"nodeName": "巴音温泉",
"nodeType": "SERVICE",
"serviceStandard": "提供24小时管家服务，含接送站、行程咨询、紧急联络。",
"refundNote": null
},
{
"dayNumber": 2,
"nodeName": "呼和诺尔草原旅游区",
"nodeType": "SCENIC",
"serviceStandard": "景区内提供免费讲解、母婴室、医疗点；请听从工作人员安排，注意草原防火。",
"refundNote": {
"intro": "退费为旅游项目门票退费",
"items": [
{ "title": "成人未参加", "amount": 44.0, "unitLabel": "/人", "settleScope": "PER_PERSON", "settleScopeLabel": "按人", "remark": "凭票根", "effectiveFrom": null, "effectiveTo": null },
{ "title": "整团未到", "amount": 100.0, "unitLabel": "/团", "settleScope": "PER_TEAM", "settleScopeLabel": "按团", "remark": null, "effectiveFrom": null, "effectiveTo": null }
]
}
},
{
"dayNumber": 2,
"nodeName": "黄河湿地漂流",
"nodeType": "ACTIVITY",
"serviceStandard": "漂流配备专业教练与救生装备，全程安全护航；12岁以下需成人陪同。",
"refundNote": null
}
]
}
}
```
> 说明：示例中节点 `serviceStandard` 为测试服联调写入的样例数据。若资源未配置 `service_standard`，该字段返回 `null`（详见《资源服务标准字段》一文，运营在资源上配置后即自动带出）。
## 6. 测试服实测（dev-v3）
12 个产品调用全部 `code=200`。模板块、退费说明块用真数据验证通过；节点服务标准块在景区 / 游玩项目 / 服务各配一条 `service_standard` 后，三类节点均正确返回上方示例值。
## 7. 前端动作
1. 进入 Step5 服务标准 tab 调本接口。
2. 渲染三块：`template` 模板内容、`nodes[].serviceStandard` 节点服务标准、`nodes[].refundNote` 节点退费说明，均只读。
3. `template` / `serviceStandard` / `refundNote` 均可能为 `null`，按需隐藏对应区块。
4. 绑定（写）走 supplement 的 `serviceStandardTemplateId`，预览（读）走本接口，两者配合。

124
changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md
查看文件

@ -1,22 +1,118 @@
# 服务标准模板与产品的关联方式（产品 Step5 补充信息） # 【说明补齐·管理后台】服务标准模板与产品的关联方式（产品 Step5）
端类型：管理后台 > PR: #3375 服务: hl-product-service-v2 | 更新时间: 2026-06-03
日期：2026-06-03 > 存放目录: changelogs-v2/2026-06/ 影响范围: 管理后台「产品编辑 / Step5 补充信息」（服务标准模板绑定）
PR：#3375
前端反馈这块没收到说明，这里补齐。服务标准模板是一份统一维护的全局模板库，产品通过纯引用一个模板 ID 与它关联，不复制模板正文。 ## ⚠️ 关键说明
## 怎么关联 前端反馈「服务标准模板怎么和产品关联」一直没有同步说明，本文补齐，含完整接口、字段、请求/响应示例。
- 取启用模板下拉：GET /admin/product/service-standard-template/enabled，返回 [{id, name}] - 服务标准模板是一份**统一维护的全局模板库**，产品通过**纯引用一个模板 ID**（`serviceStandardTemplateId`）与它关联，不复制模板正文。
- 取模板详情做预览：GET /admin/product/service-standard-template/{id}，返回 intro、applicableScope、sections[].items[]（6 字段：title/content/remark/color/contactName/phone） - 所有产品（含私人定制）的服务标准都**实时按模板 ID 查询展示**，模板改了已绑定产品实时跟随。
- 保存绑定：PUT /admin/product/item/{id}/supplement，请求体字段 serviceStandardTemplateId（Long，可空）就是绑定的模板 ID - 原私人定制完成设计冻快照的机制（`service_standard_snapshot`）已废除（PR #3375），**接口结构不变，前端无需改动**。
- 回显：产品/Step5 读取接口返回的 serviceStandardTemplateId 即当前绑定，未绑定为 null
## 展示语义 ## 1. 接口背景
所有产品（含私人定制）的服务标准都按 serviceStandardTemplateId 实时查模板展示，模板改了已绑定产品实时跟随。原私人定制完成设计时冻快照的机制（service_standard_snapshot）已废除（PR #3375），接口结构不变，前端无需改动。 产品编辑 Step5「补充信息」里需要给产品绑定一份服务标准模板。绑定关系存在产品的 `serviceStandardTemplateId` 字段（纯引用，可空）。前端需要：拉模板下拉、预览模板内容、保存绑定、回显当前绑定。
## 前端动作 ## 2. 接口清单
在 Step5 做模板绑定 UI：用 enabled 拉下拉，选中后把 serviceStandardTemplateId 随 supplement 提交，详情接口做预览。无破坏性变更。 | # | 用途 | 方法 | 路径 |
|---|------|------|------|
| 1 | 启用模板下拉 | GET | `/admin/product/service-standard-template/enabled` |
| 2 | 模板详情（预览） | GET | `/admin/product/service-standard-template/{id}` |
| 3 | 保存绑定 | PUT | `/admin/product/item/{id}/supplement` |
## 3. 详细用法与示例
### 3.1 拉模板下拉（接口 1）
```bash
curl -H "Authorization: Bearer <admin-token>" \
"https://api.test.1814.love:9443/admin/product/service-standard-template/enabled"
```
响应（只返 id + name，供下拉选择）：
```json
{
"code": 200,
"data": [
{ "id": "2061281473171775490", "name": "6字段服务标准模板" }
]
}
```
### 3.2 预览选中模板内容（接口 2）
```bash
curl -H "Authorization: Bearer <admin-token>" \
"https://api.test.1814.love:9443/admin/product/service-standard-template/2061281473171775490"
```
响应（含分组 sections 与每条 6 字段）：
```json
{
"code": 200,
"data": {
"id": "2061281473171775490",
"name": "6字段服务标准模板",
"intro": "全国统一的服务标准",
"applicableScope": "本周期本产品全部出团人群",
"sections": [
{
"title": "用车服务",
"items": [
{
"title": "专业司机",
"content": "持有A1驾照，8年以上驾龄",
"remark": "提供接送指引",
"color": "#FF6600",
"contactName": "李师傅",
"phone": "13800000000"
}
]
}
],
"status": "ENABLED",
"statusLabel": "启用"
}
}
```
模板条目 6 字段说明：
| 字段 | 类型 | 说明 |
|------|------|------|
| title | String | 条目标题，如「专业司机」 |
| content | String | 条目正文 |
| remark | String | 备注，可空 |
| color | String | 标题色值 `#RRGGBB`，可空 |
| contactName | String | 联系人，可空 |
| phone | String | 联系电话，可空 |
### 3.3 保存绑定（接口 3）
Step5 保存时在 supplement 请求体里带上 `serviceStandardTemplateId` 即可（解绑传 `null`）：
```bash
curl -X PUT -H "Authorization: Bearer <admin-token>" -H "Content-Type: application/json" \
-d '{"serviceStandardTemplateId": 2061281473171775490}' \
"https://api.test.1814.love:9443/admin/product/item/2056938821550747650/supplement"
```
> 注：supplement 请求体含 Step5 全量字段，此处仅示意服务标准模板字段，实际提交按 Step5 既有结构整体提交。
### 3.4 回显当前绑定
产品 / Step5 读取接口返回的 `serviceStandardTemplateId` 即当前绑定（未绑定为 `null`），前端据此回填下拉选中项。
## 4. 前端动作
1. 进入 Step5 服务标准区，用接口 1 拉下拉。
2. 选中某模板，用接口 2 拉详情做内容预览。
3. 保存时把 `serviceStandardTemplateId` 随接口 3（supplement）整体提交。
4. 回显时读 Step5 数据里的 `serviceStandardTemplateId` 回填下拉。
无破坏性变更，按需接入即可。

70
changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md
查看文件

@ -1,26 +1,64 @@
# 资源服务标准字段 service_standard（景区/游玩项目/服务/酒店） # 【说明补齐·管理后台】资源服务标准字段 service_standard（景区/游玩项目/服务/酒店）
端类型：管理后台 > PR: 无（字段此前已落地，本次补齐说明） 服务: hl-resource-service | 更新时间: 2026-06-03
日期：2026-06-03 > 存放目录: changelogs-v2/2026-06/ 影响范围: 管理后台「资源管理 / 景区·游玩项目·服务·酒店」（编辑表单新增字段）
前端反馈资源上新增的服务标准字段 serviceStandard 没收到说明，这里补齐。该字段是点位级服务标准，配置在资源本体上，下游（订单/小程序行程节点、产品 Step5 服务标准 tab 节点预览）实时按 resourceId 拉取展示，不冻快照，资源改了已引用处同步更新。 ## ⚠️ 关键说明
## 字段位置 前端反馈资源上新增的「服务标准」字段 `serviceStandard` 没有同步说明，本文补齐，含字段位置、请求示例、字段去向。
serviceStandard（String，最长 10000 字，可空）已在以下 4 类资源的创建/编辑请求体与详情/列表响应里： - `serviceStandard` 是**点位级服务标准**，配置在资源本体上（String，最长 10000 字，可空）。
- 下游（订单 / 小程序行程节点、产品 Step5 服务标准 tab 节点预览）**实时按 resourceId 拉取展示，不冻快照**，资源改了已引用处同步更新。
- 编辑接口是**字段级 PATCH**：请求体只传 `serviceStandard` 即可单独更新该字段，其它字段为 null 时跳过、不受影响。
- 景区：POST /admin/scenic/spot、PUT /admin/scenic/spot/{scenicId} ## 1. 字段背景
- 游玩项目：POST /admin/activity/item、PUT /admin/activity/item/{activityId}
- 服务：POST /admin/service/item、PUT /admin/service/item/{serviceId}
- 酒店：POST/PUT /admin/hotel/...
编辑接口是字段级 PATCH：只传 serviceStandard 即可单独更新，不影响其它字段。 为支持订单/小程序行程节点、产品 Step5 服务标准 tab 展示「每个点位的服务标准」，在 4 类资源上增加了 `serviceStandard` 字段，由运营在资源编辑页维护。
## 字段去向 ## 2. 字段所在接口
- 订单/小程序行程节点：按节点 resourceId 实时取资源 serviceStandard 展示 `serviceStandard` 已在以下 4 类资源的创建 / 编辑请求体与详情 / 列表响应里：
- 产品 Step5 服务标准 tab 预览：GET /admin/product/item/{id}/service-standard-preview 的 nodes[].serviceStandard 即来自此字段
## 前端动作 | # | 资源 | 创建 | 编辑（字段级 PATCH） |
|---|------|------|------|
| 1 | 景区 Scenic | POST `/admin/scenic/spot` | PUT `/admin/scenic/spot/{scenicId}` |
| 2 | 游玩项目 Activity | POST `/admin/activity/item` | PUT `/admin/activity/item/{activityId}` |
| 3 | 服务 ServiceItem | POST `/admin/service/item` | PUT `/admin/service/item/{serviceId}` |
| 4 | 酒店 Hotel | POST `/admin/hotel/item` | PUT `/admin/hotel/item/{hotelId}` |
在景区/游玩项目/服务/酒店的编辑表单加 serviceStandard 输入项，接入创建/编辑与详情回显。可空，无破坏性变更。 字段约束：`@Size(max=10000)`，可空。
## 3. 详细用法与示例
### 3.1 单独更新某资源的服务标准（PATCH）
编辑接口逐字段判空，只传 `serviceStandard` 即可，不影响其它字段。以景区为例（测试服实测）：
```bash
curl -X PUT -H "Authorization: Bearer <admin-token>" -H "Content-Type: application/json" \
-d '{"serviceStandard": "景区内提供免费讲解、母婴室、医疗点；请听从工作人员安排，注意草原防火。"}' \
"https://api.test.1814.love:9443/admin/scenic/spot/3001000000000000010"
```
响应：
```json
{ "code": 200, "data": { "...": "...", "serviceStandard": "景区内提供免费讲解、母婴室、医疗点；请听从工作人员安排，注意草原防火。" } }
```
游玩项目 / 服务 / 酒店同理，把路径换成对应资源即可（详见接口表）。
### 3.2 详情回显
资源详情 / 列表响应里都带 `serviceStandard` 字段，编辑页回填即可（未配置为 null）。
## 4. 字段去向（配了之后哪里展示）
- 订单 / 小程序行程节点：按节点 resourceId 实时取资源 `serviceStandard` 展示（点位级服务标准）。
- 产品编辑 Step5 服务标准 tab：`GET /admin/product/item/{id}/service-standard-preview` 的 `nodes[].serviceStandard` 即来自此字段（详见《产品 Step5 服务标准 tab 只读预览》）。
## 5. 前端动作
1. 在景区 / 游玩项目 / 服务 / 酒店的编辑表单加 `serviceStandard`（服务标准，多行文本，≤10000 字）输入项。
2. 创建 / 编辑提交时带上该字段；详情回显读 `serviceStandard` 回填。
3. 可空，无破坏性变更，按需接入。