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

docs(v2): 服务标准三篇 changelog 改朴素简洁版(去圈号标题/表格/多余粗体)

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

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

@ -1,69 +1,37 @@
# 产品编辑 Step5「服务标准」tab —— 只读预览接口（一个接口返三块）
# 产品 Step5 服务标准 tab 只读预览接口
- **端类型**：管理后台
- **变更类型**：新增接口
- **日期**：2026-06-03
- **PR**：[#3377](https://git.1814.love:8443/wx/HL/pulls/3377)
- **后端负责人**：wx
端类型：管理后台
日期：2026-06-03
PR：#3377
---
Step5 补充信息新增服务标准 tab，一个接口返三块（都只读、实时拉取不冻快照）：当前绑定模板内容、各行程节点服务标准、各行程节点退费说明。模板的绑定（写）走 Step5 保存的 serviceStandardTemplateId（见另一篇《服务标准模板与产品关联说明》），本接口只负责只读预览。
## ① 背景
## 接口
产品编辑 Step5「补充信息」新增「服务标准」tab，一屏内同时给运营看三块（均**只读、实时**，不冻快照）：
1. 当前绑定的服务标准模板内容
2. 各行程节点的服务标准（来自资源 service_standard）
3. 各行程节点的退费说明（来自资源退费说明）
GET /admin/product/item/{id}/service-standard-preview（admin token，产品数据权限与产品详情同口径）
模板的**绑定（写）**走既有 Step5 保存（`serviceStandardTemplateId`，见 6-03 另一篇《服务标准模板与产品关联说明》）。本接口只负责 tab 内的**只读预览展示**。
---
## ② 新增接口
| 接口 | 方法 | 路径 | 鉴权 |
|------|------|------|------|
| 服务标准预览 | GET | `/admin/product/item/{id}/service-standard-preview` | admin token；产品数据权限（与产品详情同口径） |
响应 `data` 结构：
返回 data：
```
{
"templateId": 2061281473171775490, // 当前绑定模板ID，未绑定为 null
"template": { // 绑定模板完整内容，未绑定为 null
"id", "name", "intro", "applicableScope",
"sections": [ { "title", "items": [ { "title","content","remark","color","contactName","phone" } ] } ]
},
"nodes": [ // 行程节点的服务标准+退费说明（仅含有内容的节点；皆空的节点不返回）
templateId, // 当前绑定模板 ID，未绑定为 null
template, // 绑定模板完整内容(id/name/intro/applicableScope/sections[].items[6字段])，未绑定为 null
nodes: [ // 行程节点的服务标准+退费说明，只含有内容的节点，皆空的节点不返回
{
"dayNumber": 2,
"nodeName": "呼和诺尔草原旅游区",
"nodeType": "SCENIC", // SCENIC/ACTIVITY/HOTEL/RESTAURANT...
"serviceStandard": "……", // 资源节点服务标准，无则 null
"refundNote": { // 退费说明，无则 null
"intro": "……",
"items": [
{ "title","amount","unitLabel","settleScope","settleScopeLabel","remark","effectiveFrom","effectiveTo" }
]
}
dayNumber,
nodeName,
nodeType, // SCENIC/ACTIVITY/HOTEL/RESTAURANT...
serviceStandard, // 节点服务标准，无则 null
refundNote: { intro, items:[{title,amount,unitLabel,settleScope,settleScopeLabel,remark,effectiveFrom,effectiveTo}] } // 无则 null
}
]
}
```
---
## 测试服实测（dev-v3）
## ③ 测试服实测（已部署 dev-v3）
12 个产品调用全 200。模板块、退费说明块用真数据验证通过；节点服务标准块在景区/游玩项目/服务各配一条 service_standard 后，三类节点均正确返回。
- 12 个产品调用全 `code=200`。
- **模板块**：产品 2056938821550747650 → `templateId=2061281473171775490`、`template` 含完整 sections，正确返回。
- **退费说明块**：产品 2056944461216100353 → 节点「呼和诺尔草原旅游区(SCENIC)」`refundNote.items` 2 条（成人未参加/整团未到），正确返回。
- **节点服务标准块**：当前测试库 66 个景区**均未配置 `service_standard`**，故 `serviceStandard` 现返回 null。字段链路已端到端打通（资源端已填充、本接口已映射），**运营在资源上配置 service_standard 后即自动展示**，前端无需改动。
## 前端动作
---
## ④ 前端动作
- 在 Step5「服务标准」tab 调本接口渲染三块（模板内容 + 节点服务标准 + 节点退费说明），均为**只读展示**。
- 节点列表已按天/节点顺序、过滤掉无服务标准且无退费说明的节点；`serviceStandard`/`refundNote` 可能为 null，按需隐藏。
- 与模板**绑定**（写）配合使用：绑定走 `PUT /admin/product/item/{id}/supplement` 的 `serviceStandardTemplateId`，预览走本接口。
在服务标准 tab 调本接口渲染三块，均只读。serviceStandard/refundNote 可能为 null，按需隐藏。绑定写走 supplement 的 serviceStandardTemplateId，预览读走本接口。

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

@ -1,47 +1,22 @@
# 服务标准模板与产品的关联方式（产品编辑 Step5 补充信息）——说明补齐
# 服务标准模板与产品的关联方式（产品 Step5 补充信息）
- **端类型**：管理后台
- **变更类型**：说明补齐（既有功能，此前未同步给前端）+ 行为统一（私人定制不再冻结快照）
- **日期**：2026-06-03
- **PR**：[#3375](https://git.1814.love:8443/wx/HL/pulls/3375)（行为统一部分）
- **后端负责人**：wx
端类型：管理后台
日期：2026-06-03
PR：#3375
---
前端反馈这块没收到说明，这里补齐。服务标准模板是一份统一维护的全局模板库，产品通过纯引用一个模板 ID 与它关联，不复制模板正文。
## ① 背景
## 怎么关联
前端反馈：**「服务标准模板怎么和产品关联」一直没有收到说明**。本文补齐这块的完整接口契约，供产品编辑 Step5「补充信息」里做「服务标准」相关 UI（绑定模板）使用。
- 取启用模板下拉：GET /admin/product/service-standard-template/enabled，返回 [{id, name}]
- 取模板详情做预览：GET /admin/product/service-standard-template/{id}，返回 intro、applicableScope、sections[].items[]（6 字段：title/content/remark/color/contactName/phone）
- 保存绑定：PUT /admin/product/item/{id}/supplement，请求体字段 serviceStandardTemplateId（Long，可空）就是绑定的模板 ID
- 回显：产品/Step5 读取接口返回的 serviceStandardTemplateId 即当前绑定，未绑定为 null
服务标准模板（出团服务说明书）是一份**统一维护的全局模板库**；产品通过**纯引用一个模板 ID** 与之关联，不复制模板内容。
## 展示语义
---
所有产品（含私人定制）的服务标准都按 serviceStandardTemplateId 实时查模板展示，模板改了已绑定产品实时跟随。原私人定制完成设计时冻快照的机制（service_standard_snapshot）已废除（PR #3375），接口结构不变，前端无需改动。
## ② 关联机制（产品 ←→ 服务标准模板）
## 前端动作
| 步骤 | 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|------|
| 取模板下拉 | 启用模板下拉 | GET | `/admin/product/service-standard-template/enabled` | 返回 `[{id, name}]`，仅 status=ENABLED |
| 取模板详情(预览) | 模板详情 | GET | `/admin/product/service-standard-template/{id}` | 返回 `{id,name,intro,applicableScope,sections:[{title,items:[{title,content,remark,color,contactName,phone}]}]}` |
| 取模板分页 | 模板分页 | GET | `/admin/product/service-standard-template/page?page=&pageSize=` | 列表页不下钻 sections（为 null），仅主表字段 |
| **保存绑定** | Step5 补充信息保存 | PUT | `/admin/product/item/{id}/supplement` | 请求体字段 **`serviceStandardTemplateId`**（Long，可空）即为产品绑定的服务标准模板 ID |
- **绑定即"纯引用"**：产品只存 `serviceStandardTemplateId`，不存模板正文。
- **回显**：产品详情/Step5 读取接口返回的 `serviceStandardTemplateId` 即当前绑定，前端据此回填下拉选中项；未绑定为 null。
---
## ③ 展示语义（统一实时引用，私人定制不再冻快照）
- **所有产品类型**（含 CORE/GROUP/CUSTOM 私人定制）C 端/订单详情的服务标准，**统一按 `serviceStandardTemplateId` 实时查模板展示**。
- 模板内容被运营修改后，**已绑定的产品实时跟随**（含私人定制）。
- 此前私人定制产品在「完成设计」时会冻结一份快照（`service_standard_snapshot`），**现已废除**（PR #3375）：私人定制与普通产品行为一致，统一实时引用。**此为后端内部数据来源变化，接口结构不变，前端无需改动**。
---
## ④ 前端动作
- 在产品编辑 Step5「补充信息」做服务标准模板的**绑定 UI**：用 `/enabled` 拉下拉、选中后把 `serviceStandardTemplateId` 随 `PUT /{id}/supplement` 提交；可用 `/{id}` 拉模板详情做选中预览。
- 回显：读 Step5 数据里的 `serviceStandardTemplateId` 回填。
- 无破坏性变更，按需接入即可。
> 说明：产品编辑页「服务标准」tab 中**只读展示行程节点服务标准/退费说明**的能力为独立后端需求，正在设计，待后端接口就绪后另发 changelog。
在 Step5 做模板绑定 UI：用 enabled 拉下拉，选中后把 serviceStandardTemplateId 随 supplement 提交，详情接口做预览。无破坏性变更。

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

@ -1,48 +1,26 @@
# 资源「服务标准」字段（service_standard）—— 说明补齐（景区/游玩项目/服务/酒店）
# 资源服务标准字段 service_standard（景区/游玩项目/服务/酒店）
- **端类型**：管理后台
- **变更类型**：说明补齐（字段此前已存在，未同步给前端）
- **日期**：2026-06-03
- **后端负责人**：wx
端类型：管理后台
日期：2026-06-03
---
前端反馈资源上新增的服务标准字段 serviceStandard 没收到说明，这里补齐。该字段是点位级服务标准，配置在资源本体上，下游（订单/小程序行程节点、产品 Step5 服务标准 tab 节点预览）实时按 resourceId 拉取展示，不冻快照，资源改了已引用处同步更新。
## ① 背景
## 字段位置
前端反馈：资源（景区/游玩项目/服务/酒店）上新增的**「服务标准」字段 `serviceStandard`** 一直没有同步说明。本文补齐。
serviceStandard（String，最长 10000 字，可空）已在以下 4 类资源的创建/编辑请求体与详情/列表响应里：
该字段是**点位级服务标准**：配置在资源本体上，下游（订单详情/小程序节点、以及产品编辑 Step5「服务标准」tab 的节点预览）**实时按 resourceId 拉取展示，不冻快照**——资源上改了，已引用的产品/订单同步更新。
- 景区：POST /admin/scenic/spot、PUT /admin/scenic/spot/{scenicId}
- 游玩项目：POST /admin/activity/item、PUT /admin/activity/item/{activityId}
- 服务：POST /admin/service/item、PUT /admin/service/item/{serviceId}
- 酒店：POST/PUT /admin/hotel/...
---
编辑接口是字段级 PATCH：只传 serviceStandard 即可单独更新，不影响其它字段。
## ② 涉及资源与接口
## 字段去向
`serviceStandard`（String，最长 10000 字）已在以下 4 类资源的**创建/编辑请求体**与**详情/列表响应**中：
- 订单/小程序行程节点：按节点 resourceId 实时取资源 serviceStandard 展示
- 产品 Step5 服务标准 tab 预览：GET /admin/product/item/{id}/service-standard-preview 的 nodes[].serviceStandard 即来自此字段
| 资源 | 创建 | 编辑 | 详情/列表(响应含 serviceStandard) |
|------|------|------|------|
| 景区 Scenic | `POST /admin/scenic/spot` | `PUT /admin/scenic/spot/{scenicId}` | `GET /admin/scenic/spot/{scenicId}`、`GET /admin/scenic/spots` |
| 游玩项目 Activity | `POST /admin/activity/item` | `PUT /admin/activity/item/{activityId}` | 活动详情/列表 |
| 服务 ServiceItem | `POST /admin/service/item` | `PUT /admin/service/item/{serviceId}` | 服务详情/列表 |
| 酒店 Hotel | `POST /admin/hotel/...` 创建 | `PUT /admin/hotel/...` 编辑 | 酒店详情/列表 |
## 前端动作
- 编辑接口为**字段级 PATCH**：请求体只传 `serviceStandard` 即可单独更新该字段，不影响其它字段（其它字段为 null 时跳过）。
- 字段约束：`@Size(max=10000)`；可空。
---
## ③ 下游消费（字段去向）
- 订单详情 / 小程序行程节点：按节点 resourceId 实时取资源 `serviceStandard` 展示（点位级服务标准）。
- 产品编辑 Step5「服务标准」tab 只读预览：`GET /admin/product/item/{id}/service-standard-preview` 的 `nodes[].serviceStandard` 即来自此字段（见 6-03《产品 Step5 服务标准 tab 只读预览接口》）。
---
## ④ 测试服实测
在景区(呼和诺尔草原旅游区)/游玩项目(漂流)/服务项 各写入一条 `serviceStandard` 后，产品 Step5 预览接口 `nodes[].serviceStandard` 三类节点均正确返回该值。
## ⑤ 前端动作
- 在景区/游玩项目/服务/酒店的**编辑表单**加 `serviceStandard`（服务标准）输入项，按需接入创建/编辑请求与详情回显。
- 无破坏性变更，可空，按需接入。
在景区/游玩项目/服务/酒店的编辑表单加 serviceStandard 输入项，接入创建/编辑与详情回显。可空，无破坏性变更。