junhong_cmp_fiber/openspec/changes/archive/2026-03-16-asset-wallet-interface/proposal.md

Why

asset-detail-refactor 完成了资产详情体系（解析、状态、套餐、停复机），但遗漏了资产钱包维度的查询入口：管理员无法在 Admin 端查看某张卡或设备的钱包余额与收支流水。同时，现有 CardWallet 系列命名（tb_card_wallet、CardWalletStore…）与实际承载的两种资产（iot_card + device）不符，趁本次新增接口前一并清理，统一更名为 AssetWallet。

What Changes

• BREAKING（内部重命名） CardWallet → AssetWallet：三张数据库表改名，对应 Model / Store / bootstrap / Redis Key 全量重命名；H5 recharge 接口的 JSON 字段名不变，前端零感知
• BREAKING（内部字段变更） tb_asset_wallet_transaction.reference_id (bigint) → reference_no (varchar 50)：存储充值单号（CRCH…）或订单号（ORD…），便于前端直接跳转
• 新增 在 WalletPay（卡钱包支付路径）中补写 AssetWalletTransaction 扣款流水（transaction_type="deduct", reference_no=order.OrderNo），修复现有流水表中扣款记录缺失的问题
• 新增 管理端资产钱包概况接口 GET /api/admin/assets/:asset_type/:id/wallet
• 新增 管理端资产钱包流水列表接口 GET /api/admin/assets/:asset_type/:id/wallet/transactions

Capabilities

New Capabilities

• asset-wallet-query：Admin 端查询资产（卡/设备）关联钱包的余额概况与收支流水，支持分页，含充值/扣款流水的来源编号可跳转

Modified Capabilities

• asset-wallet：tb_card_wallet、tb_card_wallet_transaction、tb_card_recharge_record 三张表统一改名为 tb_asset_wallet、tb_asset_wallet_transaction、tb_asset_recharge_record；reference_id (bigint) 字段改为 reference_no (varchar 50)；WalletPay 补写扣款 transaction 记录

Impact

数据库迁移：

• tb_card_wallet → tb_asset_wallet（含 reference_id → reference_no 字段变更）
• tb_card_wallet_transaction → tb_asset_wallet_transaction
• tb_card_recharge_record → tb_asset_recharge_record

Model 层：

• internal/model/card_wallet.go 全量重命名：CardWallet → AssetWallet、CardWalletTransaction → AssetWalletTransaction、CardRechargeRecord → AssetRechargeRecord
• AssetWalletTransaction.ReferenceID *uint → ReferenceNo *string

Store 层：

• card_wallet_store.go → asset_wallet_store.go（CardWalletStore → AssetWalletStore）
• card_wallet_transaction_store.go → asset_wallet_transaction_store.go
• card_recharge_store.go → asset_recharge_store.go

Service 层：

• internal/service/order/service.go：cardWalletStore → assetWalletStore；WalletPay 卡钱包路径补写扣款 transaction
• internal/service/recharge/service.go：cardWalletStore → assetWalletStore；交易记录写入 ReferenceNo = recharge.RechargeNo

Handler 层：

• 新增 internal/handler/admin/asset_wallet.go：AssetWalletHandler（两个新 Handler 方法）

路由层：

• internal/routes/asset.go 新增两条路由（wallet、wallet/transactions）

Bootstrap 层：

• internal/bootstrap/stores.go：CardWallet* → AssetWallet*
• internal/bootstrap/services.go：更新依赖注入

常量层：

• pkg/constants/redis.go：RedisCardWalletBalanceKey → RedisAssetWalletBalanceKey

DTO 层：

• internal/model/dto/ 新增 asset_wallet_dto.go：AssetWalletResponse、AssetWalletTransactionListRequest、AssetWalletTransactionListResponse、AssetWalletTransactionItem

API 文档：

• cmd/api/docs.go 和 cmd/gendocs/main.go 新增 AssetWalletHandler