huang
f3297f0529
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
61 lines
3.6 KiB
Markdown
61 lines
3.6 KiB
Markdown
## 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`
|