# asset-suspend-resume Specification

## Purpose

提供统一的资产停复机接口，包括设备级批量停复机和单卡停复机，含保护期感知逻辑。废弃原分散在各模块的旧停复机接口，统一使用 `/api/admin/assets/` 路径。

## Requirements

### Requirement: 设备停机接口

系统 SHALL 提供设备停机接口，批量停用设备下所有已实名卡，并建立停机保护期。

**API 端点**: `POST /api/admin/assets/device/:device_id/stop`

**执行流程**:
1. 验证设备存在（不存在返回 HTTP 404）
2. 检查设备是否在保护期（`RedisDeviceProtectKey(deviceID, "stop")` 或 `"start"` 存在则返回 HTTP 403）
3. 获取该设备所有已实名（`real_name_status = 1`）的绑定卡
4. 遍历调用网关停机接口（未实名卡跳过，永远是停机状态）
5. 更新成功停机的卡的 `network_status = 0`，`stopped_at = now()`，`stop_reason = "manual"`
6. 在 Redis 中设置停机保护期：`RedisDeviceProtectKey(deviceID, "stop")`，TTL = 1 小时
7. 响应：返回成功，附带失败卡列表（如有）

**保护期说明**:
- 保护期时长：1 小时（常量 `DeviceProtectPeriodDuration = 1 * time.Hour`，定义在 `pkg/constants/`）
- 停机保护期 key：`protect:device:{device_id}:stop`
- 复机保护期 key：`protect:device:{device_id}:start`
- 两个 key 互斥：设置 stop 保护期时删除 start 保护期，反之亦然

**批量部分失败策略**:
- 部分卡调网关失败：**仍设置** Redis 保护期（保护期从发起操作时算起）
- 已成功停机的卡**不回滚**
- 失败的卡记录 Error 日志，响应体中携带失败列表

#### Scenario: 成功执行设备停机

- **WHEN** 管理员调用 `POST /api/admin/assets/device/456/stop`，该设备有 3 张已实名卡
- **THEN** 系统批量调网关停机，更新 3 张卡 network_status=0，设置 1 小时 stop 保护期，返回成功

#### Scenario: 设备存在保护期

- **WHEN** 管理员在设备已有 stop 保护期时再次调用停机接口
- **THEN** 系统返回 HTTP 403，提示"设备处于保护期，不允许操作"

#### Scenario: 设备下无已实名卡

- **WHEN** 管理员对只有未实名卡的设备执行停机
- **THEN** 系统返回成功（0 张卡操作），设置 stop 保护期

#### Scenario: 设备不存在

- **WHEN** 管理员调用不存在的设备 ID
- **THEN** 系统返回 HTTP 404

#### Scenario: 部分卡停机失败

- **WHEN** 设备有 3 张卡，1 张网关调用失败
- **THEN** 2 张成功停机，1 张失败记录日志，**仍设置** stop 保护期，响应中包含失败卡信息

---

### Requirement: 设备复机接口

系统 SHALL 提供设备复机接口，批量恢复设备下所有已实名卡，并建立复机保护期。

**API 端点**: `POST /api/admin/assets/device/:device_id/start`

**执行流程**:
1. 验证设备存在（不存在返回 HTTP 404）
2. 检查设备是否在保护期（stop 或 start 保护期均存在时返回 HTTP 403）
3. 获取该设备所有已实名（`real_name_status = 1`）的绑定卡
4. 遍历调用网关复机接口
5. 更新成功复机的卡的 `network_status = 1`，`resumed_at = now()`
6. 设置复机保护期：`RedisDeviceProtectKey(deviceID, "start")`，TTL = 1 小时
7. 响应：返回成功

#### Scenario: 成功执行设备复机

- **WHEN** 管理员调用 `POST /api/admin/assets/device/456/start`，该设备有 2 张已实名卡
- **THEN** 系统批量复机，更新卡状态，设置 1 小时 start 保护期，返回成功

#### Scenario: 设备在 start 保护期内再次复机

- **WHEN** 设备已有 start 保护期时再次调用复机接口
- **THEN** 系统返回 HTTP 403，提示"设备处于保护期，不允许操作"

