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

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)