fetch(add): 订单管理-企业设备

openspec/changes/add-enterprise-device-authorization/specs/enterprise-device-authorization/spec.md

@@ -0,0 +1,291 @@
+# 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)