diff --git a/changelogs/2026-03/25_1212_resource_status_approval.md b/changelogs/2026-03/25_1212_resource_status_approval.md new file mode 100644 index 0000000..f6d82e0 --- /dev/null +++ b/changelogs/2026-03/25_1212_resource_status_approval.md @@ -0,0 +1,124 @@ +# 资源状态切换:非超管需走审批流程 + +**日期**: 2026-03-25 +**服务**: hl-resource-service +**影响范围**: 所有资源模块(景区、酒店、餐厅、活动、车辆、物资、费用项、服务项、人员)的状态切换开关 + +--- + +## 背景说明 + +当前前端资源列表页的状态 toggle 开关,直接调用了 `PUT /{resource}/{id}/status` 接口。该接口仅限 SUPER_ADMIN 使用,非超管用户操作时会报错 **"仅超级管理员可直接修改状态"**。 + +**后端已有完整的审批接口**,前端需根据用户角色分别调用不同接口: + +| 用户角色 | 行为 | 调用接口 | +|---------|------|---------| +| SUPER_ADMIN | 直接生效 | `PUT /{resource}/{id}/status` | +| 其他角色 | 提交审批 | `POST /{resource}/{id}/submit-approval` | + +--- + +## 各资源审批接口清单 + +| # | 资源 | 审批接口路径 | 方法 | +|---|------|-------------|------| +| 1 | 景区 | `/admin/scenic/spot/{scenicId}/submit-approval` | POST | +| 2 | 酒店 | `/admin/hotel/item/{hotelId}/submit-approval` | POST | +| 3 | 房型 | `/admin/hotel/room-type/{roomTypeId}/submit-approval` | POST | +| 4 | 餐厅 | `/admin/restaurant/item/{restaurantId}/submit-approval` | POST | +| 5 | 活动 | `/admin/activity/item/{activityId}/submit-approval` | POST | +| 6 | 车辆 | `/admin/vehicle/model/{vehicleId}/submit-approval` | POST | +| 7 | 物资 | `/admin/supplies/item/{suppliesId}/submit-approval` | POST | +| 8 | 费用项 | `/admin/cost/item/{costId}/submit-approval` | POST | +| 9 | 服务项 | `/admin/service/item/{serviceId}/submit-approval` | POST | +| 10 | 人员 | `/admin/staff/{staffId}/submit-approval` | POST | + +--- + +## 审批接口详细定义 + +### 使用场景 + +非超管用户在资源列表页点击状态 toggle 时,弹出确认框让用户填写审批理由,然后调用此接口提交企微OA审批。审批通过后状态自动变更。 + +### 请求参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| targetStatus | Integer | 是 | 目标状态:`0`=下架,`1`=上架 | +| reason | String | 是 | 审批理由,不能为空 | + +### 请求示例 + +```json +POST /admin/scenic/spot/123456/submit-approval + +{ + "targetStatus": 1, + "reason": "内容审核完毕,申请上架" +} +``` + +### 响应示例 + +**成功(200)**: +```json +{ + "code": 200, + "message": "success", + "data": { + "spNo": "202603250001" + } +} +``` + +**失败 - 已有审批进行中**: +```json +{ + "code": 400, + "message": "该资源已有审批进行中,请等待审批结果" +} +``` + +--- + +## 前端实现建议 + +``` +状态 Toggle 开关被点击 + │ + ├─ 当前角色 = SUPER_ADMIN ? + │ ├─ 是 → 直接调 PUT /{resource}/{id}/status(现有逻辑不变) + │ └─ 否 ↓ + │ + ├─ 弹出确认框 + │ ┌──────────────────────────────┐ + │ │ 申请 [上架/下架] │ + │ │ │ + │ │ 审批理由: │ + │ │ ┌──────────────────────┐ │ + │ │ │ (textarea) │ │ + │ │ └──────────────────────┘ │ + │ │ │ + │ │ [取消] [提交审批] │ + │ └──────────────────────────────┘ + │ + └─ 调 POST /{resource}/{id}/submit-approval + │ + ├─ 成功 → 提示 "审批已提交,请等待审批结果" + │ toggle 恢复原状态(审批未通过前不变) + └─ 失败 → 提示错误信息,toggle 恢复原状态 +``` + +### 角色判断 + +用户角色已存储在登录 token 中(`X-Admin-Role` header),前端可从本地存储中获取 `role` 字段判断是否为 `SUPER_ADMIN`。 + +--- + +## 注意事项 + +1. **审批期间 toggle 状态不变**:提交审批后资源进入 `PENDING_APPROVAL` 状态,但显示状态不变,等审批通过后自动切换 +2. **不可重复提交**:同一资源有未完成的审批时,再次提交会返回 400 错误 +3. **所有资源模块统一逻辑**:景区、酒店、餐厅、活动等全部适用,前端可封装通用组件