4.6 KiB
4.6 KiB
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.tssrc/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.tssrc/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任务列表的筛选参数与分页响应结构（当前导出文档未包含该接口块）。