From a38678b311636832d06b7cbb958311a25e3b8272 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 3 Jun 2026 11:51:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(v2):=20=E6=9C=8D=E5=8A=A1=E6=A0=87?= =?UTF-8?q?=E5=87=86=E4=B8=89=E7=AF=87=20changelog=20=E6=94=B9=E6=9C=B4?= =?UTF-8?q?=E7=B4=A0=E7=AE=80=E6=B4=81=E7=89=88(=E5=8E=BB=E5=9C=88?= =?UTF-8?q?=E5=8F=B7=E6=A0=87=E9=A2=98/=E8=A1=A8=E6=A0=BC/=E5=A4=9A?= =?UTF-8?q?=E4=BD=99=E7=B2=97=E4=BD=93)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...品Step5服务标准tab-只读预览接口-管理后台.md | 72 ++++++------------- .../03_服务标准模板与产品关联说明-管理后台.md | 53 ++++---------- .../2026-06/03_资源服务标准字段-管理后台.md | 54 +++++--------- 3 files changed, 50 insertions(+), 129 deletions(-) diff --git a/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md b/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md index 6c6de33..1aded7c 100644 --- a/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md +++ b/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，预览读走本接口。 diff --git a/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md b/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md index 8dca22d..2c8a4ec 100644 --- a/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md +++ b/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 提交，详情接口做预览。无破坏性变更。 diff --git a/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md b/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md index 7c6c981..1d4769e 100644 --- a/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md +++ b/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 输入项，接入创建/编辑与详情回显。可空，无破坏性变更。