docs(02-01): 完成 PERM+FIN+POLL 9项修复计划 PERM-01/02 FIN-01/02/03 POLL-01/02/03/04

docs/前端接口变更说明.md

@@ -1,6 +1,6 @@
 # 前端接口变更说明
 
-> 最后更新：2026-03-19
+> 最后更新：2026-03-20
 
 ---
 
@@ -37,7 +37,9 @@
 | 接口 | 变更内容 |
 |------|----------|
 | `POST /api/admin/shop-package-batch-pricing/batch-update` | 仅支持批量调整成本价（移除 `pricing_target`） |
-| 所有返回 `PackageResponse` 的套餐列表接口 | 响应新增 `retail_price` 字段 |
+| 所有返回 `PackageResponse` 的套餐接口 | 响应新增 `virtual_ratio`、`one_time_commission_amount`、`tier_info`、`calendar_type`、`data_reset_cycle`、`enable_realname_activation` 等字段 |
+| `GET /api/admin/iot-cards/standalone` | 响应新增 `virtual_no`（虚拟号）字段 |
+| `GET /api/admin/devices` | `device_no` 重命名为 `virtual_no`，新增 `bound_card_count`、`first_commission_paid`、`accumulated_recharge` 字段 |
 | 运营商创建/编辑接口 | 新增 `realname_link_type` 和 `realname_link_template` 字段 |
 
 ### 新增（后台）
@@ -54,6 +56,9 @@
 | `POST /api/admin/exchanges/:id/complete` | 确认完成 |
 | `POST /api/admin/exchanges/:id/cancel` | 取消换货 |
 | `POST /api/admin/exchanges/:id/renew` | 旧资产转新（generation+1） |
+| 微信支付配置管理（8 个接口） | `GET/POST/PUT/DELETE /api/admin/wechat-configs` 及 `active`、`activate`、`deactivate` 子路由 |
+| 代理预充值（4 个接口） | `/api/admin/agent-recharges` 创建/列表/详情/线下确认 |
+| 资产管理（11 个接口） | `/api/admin/assets/*` 资产解析、状态刷新、套餐、停复机、钱包概况/流水 |
 
 ### 新增（C 端）
 
@@ -124,13 +129,57 @@ POST /api/admin/shop-package-batch-pricing/batch-update
 
 ---
 
-### 套餐列表响应新增 `retail_price` 字段
+### 套餐响应新增字段（`PackageResponse`）
 
-所有返回 `PackageResponse` 的套餐列表接口，响应体新增字段：
+所有返回 `PackageResponse` 的套餐接口，响应体新增字段：
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `retail_price` | int64 | 零售价（单位：分），代理商可见 |
+| `retail_price` | int64 | 零售价（分），代理商可见 |
+| `profit_margin` | int64 | 利润空间（分），仅代理用户可见 |
+| `current_commission_rate` | string | 当前返佣比例，仅代理用户可见 |
+| `one_time_commission_amount` | int64 | 一次性佣金金额（分），代理视角 |
+| `tier_info` | object | 梯度返佣信息（含 `current_rate` / `next_threshold` / `next_rate`），仅代理可见 |
+| `virtual_ratio` | float64 | 虚流量比例（`real_data_mb/virtual_data_mb`） |
+| `calendar_type` | string | 套餐周期类型：`natural_month` / `by_day` |
+| `duration_days` | int | 套餐天数（`calendar_type=by_day` 时有值） |
+| `data_reset_cycle` | string | 流量重置周期：`daily` / `monthly` / `yearly` / `none` |
+| `enable_realname_activation` | bool | 是否启用实名激活 |
+
+---
+
+### IoT 卡列表响应新增 `virtual_no` 字段
+
+接口：
+
+```
+GET /api/admin/iot-cards/standalone
+```
+
+响应体新增字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `virtual_no` | string | 卡虚拟号（用于客服查找资产） |
+
+---
+
+### 设备列表字段调整
+
+接口：
+
+```
+GET /api/admin/devices
+```
+
+字段变更如下：
+
+| 变更类型 | 字段 | 类型 | 说明 |
+|----------|------|------|------|
+| 重命名 | `device_no` → `virtual_no` | string | 设备虚拟号/别名 |
+| 新增 | `bound_card_count` | int | 绑定卡数量 |
+| 新增 | `first_commission_paid` | bool | 一次性佣金是否已发放 |
+| 新增 | `accumulated_recharge` | int64 | 累计充值金额（分） |
 
 ---
 
