feat: 实现企业设备授权功能并归档 OpenSpec 变更

- 新增企业设备授权模块（Model、DTO、Service、Handler、Store） - 实现设备授权的创建、查询、更新、删除等完整业务逻辑 - 添加企业卡授权与设备授权的关联关系 - 新增 2 个数据库迁移脚本 - 同步 OpenSpec delta specs 到 main specs - 归档 add-enterprise-device-authorization 变更 - 更新 API 文档和路由配置 - 新增完整的集成测试和单元测试覆盖
2026-01-29 13:18:49 +08:00
parent e87513541b
commit b02175271a
118 changed files with 14306 additions and 472 deletions
--- a/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/.openspec.yaml
+++ b/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-29
--- a/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/design.md
+++ b/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/design.md
@@ -0,0 +1,181 @@
+## 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 设备授权（有值）
+- 回收设备授权时可以精确定位需要回收的卡授权记录
+- 支持查询"某设备授权下的所有卡"
+
+**表结构变更**：
+```sql
+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. 设备授权唯一性约束
+
+**决策**：使用部分唯一索引保证一个设备同时只能授权给一个企业
+
+**实现**：
+```sql
+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 个设备
--- a/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/proposal.md
+++ b/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/proposal.md
@@ -0,0 +1,53 @@
+## Why
+
+企业用户目前只能管理被授权的单卡，但实际业务中设备（绑定 1-4 张卡）是更常见的授权单位。企业需要以设备为维度查看和管理被授权的资产，包括查看设备列表、设备详情及其绑定的卡，以及对卡进行停机/复机操作。这与"分销设备给代理"的模式类似，但目标是企业而非店铺。
+
+## What Changes
+
+- **新增设备授权表**：`tb_enterprise_device_authorization`，记录设备与企业的授权关系
+- **修改卡授权表**：`tb_enterprise_card_authorization` 新增 `device_auth_id` 字段，关联设备授权记录
+- **新增设备授权 API**（后台）：授权设备给企业、回收设备授权、企业设备列表
+- **新增企业端设备管理 API**（H5）：设备列表、设备详情（含卡）、停机/复机
+- **修改单卡授权逻辑**：**BREAKING** 禁止通过单卡授权入口授权已绑定设备的卡，移除 DeviceBundle 支持
+- **授权联动**：授权设备时自动授权设备下所有已绑定的卡，回收时同步回收
+
+## Capabilities
+
+### New Capabilities
+
+- `enterprise-device-authorization`: 设备授权企业用户功能，包含设备授权/回收、设备授权记录管理、企业端设备列表和管理
+
+### Modified Capabilities
+
+- `enterprise-card-authorization`: 禁止授权已绑定设备的卡，移除 DeviceBundle 确认流程，强制使用设备授权入口
+
+## Impact
+
+**数据库**:
+- 新增表 `tb_enterprise_device_authorization`
+- 修改表 `tb_enterprise_card_authorization`（新增字段 + 索引）
+
+**后台 API**:
+- 新增 `POST /api/admin/enterprises/:id/allocate-devices`
+- 新增 `POST /api/admin/enterprises/:id/recall-devices`
+- 新增 `GET /api/admin/enterprises/:id/devices`
+- 修改 `POST /api/admin/enterprises/:id/allocate-cards`（禁止设备卡）
+
+**H5 API**:
+- 新增 `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`
+
+**代码模块**:
+- Model: 新增 `EnterpriseDeviceAuthorization`，修改 `EnterpriseCardAuthorization`
+- Store: 新增 `EnterpriseDeviceAuthorizationStore`
+- Service: 新增 `enterprise_device` 服务，修改 `enterprise_card` 服务
+- Handler: 新增 `admin/enterprise_device.go`，新增 `h5/enterprise_device.go`
+- Routes: 新增设备授权路由注册
+- DTO: 新增设备授权相关 DTO
+
+**前端影响**:
+- 后台管理系统需要新增设备授权功能页面
+- 企业端 H5 需要新增设备列表和管理页面
+- 单卡授权页面行为变更（不再支持授权设备卡）
--- a/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/specs/enterprise-card-authorization/spec.md
+++ b/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/specs/enterprise-card-authorization/spec.md
@@ -0,0 +1,132 @@
+## MODIFIED Requirements
+
+### Requirement: 企业单卡授权管理
+
+系统 SHALL 支持将 IoT 卡授权给企业使用，授权不转移所有权，仅授予使用权限。
+
+**授权规则**：
+- 代理只能授权自己的卡（owner_type="agent" 且 owner_id=自己的 shop_id）给自己的企业
+- 平台可以授权任意卡，但如果是代理的卡，只能授权给该代理的企业
+- 支持批量授权（最多1000张卡）
+- **已绑定设备的卡不能通过单卡授权接口授权，MUST 使用设备授权接口**
+- 只能授权状态为 "已分销(2)" 的卡
+
+**授权记录存储**：
+- 使用 `enterprise_card_authorization` 表记录授权关系
+- 通过单卡授权创建的记录 device_auth_id 为 NULL
+- 不使用 `asset_allocation_record` 表（该表用于分配，非授权）
+
+**权限控制**：
+- 企业用户只能查看被授权的卡
+- 授权后卡的 shop_id 保持不变（所有权不转移）
+- 回收授权后企业立即失去访问权限
+
+#### Scenario: 代理授权自己的卡给自己的企业
+
+- **WHEN** 代理（shop_id=10）将自己的未绑定设备的卡授权给企业（enterprise_id=5, owner_shop_id=10）
+- **THEN** 系统创建授权记录（device_auth_id=NULL），企业可以查看和管理该卡
+
+#### Scenario: 平台授权任意卡给企业
+
+- **WHEN** 平台管理员将未绑定设备的卡授权给企业
+- **THEN** 系统创建授权记录（device_auth_id=NULL），企业获得该卡的访问权限
+
+#### Scenario: 代理无法授权其他代理的卡
+
+- **WHEN** 代理（shop_id=10）尝试授权其他代理的卡（owner_id=20）给企业
+- **THEN** 系统拒绝操作，返回权限错误
+
+#### Scenario: 已绑定设备的卡不能通过单卡授权
+
+- **WHEN** 用户尝试通过单卡授权接口授权已绑定到设备的卡
+- **THEN** 系统拒绝操作，返回错误码 CodeCannotAuthorizeBoundCard，提示"该卡已绑定设备，请使用设备授权功能"
+
+#### Scenario: 只能授权已分销状态的卡
+
+- **WHEN** 用户尝试授权非"已分销"状态的卡
+- **THEN** 系统拒绝操作，提示只能授权"已分销"状态的卡
+
+---
+
+### Requirement: 企业卡授权数据模型
+
+系统 SHALL 定义 EnterpriseCardAuthorization 实体，记录企业卡授权关系。
+
+**实体字段**：
+- `id`: 主键（BIGINT）
+- `enterprise_id`: 被授权企业ID（BIGINT，关联 enterprises 表）
+- `card_id`: IoT卡ID（BIGINT，关联 iot_cards 表）
+- `authorizer_id`: 授权人账号ID（BIGINT，关联 accounts 表）
+- `authorizer_type`: 授权人类型（SMALLINT，2=平台用户 3=代理账号）
+- `authorized_at`: 授权时间（TIMESTAMP）
+- `revoked_at`: 回收时间（TIMESTAMP，可空）
+- `revoked_by`: 回收人账号ID（BIGINT，可空）
+- `remark`: 备注（VARCHAR(500)）
+- **`device_auth_id`: 关联的设备授权ID（BIGINT，可空）**
+  - NULL = 通过单卡授权创建
+  - 有值 = 通过设备授权创建
+- `created_at`: 创建时间（TIMESTAMP）
+- `updated_at`: 更新时间（TIMESTAMP）
+
+**新增索引**：
+- `idx_eca_device_auth ON tb_enterprise_card_authorization(device_auth_id)`
+
+#### Scenario: 创建单卡授权记录
+
+- **WHEN** 通过单卡授权接口授权卡给企业时
+- **THEN** 系统创建 EnterpriseCardAuthorization 记录，device_auth_id 为 NULL
+
+#### Scenario: 创建设备关联卡授权记录
+
+- **WHEN** 通过设备授权创建卡授权记录时
+- **THEN** 系统创建 EnterpriseCardAuthorization 记录，device_auth_id 指向对应的设备授权ID
+
+#### Scenario: 回收授权
+
+- **WHEN** 回收企业的卡授权时
+- **THEN** 系统更新对应记录的 revoked_at 和 revoked_by 字段，不删除记录（保留历史）
+
+---
+
+### Requirement: 批量授权接口
+
+系统 SHALL 提供批量授权接口，支持一次授权多张卡给企业。
+
+**接口设计**：
+- 路径：`POST /api/admin/enterprises/:id/allocate-cards`
+- 请求体：
+  ```json
+  {
+    "iccids": ["8986001234567890", "8986001234567891"],
+    "remark": "批量授权"
+  }
+  ```
+- 响应：成功/失败的卡列表及原因
+
+**处理流程**：
+1. 验证每张卡的授权权限
+2. 检查卡状态是否为"已分销"
+3. **检查卡是否已绑定设备，绑定设备的卡直接拒绝并返回错误**
+4. 检查是否已授权给该企业
+5. 创建授权记录（device_auth_id = NULL）
+6. 返回处理结果
+
+**移除功能**：
+- ~~DeviceBundle 预检和确认流程~~（已移除）
+- ~~confirm_device_bundles 参数~~（已移除）
+- ~~AllocatedDevices 响应字段~~（已移除）
+
+#### Scenario: 批量授权成功
+
+- **WHEN** 代理批量授权 5 张未绑定设备的卡给企业
+- **THEN** 系统创建 5 条授权记录（device_auth_id 均为 NULL），返回全部成功
+
+#### Scenario: 批量授权遇到设备卡
+
+- **WHEN** 代理批量授权 5 张卡，其中 2 张已绑定设备
+- **THEN** 系统创建 3 条授权记录，返回 3 张成功、2 张失败，失败原因为"该卡已绑定设备，请使用设备授权功能"
+
+#### Scenario: 批量授权部分成功
+
+- **WHEN** 代理批量授权 5 张卡，其中 1 张已绑定设备、1 张非已分销状态
+- **THEN** 系统创建 3 条授权记录，返回 3 张成功、2 张失败及各自失败原因
--- a/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/specs/enterprise-device-authorization/spec.md
+++ b/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/specs/enterprise-device-authorization/spec.md
@@ -0,0 +1,319 @@
+## ADDED Requirements
+
+### Requirement: 设备授权企业数据模型
+
+系统 SHALL 定义 EnterpriseDeviceAuthorization 实体，记录设备与企业的授权关系。
+
+**实体字段**：
+- `id`: 主键（BIGSERIAL）
+- `enterprise_id`: 被授权企业ID（BIGINT，NOT NULL）
+- `device_id`: 被授权设备ID（BIGINT，NOT NULL）
+- `authorized_by`: 授权人账号ID（BIGINT，NOT NULL）
+- `authorized_at`: 授权时间（TIMESTAMP，NOT NULL）
+- `authorizer_type`: 授权人类型（SMALLINT，2=平台用户 3=代理账号）
+- `revoked_by`: 回收人账号ID（BIGINT，可空）
+- `revoked_at`: 回收时间（TIMESTAMP，可空）
+- `remark`: 备注（VARCHAR(500)）
+- `created_at`, `updated_at`, `deleted_at`: 标准时间字段
+
+**唯一性约束**：
+- 一个设备同时只能授权给一个企业：`UNIQUE (device_id) WHERE revoked_at IS NULL AND deleted_at IS NULL`
+
+**表名**：`tb_enterprise_device_authorization`
+
+#### Scenario: 创建设备授权记录
+
+- **WHEN** 授权设备给企业时
+- **THEN** 系统创建 EnterpriseDeviceAuthorization 记录，authorized_at 设置为当前时间，revoked_at 为 NULL
+
+#### Scenario: 设备重复授权被拒绝
+
+- **WHEN** 尝试将已授权给企业A的设备（未回收）再授权给企业B
+- **THEN** 系统拒绝操作，返回错误"设备已授权给其他企业"
+
+#### Scenario: 回收后可重新授权
+
+- **WHEN** 设备授权已被回收后，重新授权给同一企业或其他企业
+- **THEN** 系统允许创建新的授权记录
+
+---
+
+### Requirement: 卡授权记录关联设备授权
+
+系统 SHALL 在 EnterpriseCardAuthorization 表中添加 device_auth_id 字段，关联设备授权记录。
+
+**新增字段**：
+- `device_auth_id`: 关联的设备授权ID（BIGINT，可空）
+  - NULL = 通过单卡授权创建
+  - 有值 = 通过设备授权创建
+
+**索引**：
+- `idx_eca_device_auth ON tb_enterprise_card_authorization(device_auth_id)`
+
+#### Scenario: 设备授权创建关联卡授权
+
+- **WHEN** 通过设备授权创建卡授权记录时
+- **THEN** 卡授权记录的 device_auth_id 字段设置为对应的设备授权ID
+
+#### Scenario: 单卡授权不关联设备
+
+- **WHEN** 通过单卡授权创建卡授权记录时
+- **THEN** 卡授权记录的 device_auth_id 字段为 NULL
+
+---
+
+### Requirement: 设备授权管理功能
+
+系统 SHALL 提供设备授权给企业的功能，支持批量授权和回收。
+
+**授权规则**：
+- 代理只能授权自己店铺的设备给自己店铺下的企业
+- 平台可以授权任意设备给任意企业
+- 设备 MUST 属于操作者（平台或代理店铺）
+- 设备 MUST 处于"已分销"状态（status=2）
+- 设备 MUST 未授权给其他企业（唯一性约束）
+
+**授权联动**：
+- 授权设备时，系统 SHALL 自动授权设备下所有已绑定的卡
+- 卡授权记录的 device_auth_id 指向设备授权记录
+- 如果设备没有绑定卡，仍然创建设备授权记录（无卡授权）
+
+#### Scenario: 代理授权设备给自己的企业
+
+- **WHEN** 代理（shop_id=10）将自己店铺的设备授权给企业（owner_shop_id=10）
+- **THEN** 系统创建设备授权记录，并为设备下所有已绑定的卡创建卡授权记录
+
+#### Scenario: 平台授权任意设备
+
+- **WHEN** 平台管理员授权设备给任意企业
+- **THEN** 系统创建授权记录，不检查设备和企业的归属关系
+
+#### Scenario: 代理无法授权其他店铺的设备
+
+- **WHEN** 代理（shop_id=10）尝试授权其他店铺的设备（shop_id=20）
+- **THEN** 系统拒绝操作，返回权限错误
+
+#### Scenario: 设备授权联动卡授权
+
+- **WHEN** 授权一个绑定了3张卡的设备给企业
+- **THEN** 系统创建1条设备授权记录和3条卡授权记录，所有卡授权的 device_auth_id 指向该设备授权
+
+---
+
+### Requirement: 批量授权设备接口
+
+系统 SHALL 提供批量授权设备给企业的后台接口。
+
+**接口设计**：
+- 路径：`POST /api/admin/enterprises/:id/allocate-devices`
+- 请求体：
+  ```json
+  {
+    "device_nos": ["D001", "D002", "D003"],
+    "remark": "批量授权备注"
+  }
+  ```
+- 响应体：
+  ```json
+  {
+    "success_count": 2,
+    "fail_count": 1,
+    "failed_items": [
+      { "device_no": "D003", "reason": "设备不存在" }
+    ],
+    "authorized_devices": [
+      { "device_id": 1, "device_no": "D001", "card_count": 3 },
+      { "device_id": 2, "device_no": "D002", "card_count": 2 }
+    ]
+  }
+  ```
+
+**处理流程**：
+1. 验证企业存在且有权限
+2. 验证每个设备的授权权限
+3. 检查设备状态和唯一性约束
+4. 在事务内创建设备授权和卡授权记录
+5. 返回处理结果
+
+#### Scenario: 批量授权成功
+
+- **WHEN** 平台批量授权3个符合条件的设备给企业
+- **THEN** 系统创建3条设备授权记录和对应的卡授权记录，返回全部成功
+
+#### Scenario: 批量授权部分成功
+
+- **WHEN** 代理批量授权3个设备，其中1个已授权给其他企业
+- **THEN** 系统创建2条设备授权记录，返回2个成功、1个失败及失败原因
+
+---
+
+### Requirement: 设备授权回收功能
+
+系统 SHALL 提供回收设备授权的功能，回收时同步回收关联的卡授权。
+
+**回收规则**：
+- 代理可以回收自己授权的设备
+- 平台可以回收任何设备授权
+- 回收操作在事务内完成
+
+**回收联动**：
+- 回收设备授权时，系统 SHALL 同步回收所有 device_auth_id 指向该设备授权的卡授权记录
+- 更新 revoked_at 和 revoked_by 字段
+
+**接口设计**：
+- 路径：`POST /api/admin/enterprises/:id/recall-devices`
+- 请求体：
+  ```json
+  {
+    "device_nos": ["D001", "D002"]
+  }
+  ```
+
+#### Scenario: 回收设备授权联动回收卡授权
+
+- **WHEN** 回收一个绑定了3张卡的设备的授权
+- **THEN** 系统更新设备授权的 revoked_at，同时更新3条关联卡授权的 revoked_at
+
+#### Scenario: 回收后企业无法访问设备和卡
+
+- **WHEN** 设备授权被回收后，企业用户查询设备或卡
+- **THEN** 系统不返回该设备和其下的卡
+
+---
+
+### Requirement: 后台企业设备列表
+
+系统 SHALL 提供后台管理查询企业授权设备列表的接口。
+
+**接口设计**：
+- 路径：`GET /api/admin/enterprises/:id/devices`
+- 查询参数：`page`, `page_size`, `device_no`, `status`
+- 响应：设备列表，包含设备信息和绑定卡数量
+
+**数据权限**：
+- 平台用户可查看所有企业的授权设备
+- 代理用户只能查看自己店铺下企业的授权设备
+
+#### Scenario: 查询企业授权设备列表
+
+- **WHEN** 管理员查询企业ID=5的授权设备
+- **THEN** 系统返回该企业所有授权设备列表，每个设备包含绑定卡数量
+
+---
+
+### Requirement: 企业端设备列表
+
+系统 SHALL 提供企业用户查询自己授权设备列表的 H5 接口。
+
+**接口设计**：
+- 路径：`GET /api/h5/enterprise/devices`
+- 查询参数：`page`, `page_size`, `device_no`
+- 响应：
+  ```json
+  {
+    "list": [
+      {
+        "device_id": 1,
+        "device_no": "D001",
+        "device_name": "GPS追踪器-001",
+        "device_model": "GT-100",
+        "card_count": 3,
+        "authorized_at": "2025-01-29T10:00:00Z"
+      }
+    ],
+    "total": 10
+  }
+  ```
+
+**数据权限**：
+- 企业用户只能看到授权给自己企业的设备
+- 通过 GORM Callback 自动过滤
+
+#### Scenario: 企业用户查看设备列表
+
+- **WHEN** 企业用户查询设备列表
+- **THEN** 系统返回授权给该企业的所有设备，包含设备信息和卡数量
+
+#### Scenario: 企业用户无法看到未授权设备
+
+- **WHEN** 企业用户查询设备列表
+- **THEN** 系统不返回未授权给该企业的设备
+
+---
+
+### Requirement: 企业端设备详情
+
+系统 SHALL 提供企业用户查询设备详情的 H5 接口，包含设备绑定的卡列表。
+
+**接口设计**：
+- 路径：`GET /api/h5/enterprise/devices/:device_id`
+- 响应：
+  ```json
+  {
+    "device": {
+      "device_id": 1,
+      "device_no": "D001",
+      "device_name": "GPS追踪器-001",
+      "device_model": "GT-100",
+      "device_type": "GPS",
+      "authorized_at": "2025-01-29T10:00:00Z"
+    },
+    "cards": [
+      {
+        "card_id": 101,
+        "iccid": "8986001234567890",
+        "msisdn": "1380000001",
+        "carrier_name": "中国联通",
+        "network_status": 1,
+        "network_status_name": "开机"
+      }
+    ]
+  }
+  ```
+
+**可见信息**：
+- 设备基本信息：设备号、名称、型号、类型
+- 卡信息：ICCID、MSISDN、运营商、网络状态
+
+**不可见信息**：
+- 成本价、分销价、供应商等商业敏感信息
+
+#### Scenario: 企业用户查看设备详情
+
+- **WHEN** 企业用户查看授权设备ID=1的详情
+- **THEN** 系统返回设备信息和该设备绑定的所有卡信息
+
+#### Scenario: 企业用户无法查看未授权设备
+
+- **WHEN** 企业用户尝试查看未授权的设备详情
+- **THEN** 系统返回 404 错误
+
+---
+
+### Requirement: 企业端设备卡停机复机
+
+系统 SHALL 提供企业用户对设备下的卡进行停机/复机操作的 H5 接口。
+
+**接口设计**：
+- 停机：`POST /api/h5/enterprise/devices/:device_id/cards/:card_id/suspend`
+- 复机：`POST /api/h5/enterprise/devices/:device_id/cards/:card_id/resume`
+
+**权限校验**：
+- 设备 MUST 授权给当前企业
+- 卡 MUST 属于该设备（通过 device_sim_binding 验证）
+- 卡 MUST 通过设备授权（device_auth_id 不为空且有效）
+
+#### Scenario: 企业用户停机设备下的卡
+
+- **WHEN** 企业用户对授权设备下的卡执行停机操作
+- **THEN** 系统更新卡的 network_status 为 0（停机）
+
+#### Scenario: 企业用户复机设备下的卡
+
+- **WHEN** 企业用户对授权设备下的卡执行复机操作
+- **THEN** 系统更新卡的 network_status 为 1（开机）
+
+#### Scenario: 无法操作未授权设备的卡
+
+- **WHEN** 企业用户尝试操作未授权设备下的卡
+- **THEN** 系统返回 403 错误
--- a/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/tasks.md
+++ b/openspec/changes/archive/2026-01-29-add-enterprise-device-authorization/tasks.md
@@ -0,0 +1,163 @@
+## 1. 数据库迁移
+
+- [x] 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
+
+- [x] 1.2 创建 `tb_enterprise_card_authorization` 表修改迁移文件
+  - 新增字段：device_auth_id（BIGINT，可空）
+  - 添加索引：idx_eca_device_auth
+
+- [x] 1.3 执行迁移并验证表结构正确
+
+## 2. Model 层
+
+- [x] 2.1 创建 `EnterpriseDeviceAuthorization` 模型
+  - 文件路径：`internal/model/enterprise_device_authorization.go`
+  - 包含所有字段和 TableName 方法
+  - 遵循项目 GORM 模型规范
+
+- [x] 2.2 修改 `EnterpriseCardAuthorization` 模型
+  - 新增 `DeviceAuthID` 字段（`*uint`）
+  - 添加 GORM 标签：`gorm:"column:device_auth_id;comment:关联的设备授权ID"`
+
+## 3. Store 层
+
+- [x] 3.1 创建 `EnterpriseDeviceAuthorizationStore`
+  - 文件路径：`internal/store/postgres/enterprise_device_authorization_store.go`
+  - 实现方法：Create, BatchCreate, GetByID, GetByDeviceID, GetByEnterpriseID
+  - 实现方法：ListByEnterprise（分页、筛选）, RevokeByIDs, GetActiveAuthsByDeviceIDs
+  - 实现方法：ListDeviceIDsByEnterprise（获取企业授权的设备ID列表）
+
+- [x] 3.2 修改 `EnterpriseCardAuthorizationStore`
+  - 新增方法：RevokeByDeviceAuthID（根据设备授权ID批量回收卡授权）
+
+## 4. Service 层 - 设备授权服务
+
+- [x] 4.1 创建 `enterprise_device` 服务
+  - 文件路径：`internal/service/enterprise_device/service.go`
+  - 依赖注入：db, enterpriseStore, deviceStore, deviceSimBindingStore, enterpriseDeviceAuthStore, enterpriseCardAuthStore, logger
+
+- [x] 4.2 实现 `AllocateDevices` 方法（授权设备给企业）
+  - 验证企业存在和权限
+  - 验证每个设备的权限和状态
+  - 检查唯一性约束（设备未授权给其他企业）
+  - 在事务内创建设备授权和卡授权记录
+  - 返回授权结果
+
+- [x] 4.3 实现 `RecallDevices` 方法（回收设备授权）
+  - 验证授权记录存在
+  - 在事务内回收设备授权和关联的卡授权
+  - 返回回收结果
+
+- [x] 4.4 实现 `ListDevices` 方法（后台管理：企业设备列表）
+  - 分页查询授权给企业的设备
+  - 包含设备信息和绑定卡数量
+
+- [x] 4.5 实现 `ListDevicesForEnterprise` 方法（H5：企业设备列表）
+  - 企业用户查询自己的授权设备
+  - 数据权限自动过滤
+
+- [x] 4.6 实现 `GetDeviceDetail` 方法（H5：设备详情）
+  - 查询设备信息和绑定的卡列表
+  - 验证企业权限
+
+- [x] 4.7 实现 `SuspendCard` 和 `ResumeCard` 方法（H5：停机/复机）
+  - 验证设备和卡的授权关系
+  - 更新卡的网络状态
+
+## 5. Service 层 - 修改单卡授权服务
+
+- [x] 5.1 修改 `enterprise_card/service.go` 的 `AllocateCardsPreview` 方法
+  - 移除 DeviceBundle 处理逻辑
+  - 绑定设备的卡直接加入 FailedItems，原因为"该卡已绑定设备，请使用设备授权功能"
+  - 移除 DeviceBundles 响应字段
+
+- [x] 5.2 修改 `enterprise_card/service.go` 的 `AllocateCards` 方法
+  - 移除 DeviceBundle 确认流程（confirm_device_bundles 参数）
+  - 移除 AllocatedDevices 响应字段
+  - 绑定设备的卡直接拒绝
+
+- [x] 5.3 清理相关 DTO
+  - 移除或标记废弃：DeviceBundle, DeviceBundleCard, ConfirmDeviceBundles, AllocatedDevice 相关字段
+  - 更新 AllocateCardsReq 和 AllocateCardsResp
+
+## 6. Handler 层 - 后台管理
+
+- [x] 6.1 创建 `admin/enterprise_device.go` Handler
+  - AllocateDevices：授权设备给企业
+  - RecallDevices：回收设备授权
+  - ListDevices：企业设备列表
+
+- [x] 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
+
+- [x] 6.3 更新 Bootstrap 注册
+  - 在 `internal/bootstrap/` 中注册新的 Store、Service、Handler
+
+## 7. Handler 层 - 企业端 H5
+
+- [x] 7.1 创建 `h5/enterprise_device.go` Handler
+  - ListDevices：设备列表
+  - GetDeviceDetail：设备详情
+  - SuspendCard：停机卡
+  - ResumeCard：复机卡
+
+- [x] 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 层
+
+- [x] 8.1 创建设备授权相关 DTO
+  - 文件路径：`internal/model/dto/enterprise_device_authorization_dto.go`
+  - AllocateDevicesReq / AllocateDevicesResp
+  - RecallDevicesReq / RecallDevicesResp
+  - EnterpriseDeviceListReq / EnterpriseDeviceListResp
+  - EnterpriseDeviceDetailResp
+  - DeviceCardSuspendReq / DeviceCardResumeReq
+
+## 9. 错误码
+
+- [x] 9.1 新增设备授权相关错误码
+  - CodeDeviceAlreadyAuthorized：设备已授权给该企业
+  - CodeDeviceNotAuthorized：设备未授权给该企业
+  - CodeDeviceAuthorizedToOther：设备已授权给其他企业
+  - CodeCannotAuthorizeOthersDevice：不能授权非自己的设备
+
+## 10. 测试
+
+- [x] 10.1 Store 层单元测试
+  - EnterpriseDeviceAuthorizationStore 各方法测试
+  - EnterpriseCardAuthorizationStore 新方法测试
+
+- [x] 10.2 Service 层单元测试
+  - enterprise_device 服务各方法测试
+  - 权限验证测试
+  - 授权联动测试
+  - 测试覆盖率：88.9%
+
+- [x] 10.3 修改 enterprise_card 服务测试
+  - 验证绑定设备的卡被正确拒绝
+  - 移除 DeviceBundle 相关测试
+
+- [x] 10.4 集成测试
+  - 完整授权/回收流程测试
+  - 企业端 API 测试
+  - 权限隔离测试
+
+## 11. 文档更新
+
+- [x] 11.1 更新 OpenAPI 文档生成器
+  - 在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中注册新 Handler
+  - 重新生成 OpenAPI 文档
+
+- [x] 11.2 创建功能文档
+  - 在 `docs/enterprise-device-authorization/` 目录下创建设备授权功能说明文档
--- a/openspec/changes/archive/2026-01-29-add-role-handler-validation/.openspec.yaml
+++ b/openspec/changes/archive/2026-01-29-add-role-handler-validation/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-29
--- a/openspec/changes/archive/2026-01-29-add-role-handler-validation/design.md
+++ b/openspec/changes/archive/2026-01-29-add-role-handler-validation/design.md
@@ -0,0 +1,99 @@
+# 设计：RoleHandler 请求验证
+
+## 上下文
+
+项目中已有标准的请求验证模式：
+- 使用 `github.com/go-playground/validator/v10` 库
+- 在 bootstrap 层创建全局 validator 实例
+- Handler 构造函数接收 validator
+- 请求解析后立即调用 `validator.Struct()` 验证
+
+AuthHandler 已正确实现此模式（参考 `internal/handler/admin/auth.go:34`），RoleHandler 需要遵循相同模式。
+
+## 目标 / 非目标
+
+**目标：**
+- RoleHandler 遵循项目验证标准模式
+- 所有请求在到达 Service 层前完成验证
+- 取消被跳过的集成测试
+
+**非目标：**
+- 不修改 DTO 的 validate 标签（已正确定义）
+- 不改变错误响应格式（使用现有 CodeInvalidParam）
+- 不引入新的验证库或模式
+
+## 决策
+
+### 决策 1：遵循 AuthHandler 模式
+
+**方法：** 完全复制 AuthHandler 的验证模式到 RoleHandler
+
+**理由：**
+- 保持代码库一致性
+- AuthHandler 模式已验证有效
+- 无需重新设计验证流程
+
+**实现细节：**
+```go
+// 1. RoleHandler 结构体添加 validator 字段
+type RoleHandler struct {
+    service   *roleService.Service
+    validator *validator.Validate  // 新增
+}
+
+// 2. 构造函数接收 validator
+func NewRoleHandler(service *roleService.Service, validator *validator.Validate) *RoleHandler {
+    return &RoleHandler{
+        service:   service,
+        validator: validator,
+    }
+}
+
+// 3. Create 方法中验证
+func (h *RoleHandler) Create(c *fiber.Ctx) error {
+    var req dto.CreateRoleRequest
+    if err := c.BodyParser(&req); err != nil {
+        return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+    }
+    
+    // 新增验证逻辑
+    if err := h.validator.Struct(&req); err != nil {
+        return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
+    }
+    
+    // ... 现有逻辑
+}
+```
+
+### 决策 2：验证所有接受 body 的方法
+
+**需要验证的方法：**
+- `Create()` - CreateRoleRequest
+- `Update()` - UpdateRoleRequest
+- `AssignPermissions()` - AssignPermissionsRequest
+- `UpdateStatus()` - UpdateRoleStatusRequest
+
+**不需要验证的方法：**
+- `Get()` - 只有路径参数，已有 ParseUint 检查
+- `List()` - Query 参数，已有 QueryParser
+- `GetPermissions()` - 只有路径参数
+- `RemovePermission()` - 只有路径参数
+- `Delete()` - 只有路径参数
+
+### 决策 3：错误消息格式
+
+**使用现有格式：**
+```go
+errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
+```
+
+**理由：**
+- 与 AuthHandler 保持一致
+- validator 库的错误消息已足够清晰
+- 前端可以解析错误码和消息
+
+## 测试策略
+
+- 取消 `tests/integration/role_test.go:51` 的 TODO 跳过
+- 运行现有测试验证"缺少必填字段返回错误"场景
+- 无需添加新测试（现有被跳过的测试已覆盖验证逻辑）
--- a/openspec/changes/archive/2026-01-29-add-role-handler-validation/proposal.md
+++ b/openspec/changes/archive/2026-01-29-add-role-handler-validation/proposal.md
@@ -0,0 +1,27 @@
+# 提案：为 RoleHandler 添加请求验证
+
+## 为什么
+
+当前 RoleHandler 缺少请求参数验证，导致无效的请求可以通过 Handler 层传递到 Service 层。这违反了项目的"Handler 层负责参数验证"原则，并且导致集成测试被迫跳过（tests/integration/role_test.go:51,282）。
+
+其他 Handler（如 AuthHandler）已经正确实现了验证，RoleHandler 需要遵循相同模式。
+
+## 变更内容
+
+- RoleHandler 将接收 validator 实例并验证所有请求参数
+- Create 和 Update 方法将调用 validator.Struct() 验证 DTO
+- 取消 role_test.go 中被跳过的验证测试
+
+## 能力
+
+### 新增能力
+- `role-request-validation`: RoleHandler 的所有请求（Create、Update、AssignPermissions、UpdateStatus）都将验证必填字段和格式
+
+### 修改能力
+无（现有功能无变化，只是增强了输入验证）
+
+## 影响范围
+
+- `internal/handler/admin/role.go`: 添加 validator 字段，调用验证方法
+- `internal/bootstrap/handlers.go`: 传递 validator 给 RoleHandler
+- `tests/integration/role_test.go`: 取消被跳过的测试
--- a/openspec/changes/archive/2026-01-29-add-role-handler-validation/specs/role-request-validation/spec.md
+++ b/openspec/changes/archive/2026-01-29-add-role-handler-validation/specs/role-request-validation/spec.md
@@ -0,0 +1,67 @@
+# 规格：角色请求验证
+
+## 新增需求
+
+### 需求：Create 方法验证必填字段
+
+RoleHandler.Create 方法必须验证 CreateRoleRequest 的所有必填字段。
+
+#### 场景：缺少 role_name 返回验证错误
+
+- **WHEN** 客户端发送 POST /api/admin/roles 请求，body 缺少 role_name 字段
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+- **AND** 错误消息提示 "参数验证失败"
+
+#### 场景：缺少 role_type 返回验证错误
+
+- **WHEN** 客户端发送 POST /api/admin/roles 请求，body 缺少 role_type 字段
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+
+#### 场景：role_name 过长返回验证错误
+
+- **WHEN** 客户端发送 POST /api/admin/roles 请求，role_name 超过 50 个字符
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+
+### 需求：Update 方法验证字段格式
+
+RoleHandler.Update 方法必须验证 UpdateRoleRequest 的字段格式。
+
+#### 场景：role_name 过长返回验证错误
+
+- **WHEN** 客户端发送 PUT /api/admin/roles/:id 请求，role_name 超过 50 个字符
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+
+#### 场景：status 值非法返回验证错误
+
+- **WHEN** 客户端发送 PUT /api/admin/roles/:id 请求，status 值不是 0 或 1
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+
+### 需求：AssignPermissions 方法验证权限ID列表
+
+RoleHandler.AssignPermissions 方法必须验证权限ID列表不为空。
+
+#### 场景：perm_ids 为空数组返回验证错误
+
+- **WHEN** 客户端发送 POST /api/admin/roles/:id/permissions 请求，perm_ids 为空数组 []
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+
+### 需求：UpdateStatus 方法验证状态值
+
+RoleHandler.UpdateStatus 方法必须验证状态值在有效范围内。
+
+#### 场景：status 值非法返回验证错误
+
+- **WHEN** 客户端发送 PUT /api/admin/roles/:id/status 请求，status 值不是 0 或 1
+- **THEN** 返回 HTTP 400
+- **AND** 响应包含错误码（CodeInvalidParam）
+
+## 测试要求
+
+- 取消 tests/integration/role_test.go 中的 TODO 跳过（第 51 行）
+- 验证测试能够通过，证明验证逻辑正常工作
--- a/openspec/changes/archive/2026-01-29-add-role-handler-validation/tasks.md
+++ b/openspec/changes/archive/2026-01-29-add-role-handler-validation/tasks.md
@@ -0,0 +1,30 @@
+# 实现任务
+
+## 1. 修改 RoleHandler 结构
+
+- [x] 1.1 在 RoleHandler 结构体中添加 `validator *validator.Validate` 字段
+- [x] 1.2 修改 NewRoleHandler 构造函数，接收 validator 参数
+- [x] 1.3 导入 `github.com/go-playground/validator/v10` 包
+
+## 2. 添加验证逻辑
+
+- [x] 2.1 Create 方法：BodyParser 后调用 validator.Struct(&req)
+- [x] 2.2 Update 方法：BodyParser 后调用 validator.Struct(&req)
+- [x] 2.3 AssignPermissions 方法：BodyParser 后调用 validator.Struct(&req)
+- [x] 2.4 UpdateStatus 方法：BodyParser 后调用 validator.Struct(&req)
+
+## 3. 更新 Bootstrap
+
+- [x] 3.1 修改 internal/bootstrap/handlers.go 中的 initHandlers 函数
+- [x] 3.2 传递 validate 参数给 NewRoleHandler：`admin.NewRoleHandler(svc.Role, validate)`
+
+## 4. 取消测试跳过
+
+- [x] 4.1 删除 tests/integration/role_test.go:51-62 的 TODO 跳过代码
+- [x] 4.2 取消注释被跳过的测试代码
+
+## 5. 验证
+
+- [x] 5.1 运行 `go test -v ./tests/integration/role_test.go` 确保测试通过
+- [x] 5.2 运行 LSP diagnostics 检查 internal/handler/admin/role.go
+- [x] 5.3 确认没有编译错误
--- a/openspec/changes/fix-authorization-remark-permission/.openspec.yaml
+++ b/openspec/changes/fix-authorization-remark-permission/.openspec.yaml
@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-01-29
+
--- a/openspec/changes/fix-authorization-remark-permission/design.md
+++ b/openspec/changes/fix-authorization-remark-permission/design.md
@@ -0,0 +1,48 @@
+# 授权记录备注修改权限修复 - 设计
+
+## 目标
+
+1. 代理用户无法修改非本人创建的授权记录备注。
+2. 企业用户无法修改任何授权记录备注。
+3. 平台/超级管理员可修改任意授权记录备注。
+4. 任何情况下都必须满足数据可见性（代理只能在自己店铺企业范围内操作）。
+
+## 现状与风险点
+
+- 备注更新当前仅按 `id` 更新，缺少“创建者/可见性”约束。
+- 现有数据权限 callback 主要作用于 Query，不覆盖 Update，因此必须在业务链路显式校验。
+
+## 方案
+
+### 1) Service 层统一鉴权
+
+在 `AuthorizationService.UpdateRecordRemark` 内新增权限判断：
+
+- 取当前用户信息（user_id/user_type/shop_id/enterprise_id）
+- 先通过 `GetByIDWithJoin` 获取授权记录详情（包含 `authorized_by`、`enterprise_id` 等）
+- 按规则判断：
+  - 平台/超级管理员：允许
+  - 代理：
+    - 必须 `record.AuthorizedBy == 当前 user_id`
+    - 且授权记录对应企业必须属于当前店铺（`enterprise.owner_shop_id == shop_id`，可通过 join 查询或使用现有原生 SQL 结果）
+  - 企业：直接拒绝
+
+### 2) Store 层更新增加约束（防御性）
+
+提供一个“带约束”的更新方法（示例语义）：
+- 平台路径：`UpdateRemarkByID(id, remark)`
+- 代理路径：`UpdateRemarkByIDAndAuthorizedBy(id, remark, userID)`（必要时再加 enterprise 范围约束）
+
+确保即使上层遗漏判断，也难以越权更新成功。
+
+### 3) 错误与返回
+
+- 无权限：返回统一错误码（例如 `CodeForbidden`），错误信息使用中文并可被前端直接展示。
+
+## 验收标准
+
+- 平台用户可修改任意授权记录备注。
+- 代理用户仅可修改自己创建的授权记录备注；修改他人创建的记录必须失败。
+- 企业用户调用修改备注接口必须失败。
+- 新增/更新用例后相关集成测试通过。
+
--- a/openspec/changes/fix-authorization-remark-permission/proposal.md
+++ b/openspec/changes/fix-authorization-remark-permission/proposal.md
@@ -0,0 +1,25 @@
+# 授权记录备注修改权限修复
+
+## Why
+
+当前“授权记录备注修改”链路缺少明确的权限边界校验：代理用户可能通过接口修改不属于自己创建的授权记录备注；企业用户也需要被明确禁止修改。
+
+该问题会导致越权修改、审计信息失真，属于高风险权限缺陷。
+
+## What Changes
+
+- **权限规则落地**：
+  - 平台/超级管理员：可修改任意授权记录备注
+  - 代理：仅可修改“自己创建的授权记录”的备注（且必须在其可见数据范围内）
+  - 企业：禁止修改授权记录备注
+- **服务端强校验**：在 Service 层统一做权限判断与可见性校验，Store 层更新语句增加必要约束，避免仅凭 `id` 更新造成越权。
+- **补充测试**：新增集成测试覆盖平台/代理/企业三种用户场景，确保规则稳定。
+
+## Impact
+
+涉及文件（预期）：
+- Handler：`internal/handler/admin/authorization.go`
+- Service：`internal/service/enterprise_card/authorization_service.go`
+- Store：`internal/store/postgres/enterprise_card_authorization_store.go`
+- 测试：`tests/integration/authorization_test.go`（或新增对应用例文件）
+
--- a/openspec/changes/fix-authorization-remark-permission/tasks.md
+++ b/openspec/changes/fix-authorization-remark-permission/tasks.md
@@ -0,0 +1,18 @@
+# 授权记录备注修改权限修复 - 实现任务
+
+## 1. 权限规则实现
+
+- [ ] 1.1 在 `internal/service/enterprise_card/authorization_service.go` 中为 `UpdateRecordRemark` 增加权限校验：平台全量、代理仅本人创建、企业禁止
+- [ ] 1.2 在 `internal/store/postgres/enterprise_card_authorization_store.go` 增加带约束的更新方法（至少支持 `id + authorized_by` 约束）
+- [ ] 1.3 更新 `internal/handler/admin/authorization.go`：将权限失败场景返回统一错误（中文错误消息）
+
+## 2. 测试
+
+- [ ] 2.1 为平台用户新增集成测试：可修改任意授权记录备注
+- [ ] 2.2 为代理用户新增集成测试：可修改本人创建记录、不可修改他人创建记录
+- [ ] 2.3 为企业用户新增集成测试：调用修改备注接口必须失败
+
+## 3. 验证
+
+- [ ] 3.1 运行 `go test ./...` 确保通过
+
--- a/openspec/changes/fix-commission-calculation-trigger-and-snapshot/.openspec.yaml
+++ b/openspec/changes/fix-commission-calculation-trigger-and-snapshot/.openspec.yaml
@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-01-29
+
--- a/openspec/changes/fix-commission-calculation-trigger-and-snapshot/design.md
+++ b/openspec/changes/fix-commission-calculation-trigger-and-snapshot/design.md
@@ -0,0 +1,39 @@
+# 佣金计算链路修复 - 设计
+
+## 目标
+
+1. 订单创建时就写入后续佣金计算所需的关键字段快照。
+2. 订单支付成功后（首次成功支付）自动 enqueue 佣金计算异步任务。
+3. 佣金计算具备可重复执行的幂等语义（订单佣金已计算则跳过）。
+
+## 关键字段来源（你已确认）
+
+以购买校验结果为准：
+- `allocation`：来自 `PurchaseValidationResult.Allocation`
+- `SeriesID`：`allocation.SeriesID`
+- `SellerShopID`：`allocation.ShopID`（该分配记录对应的“售卖/收益归属店铺”）
+- `SellerCostPrice`：根据 allocation 的基础返佣规则从订单金额推导（与成本价差计算一致的口径）
+
+说明：这里的 SellerCostPrice 是为了支持“成本价差佣金”计算，作为链路上的稳定快照，避免后续配置变更影响历史订单。
+
+## 支付成功后触发佣金计算
+
+- 触发点：订单支付成功且为首次成功支付（由“订单激活幂等提案”提供门闸）。
+- 触发动作：enqueue `commission:calculate`，payload 为 `order_id`。
+- 入队失败策略：
+  - 不回滚支付成功（避免影响主链路）
+  - 保持 `commission_status = pending`，允许后续重试（例如后台补偿任务/人工触发/定时任务扫描）
+
+## 事务一致性（可选）
+
+当前佣金计算服务使用了 `Transaction` 包裹，但内部 Store 若未使用同一个 `tx`，一致性会被破坏。
+
+推荐方案之一：
+- 为各 Store 增加 `WithDB(tx)` 或在方法中接收 `db *gorm.DB` 参数，确保写入走同一个事务 `tx`。
+
+## 验收标准
+
+- 创建订单后，订单表中 `series_id/seller_shop_id/seller_cost_price` 等字段正确写入。
+- 首次支付成功后，会 enqueue 佣金计算任务（可通过日志/测试验证）。
+- 佣金任务重复执行不重复发放（已计算则跳过）。
+
--- a/openspec/changes/fix-commission-calculation-trigger-and-snapshot/proposal.md
+++ b/openspec/changes/fix-commission-calculation-trigger-and-snapshot/proposal.md
@@ -0,0 +1,25 @@
+# 佣金计算链路修复：支付后自动入队 + 订单佣金字段快照
+
+## Why
+
+你确认的目标：**订单支付成功后自动触发佣金计算（异步任务）**，且佣金计算所需的关键字段应当来源于“购买校验结果”。
+
+当前实现存在以下风险：
+- 佣金计算依赖订单字段（如 `series_id/seller_shop_id/seller_cost_price`），但订单创建时未填充，可能导致计算错误或空指针风险。
+- 佣金计算任务已定义，但缺少稳定触发入口，导致支付后佣金不计算或需要人工补偿。
+
+## What Changes
+
+- **订单创建时写入佣金快照字段**：基于购买校验结果（allocation/series）填充订单的 `SeriesID/SellerShopID/SellerCostPrice` 等字段，确保后续计算稳定。
+- **支付成功后自动入队佣金计算任务**：在订单从待支付变为已支付的“首次成功支付”场景，enqueue `commission:calculate` 异步任务，执行佣金计算。
+- **计算事务一致性（可选但推荐）**：调整佣金计算服务的事务使用方式，确保“佣金记录 + 钱包入账 + 订单佣金状态更新”具备一致性。
+- **补充测试**：新增/完善测试，避免回归。
+
+## Impact
+
+涉及模块（预期）：
+- 订单创建：`internal/service/order/service.go`
+- 异步任务：`internal/task/commission_calculation.go`（触发入口）与队列注入
+- 佣金计算：`internal/service/commission_calculation/service.go`
+- 测试：`internal/service/order/service_test.go`、`internal/task/*` 或集成测试
+
--- a/openspec/changes/fix-commission-calculation-trigger-and-snapshot/tasks.md
+++ b/openspec/changes/fix-commission-calculation-trigger-and-snapshot/tasks.md
@@ -0,0 +1,24 @@
+# 佣金计算链路修复 - 实现任务
+
+## 1. 订单佣金字段快照
+
+- [ ] 1.1 在 `internal/service/order/service.go` 创建订单时，从购买校验结果填充 `SeriesID/SellerShopID/SellerCostPrice`
+- [ ] 1.2 补充/复用“成本价推导”工具方法，确保口径与佣金计算一致
+
+## 2. 支付成功后自动入队
+
+- [ ] 2.1 在首次支付成功路径 enqueue `commission:calculate`（payload: order_id）
+- [ ] 2.2 注入队列客户端到订单服务（遵循现有 bootstrap 依赖注入方式）
+- [ ] 2.3 明确入队失败策略：记录日志，订单保持 `commission_status=pending` 可重试
+
+## 3. 佣金计算一致性与健壮性（可选但推荐）
+
+- [ ] 3.1 调整 `internal/service/commission_calculation/service.go`，确保事务内对佣金记录/钱包/订单状态更新使用同一 `tx`
+- [ ] 3.2 增加必要的空值保护：缺少关键字段时返回业务错误而非 panic
+
+## 4. 测试与验证
+
+- [ ] 4.1 新增单元测试：订单创建后佣金快照字段写入正确
+- [ ] 4.2 新增单元/集成测试：支付成功后会 enqueue 佣金计算任务（可通过可注入的队列 client 验证）
+- [ ] 4.3 运行 `go test ./...` 确保通过
+
--- a/openspec/changes/fix-one-time-commission-config-and-accumulation/.openspec.yaml
+++ b/openspec/changes/fix-one-time-commission-config-and-accumulation/.openspec.yaml
@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-01-29
+
--- a/openspec/changes/fix-one-time-commission-config-and-accumulation/design.md
+++ b/openspec/changes/fix-one-time-commission-config-and-accumulation/design.md
@@ -0,0 +1,61 @@
+# 一次性佣金修复 - 设计
+
+## 目标
+
+1. 通过 `ShopSeriesAllocation` 创建/更新接口即可配置一次性佣金并生效（你确认 B=1）。
+2. “累计充值触发”场景每次支付成功都累加保存，达到阈值触发一次性佣金发放。
+3. 发放具备幂等：同一资源（卡/设备）只发放一次。
+
+## 1) 配置落库
+
+### 固定类型（fixed）
+
+在 `tb_shop_series_allocation` 写入：
+- enable_one_time_commission
+- one_time_commission_type = fixed
+- one_time_commission_trigger
+- one_time_commission_threshold
+- one_time_commission_mode（fixed/percent）
+- one_time_commission_value
+
+### 梯度类型（tiered）
+
+在 `tb_shop_series_allocation` 写入：
+- enable_one_time_commission
+- one_time_commission_type = tiered
+- one_time_commission_trigger
+- one_time_commission_threshold
+
+并在 `tb_shop_series_one_time_commission_tier` 维护档位：
+- allocation_id
+- tier_type（sales_count/sales_amount）
+- threshold_value
+- commission_mode（fixed/percent）
+- commission_value
+
+更新策略建议：
+- 更新配置时：先删除 allocation_id 对应的旧 tiers，再批量插入新 tiers（实现简单且可控）
+
+## 2) 累计触发逻辑
+
+针对 `accumulated_recharge`：
+- 每次支付成功都更新 `AccumulatedRecharge += orderAmount`
+- 若累计达到阈值且未发放过：
+  - 计算佣金金额
+  - 创建佣金记录并入账
+  - 标记 `FirstCommissionPaid = true`
+
+注意：累计的更新应当以“支付成功”为准，避免未支付订单污染累计值。
+
+## 3) 测试
+
+- 配置落库测试：创建/更新分配后，查询数据库字段与 tiers 表是否一致
+- 累计触发测试：模拟多次支付累计到阈值，验证只发放一次且累计值递增
+- 修复现有单测字段不匹配导致的编译失败
+
+## 验收标准
+
+- 创建/更新 `ShopSeriesAllocation` 时，一次性佣金配置能正确落库并在查询响应中返回。
+- 累计触发场景下，多次支付能累加并在达到阈值时发放一次性佣金；之后不重复发放。
+- `go test ./...` 通过。
+
--- a/openspec/changes/fix-one-time-commission-config-and-accumulation/proposal.md
+++ b/openspec/changes/fix-one-time-commission-config-and-accumulation/proposal.md
@@ -0,0 +1,30 @@
+# 一次性佣金修复：配置可落库 + 累计触发可累加 + 单测修复
+
+## Why
+
+一次性佣金能力已引入配置字段与计算逻辑，但目前存在两类关键问题：
+
+1. **配置无法生效**：你确认希望通过 `ShopSeriesAllocation` 的创建/更新接口（B=1）直接配置一次性佣金并落库生效；否则会出现“接口看起来支持配置，但实际不生效”的问题。
+2. **累计触发无法累加**：你确认累计规则为“每次购买都要累加，达到阈值就发放佣金”；如果不写回累计值，阈值永远达不到。
+
+此外，相关单测目前编译失败，需要修复以保证回归可控。
+
+## What Changes
+
+- **一次性佣金配置落库**：
+  - 在 `ShopSeriesAllocation` 创建/更新时写入一次性佣金相关字段
+  - 若类型为梯度（tiered），同步维护 `tb_shop_series_one_time_commission_tier` 档位数据（更新时先清理再重建或做差量更新）
+- **累计触发逻辑修复**：
+  - 对“累计充值触发”场景，每次支付成功都写回累计金额
+  - 达到阈值的那次发放一次性佣金，并标记 `FirstCommissionPaid` 防止重复发放
+- **测试修复与补充**：
+  - 修复 `tests/unit/my_commission_service_test.go` 字段不匹配导致的编译失败
+  - 新增测试覆盖：配置落库与累计逻辑
+
+## Impact
+
+涉及模块（预期）：
+- 分配配置：`internal/service/shop_series_allocation/service.go`、`internal/store/postgres/shop_series_one_time_commission_tier_store.go`
+- 佣金计算：`internal/service/commission_calculation/service.go`
+- 测试：`tests/unit/my_commission_service_test.go` 及新增用例
+
--- a/openspec/changes/fix-one-time-commission-config-and-accumulation/tasks.md
+++ b/openspec/changes/fix-one-time-commission-config-and-accumulation/tasks.md
@@ -0,0 +1,24 @@
+# 一次性佣金修复 - 实现任务
+
+## 1. 配置落库（ShopSeriesAllocation）
+
+- [ ] 1.1 更新 `internal/service/shop_series_allocation/service.go`：在创建分配时处理 `EnableOneTimeCommission/OneTimeCommissionConfig` 并落库
+- [ ] 1.2 更新 `internal/service/shop_series_allocation/service.go`：在更新分配时支持更新一次性佣金配置并落库
+- [ ] 1.3 梯度配置：使用 `ShopSeriesOneTimeCommissionTierStore` 在创建/更新时写入 tiers（更新时先清理再重建）
+- [ ] 1.4 参数校验：启用一次性佣金时必须提供配置；fixed 必须有 mode/value；tiered 必须有 tiers
+
+## 2. 累计触发逻辑修复
+
+- [ ] 2.1 更新 `internal/service/commission_calculation/service.go`：累计触发场景每次支付成功都写回累计金额
+- [ ] 2.2 达到阈值时仅发放一次，发放后标记 `FirstCommissionPaid=true`
+
+## 3. 测试修复与补充
+
+- [ ] 3.1 修复 `tests/unit/my_commission_service_test.go`：将 `CommissionType` 调整为 `CommissionSource`
+- [ ] 3.2 新增测试：一次性佣金配置落库（含 tiered tiers 落库）
+- [ ] 3.3 新增测试：累计触发多次支付后达到阈值触发一次性佣金且不重复
+
+## 4. 验证
+
+- [ ] 4.1 运行 `go test ./...` 确保通过
+
--- a/openspec/changes/fix-order-activation-idempotency/.openspec.yaml
+++ b/openspec/changes/fix-order-activation-idempotency/.openspec.yaml
@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-01-29
+
--- a/openspec/changes/fix-order-activation-idempotency/design.md
+++ b/openspec/changes/fix-order-activation-idempotency/design.md
@@ -0,0 +1,40 @@
+# 订单激活幂等性修复 - 设计
+
+## 目标
+
+1. 同一订单被重复支付/重复回调/重复请求时，只会激活一次套餐使用记录。
+2. 重复请求返回“幂等成功”（不报错，不重复激活）。
+3. 避免因并发导致的重复插入。
+
+## 方案
+
+### 1) 以状态机作为幂等门闸
+
+将订单支付状态从 `pending` 变更为 `paid` 时使用条件更新：
+
+- `UPDATE tb_order SET payment_status=paid,... WHERE id=? AND payment_status=pending`
+- 若 `RowsAffected == 0`：
+  - 视为订单已被处理（可能已支付/已取消/已退款）
+  - 对“已支付”场景直接返回成功（幂等成功）
+  - 对“非待支付且非已支付”场景返回对应业务错误（例如已取消不允许支付）
+
+这样可以确保并发下只有一个请求能“拿到激活资格”。
+
+### 2) 激活逻辑只在首次成功支付后执行
+
+`activatePackage` 只在上述条件更新成功后执行；并确保激活过程内的数据读取使用同一个事务 `tx`（避免出现读取不一致或部分写入）。
+
+### 3) 防御性约束（可选但推荐）
+
+为 `tb_package_usage` 增加唯一约束（示例）：
+- 同一订单下，同一 `package_id` 只能有一条 usage
+- 以 `order_id + package_id` 为主（按当前业务：一个订单对应一个资源，且一次购买不应重复同套餐）
+
+如果未来允许同订单同套餐多份购买，则需要同时引入 `quantity` 或 usage 的明细拆分策略，再调整唯一约束。
+
+## 验收标准
+
+- 重复调用钱包支付/支付回调接口，不会重复生成 `tb_package_usage` 记录。
+- 幂等重复请求返回成功。
+- 新增测试通过。
+
--- a/openspec/changes/fix-order-activation-idempotency/proposal.md
+++ b/openspec/changes/fix-order-activation-idempotency/proposal.md
@@ -0,0 +1,23 @@
+# 订单激活幂等性修复（同订单只激活一次）
+
+## Why
+
+业务规则确认：**同一个订单只能激活一次**，不允许重复生成套餐生效记录。
+
+当前订单支付成功后会生成 `PackageUsage`（套餐使用记录）。在并发请求、回调重放、网络重试等场景下，如果缺少幂等控制，可能重复插入套餐使用记录，导致用户重复获得权益，属于高风险资金/权益漏洞。
+
+## What Changes
+
+- **支付状态原子转换**：将“待支付 -> 已支付”的状态变更做成原子操作（带条件更新），只有第一次成功转换才会触发套餐激活。
+- **激活过程幂等**：`activatePackage` 只在“首次支付成功”场景执行；重复请求返回“幂等成功”（你确认 A=1）。
+- **可选防御性约束**：为 `tb_package_usage` 增加必要的唯一约束或幂等检查，防止异常路径插入重复记录。
+- **补充测试**：覆盖并发/重复调用场景，验证不会重复激活。
+
+## Impact
+
+涉及模块（预期）：
+- Service：`internal/service/order/service.go`
+- Store（可选）：`internal/store/postgres/order_store.go` / `internal/store/postgres/order_item_store.go`
+- 迁移（可选）：新增唯一索引
+- 测试：`internal/service/order/service_test.go` 或 `tests/integration/*`
+
--- a/openspec/changes/fix-order-activation-idempotency/tasks.md
+++ b/openspec/changes/fix-order-activation-idempotency/tasks.md
@@ -0,0 +1,22 @@
+# 订单激活幂等性修复 - 实现任务
+
+## 1. 状态原子转换
+
+- [ ] 1.1 在 `internal/service/order/service.go` 中将支付成功状态更新改为条件更新（仅 `pending -> paid` 成功时继续）
+- [ ] 1.2 重复请求处理：当订单已支付时返回成功（幂等成功）；当订单为已取消/已退款等非待支付状态时返回业务错误
+
+## 2. 激活幂等与事务一致性
+
+- [ ] 2.1 调整 `activatePackage`：只在首次支付成功后执行
+- [ ] 2.2 确保 `activatePackage` 内部读取订单明细/套餐信息使用事务 `tx`（避免使用非事务 DB 导致不一致）
+
+## 3. 防御性约束（可选）
+
+- [ ] 3.1 评估并新增 `tb_package_usage` 的唯一索引（例如 `order_id + package_id`），并提供 down.sql
+- [ ] 3.2 对应调整代码：若插入触发唯一冲突，按幂等成功处理或提前查询避免冲突
+
+## 4. 测试与验证
+
+- [ ] 4.1 新增单元/集成测试：重复支付/重复回调不会重复插入 usage
+- [ ] 4.2 运行 `go test ./...` 确保通过
+