# Spec: Enterprise Device Authorization

## Overview

企业设备授权功能允许运营人员将设备授权给企业客户使用,并支持查看授权设备列表和撤销授权操作。

## ADDED Requirements

### Requirement: System SHALL define enterprise device types

系统必须提供完整的企业设备授权相关类型定义,确保类型安全。

#### Scenario: 定义企业设备列表项类型

**Given** 需要展示企业设备列表 **When** 定义 `EnterpriseDeviceItem` 接口 **Then** 接口必须包含以下字段:

- `device_id: number` - 设备ID
- `device_no: string` - 设备号
- `device_name: string` - 设备名称
- `device_model: string` - 设备型号
- `card_count: number` - 绑定卡数量
- `authorized_at: string` - 授权时间

#### Scenario: 定义设备列表查询参数

**Given** 需要查询和搜索企业设备 **When** 定义 `EnterpriseDeviceListParams` 接口 **Then** 接口必须包含以下可选字段:

- `page?: number` - 页码
- `page_size?: number` - 每页数量
- `device_no?: string` - 设备号模糊搜索

#### Scenario: 定义授权设备请求类型

**Given** 需要授权设备给企业 **When** 定义 `AllocateDevicesRequest` 接口 **Then** 接口必须包含:

- `device_nos: string[]` - 设备号列表 (nullable, 最多100个)
- `remark?: string` - 授权备注

#### Scenario: 定义授权设备响应类型

**Given** 授权操作需要返回详细结果 **When** 定义 `AllocateDevicesResponse` 接口 **Then** 接口必须包含:

- `success_count: number` - 成功数量
- `fail_count: number` - 失败数量
- `authorized_devices: AuthorizedDeviceItem[]` - 已授权设备列表 (nullable)
- `failed_items: FailedDeviceItem[]` - 失败项列表 (nullable)

**And** `AuthorizedDeviceItem` 包含:

- `device_id: number` - 设备ID
- `device_no: string` - 设备号
- `card_count: number` - 绑定卡数量

**And** `FailedDeviceItem` 包含:

- `device_no: string` - 设备号
- `reason: string` - 失败原因

#### Scenario: 定义撤销授权请求类型

**Given** 需要撤销设备授权 **When** 定义 `RecallDevicesRequest` 接口 **Then** 接口必须包含:

- `device_nos: string[]` - 设备号列表 (nullable, 最多100个)

#### Scenario: 定义撤销授权响应类型

**Given** 撤销操作需要返回结果统计 **When** 定义 `RecallDevicesResponse` 接口 **Then** 接口必须包含:

- `success_count: number` - 成功数量
- `fail_count: number` - 失败数量
- `failed_items: FailedDeviceItem[]` - 失败项列表 (nullable)

---

### Requirement: System SHALL provide enterprise device authorization API services

系统必须提供企业设备授权相关的 API 服务方法。

#### Scenario: 授权设备给企业

**Given** 运营人员需要授权设备给企业客户 **When** 调用 `EnterpriseService.allocateDevices(enterpriseId, data)` **Then** 必须发送 POST 请求到 `/api/admin/enterprises/{id}/allocate-devices` **And** 请求体必须包含设备号列表和可选备注 **And** 返回授权结果,包含成功/失败统计和详细列表

#### Scenario: 获取企业设备列表

**Given** 需要查看企业的设备列表 **When** 调用 `EnterpriseService.getEnterpriseDevices(enterpriseId, params)` **Then** 必须发送 GET 请求到 `/api/admin/enterprises/{id}/devices` **And** 支持分页参数 (page, page_size) **And** 支持设备号模糊搜索 **And** 返回设备列表和总数

#### Scenario: 撤销设备授权

**Given** 需要撤销企业的设备授权 **When** 调用 `EnterpriseService.recallDevices(enterpriseId, data)` **Then** 必须发送 POST 请求到 `/api/admin/enterprises/{id}/recall-devices` **And** 请求体必须包含设备号列表 **And** 返回撤销结果,包含成功/失败统计和失败原因

---

### Requirement: System SHALL provide enterprise device list page

系统必须提供企业设备列表管理页面,支持查询、授权和撤销操作。

#### Scenario: 显示企业设备列表

**Given** 用户访问企业设备列表页面 **When** 页面加载完成 **Then** 必须显示设备列表表格 **And** 表格必须包含以下列:

- 设备ID
- 设备号
- 设备名称
- 设备型号
- 绑定卡数量
- 授权时间

**And** 必须支持分页功能 **And** 必须显示加载状态

#### Scenario: 搜索企业设备

