diff --git a/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md b/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md index 1aded7c..55b1d04 100644 --- a/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md +++ b/changelogs-v2/2026-06/03_产品Step5服务标准tab-只读预览接口-管理后台.md @@ -1,37 +1,118 @@ -# 产品 Step5 服务标准 tab 只读预览接口 +# 【新增接口·管理后台】产品 Step5 服务标准 tab 只读预览 -端类型：管理后台 -日期：2026-06-03 -PR：#3377 +> PR: #3377 服务: hl-product-service-v2 | 更新时间: 2026-06-03 +> 存放目录: changelogs-v2/2026-06/ 影响范围: 管理后台「产品编辑 / Step5 补充信息 / 服务标准 tab」 -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 " \ + "https://api.test.1814.love:9443/admin/product/item/2056944461216100353/service-standard-preview" +``` + +## 4. 响应结构与字段说明 ``` { - templateId, // 当前绑定模板 ID，未绑定为 null - template, // 绑定模板完整内容(id/name/intro/applicableScope/sections[].items[6字段])，未绑定为 null - nodes: [ // 行程节点的服务标准+退费说明，只含有内容的节点，皆空的节点不返回 - { - dayNumber, - nodeName, - nodeType, // SCENIC/ACTIVITY/HOTEL/RESTAURANT... - serviceStandard, // 节点服务标准，无则 null - refundNote: { intro, items:[{title,amount,unitLabel,settleScope,settleScopeLabel,remark,effectiveFrom,effectiveTo}] } // 无则 null - } - ] + "templateId": Long, // 当前绑定模板 ID，未绑定为 null + "template": { ... }, // 绑定模板完整内容，结构同模板详情接口，未绑定为 null + "nodes": [ ... ] // 行程节点服务标准+退费说明，仅含有内容的节点，皆空节点不返回 } ``` -## 测试服实测（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`，预览（读）走本接口，两者配合。 diff --git a/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md b/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md index 2c8a4ec..eaf19e1 100644 --- a/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md +++ b/changelogs-v2/2026-06/03_服务标准模板与产品关联说明-管理后台.md @@ -1,22 +1,118 @@ -# 服务标准模板与产品的关联方式（产品 Step5 补充信息） +# 【说明补齐·管理后台】服务标准模板与产品的关联方式（产品 Step5） -端类型：管理后台 -日期：2026-06-03 -PR：#3375 +> PR: #3375 服务: hl-product-service-v2 | 更新时间: 2026-06-03 +> 存放目录: changelogs-v2/2026-06/ 影响范围: 管理后台「产品编辑 / Step5 补充信息」（服务标准模板绑定） -前端反馈这块没收到说明，这里补齐。服务标准模板是一份统一维护的全局模板库，产品通过纯引用一个模板 ID 与它关联，不复制模板正文。 +## ⚠️ 关键说明 -## 怎么关联 +前端反馈「服务标准模板怎么和产品关联」一直没有同步说明，本文补齐，含完整接口、字段、请求/响应示例。 -- 取启用模板下拉：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`）与它关联，不复制模板正文。 +- 所有产品（含私人定制）的服务标准都**实时按模板 ID 查询展示**，模板改了已绑定产品实时跟随。 +- 原私人定制完成设计冻快照的机制（`service_standard_snapshot`）已废除（PR #3375），**接口结构不变，前端无需改动**。 -## 展示语义 +## 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 " \ + "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 " \ + "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 " -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` 回填下拉。 + +无破坏性变更，按需接入即可。 diff --git a/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md b/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md index 1d4769e..b1dca08 100644 --- a/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md +++ b/changelogs-v2/2026-06/03_资源服务标准字段-管理后台.md @@ -1,26 +1,64 @@ -# 资源服务标准字段 service_standard（景区/游玩项目/服务/酒店） +# 【说明补齐·管理后台】资源服务标准字段 service_standard（景区/游玩项目/服务/酒店） -端类型：管理后台 -日期：2026-06-03 +> PR: 无（字段此前已落地，本次补齐说明） 服务: hl-resource-service | 更新时间: 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} -- 游玩项目：POST /admin/activity/item、PUT /admin/activity/item/{activityId} -- 服务：POST /admin/service/item、PUT /admin/service/item/{serviceId} -- 酒店：POST/PUT /admin/hotel/... +## 1. 字段背景 -编辑接口是字段级 PATCH：只传 serviceStandard 即可单独更新，不影响其它字段。 +为支持订单/小程序行程节点、产品 Step5 服务标准 tab 展示「每个点位的服务标准」，在 4 类资源上增加了 `serviceStandard` 字段，由运营在资源编辑页维护。 -## 字段去向 +## 2. 字段所在接口 -- 订单/小程序行程节点：按节点 resourceId 实时取资源 serviceStandard 展示 -- 产品 Step5 服务标准 tab 预览：GET /admin/product/item/{id}/service-standard-preview 的 nodes[].serviceStandard 即来自此字段 +`serviceStandard` 已在以下 4 类资源的创建 / 编辑请求体与详情 / 列表响应里： -## 前端动作 +| # | 资源 | 创建 | 编辑（字段级 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 " -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. 可空，无破坏性变更，按需接入。