49 lines
4.6 KiB
Markdown
49 lines
4.6 KiB
Markdown
# Change: 新增手机号资产关联管理（管理后台）
|
||
|
||
## Why
|
||
|
||
H5 短信验证通过后会产生「手机号—资产」关联，运营侧需要治理能力：查询存量关联、单条/批量/按 CSV 导入批量解绑，并在设备、单卡、资产详情等既有场景里直接看到该资产当前关联的手机号。目前管理后台没有任何关联查询与解绑入口，只能走数据库操作。
|
||
|
||
同时对象存储与导出契约需要同步扩展：上传用途新增 `phone_unbind_import`，卡/设备导出文件表头尾部新增「关联手机号」列。
|
||
|
||
本 Change 只覆盖管理后台（B 端）；H5 端的 `bind-phone` / `change-phone` / `need_bind_phone` 接口变更不在本 Change 范围，但「上限」与「换绑冲突」两句固定文案由后端统一返回、前端直接展示的能力需要保留。
|
||
|
||
## What Changes
|
||
|
||
- 新增“手机号资产关联”能力，仅超管/平台账号可见可操作（代理/企业/个人由后端 403 兜底）：
|
||
- `GET /api/admin/phone-asset-associations`：关联列表，支持资产标识（ICCID/虚拟号/IMEI/SN/接入号，精确匹配）、完整手机号（精确匹配）、状态（0 已失效 / 1 有效）、创建时间区间筛选，分页返回。
|
||
- `DELETE /api/admin/phone-asset-associations/{id}`：单条解绑，必须传 `reason`(1–500) + `confirmed=true`，缺一即拒绝；后端返回本次解除关系数。
|
||
- `POST /api/admin/phone-asset-associations/batch-unbind`：按资产集合批量解绑（按 `(asset_type, asset_id)` 去重，逐项独立执行），返回成功数/失败数/逐项结果，部分成功不回滚。
|
||
- `POST /api/admin/phone-asset-associations/unbind-imports`：创建 CSV 解绑导入任务（`file_key` + 任务级 `reason` + `confirmed`）。
|
||
- `GET /api/admin/phone-asset-associations/unbind-imports`：解绑导入任务列表。
|
||
- `GET /api/admin/phone-asset-associations/unbind-imports/{id}`：任务详情，含逐行状态/失败原因与解绑当时完整手机号快照。
|
||
- 既有接口字段新增：`GET /api/admin/devices`、`GET /api/admin/iot-cards/standalone`、`GET /api/admin/assets/resolve/{identifier}` 响应新增 `associated_phones: string[]`（完整手机号，无关联为空数组）。
|
||
- 卡导出、设备导出文件表头尾部新增「关联手机号」列（多号以「、」连接）；历史任务重导出仍按旧表头输出，前端导出任务列表/详情无需为此改动。
|
||
- `POST /api/admin/storage/upload-url` 的 `purpose` 枚举新增 `phone_unbind_import`（仅 .csv，目录前缀 `phone-unbind-imports/YYYY/MM/DD/uuid.csv`）。
|
||
- 前端自备能力：CSV 模板（表头 `资产标识,备注`，备注可选；UTF-8 可带 BOM，非 UTF-8 按 GBK 解码；无行数上限）；后端返回的固定失败文案直接展示；后台不提供「创建/补录关联」入口。
|
||
|
||
## Impact
|
||
|
||
- Affected specs:
|
||
- `phone-asset-association-management`
|
||
- Affected code:
|
||
- `src/api/modules/phoneAsset.ts`（新增）
|
||
- `src/types/api/phoneAsset.ts`（新增）
|
||
- `src/api/modules/index.ts`、`src/types/api/index.ts`
|
||
- `src/api/modules/storage.ts`（`FilePurpose` 增加 `phone_unbind_import`）
|
||
- `src/api/modules/device.ts`、`src/api/modules/card.ts`、`src/api/modules/asset.ts`（`associated_phones` 字段类型）
|
||
- `src/types/api/device.ts`、`src/types/api/card.ts`、`src/types/api/asset.ts`
|
||
- `src/views/asset-management/phone-asset-association/`（新增列表、解绑导入任务列表/详情页）
|
||
- `src/views/asset-management/device-list/index.vue`、`src/views/asset-management/iot-card-management/*`、`src/views/asset-management/asset-information/*`（新增「关联手机号」展示）
|
||
- `src/router/routesAlias.ts`、`src/router/routes/asyncRoutes.ts`（菜单与路由）
|
||
- 菜单、权限码与国际化文案配置文件
|
||
- Dependencies:
|
||
- 后端按 `docs/产品迭代8月份/手机号资产关联.md` 提供上述接口、Bearer JWT 鉴权与 403 语义。
|
||
- 解绑导入复用现有对象存储上传流程（`StorageService.getUploadUrl` + PUT 直传 + `file_key`）。
|
||
- 新增按钮/页面的权限编码以管理后台菜单权限配置为准，前端用 `v-permission` 与 `usePermission` 控制可见性。
|
||
- Breaking changes:
|
||
- 无。全部为新增页面、接口模块、类型字段与枚举扩展。
|
||
- 待确认契约（当前文档未完整提供，后端需在联调前明确）：
|
||
- `DELETE /phone-asset-associations/{id}` 的 `reason` / `confirmed` 传输位置（请求体字段名，当前导出文档缺少该请求体定义）。
|
||
- `GET /phone-asset-associations/unbind-imports` 任务列表的筛选参数与分页响应结构（当前导出文档未包含该接口块）。
|