junhong_cmp_fiber/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/tasks.md

1. 数据库迁移

• 1.1 创建 tb_enterprise_device_authorization 表迁移文件

  • 包含所有字段：enterprise_id, device_id, authorized_by, authorized_at, authorizer_type, revoked_by, revoked_at, remark
  • 添加部分唯一索引：UNIQUE (device_id) WHERE revoked_at IS NULL AND deleted_at IS NULL
  • 添加常规索引：idx_eda_enterprise, idx_eda_device, idx_eda_authorized_by

• 1.2 创建 tb_enterprise_card_authorization 表修改迁移文件

  • 新增字段：device_auth_id（BIGINT，可空）
  • 添加索引：idx_eca_device_auth

• 1.3 执行迁移并验证表结构正确

2. Model 层

• 2.1 创建 EnterpriseDeviceAuthorization 模型

  • 文件路径：internal/model/enterprise_device_authorization.go
  • 包含所有字段和 TableName 方法
  • 遵循项目 GORM 模型规范

• 2.2 修改 EnterpriseCardAuthorization 模型

  • 新增 DeviceAuthID 字段（*uint）
  • 添加 GORM 标签：gorm:"column:device_auth_id;comment:关联的设备授权ID"

3. Store 层

• 3.1 创建 EnterpriseDeviceAuthorizationStore

  • 文件路径：internal/store/postgres/enterprise_device_authorization_store.go
  • 实现方法：Create, BatchCreate, GetByID, GetByDeviceID, GetByEnterpriseID
  • 实现方法：ListByEnterprise（分页、筛选）, RevokeByIDs, GetActiveAuthsByDeviceIDs
  • 实现方法：ListDeviceIDsByEnterprise（获取企业授权的设备ID列表）

• 3.2 修改 EnterpriseCardAuthorizationStore

  • 新增方法：RevokeByDeviceAuthID（根据设备授权ID批量回收卡授权）

4. Service 层 - 设备授权服务

• 4.1 创建 enterprise_device 服务

  • 文件路径：internal/service/enterprise_device/service.go
  • 依赖注入：db, enterpriseStore, deviceStore, deviceSimBindingStore, enterpriseDeviceAuthStore, enterpriseCardAuthStore, logger

• 4.2 实现 AllocateDevices 方法（授权设备给企业）

  • 验证企业存在和权限
  • 验证每个设备的权限和状态
  • 检查唯一性约束（设备未授权给其他企业）
  • 在事务内创建设备授权和卡授权记录
  • 返回授权结果

• 4.3 实现 RecallDevices 方法（回收设备授权）

  • 验证授权记录存在
  • 在事务内回收设备授权和关联的卡授权
  • 返回回收结果

• 4.4 实现 ListDevices 方法（后台管理：企业设备列表）

  • 分页查询授权给企业的设备
  • 包含设备信息和绑定卡数量

• 4.5 实现 ListDevicesForEnterprise 方法（H5：企业设备列表）

  • 企业用户查询自己的授权设备
  • 数据权限自动过滤

• 4.6 实现 GetDeviceDetail 方法（H5：设备详情）

  • 查询设备信息和绑定的卡列表
  • 验证企业权限

• 4.7 实现 SuspendCard 和 ResumeCard 方法（H5：停机/复机）

  • 验证设备和卡的授权关系
  • 更新卡的网络状态

5. Service 层 - 修改单卡授权服务

• 5.1 修改 enterprise_card/service.go 的 AllocateCardsPreview 方法

  • 移除 DeviceBundle 处理逻辑
  • 绑定设备的卡直接加入 FailedItems，原因为"该卡已绑定设备，请使用设备授权功能"
  • 移除 DeviceBundles 响应字段

• 5.2 修改 enterprise_card/service.go 的 AllocateCards 方法

  • 移除 DeviceBundle 确认流程（confirm_device_bundles 参数）
  • 移除 AllocatedDevices 响应字段
  • 绑定设备的卡直接拒绝

• 5.3 清理相关 DTO

  • 移除或标记废弃：DeviceBundle, DeviceBundleCard, ConfirmDeviceBundles, AllocatedDevice 相关字段
  • 更新 AllocateCardsReq 和 AllocateCardsResp

6. Handler 层 - 后台管理

• 6.1 创建 admin/enterprise_device.go Handler

  • AllocateDevices：授权设备给企业
  • RecallDevices：回收设备授权
  • ListDevices：企业设备列表

• 6.2 注册后台路由

  • 文件路径：internal/routes/enterprise_device.go
  • POST /api/admin/enterprises/:id/allocate-devices
  • POST /api/admin/enterprises/:id/recall-devices
  • GET /api/admin/enterprises/:id/devices

• 6.3 更新 Bootstrap 注册

  • 在 internal/bootstrap/ 中注册新的 Store、Service、Handler

7. Handler 层 - 企业端 H5

• 7.1 创建 h5/enterprise_device.go Handler

  • ListDevices：设备列表
  • GetDeviceDetail：设备详情
  • SuspendCard：停机卡
  • ResumeCard：复机卡

• 7.2 注册 H5 路由

  • 文件路径：internal/routes/h5/enterprise_device.go
  • GET /api/h5/enterprise/devices
  • GET /api/h5/enterprise/devices/:device_id
  • POST /api/h5/enterprise/devices/:device_id/cards/:card_id/suspend
  • POST /api/h5/enterprise/devices/:device_id/cards/:card_id/resume

8. DTO 层

• 8.1 创建设备授权相关 DTO
  • 文件路径：internal/model/dto/enterprise_device_authorization_dto.go
  • AllocateDevicesReq / AllocateDevicesResp
  • RecallDevicesReq / RecallDevicesResp
  • EnterpriseDeviceListReq / EnterpriseDeviceListResp
  • EnterpriseDeviceDetailResp
  • DeviceCardSuspendReq / DeviceCardResumeReq

9. 错误码

• 9.1 新增设备授权相关错误码
  • CodeDeviceAlreadyAuthorized：设备已授权给该企业
  • CodeDeviceNotAuthorized：设备未授权给该企业
  • CodeDeviceAuthorizedToOther：设备已授权给其他企业
  • CodeCannotAuthorizeOthersDevice：不能授权非自己的设备

10. 测试

• 10.1 Store 层单元测试

  • EnterpriseDeviceAuthorizationStore 各方法测试
  • EnterpriseCardAuthorizationStore 新方法测试

• 10.2 Service 层单元测试

  • enterprise_device 服务各方法测试
  • 权限验证测试
  • 授权联动测试
  • 测试覆盖率：88.9%

• 10.3 修改 enterprise_card 服务测试

  • 验证绑定设备的卡被正确拒绝
  • 移除 DeviceBundle 相关测试

• 10.4 集成测试

  • 完整授权/回收流程测试
  • 企业端 API 测试
  • 权限隔离测试

11. 文档更新

• 11.1 更新 OpenAPI 文档生成器

  • 在 cmd/api/docs.go 和 cmd/gendocs/main.go 中注册新 Handler
  • 重新生成 OpenAPI 文档

• 11.2 创建功能文档

  • 在 docs/enterprise-device-authorization/ 目录下创建设备授权功能说明文档