From 4cdf3606e9ab2b51fac0fce53828df8b69976454 Mon Sep 17 00:00:00 2001 From: lc Date: Fri, 18 Sep 2026 10:16:09 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7737=20=E9=A4=90=E9=A3=9F?= =?UTF-8?q?=E7=AE=A1=E7=90=86=E6=8E=A5=E5=8F=A3=201.1=E2=80=931.7=20?= =?UTF-8?q?=E4=B8=8E=E8=8F=9C=E5=8D=95=EF=BC=88=E6=96=B0=E5=A2=9E=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- .../18_7737_餐食管理接口-新增接口-管理后台.md | 580 ++++++++++++++++++ 1 file changed, 580 insertions(+) create mode 100644 changelogs-v2/2026-09/18_7737_餐食管理接口-新增接口-管理后台.md diff --git a/changelogs-v2/2026-09/18_7737_餐食管理接口-新增接口-管理后台.md b/changelogs-v2/2026-09/18_7737_餐食管理接口-新增接口-管理后台.md new file mode 100644 index 00000000..ab646e04 --- /dev/null +++ b/changelogs-v2/2026-09/18_7737_餐食管理接口-新增接口-管理后台.md @@ -0,0 +1,580 @@ +--- +schema: "hl-changelog/v2" +ticket: "7737" +title: "餐食管理接口（分页、下拉、详情、新建、修改、上下架、删除）" +consumer: "admin" +author: "lc(GIT)" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-18" +status_note: "新增 7 个接口与「资源管理 → 餐食管理」菜单（component 为 /resource/dish）。前端需新做餐食管理页面并按本文契约对接。" +updated_at: "2026-09-18" +base: "dev-v3" +--- + +# resource/user/gateway: 餐食管理接口 + +**服务**: hl-resource-service（接口）、hl-user-service（菜单）、hl-gateway（路由） +**PR**: #7918 +**Issue**: #7737 + +--- + +## ⚠️ 关键变化 + +🔴 **新增 7 个接口，路径前缀 `/admin/dish/items`。** 餐食不关联餐厅；下拉（1.2）只返回上架餐食，不按餐厅过滤。 + +🔴 **新增菜单「资源管理 → 餐食管理」**：menu_id `422`，path `/dish/list`，component `/resource/dish`，与「餐厅管理」同级同排序；已授权超级管理员、管理员、定制师。前端需按该 component 路径提供页面。 + +🔴 **新建不传 `settleType` 时存 `cash`（现付）；修改是整份覆盖，`imageUrl` / `settleType` / `remark` 传 `null` 即清空。** + +--- + +## 一、背景 + +新增「餐食管理」：维护餐食（编码、名称、单价、图片、结算方式、上下架），供订单「用餐」选用。系统不预置任何餐食。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 分页查询餐食 | GET | `/admin/dish/items/page` | 新增 | 餐食管理列表 | +| 2 | 查询餐食列表 | GET | `/admin/dish/items/list` | 新增 | 下拉用，只返回上架 | +| 3 | 查询餐食详情 | GET | `/admin/dish/items/{dishId}/view` | 新增 | 编辑回显 | +| 4 | 新建餐食 | POST | `/admin/dish/items/add` | 新增 | 默认上架、默认现付 | +| 5 | 修改餐食 | PUT | `/admin/dish/items/{dishId}/update` | 新增 | 整份覆盖 | +| 6 | 上架 / 下架餐食 | PUT | `/admin/dish/items/{dishId}/status/update` | 新增 | 不走审批，立即生效 | +| 7 | 删除餐食 | DELETE | `/admin/dish/items/{dishId}/del` | 新增 | 软删除，不检查是否在用 | + +--- + +## 三、接口详情 + +### 1. 分页查询餐食 `GET /admin/dish/items/page` + +**VO**: `DishPageReqVO` → `PageResult` + +#### 使用场景 + +餐食管理列表分页查询。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| keyword | Query | String | 否 | 去首尾空格后 ≤64 | 包含式模糊匹配编码、名称；`%`、`_` 按字面量匹配 | +| dishCode | Query | String | 否 | 去首尾空格后 ≤20 | 编码精确匹配 | +| status | Query | Integer | 否 | 0 / 1 | 0=下架，1=上架；不传查全部 | +| settleType | Query | String | 否 | cash / sign / company | 结算方式；不传查全部 | +| createdByName | Query | String | 否 | — | 创建人姓名包含式匹配；去首尾空格后为空按不传 | +| page | Query | Integer | 否 | ≥1，默认 1 | 页码 | +| pageSize | Query | Integer | 否 | 1–100，默认 20 | 每页条数 | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| records[].dishId | String | 餐食 ID（雪花，字符串） | +| records[].dishCode | String | 编码 | +| records[].dishName | String | 餐食名称 | +| records[].unitPrice | Number | 单价（每人每餐，元，两位小数） | +| records[].imageUrl | String | 图片 URL，可为 null | +| records[].settleType | String | 结算方式，字典 `resource_settle_type`：cash / sign / company，可为 null | +| records[].status | Integer | 0=下架，1=上架 | +| records[].remark | String | 备注，可为 null | +| records[].createdBy | String | 创建人 ID | +| records[].createdByName | String | 创建人姓名（企微姓名优先，没有取管理员用户名）；查不到为 null | +| records[].createdAt | String | 创建时间 `yyyy-MM-dd HH:mm:ss` | +| total / page / pageSize | Integer | 总条数、当前页、每页条数 | + +#### 请求示例 + +```http +GET /admin/dish/items/page?keyword=三百&status=1&page=1&pageSize=20 +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "dishId": "2100767707048636418", + "dishCode": "STANDARD_300", + "dishName": "标准三百快", + "unitPrice": 30.00, + "imageUrl": null, + "settleType": "sign", + "status": 1, + "remark": null, + "createdBy": "1900000000000000001", + "createdByName": "张三", + "createdAt": "2026-09-18 10:02:11" + } + ], + "total": 1, + "page": 1, + "pageSize": 20 + } +} +``` + +#### 空数据 / 降级响应 + +无数据时 `records` 为 `[]`、`total` 为 0。创建人姓名查询失败时 `createdByName` 为 null，列表照常返回；按创建人姓名筛选而无匹配时返回空页。 + +#### 错误响应 + +```json +{ "code": 400, "message": "每页条数最大为100", "success": false, "data": null } +``` + +#### 业务边界 + +- 只查未删除餐食，各条件之间是「并且」。 +- 按更新时间倒序、餐食 ID 倒序。 + +--- + +### 2. 查询餐食列表 `GET /admin/dish/items/list` + +**VO**: `DishListReqVO` → `List` + +#### 使用场景 + +下拉数据源：订单「用餐」的餐食选择、保存模版时选餐食。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| keyword | Query | String | 否 | 去首尾空格后 ≤64 | 模糊匹配编码、名称 | +| settleType | Query | String | 否 | cash / sign / company | 结算方式 | +| limit | Query | Integer | 否 | 1–200，默认 50 | 最大返回条数 | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| [] | Array | 每项字段同接口 1 的 `records[]`，`status` 恒为 1 | + +#### 请求示例 + +```http +GET /admin/dish/items/list?limit=50 +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "dishId": "2100767707048636418", + "dishCode": "STANDARD_300", + "dishName": "标准三百快", + "unitPrice": 30.00, + "imageUrl": null, + "settleType": "sign", + "status": 1, + "remark": null, + "createdBy": "1900000000000000001", + "createdByName": "张三", + "createdAt": "2026-09-18 10:02:11" + } + ] +} +``` + +#### 空数据 / 降级响应 + +没有上架餐食时 `data` 为 `[]`。 + +#### 错误响应 + +```json +{ "code": 400, "message": "limit最大为200", "success": false, "data": null } +``` + +#### 业务边界 + +- 只返回未删除且上架的餐食；下架后立即查不到，重新上架后恢复。 +- 不按餐厅过滤；按创建时间升序、餐食 ID 升序。 + +--- + +### 3. 查询餐食详情 `GET /admin/dish/items/{dishId}/view` + +**VO**: `DishRespVO` + +#### 使用场景 + +编辑回显。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| dishId | Path | String | 是 | 正数 | 餐食 ID | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| （同接口 1 的 records[]） | — | 字段完全一致 | + +#### 请求示例 + +```http +GET /admin/dish/items/2100767707048636418/view +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "dishId": "2100767707048636418", + "dishCode": "STANDARD_300", + "dishName": "标准三百快", + "unitPrice": 30.00, + "imageUrl": null, + "settleType": "cash", + "status": 1, + "remark": null, + "createdBy": "1900000000000000001", + "createdByName": "张三", + "createdAt": "2026-09-18 10:02:11" + } +} +``` + +#### 空数据 / 降级响应 + +无空数据分支：餐食不存在或已删除返回 340001。 + +#### 错误响应 + +```json +{ "code": 340001, "message": "餐食不存在", "success": false, "data": null } +``` + +#### 业务边界 + +- `dishId` 非正数或非数字返回 400。 + +--- + +### 4. 新建餐食 `POST /admin/dish/items/add` + +**VO**: `DishCreateReqVO` → `DishWriteRespVO` + +#### 使用场景 + +新建餐食；新建默认上架，不走审批。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| dishCode | Body | String | 是 | 去首尾空格后 1–20 | 编码，未删除餐食内不能重复 | +| dishName | Body | String | 是 | 去首尾空格后 1–500 | 餐食名称，未删除餐食内不能重复 | +| unitPrice | Body | Number | 是 | 0–99999999.99，最多两位小数 | 单价 | +| imageUrl | Body | String | 否 | ≤65535 | 图片 URL | +| settleType | Body | String | 否 | cash / sign / company | 结算方式；不传存 cash | +| status | Body | Integer | 否 | 0 / 1 | 不传为 1（上架） | +| remark | Body | String | 否 | ≤500 | 备注 | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| dishId | String | 新餐食 ID | +| dishName | String | 餐食名称 | + +#### 请求示例 + +```json +{ + "dishCode": "STANDARD_300", + "dishName": "标准三百快", + "unitPrice": 30.00, + "settleType": "sign" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { "dishId": "2100767707048636418", "dishName": "标准三百快" } +} +``` + +#### 空数据 / 降级响应 + +无降级：要么 200 写入，要么返回错误码且零写入。 + +#### 错误响应 + +```json +{ "code": 340002, "message": "编码已存在：STANDARD_300", "success": false, "data": null } +``` + +```json +{ "code": 340003, "message": "餐食名称已存在：标准三百快", "success": false, "data": null } +``` + +#### 业务边界 + +- 字符串入参先去首尾空格，再校验长度、查重。 +- 编码、名称只在未删除餐食内唯一；删除后同编码、同名称可以重新新建。 + +--- + +### 5. 修改餐食 `PUT /admin/dish/items/{dishId}/update` + +**VO**: `DishUpdateReqVO` → `DishWriteRespVO` + +#### 使用场景 + +修改餐食全部字段（整份覆盖）。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| dishId | Path | String | 是 | 正数 | 餐食 ID | +| dishCode | Body | String | 是 | 去首尾空格后 1–20 | 未删除餐食内不能重复（排除自己） | +| dishName | Body | String | 是 | 去首尾空格后 1–500 | 未删除餐食内不能重复（排除自己） | +| unitPrice | Body | Number | 是 | 0–99999999.99，最多两位小数 | 单价 | +| imageUrl | Body | String | 否 | ≤65535 | 传 null 清空 | +| settleType | Body | String | 否 | cash / sign / company | 传 null 清空 | +| status | Body | Integer | 是 | 0 / 1 | 状态 | +| remark | Body | String | 否 | ≤500 | 传 null 清空 | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| dishId | String | 餐食 ID | +| dishName | String | 修改后的名称 | + +#### 请求示例 + +```json +{ + "dishCode": "STANDARD_300", + "dishName": "标准三百快", + "unitPrice": 32.00, + "imageUrl": null, + "settleType": "company", + "status": 1, + "remark": null +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { "dishId": "2100767707048636418", "dishName": "标准三百快" } +} +``` + +#### 空数据 / 降级响应 + +无降级：要么 200 覆盖写入，要么返回错误码且不改动数据。 + +#### 错误响应 + +```json +{ "code": 340001, "message": "餐食不存在", "success": false, "data": null } +``` + +#### 业务边界 + +- 整份覆盖：未传或传 null 的可选字段会被清空，编辑前先调接口 3 读回全量。 +- 编码重复 340002、名称重复 340003；已生成的订单用餐信息不受修改影响。 + +--- + +### 6. 上架 / 下架餐食 `PUT /admin/dish/items/{dishId}/status/update` + +**VO**: `DishStatusUpdateReqVO` + +#### 使用场景 + +切换上下架，不走审批，立即生效。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| dishId | Path | String | 是 | 正数 | 餐食 ID | +| status | Body | Integer | 是 | 0 / 1 | 0=下架，1=上架 | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据 | + +#### 请求示例 + +```json +{ "status": 0 } +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "success": true, "data": null } +``` + +#### 空数据 / 降级响应 + +状态没变化直接返回成功。 + +#### 错误响应 + +```json +{ "code": 340001, "message": "餐食不存在", "success": false, "data": null } +``` + +#### 业务边界 + +- 下架后接口 2 立即查不到；重新上架后恢复。 + +--- + +### 7. 删除餐食 `DELETE /admin/dish/items/{dishId}/del` + +**VO**: `Result`（无请求体） + +#### 使用场景 + +软删除餐食。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| dishId | Path | String | 是 | 正数 | 餐食 ID | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据 | + +#### 请求示例 + +```http +DELETE /admin/dish/items/2100767707048636418/del +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "success": true, "data": null } +``` + +#### 空数据 / 降级响应 + +无降级：已删除的餐食再删返回 340001。 + +#### 错误响应 + +```json +{ "code": 340001, "message": "餐食不存在", "success": false, "data": null } +``` + +#### 业务边界 + +- 不检查是否被模版或订单用过；删除后同编码、同名称可以重新新建。 + +--- + +## 四、契约约束与正确调用方式 + +- ID 均为字符串，原样透传，不要转成数字。 +- 编辑流程：接口 3 读全量 → 修改 → 接口 5 整份提交；可选字段不传即清空。 +- 结算方式取值见字典 `resource_settle_type`（cash 现付 / sign 签单 / company 公司付款）。 +- 参数校验失败统一返回 `code=400` 与中文提示；业务错误码见各接口。 + +--- + +## 五、数据库行为 + +- 新建、修改、上下架、删除都只写餐食数据；删除为软删除，删除后同编码、同名称可重建。 +- 失败请求（参数校验、重复、不存在）零写入。 +- 写接口记操作日志，模块「餐食管理」。 + +--- + +## 六、边界行为 + +| 场景 | 行为 | +|---|---| +| 新建不传 `settleType` / `status` | 存 `cash`、上架 | +| 编码或名称前后带空格 | 去掉后保存、查重 | +| 编码与未删除餐食重复 | 340002，零写入 | +| 名称与未删除餐食重复 | 340003，零写入 | +| 餐食不存在或已删除（详情/修改/上下架/删除） | 340001 | +| 上下架目标状态与当前相同 | 200，不改数据 | +| 下架后调接口 2 | 查不到；重新上架后恢复 | +| 删除后用同编码、同名称新建 | 200，得到新 ID | + +--- + +## 七、不影响范围 + +- 既有接口、既有错误码不变；餐厅选项接口 `/admin/resource-options/restaurants` 不变。 +- 产品行程天仍用字典 `meal_option`，不接餐食。 + +--- + +## 八、测试环境已验证 + +TEST 已部署 dev-v3 `00e882be4`（hl-resource-service、hl-user-service、hl-gateway），经网关用管理员身份逐项实测：7 个接口的入参边界与出参字段、新建默认现付与上架、340001/340002/340003、下架后下拉不返回与重新上架恢复、删除后同编码同名称重建、「资源管理」下出现「餐食管理」菜单，全部通过。 + +--- + +## 十、相关文档 + +- Issue：https://git.1814.love:8443/wx/HL/issues/7737 +- PR：https://git.1814.love:8443/wx/HL/pulls/7918 + +--- + +## 关联 / 联系人 + +- 后端：@lc