---

### Requirement: 卡停机接口

系统 SHALL 提供单卡停机接口，含保护期感知逻辑。

**API 端点**: `POST /api/admin/assets/card/:iccid/stop`

**执行流程**:
1. 通过 ICCID 查找卡（不存在返回 HTTP 404）
2. 检查卡是否已实名（`real_name_status = 0` 时返回 HTTP 403：未实名卡不允许停复机）
3. 若卡绑定了设备，检查该设备的保护期：
   - 设备有 **stop 保护期**：允许停机（本已是停机方向，无冲突）
   - 设备有 **start 保护期**：允许停机（用户可主动停单张卡）
   - 设备无保护期：正常执行
4. 调用网关停机接口
5. 更新卡 `network_status = 0`，`stopped_at = now()`，`stop_reason = "manual"`

#### Scenario: 独立卡（未绑定设备）停机

- **WHEN** 管理员对一张未绑定设备的已实名卡执行停机
- **THEN** 系统正常调网关停机，更新卡状态

#### Scenario: 绑定设备且设备在 start 保护期内停机

- **WHEN** 管理员对绑定了设备且设备有 start 保护期的卡执行停机
- **THEN** 系统允许执行（用户主动停单张卡不违反 start 保护期），正常停机

#### Scenario: 对未实名卡执行停机

- **WHEN** 管理员对 real_name_status=0（未实名）的卡执行停机
- **THEN** 系统返回 HTTP 403，提示"未实名卡不允许停复机操作"

---

### Requirement: 卡复机接口

系统 SHALL 提供单卡复机接口，含保护期感知逻辑。

**API 端点**: `POST /api/admin/assets/card/:iccid/start`

**执行流程**:
1. 通过 ICCID 查找卡（不存在返回 HTTP 404）
2. 检查卡是否已实名（`real_name_status = 0` 时返回 HTTP 403）
3. 若卡绑定了设备，检查该设备的保护期：
   - 设备有 **stop 保护期**：**不允许**手动复机，返回 HTTP 403（设备处于停机保护期）
   - 设备有 **start 保护期**：允许复机（本已是复机方向，无冲突）
   - 设备无保护期：正常执行
4. 调用网关复机接口
5. 更新卡 `network_status = 1`，`resumed_at = now()`，清空 `stop_reason`

#### Scenario: 独立卡（未绑定设备）复机

- **WHEN** 管理员对一张未绑定设备的已实名停机卡执行复机
- **THEN** 系统正常调网关复机，更新卡状态

#### Scenario: 设备处于 stop 保护期时尝试复机

- **WHEN** 管理员对绑定了设备且设备有 stop 保护期的卡执行复机
- **THEN** 系统返回 HTTP 403，提示"设备处于停机保护期，不允许手动复机"

#### Scenario: 设备在 start 保护期内复机

- **WHEN** 管理员对绑定了设备且设备有 start 保护期的卡执行复机
- **THEN** 系统允许执行（本已是复机方向），正常复机

#### Scenario: 对未实名卡执行复机

- **WHEN** 管理员对 real_name_status=0 的卡执行复机
- **THEN** 系统返回 HTTP 403，提示"未实名卡不允许停复机操作"

---

### Requirement: 废弃旧停复机接口

系统 SHALL 删除以下重复的停复机接口，统一使用新的 `/api/admin/assets/` 路径。

**待删除接口**:
- `POST /api/admin/enterprises/:id/cards/:card_id/suspend`
- `POST /api/admin/enterprises/:id/cards/:card_id/resume`
- `POST /h5/devices/:device_id/cards/:card_id/suspend`
- `POST /h5/devices/:device_id/cards/:card_id/resume`
- 旧 Admin 卡停复机接口（`POST /iot-cards/:iccid/suspend|resume`）

#### Scenario: 调用已删除的旧接口

- **WHEN** 前端调用 `POST /api/admin/enterprises/:id/cards/:card_id/suspend`
- **THEN** 系统返回 HTTP 404（路由已不存在）