**Given** 设备列表已加载 **When** 用户在搜索框输入设备号 **And** 点击搜索按钮 **Then** 必须根据设备号模糊查询设备 **And** 必须更新设备列表显示 **And** 必须重置到第一页

#### Scenario: 授权设备对话框

**Given** 用户点击"授权设备"按钮 **When** 授权设备对话框打开 **Then** 必须显示设备号输入框 (textarea) **And** 必须显示备注输入框 (可选) **And** 必须提示支持的输入格式 (换行或逗号分隔) **And** 必须提示最多100个设备号限制 **And** 必须有表单验证 (设备号必填)

#### Scenario: 提交授权设备

**Given** 用户在对话框中输入了设备号列表 **When** 用户点击提交按钮 **Then** 必须解析设备号列表 (支持换行和逗号分隔) **And** 必须去除空白字符和空行 **And** 必须验证设备号数量不超过100个 **And** 必须调用授权 API **And** 必须显示加载状态 **And** 授权完成后必须展示结果:

- 成功数量
- 失败数量
- 失败设备列表及原因

**And** 如果有成功授权的设备,必须刷新设备列表 **And** 必须关闭对话框

#### Scenario: 撤销设备授权

**Given** 用户选中了要撤销的设备 **When** 用户点击"撤销授权"按钮 **Then** 必须显示二次确认对话框 **And** 确认对话框必须显示将要撤销的设备数量

**When** 用户确认撤销 **Then** 必须调用撤销 API **And** 必须显示加载状态 **And** 撤销完成后必须展示结果:

- 成功数量
- 失败数量
- 失败设备列表及原因

**And** 如果有成功撤销的设备,必须刷新设备列表

#### Scenario: 错误处理

**Given** API 调用可能失败 **When** API 返回错误 **Then** 必须显示友好的错误提示消息 **And** 必须在控制台记录错误详情 **And** 必须停止加载状态

#### Scenario: 分页切换

**Given** 设备列表超过一页 **When** 用户切换页码或每页数量 **Then** 必须保持当前的搜索条件 **And** 必须重新加载设备列表 **And** 必须显示加载状态

---

### Requirement: System SHALL configure routing for enterprise device list

系统必须为企业设备列表配置正确的路由。

#### Scenario: 注册企业设备列表路由

**Given** 需要访问企业设备列表页面 **When** 配置路由 **Then** 必须在资产管理模块 (`/asset-management`) 下添加子路由 **And** 路由路径必须为 `enterprise-devices` **And** 路由名称必须为 `EnterpriseDevices` **And** 必须使用路由别名 `RoutesAlias.EnterpriseDevices` **And** 必须配置 meta 信息:

- `title: 'menus.assetManagement.enterpriseDevices'`
- `keepAlive: true`

---

### Requirement: System SHALL provide internationalization support

系统必须提供中英文翻译支持。

#### Scenario: 中文翻译

**Given** 系统语言设置为中文 **When** 访问企业设备相关页面 **Then** 所有文本必须显示中文,包括:

- 菜单标题: "企业设备列表"
- 搜索表单标签和占位符
- 表格列名
- 按钮文本
- 对话框标题和内容
- 提示消息

#### Scenario: 英文翻译

**Given** 系统语言设置为英文 **When** 访问企业设备相关页面 **Then** 所有文本必须显示英文,包括:

- 菜单标题: "Enterprise Devices"
- 搜索表单标签和占位符
- 表格列名
- 按钮文本
- 对话框标题和内容
- 提示消息

---

### Requirement: System SHALL optimize user experience

系统必须提供良好的用户体验。

#### Scenario: 批量输入设备号

**Given** 用户需要授权多个设备 **When** 在设备号输入框中输入 **Then** 必须支持以下输入方式:

- 每行一个设备号
- 逗号分隔的设备号
- 混合使用换行和逗号

**And** 系统必须能正确解析所有格式 **And** 必须自动去除首尾空白字符 **And** 必须过滤空行

#### Scenario: 操作结果展示

**Given** 批量操作完成 **When** 显示操作结果 **Then** 必须清晰展示:

- 总共处理的数量
- 成功的数量
- 失败的数量
- 每个失败项的设备号和失败原因

**And** 如果全部成功,必须显示成功提示 **And** 如果部分失败,必须显示警告提示 **And** 如果全部失败,必须显示错误提示

#### Scenario: 表格列管理

**Given** 设备列表表格已显示 **When** 用户点击列管理按钮 **Then** 必须能够选择显示/隐藏的列 **And** 列配置必须被保存

## Related Specs

- 参考现有的企业卡授权功能 (enterpriseCard.ts)
- 依赖现有的企业客户管理功能 (enterprise.ts)
- 关联设备管理模块 (add-device-management)