@@ -360,6 +409,651 @@ flowchart TD
 
 ---
 
+### 微信支付配置管理
+
+> 权限：仅超级管理员和平台用户可访问。
+
+#### W1 获取当前生效的支付配置
+
+```
+GET /api/admin/wechat-configs/active
+```
+
+- **认证**：需要后台 Bearer Token
+- **请求参数**：无
+
+**响应体（`WechatConfigResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | uint | 配置ID |
+| `name` | string | 配置名称 |
+| `description` | string | 配置描述 |
+| `provider_type` | string | 支付渠道类型 (`wechat`:微信直连, `fuiou`:富友) |
+| `is_active` | bool | 是否激活 |
+| `oa_app_id` | string | 公众号AppID |
+| `oa_app_secret` | string | 公众号AppSecret（已脱敏） |
+| `oa_token` | string | 公众号Token（已脱敏） |
+| `oa_aes_key` | string | 公众号AES加密Key（已脱敏） |
+| `oa_oauth_redirect_url` | string | OAuth回调地址 |
+| `miniapp_app_id` | string | 小程序AppID |
+| `miniapp_app_secret` | string | 小程序AppSecret（已脱敏） |
+| `wx_mch_id` | string | 微信商户号 |
+| `wx_api_v3_key` | string | 微信APIv3密钥（已脱敏） |
+| `wx_api_v2_key` | string | 微信APIv2密钥（已脱敏） |
+| `wx_cert_content` | string | 微信支付证书内容（配置状态） |
+| `wx_key_content` | string | 微信支付密钥内容（配置状态） |
+| `wx_serial_no` | string | 微信证书序列号 |
+| `wx_notify_url` | string | 微信支付回调地址 |
+| `fy_ins_cd` | string | 富友机构号 |
+| `fy_mchnt_cd` | string | 富友商户号 |
+| `fy_term_id` | string | 富友终端号 |
+| `fy_private_key` | string | 富友私钥（配置状态） |
+| `fy_public_key` | string | 富友公钥（配置状态） |
+| `fy_api_url` | string | 富友API地址 |
+| `fy_notify_url` | string | 富友支付回调地址 |
+| `created_at` | string | 创建时间 |
+| `updated_at` | string | 更新时间 |
+
+**敏感字段说明**：
+- 短密钥字段（如 `oa_app_secret`、`wx_api_v3_key`）返回 `xxxx***xxxx` 脱敏形式。
+- 长文本密钥/证书字段（如 `wx_cert_content`、`fy_private_key`）返回 `[已配置]` 或 `[未配置]`。
+
+---
+
+#### W2 支付配置列表
+
+```
+GET /api/admin/wechat-configs
+```
+
+- **认证**：需要后台 Bearer Token
+
+**Query 参数：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page` | int | 否 | 页码，最小 1 |
+| `page_size` | int | 否 | 每页数量，1~100 |
+| `provider_type` | string | 否 | 支付渠道类型 (`wechat`/`fuiou`) |
+| `is_active` | bool | 否 | 是否激活 (`true`:已激活, `false`:未激活) |
+
+**响应体（`WechatConfigListResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `list` | array | 配置列表（每项字段同 `WechatConfigResponse`） |
+| `total` | int64 | 总数 |
+| `page` | int | 当前页 |
+| `page_size` | int | 每页数量 |
+
+---
+
+#### W3 创建支付配置
+
+```
+POST /api/admin/wechat-configs
+```
+
+- **认证**：需要后台 Bearer Token
+
+**请求体（`CreateWechatConfigRequest`）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 配置名称 |
+| `description` | string | 否 | 配置描述 |
+| `provider_type` | string | 是 | 支付渠道类型 (`wechat`:微信直连, `fuiou`:富友) |
+| `oa_app_id` | string | 否 | 公众号AppID |
+| `oa_app_secret` | string | 否 | 公众号AppSecret |
+| `oa_token` | string | 否 | 公众号Token |
+| `oa_aes_key` | string | 否 | 公众号AES加密Key |
+| `oa_oauth_redirect_url` | string | 否 | OAuth回调地址 |
+| `miniapp_app_id` | string | 否 | 小程序AppID |
+| `miniapp_app_secret` | string | 否 | 小程序AppSecret |
+| `wx_mch_id` | string | 否 | 微信商户号 |
+| `wx_api_v3_key` | string | 否 | 微信APIv3密钥 |
+| `wx_api_v2_key` | string | 否 | 微信APIv2密钥 |
+| `wx_cert_content` | string | 否 | 微信支付证书内容(PEM格式) |
+| `wx_key_content` | string | 否 | 微信支付密钥内容(PEM格式) |
+| `wx_serial_no` | string | 否 | 微信证书序列号 |
+| `wx_notify_url` | string | 否 | 微信支付回调地址 |
+| `fy_ins_cd` | string | 否 | 富友机构号 |
+| `fy_mchnt_cd` | string | 否 | 富友商户号 |
+| `fy_term_id` | string | 否 | 富友终端号 |
+| `fy_private_key` | string | 否 | 富友私钥(PEM格式) |
+| `fy_public_key` | string | 否 | 富友公钥(PEM格式) |
+| `fy_api_url` | string | 否 | 富友API地址 |
+| `fy_notify_url` | string | 否 | 富友支付回调地址 |
+
+**响应体**：`WechatConfigResponse`（字段同 W1，敏感字段脱敏返回）
+
+---
+
+#### W4 支付配置详情
+
+```
+GET /api/admin/wechat-configs/:id
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`id`（配置ID）
+- **响应体**：`WechatConfigResponse`（字段同 W1，敏感字段脱敏返回）
+
+---
+
+#### W5 更新支付配置
+
+```
+PUT /api/admin/wechat-configs/:id
+```
+
+- **认证**：需要后台 Bearer Token
+
+**路径参数：** `id`（配置ID）
+
+**请求体（`UpdateWechatConfigRequest`，全字段可选）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 否 | 配置名称 |
+| `description` | string | 否 | 配置描述 |
+| `provider_type` | string | 否 | 支付渠道类型 (`wechat`:微信直连, `fuiou`:富友) |
+| `oa_app_id` | string | 否 | 公众号AppID |
+| `oa_app_secret` | string | 否 | 公众号AppSecret |
+| `oa_token` | string | 否 | 公众号Token |
+| `oa_aes_key` | string | 否 | 公众号AES加密Key |
+| `oa_oauth_redirect_url` | string | 否 | OAuth回调地址 |
+| `miniapp_app_id` | string | 否 | 小程序AppID |
+| `miniapp_app_secret` | string | 否 | 小程序AppSecret |
+| `wx_mch_id` | string | 否 | 微信商户号 |
+| `wx_api_v3_key` | string | 否 | 微信APIv3密钥 |
+| `wx_api_v2_key` | string | 否 | 微信APIv2密钥 |
+| `wx_cert_content` | string | 否 | 微信支付证书内容(PEM格式) |
+| `wx_key_content` | string | 否 | 微信支付密钥内容(PEM格式) |
+| `wx_serial_no` | string | 否 | 微信证书序列号 |
+| `wx_notify_url` | string | 否 | 微信支付回调地址 |
+| `fy_ins_cd` | string | 否 | 富友机构号 |
+| `fy_mchnt_cd` | string | 否 | 富友商户号 |
+| `fy_term_id` | string | 否 | 富友终端号 |
+| `fy_private_key` | string | 否 | 富友私钥(PEM格式) |
+| `fy_public_key` | string | 否 | 富友公钥(PEM格式) |
+| `fy_api_url` | string | 否 | 富友API地址 |
+| `fy_notify_url` | string | 否 | 富友支付回调地址 |
+
+**响应体**：`WechatConfigResponse`（字段同 W1，敏感字段脱敏返回）
+
+---
+
+#### W6 删除支付配置
+
+```
+DELETE /api/admin/wechat-configs/:id
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`id`（配置ID）
+- **请求体**：无
+- **响应体**：无（仅返回统一成功响应）
+
+---
+
+#### W7 激活支付配置
+
+```
+POST /api/admin/wechat-configs/:id/activate
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`id`（配置ID）
+- **请求体**：无
+- **响应体**：`WechatConfigResponse`（字段同 W1，敏感字段脱敏返回）
+
+---
+
+#### W8 停用支付配置
+
+```
+POST /api/admin/wechat-configs/:id/deactivate
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`id`（配置ID）
+- **请求体**：无
+- **响应体**：`WechatConfigResponse`（字段同 W1，敏感字段脱敏返回）
+
+---
+
+### 代理预充值
+
+> 权限：企业账号无权访问。
+
+#### R1 创建代理充值订单
+
+```
+POST /api/admin/agent-recharges
+```
+
+- **认证**：需要后台 Bearer Token
+
+**请求体（`CreateAgentRechargeRequest`）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `shop_id` | uint | 是 | 目标店铺ID，代理只能填自己店铺 |
+| `amount` | int64 | 是 | 充值金额（分），范围100元~100万元 |
+| `payment_method` | string | 是 | 支付方式 (`wechat`:微信在线支付, `offline`:线下转账仅平台可用) |
+
+**响应体（`AgentRechargeResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | uint | 充值记录ID |
+| `recharge_no` | string | 充值单号(ARCH前缀) |
+| `shop_id` | uint | 店铺ID |
+| `shop_name` | string | 店铺名称 |
+| `agent_wallet_id` | uint | 代理钱包ID |
+| `amount` | int64 | 充值金额（分） |
+| `payment_method` | string | 支付方式 (`wechat`:微信在线支付, `offline`:线下转账) |
+| `payment_channel` | string | 实际支付通道 (`wechat_direct`:微信直连, `fuyou`:富友, `offline`:线下转账) |
+| `payment_config_id` | uint | 关联支付配置ID，线下充值为 `null` |
+| `payment_transaction_id` | string | 第三方支付流水号 |
+| `status` | int | 状态 (1:待支付, 2:已完成, 3:已取消) |
+| `paid_at` | string | 支付时间 |
+| `completed_at` | string | 完成时间 |
+| `created_at` | string | 创建时间 |
+| `updated_at` | string | 更新时间 |
+
+---
+
+#### R2 代理充值订单列表
+
+```
+GET /api/admin/agent-recharges
+```
+
+- **认证**：需要后台 Bearer Token
+
+**Query 参数（`AgentRechargeListRequest`）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page` | int | 否 | 页码，默认1 |
+| `page_size` | int | 否 | 每页条数，默认20，最大100 |
+| `shop_id` | uint | 否 | 按店铺ID过滤 |
+| `status` | int | 否 | 按状态过滤 (1:待支付, 2:已完成, 3:已取消) |
+| `start_date` | string | 否 | 创建时间起始日期(YYYY-MM-DD) |
+| `end_date` | string | 否 | 创建时间截止日期(YYYY-MM-DD) |
+
+**响应体（`AgentRechargeListResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | int64 | 总记录数 |
+| `page` | int | 当前页码 |
+| `page_size` | int | 每页条数 |
+| `list` | array | 充值记录列表（每项字段同 `AgentRechargeResponse`） |
+
+---
+
+#### R3 代理充值订单详情
+
+```
+GET /api/admin/agent-recharges/:id
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`id`（充值记录ID）
+- **响应体**：`AgentRechargeResponse`（字段同 R1）
+
+---
+
+#### R4 确认线下充值
+
+```
+POST /api/admin/agent-recharges/:id/offline-pay
+```
+
+- **认证**：需要后台 Bearer Token
+
+**路径参数：** `id`（充值记录ID）
+
+**请求体（`AgentOfflinePayRequest`）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `operation_password` | string | 是 | 操作密码 |
+
+**响应体**：`AgentRechargeResponse`（字段同 R1）
+
+---
+
+### 资产管理
+
+#### Z1 通过标识符解析资产
+
+```
+GET /api/admin/assets/resolve/:identifier
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`identifier`（资产标识符，支持虚拟号/ICCID/IMEI/SN/MSISDN）
+
+**响应体（`AssetResolveResponse`）：**
+
+**基础字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `asset_type` | string | 资产类型：`card` 或 `device` |
+| `asset_id` | uint | 资产数据库ID |
+| `virtual_no` | string | 虚拟号 |
+| `status` | int | 资产状态 |
+| `batch_no` | string | 批次号 |
+| `shop_id` | uint | 所属店铺ID |
+| `shop_name` | string | 所属店铺名称 |
+| `series_id` | uint | 套餐系列ID |
+| `series_name` | string | 套餐系列名称 |
+| `first_commission_paid` | bool | 一次性佣金是否已发放 |
+| `accumulated_recharge` | int64 | 累计充值金额(分) |
+| `activated_at` | string | 激活时间 |
+| `created_at` | string | 创建时间 |
+| `updated_at` | string | 更新时间 |
+
+**状态聚合字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `real_name_status` | int | 实名状态：0未实名 1实名中 2已实名 |
+| `current_package` | string | 当前套餐名称（无套餐时为空） |
+| `package_total_mb` | int64 | 当前套餐总虚流量(MB)，已按 `virtual_ratio` 换算 |
+| `package_used_mb` | float64 | 当前已用虚流量(MB)，已按 `virtual_ratio` 换算 |
+| `package_remain_mb` | float64 | 当前套餐剩余虚流量(MB)，已按 `virtual_ratio` 换算 |
+| `device_protect_status` | string | 设备保护期状态：`none`/`stop`/`start`（仅 `asset_type=device`） |
+
+**绑定关系字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `iccid` | string | 卡ICCID（`asset_type=card`） |
+| `bound_device_id` | uint | 绑定设备ID（`asset_type=card`） |
+| `bound_device_no` | string | 绑定设备虚拟号（`asset_type=card`） |
+| `bound_device_name` | string | 绑定设备名称（`asset_type=card`） |
+| `bound_card_count` | int | 绑定卡数量（`asset_type=device`） |
+| `cards` | array | 绑定卡列表（`asset_type=device`，每项字段见下） |
+
+**`cards` 子项（`BoundCardInfo`）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `card_id` | uint | 卡ID |
+| `iccid` | string | ICCID |
+| `msisdn` | string | 手机号 |
+| `network_status` | int | 网络状态：0停机 1开机 |
+| `real_name_status` | int | 实名状态 |
+| `slot_position` | int | 插槽位置 |
+
+**设备专属字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `device_name` | string | 设备名称 |
+| `imei` | string | 设备IMEI |
+| `sn` | string | 设备序列号 |
+| `device_model` | string | 设备型号 |
+| `device_type` | string | 设备类型 |
+| `max_sim_slots` | int | 最大插槽数 |
+| `manufacturer` | string | 制造商 |
+
+**卡专属字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `carrier_id` | uint | 运营商ID |
+| `carrier_type` | string | 运营商类型 |
+| `carrier_name` | string | 运营商名称 |
+| `msisdn` | string | 手机号 |
+| `imsi` | string | IMSI |
+| `card_category` | string | 卡业务类型 |
+| `supplier` | string | 供应商 |
+| `activation_status` | int | 激活状态 |
+| `enable_polling` | bool | 是否参与轮询 |
+| `network_status` | int | 网络状态：0停机 1开机（仅 `asset_type=card`） |
+
+---
+
+#### Z2 资产实时状态
+
+```
+GET /api/admin/assets/:asset_type/:id/realtime-status
+```
+
+- **认证**：需要后台 Bearer Token
+
+**路径参数：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `asset_type` | string | 是 | 资产类型：`card` 或 `device` |
+| `id` | uint | 是 | 资产ID |
+
+**响应体（`AssetRealtimeStatusResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `asset_type` | string | 资产类型：`card` 或 `device` |
+| `asset_id` | uint | 资产ID |
+| `network_status` | int | 网络状态（`asset_type=card`）：0停机 1开机 |
+| `real_name_status` | int | 实名状态（`asset_type=card`） |
+| `current_month_usage_mb` | float64 | 本月已用流量MB（`asset_type=card`） |
+| `last_sync_time` | string | 最后同步时间（`asset_type=card`） |
+| `device_protect_status` | string | 保护期状态（`asset_type=device`）：`none`/`stop`/`start` |
+| `cards` | array | 绑定卡状态列表（`asset_type=device`，每项字段同 `BoundCardInfo`） |
+
+---
+
+#### Z3 刷新资产状态
+
+```
+POST /api/admin/assets/:asset_type/:id/refresh
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：同 Z2
+- **请求体**：无
+- **响应体**：`AssetRealtimeStatusResponse`（字段同 Z2）
+
+---
+
+#### Z4 资产套餐列表
+
+```
+GET /api/admin/assets/:asset_type/:id/packages
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：同 Z2
+
+**响应体（数组，每项为 `AssetPackageResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `package_usage_id` | uint | 套餐使用记录ID |
+| `package_id` | uint | 套餐ID |
+| `package_name` | string | 套餐名称 |
+| `package_type` | string | 套餐类型：`formal`/`addon` |
+| `usage_type` | string | 使用类型：`single_card`/`device` |
+| `status` | int | 状态：0待生效 1生效中 2已用完 3已过期 4已失效 |
+| `status_name` | string | 状态名称 |
+| `data_limit_mb` | int64 | 套餐真流量总量(MB) |
+| `virtual_limit_mb` | int64 | 套餐虚流量总量(MB)，按 `virtual_ratio` 换算 |
+| `data_usage_mb` | int64 | 已用真流量(MB) |
+| `virtual_used_mb` | float64 | 已用虚流量(MB)，按 `virtual_ratio` 换算 |
+| `virtual_remain_mb` | float64 | 剩余虚流量(MB)，按 `virtual_ratio` 换算 |
+| `virtual_ratio` | float64 | 虚流量比例(real/virtual) |
+| `activated_at` | string | 激活时间（待生效套餐为空） |
+| `expires_at` | string | 到期时间（待生效套餐为空） |
+| `master_usage_id` | uint | 主套餐ID（加油包时有值） |
+| `priority` | int | 优先级 |
+| `created_at` | string | 创建时间 |
+
+---
+
+#### Z5 当前生效套餐
+
+```
+GET /api/admin/assets/:asset_type/:id/current-package
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：同 Z2
+- **响应体**：`AssetPackageResponse`（字段同 Z4）
+
+---
+
+#### Z6 设备停机
+
+```
+POST /api/admin/assets/device/:device_id/stop
+```
+
+- **认证**：需要后台 Bearer Token
+
+**路径参数：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `device_id` | uint | 是 | 设备ID |
+
+**响应体（`DeviceSuspendResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success_count` | int | 成功停机卡数 |
+| `fail_count` | int | 失败卡数 |
+| `skip_count` | int | 跳过卡数（未实名或已停机） |
+| `failed_items` | array | 失败详情（`iccid` / `reason`） |
+
+---
+
+#### Z7 设备复机
+
+```
+POST /api/admin/assets/device/:device_id/start
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`device_id`（设备ID）
+- **请求体**：无
+- **响应体**：无（仅返回统一成功响应）
+
+---
+
+#### Z8 单卡停机
+
+```
+POST /api/admin/assets/card/:iccid/stop
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`iccid`（卡ICCID）
+- **请求体**：无
+- **响应体**：无（仅返回统一成功响应）
+
+---
+
+#### Z9 单卡复机
+
+```
+POST /api/admin/assets/card/:iccid/start
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：`iccid`（卡ICCID）
+- **请求体**：无
+- **响应体**：无（仅返回统一成功响应）
+
+---
+
+#### Z10 资产钱包概况
+
+```
+GET /api/admin/assets/:asset_type/:id/wallet
+```
+
+- **认证**：需要后台 Bearer Token
+- **路径参数**：同 Z2
+
+**响应体（`AssetWalletResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `wallet_id` | uint | 钱包数据库ID |
+| `resource_type` | string | 资源类型：`iot_card` 或 `device` |
+| `resource_id` | uint | 对应卡或设备的数据库ID |
+| `balance` | int64 | 总余额（分） |
+| `frozen_balance` | int64 | 冻结余额（分） |
+| `available_balance` | int64 | 可用余额 = `balance - frozen_balance`（分） |
+| `currency` | string | 币种，目前固定 CNY |
+| `status` | int | 钱包状态：1-正常 2-冻结 3-关闭 |
+| `status_text` | string | 状态文本 |
+| `created_at` | string | 创建时间（RFC3339） |
+| `updated_at` | string | 更新时间（RFC3339） |
+
+---
+
+#### Z11 资产钱包流水列表
+
+```
+GET /api/admin/assets/:asset_type/:id/wallet/transactions
+```
+
+- **认证**：需要后台 Bearer Token
+
+**路径参数：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `asset_type` | string | 是 | 资产类型：`card` 或 `device` |
+| `id` | uint | 是 | 资产ID |
+
+**Query 参数：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page` | int | 否 | 页码，默认1 |
+| `page_size` | int | 否 | 每页数量，默认20，最大100 |
+| `transaction_type` | string | 否 | 交易类型过滤：`recharge`/`deduct`/`refund` |
+| `start_time` | string | 否 | 开始时间（RFC3339） |
+| `end_time` | string | 否 | 结束时间（RFC3339） |
+
+**响应体（`AssetWalletTransactionListResponse`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `list` | array | 流水列表（每项字段见下） |
+| `total` | int64 | 总记录数 |
+| `page` | int | 当前页码 |
+| `page_size` | int | 每页数量 |
+| `total_pages` | int | 总页数 |
+
+**`list` 子项（`AssetWalletTransactionItem`）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | uint | 流水记录ID |
+| `transaction_type` | string | 交易类型：`recharge`/`deduct`/`refund` |
+| `transaction_type_text` | string | 交易类型文本：充值/扣款/退款 |
+| `amount` | int64 | 变动金额（分），充值为正数，扣款/退款为负数 |
+| `balance_before` | int64 | 变动前余额（分） |
+| `balance_after` | int64 | 变动后余额（分） |
+| `reference_type` | string | 关联业务类型：`recharge` 或 `order`（可空） |
+| `reference_no` | string | 关联业务编号：充值单号（CRCH…）或订单号（ORD…）（可空） |
+| `remark` | string | 备注（可空） |
+| `created_at` | string | 流水创建时间（RFC3339） |
+
+---
+
 ## 五、新增的 C 端接口
 
 所有接口位于 `/api/c/v1/` 下，**认证接口（`/auth/`）无需登录，其余全部需要 JWT 认证**（`Authorization: Bearer <token>`）。