# 资源状态切换：非超管需走审批流程

**日期**: 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. **所有资源模块统一逻辑**：景区、酒店、餐厅、活动等全部适用，前端可封装通用组件