# Asset Allocation Record

## Purpose

管理资产（IoT 卡、设备）在平台与代理商之间的流转记录，支持分配和回收操作的完整追溯。

## Requirements

### Requirement: 资产分配记录查询

系统 SHALL 提供资产分配记录的查询功能，支持查看卡和设备在平台与代理商之间的流转历史。

**记录类型**:
- `allocate`: 分配记录（上级分配给下级）
- `recall`: 回收记录（上级从下级回收）

**资产类型**:
- `iot_card`: 物联网卡（单卡）
- `device`: 设备（未来扩展）

**查询条件**:
- `allocation_type`（可选）: 分配类型，枚举值 "allocate" | "recall"
- `asset_type`（可选）: 资产类型，枚举值 "iot_card" | "device"
- `asset_identifier`（可选）: 资产标识符（ICCID 或设备号），模糊匹配
- `allocation_no`（可选）: 分配单号，精确匹配
- `from_shop_id`（可选）: 来源店铺 ID
- `to_shop_id`（可选）: 目标店铺 ID
- `operator_id`（可选）: 操作人 ID
- `created_at_start`（可选）: 创建时间起始
- `created_at_end`（可选）: 创建时间结束

**分页**:
- 默认每页 20 条，最大每页 100 条
- 返回总记录数和总页数

**数据权限**:
- 平台用户可查看所有记录
- 代理用户只能查看与自己店铺相关的记录（作为来源或目标）

**API 端点**: `GET /api/admin/asset-allocation-records`

**响应字段**:
- `id`: 记录 ID
- `allocation_no`: 分配单号
- `allocation_type`: 分配类型
- `allocation_type_name`: 分配类型名称（分配/回收）
- `asset_type`: 资产类型
- `asset_type_name`: 资产类型名称（物联网卡/设备）
- `asset_id`: 资产 ID
- `asset_identifier`: 资产标识符
- `from_owner_type`: 来源所有者类型
- `from_owner_id`: 来源所有者 ID
- `from_owner_name`: 来源所有者名称
- `to_owner_type`: 目标所有者类型
- `to_owner_id`: 目标所有者 ID
- `to_owner_name`: 目标所有者名称
- `operator_id`: 操作人 ID
- `operator_name`: 操作人名称
- `remark`: 备注
- `created_at`: 创建时间

#### Scenario: 查询所有分配记录

- **WHEN** 平台管理员查询分配记录列表，不带任何筛选条件
- **THEN** 系统返回所有分配和回收记录，按创建时间倒序排列

#### Scenario: 按资产类型筛选记录

- **WHEN** 管理员查询资产类型为 "iot_card" 的记录
- **THEN** 系统只返回物联网卡的分配/回收记录，不包含设备记录

#### Scenario: 按分配类型筛选记录

- **WHEN** 管理员查询分配类型为 "allocate" 的记录
- **THEN** 系统只返回分配记录，不包含回收记录

#### Scenario: 按 ICCID 模糊查询

- **WHEN** 管理员输入 asset_identifier = "8986001"
- **THEN** 系统返回 ICCID 包含 "8986001" 的所有分配记录

#### Scenario: 代理查询自己相关的记录

- **WHEN** 代理用户（店铺 ID=10）查询分配记录
- **THEN** 系统只返回 from_owner_id=10 或 to_owner_id=10 的记录

---

### Requirement: 资产分配记录详情

系统 SHALL 提供资产分配记录详情查询功能。

**API 端点**: `GET /api/admin/asset-allocation-records/:id`

**响应**:
- 包含记录的所有字段
- 关联卡 ID 列表（如果是设备分配，包含设备下的所有卡 ID）

#### Scenario: 查询分配记录详情

- **WHEN** 管理员查询分配记录详情（ID=1）
- **THEN** 系统返回该记录的完整信息，包括来源/目标所有者名称、操作人名称等

#### Scenario: 查询不存在的记录

- **WHEN** 管理员查询不存在的分配记录（ID=999）
- **THEN** 系统返回 404 错误，提示"分配记录不存在"