docs: 资源状态切换非超管需走审批接口

前端 toggle 开关对非 SUPER_ADMIN 用户应调用 submit-approval 审批接口，而非直接调用 status 接口。后端接口已就绪，前端需适配角色判断逻辑。 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 12:13:29 +08:00 · 2026-03-25 12:13:29 +08:00 · 6abc134a63
--- a/changelogs/2026-03/25_1212_resource_status_approval.md
+++ 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. **所有资源模块统一逻辑**：景区、酒店、餐厅、活动等全部适用，前端可封装通用组件