feat: 资产标识符标准化、资产历史订单查询及导入虚拟号强制验证
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 7m21s

主要变更:
- 新增 AssetIdentifier 模型及 Store,统一管理资产标识符(ICCID/IMEI/SN 等)
- 新增迁移:asset_identifier 表、order 表新增 asset_identifier 字段、iot_card.virtual_no NOT NULL 约束
- 资产 Handler/Service/Route 全面重构,支持标识符路由查询与解析
- 新增资产历史订单查询接口,支持跨设备/卡/钱包维度的订单聚合
- 设备与物联卡导入任务强制校验虚拟号,缺失时直接拒绝
- Excel 工具函数优化,前端导入指引文档同步更新
- 归档三个 OpenSpec 提案:asset-identifier-standardization、asset-historical-orders、import-mandatory-virtual-no
- 更新 OpenAPI 文档及相关 DTO

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-04-07 17:39:36 +08:00
parent 7e489a19fb
commit 80c6f6c756
69 changed files with 3039 additions and 851 deletions

View File

@@ -0,0 +1,33 @@
## Why
当前系统的资产详情页面没有"历史订单"维度。管理员无法在查看某个资产时直接知道它卖给过谁、买过哪些套餐。换货流程(`ExchangeOrder`)已经在数据库层记录了旧资产→新资产的映射关系,但没有被利用来追溯前代订单。随着资产复用(换货后二次销售)场景增多,管理员需要一种方式能追溯到"这个资产的来源及历史"。
## What Changes
- **[NEW]** 新增 B 端接口:`GET /api/admin/assets/:identifier/orders`,查询某资产本代的历史订单
- **[NEW]** 支持查询参数 `include_previous=true`,通过换货链追溯并返回前代资产的订单(附带世代标注)
- 接口路径遵循提案一中已确立的 `:identifier` 统一规范(依赖提案一完成后的注册表和路由规范)
## Capabilities
### New Capabilities
- `asset-historical-orders`:资产往期订单查询接口,支持本代/跨代两种视图,响应中明确标注每条订单所属世代
### Modified Capabilities
(无——本提案仅新增接口,不修改现有接口行为)
## Impact
**受影响的代码**
- `internal/handler/admin/asset.go`:新增 `Orders` handler
- `internal/routes/asset.go`:注册新路由
- `internal/service/asset/service.go`:新增 `GetOrders()` 方法,包含换货链追溯逻辑
- `internal/store/postgres/order_store.go`:新增按 `asset_identifier` 精确查询(依赖提案一的 `asset_identifier` 快照字段)
- `internal/store/postgres/exchange_order_store.go`:新增按资产 ID 查询换货链的方法
- `internal/model/dto/asset_dto.go`:新增 `AssetOrdersRequest``AssetOrdersResponse``AssetOrderItem` DTO
- `cmd/api/docs.go``cmd/gendocs/main.go`:注册新 Handler
**前置依赖**
- 提案一(`asset-identifier-standardization`)必须先完成:本提案依赖 `Order.asset_identifier` 快照字段和统一的 `:identifier` 路由规范