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

Context

当前系统支持"单卡授权企业用户"功能，通过 tb_enterprise_card_authorization 表记录卡与企业的授权关系。但现有实现存在以下问题：

1. 设备维度缺失：企业用户只能看到卡列表，无法以设备为单位管理资产
2. 逻辑不一致：单卡授权入口支持 DeviceBundle（确认后授权设备下所有卡），但没有独立的设备授权概念
3. 记录关联缺失：无法追踪卡授权是通过单独授权还是设备授权创建的

现有相关模块：

• Device 模型：设备表 tb_device，通过 shop_id 标识所有权
• DeviceSimBinding 模型：设备-卡绑定关系表，一设备最多绑定 4 张卡
• EnterpriseCardAuthorization 模型：卡授权表
• 设备分销功能：AllocateDevices 将设备分销给代理店铺（修改 shop_id）

Goals / Non-Goals

Goals:

• 支持以设备为单位授权给企业，自动授权设备下所有已绑定的卡
• 一个设备同一时间只能授权给一个企业（唯一性约束）
• 授权设备时自动创建卡授权记录，回收时同步回收
• 卡授权记录关联设备授权，支持追溯授权来源
• 企业端可以查看设备列表、设备详情及其绑定的卡
• 企业端可以对设备下的卡进行停机/复机操作
• 单卡授权入口禁止授权已绑定设备的卡

Non-Goals:

• 不涉及设备分销逻辑（设备 → 店铺，已有功能）
• 不涉及设备级别的停机/复机（仍然是卡级别操作）
• 不涉及设备解绑卡的功能（企业只能查看，不能解绑）
• 不涉及设备钱包或套餐购买功能

Decisions

1. 新增独立的设备授权表

决策：创建 tb_enterprise_device_authorization 表，与卡授权表结构类似

理由：

• 设备授权是独立的业务概念，需要独立的授权记录
• 支持设备级别的授权/回收操作和记录查询
• 与卡授权表解耦，职责清晰

替代方案：

• ❌ 在卡授权表中添加 device_id 字段：无法表达"设备授权"这个独立概念，回收设备时逻辑复杂
• ❌ 只用卡授权表+标记字段：无法追踪设备授权的元信息（授权人、时间等）

2. 卡授权表添加 device_auth_id 关联字段

决策：在 tb_enterprise_card_authorization 表添加 device_auth_id 字段

理由：

• 明确区分卡授权来源：单卡授权（NULL）vs 设备授权（有值）
• 回收设备授权时可以精确定位需要回收的卡授权记录
• 支持查询"某设备授权下的所有卡"

表结构变更：

ALTER TABLE tb_enterprise_card_authorization 
ADD COLUMN device_auth_id BIGINT DEFAULT NULL;

CREATE INDEX idx_eca_device_auth ON tb_enterprise_card_authorization(device_auth_id);

3. 设备授权唯一性约束

决策：使用部分唯一索引保证一个设备同时只能授权给一个企业

实现：

CREATE UNIQUE INDEX uq_active_device_auth 
ON tb_enterprise_device_authorization(device_id) 
WHERE revoked_at IS NULL AND deleted_at IS NULL;

理由：

• 允许历史授权记录（已回收的）存在多条
• 只限制"当前有效"的授权唯一性
• 与卡授权的设计模式一致

4. 授权联动机制

决策：授权设备时在同一事务内创建设备授权和卡授权记录

流程：

授权设备 → 事务开始
         → 创建 EnterpriseDeviceAuthorization
         → 获取 device_auth_id
         → 查询设备下所有已绑定的卡
         → 批量创建 EnterpriseCardAuthorization (device_auth_id = 上一步的ID)
         → 事务提交

回收流程：

回收设备 → 事务开始
         → 更新 EnterpriseDeviceAuthorization.revoked_at
         → 批量更新关联的 EnterpriseCardAuthorization.revoked_at
         → 事务提交

5. 单卡授权入口修改

决策：移除 DeviceBundle 支持，禁止授权已绑定设备的卡

修改点：

• Service.AllocateCards：移除 DeviceBundle 预检和处理逻辑
• Service.AllocateCardsPreview：直接返回错误而非 DeviceBundle
• DTO：移除 DeviceBundle、ConfirmDeviceBundles 等相关结构

理由：

• 职责分离：单卡授权只处理独立卡，设备授权处理设备
• 避免逻辑混淆：用户不会再在单卡入口看到设备相关提示
• 简化代码：移除复杂的 DeviceBundle 处理逻辑

BREAKING CHANGE：前端单卡授权页面需要适配，不再支持确认设备包

6. API 路径设计

后台管理（Admin）：

POST /api/admin/enterprises/:id/allocate-devices   # 授权设备
POST /api/admin/enterprises/:id/recall-devices     # 回收设备
GET  /api/admin/enterprises/:id/devices            # 设备列表

企业端（H5）：

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   # 复机

理由：

• 与现有单卡授权 API 风格一致（/enterprises/:id/allocate-cards）
• H5 端使用 /enterprise/devices 而非 /enterprises/:id/devices，因为企业用户只能访问自己的资源

7. 权限控制

后台管理：

• 平台用户：可以授权任意设备给任意企业
• 代理用户：只能授权自己店铺的设备给自己店铺下的企业

企业端：

• 只能访问授权给自己企业的设备
• 通过 GORM Callback 自动过滤

Risks / Trade-offs

[风险] 单卡授权入口 Breaking Change

影响：前端单卡授权页面行为变更，不再支持授权设备卡 缓解：

• 提前通知前端团队
• 返回明确的错误信息引导用户使用设备授权入口
• 可选：在错误响应中返回涉及的设备信息，方便前端跳转

[风险] 数据迁移

影响：如果现有数据中有通过单卡授权入口授权的设备卡，无法追溯来源 缓解：

• 新字段 device_auth_id 默认 NULL，兼容历史数据
• 历史数据视为"单卡授权"，行为不变
• 无需数据迁移脚本

[权衡] 回收粒度

选择：回收设备授权时同步回收所有关联的卡授权 权衡：不支持只回收设备授权但保留卡授权 理由：简化业务逻辑，保持授权关系一致性

[权衡] 设备新增卡后的处理

场景：设备已授权给企业后，又绑定了新的卡 选择：新卡不自动授权，需要重新授权设备或单独处理 理由：避免隐式授权带来的安全风险，保持授权行为显式可控

Open Questions

1. 设备授权记录管理页面：是否需要独立的设备授权记录列表页面（类似现有的卡授权记录页面）？

   • 建议：本期先不做，通过企业设备列表满足基本需求

2. 批量操作限制：单次授权/回收设备的数量上限？

   • 建议：与单卡授权一致，最多 100 个设备