diff --git a/changelogs-v2/2026-06/04_服务标准模板管理页-前端待建+后端CRUD契约-管理后台.md b/changelogs-v2/2026-06/04_服务标准模板管理页-前端待建+后端CRUD契约-管理后台.md new file mode 100644 index 0000000..8206d16 --- /dev/null +++ b/changelogs-v2/2026-06/04_服务标准模板管理页-前端待建+后端CRUD契约-管理后台.md @@ -0,0 +1,165 @@ +# 【前端待建·管理后台】服务标准模板管理页（后端 CRUD 已就绪，前端缺管理页 + 菜单） + +> **PR**: 无（后端接口此前已随 #3147/#3253 系列落地，本篇补发完整管理 CRUD 契约 + 提前端补管理页） +> **服务**: hl-product-service-v2 | **更新时间**: 2026-06-04 +> +> **存放目录**: `changelogs-v2/2026-06/` +> **影响范围**: 管理后台「行程管理 → 服务标准模板」（**当前缺失**，需前端新建管理页 + 菜单） + +--- + +## ⚠️ 关键说明 + +1. **现状**：管理后台找不到「服务标准模板」菜单。排查确认 —— **后端管理 CRUD 接口完全就绪**（`/admin/product/service-standard-template`，含分页/详情/启用下拉/保存/删除，测试库已有 1 条模板数据），但**前端 v2.1 没有建独立管理页**，`sys_menu` 也没建菜单。 +2. **前端现有的只是"选模板"**：`api/product/service-standard.js` 仅有 `getEnabled`(启用下拉) / `detail`(详情) / `preview`(产品预览)，用于**产品编辑 Step5「补充信息」里挑一个已有模板**（`ServiceStandardPanel.vue`）+ 订单详情展示（`ServiceStandardTab.vue`）。**没有分页/保存/删除调用，没有管理页，没有路由**。 +3. **对照「装备建议组合」**：装备建议组合是完整的 —— 前端有 `views/product/equipment-template/index.vue` + `EditModal.vue`，且 `sys_menu` 有菜单 `/product/equipment-template`（挂在「行程管理」下）。**服务标准模板缺的就是这一套**。 +4. **请前端补**：参照装备建议组合，新建服务标准模板管理页（列表 + 新增/编辑弹窗），路由建议 `/product/service-standard-template`，菜单挂「行程管理」下。菜单加好后即可在导航看到。 + +--- + +## 1. 接口背景 + +服务标准模板（出团服务说明书）：运营维护一批"服务标准"模板，产品在 Step5 补充信息里**绑定一个模板**（用 §2.3 启用下拉选）。模板本身的增删改查需要一个独立管理页（类似装备建议组合 / 报价公式那种列表管理页）。 + +模板结构是两层：**分组 Section（如"出行服务"）→ 条目 Item（主文案 + 正文 + 备注 + 颜色 + 联系人 + 电话）**。 + +--- + +## 2. 变更清单（后端均已就绪，前端待对接） + +| # | 方法 | 路径 | 说明 | 前端现状 | +|---|------|------|------|---------| +| 1 | GET | `/admin/product/service-standard-template/page` | 分页（名称模糊 + 状态过滤）| ❌ 未调用 | +| 2 | GET | `/admin/product/service-standard-template/{id}` | 详情（含分组+条目）| ✅ 已有 `getServiceStandardTemplateDetail` | +| 3 | GET | `/admin/product/service-standard-template/enabled` | 启用模板下拉（产品绑定用）| ✅ 已有 `getServiceStandardTemplateEnabled` | +| 4 | POST | `/admin/product/service-standard-template` | 保存（id 空=新增 / 非空=修改）| ❌ 未调用 | +| 5 | DELETE | `/admin/product/service-standard-template/{id}` | 软删（已绑定产品不受影响）| ❌ 未调用 | + +> 管理页主要需补 **#1 分页、#4 保存、#5 删除** 三个调用（#2/#3 已存在可复用）。 + +--- + +## 3. 接口详情 + +### 3.1 分页查询 + +**GET** `/admin/product/service-standard-template/page` + +- **认证**：管理后台 JWT | **幂等**：是 + +**Query 入参**（`ServiceStandardTemplatePageReqVO`，继承分页参数）： + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `page` | int | ❌ | 页码，默认 1 | +| `pageSize` | int | ❌ | 每页条数，默认 20 | +| `name` | string | ❌ | 模板名称模糊匹配 | +| `status` | string | ❌ | 状态过滤（ENABLED / DISABLED，留空=不过滤）| + +**出参**：`Result>`，`records[]` 为完整模板 VO（结构见 §3.2）。 + +### 3.2 详情 + +**GET** `/admin/product/service-standard-template/{id}` + +**出参**：`Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `id` | Long | 模板 ID | +| `name` | string | 模板名称 | +| `intro` | string | 顶部提示语 | +| `applicableScope` | string | 适用对象 | +| `sections[]` | array | 分组列表（见下）| +| `isDefault` | boolean | 是否默认模板 | +| `sortOrder` | int | 排序（越小越靠前）| +| `status` | string | ENABLED / DISABLED | +| `statusLabel` | string | 状态中文（启用 / 停用）| +| `createTime` / `updateTime` | datetime | 时间 | + +**`sections[]` 单项**： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `title` | string | 分组标题（如"出行服务"）| +| `items[]` | array | 条目列表（见下）| + +**`items[]` 单项（6 字段）**： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `title` | string | 主文案（如"接送站服务"）| +| `content` | string | 正文 | +| `remark` | string | 备注 / 灰色二级说明 | +| `color` | string | 文案颜色 #RRGGBB（可空）| +| `contactName` | string | 联系人（可空）| +| `phone` | string | 手机号（可空）| + +### 3.3 启用模板下拉 + +**GET** `/admin/product/service-standard-template/enabled`（不分页） + +**出参**：`Result>`，仅 `{id, name}`，仅返回 ENABLED。供产品 Step5 绑定服务标准时选择（前端已用）。 + +### 3.4 保存（新增 / 修改） + +**POST** `/admin/product/service-standard-template` + +- **认证**：管理后台 JWT | **幂等**：是（@Idempotent 5s） + +**Body 入参**（`ServiceStandardTemplateSaveReqVO`）： + +| 字段 | 类型 | 必填 | 校验 | 说明 | +|---|---|---|---|---| +| `id` | Long | ❌ | — | 空=新增 / 非空=修改 | +| `name` | string | ✅ | @NotBlank | 模板名称 | +| `intro` | string | ❌ | — | 顶部提示语 | +| `applicableScope` | string | ❌ | — | 适用对象 | +| `sections` | array | ✅ | @NotNull | 分组+条目（见下）| +| `isDefault` | boolean | ❌ | — | 是否默认模板 | +| `sortOrder` | int | ❌ | — | 排序 | +| `status` | string | ❌ | — | ENABLED / DISABLED，留空默认 ENABLED | + +**`sections[]` 单项**：`title`（✅ @NotBlank 分组标题）+ `items[]` + +**`items[]` 单项**： + +| 字段 | 类型 | 必填 | 校验 | 说明 | +|---|---|---|---|---| +| `title` | string | ✅ | @NotBlank，≤200 | 主文案 | +| `content` | string | ❌ | ≤2000 | 正文 | +| `remark` | string | ❌ | ≤2000 | 备注 | +| `color` | string | ❌ | #RRGGBB | 文案颜色 | +| `contactName` | string | ❌ | ≤100 | 联系人 | +| `phone` | string | ❌ | — | 手机号 | + +**出参**：`Result`（data = 模板 ID） + +```bash +curl -X POST "https://api.test.1814.love:9443/admin/product/service-standard-template" \ + -H "Authorization: Bearer {adminToken}" -H "Content-Type: application/json" \ + -d '{"name":"草原出团服务说明书","intro":"出团前请仔细阅读","sections":[{"title":"出行服务","items":[{"title":"接送站服务","content":"提供机场/车站免费接送","contactName":"李经理","phone":"13800000000"}]}],"status":"ENABLED"}' +# 返回: {"code":200,"data":1001,"message":"成功"} +``` + +### 3.5 删除 + +**DELETE** `/admin/product/service-standard-template/{id}` → `Result`，软删，已绑定产品不受影响。 + +--- + +## 4. 前端动作（mmg） + +1. **新建管理页**：参照「装备建议组合」(`views/product/equipment-template/index.vue` + `EditModal.vue`)，建服务标准模板列表页 + 新增/编辑弹窗，编辑弹窗支持「分组 → 条目」两层动态增删（条目 6 字段：主文案/正文/备注/颜色/联系人/电话）。 +2. **补 API 调用**：在 `api/product/service-standard.js` 增 `page` / `save` / `delete`（`enabled` / `detail` 已有）。 +3. **加菜单**：在「系统管理 → 菜单管理」加菜单，父级=「行程管理」，路由/组件 `/product/service-standard-template`（与装备建议组合 `/product/equipment-template` 并列）。 +4. 测试库已有 1 条模板数据可直接联调列表/详情。 + +--- + +## 5. 关联 / 联系人 + +- **后端管理接口**：`AdminServiceStandardTemplateController` @ `/admin/product/service-standard-template`（已部署测试服，`/page` 实测 code:200） +- **相关 changelog**：`28_3147_产品服务标准模块...`、`29_服务标准_模板改表结构6字段...`、`03_服务标准模板与产品关联说明` +- **后端负责人**：@wx +- **前端对接（管理后台）**：mmg