feat: 7月迭代

docs/产品迭代7月份/七月迭代H5_C端改动说明.md

@@ -29,22 +29,6 @@
 POST /api/c/v1/auth/verify-asset
 ```
 
-管理后台相关接口：
-
-```http
-PUT /api/admin/shops/:id
-GET /api/admin/shops
-GET /api/admin/shops/:id
-```
-
-店铺字段：
-
-```json
-{
-  "client_login_disabled": true
-}
-```
-
 #### 预期效果
 
 - 被限制的店铺无法新登录 H5/C 端。
@@ -181,12 +165,6 @@ POST /api/c/v1/orders/create
 GET /api/c/v1/asset/info
 ```
 
-后台资产解析接口也会返回相关字段：
-
-```http
-GET /api/admin/assets/resolve/:identifier
-```
-
 #### 预期效果
 
 - 用户看到资产综合计算后的最终到期时间。
@@ -285,11 +263,11 @@ GET /api/c/v1/orders/:id
 
 - #84 H5 首页隐藏设备下 ICCID：本期确认不做。
 - #73 行业卡未实名复机：保持现有逻辑。
-- #94 状态同步和运营商回调：继续读取现有资产状态字段，无新增前端调用。
-- 企业微信审批回调：由企微服务器调用，前端禁止调用。
+- #94 状态同步和运营商回调：继续读取现有资产状态字段，无新增 H5/C 端调用。
+- 企业微信审批回调：H5/C 端不调用。
 - 原路退款、聚水潭、跨品类换货、分销码/佣金提现：本期不做。
 
-## 四、前端联调注意事项
+## 四、H5/C 端联调注意事项
 
 - 金额接口字段默认单位为“分”，页面展示时转换为“元”，提交时仍传整数分。
 - `effective_realname_policy` 和 `allowed_payment_methods` 必须以后端返回值为准。

docs/所需接口文档/new-api.md

@@ -0,0 +1,277 @@
+# C 端所需接口文档
+
+## 1. 通用约定
+
+- 测试环境：`https://cmp-api.boss160.cn`
+- 鉴权：除特别说明外，所有接口都需要登录后的 JWT。
+
+```http
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+- `identifier`：资产标识符，可传 SN、IMEI、虚拟号、ICCID 或 MSISDN，长度 1～50。
+- 金额单位：分。页面展示时转换为元，提交时仍传整数分。
+- 成功响应：`code = 0`。
+- 错误响应：`400` 参数错误、`401` 未认证或过期、`403` 无权访问、`500` 服务端错误。
+
+通用成功响应格式：
+
+```json
+{
+  "code": 0,
+  "data": {},
+  "msg": "success",
+  "timestamp": "2026-07-27T10:00:00+08:00"
+}
+```
+
+错误响应格式：
+
+```json
+{
+  "code": 1001,
+  "data": {},
+  "msg": "参数验证失败",
+  "timestamp": "2026-07-27T10:00:00+08:00"
+}
+```
+
+## 2. 接口清单
+
+| 用途 | 方法 | 路径 |
+| --- | --- | --- |
+| 获取资产信息 | GET | `/api/c/v1/asset/info` |
+| 充值前校验 | GET | `/api/c/v1/wallet/recharge-check` |
+| 创建套餐订单 | POST | `/api/c/v1/orders/create` |
+| 创建充值订单 | POST | `/api/c/v1/wallet/recharge` |
+| 订单列表 | GET | `/api/c/v1/orders` |
+| 订单详情 | GET | `/api/c/v1/orders/{id}` |
+
+## 3. 获取资产信息
+
+### 请求
+
+```http
+GET /api/c/v1/asset/info?identifier=1234567890
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `identifier` | string | 是 | 资产标识符，1～50 个字符 |
+
+### `data` 关键返回字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `asset_id` | integer | 资产 ID |
+| `asset_type` | string | `card` 卡、`device` 设备 |
+| `identifier` | string | 当前资产标识符 |
+| `iccid` / `msisdn` | string | 卡 ICCID / 手机号 |
+| `sn` / `imei` / `virtual_no` | string | 设备序列号 / IMEI / 虚拟号 |
+| `device_name` / `device_model` | string | 设备名称 / 型号 |
+| `carrier_name` / `carrier_type` | string | 运营商名称 / 类型（`CMCC`、`CUCC`、`CTCC`、`CBN`） |
+| `status` / `status_name` | integer / string | 资产归属状态：`1` 在库、`2` 已分销；卡沿用卡状态枚举 |
+| `activation_status` / `activation_status_name` | integer / string | 激活状态：`0` 未激活、`1` 已激活 |
+| `network_status` / `network_status_name` | integer / string | 网络状态：`0` 停机、`1` 开机 |
+| `real_name_status` / `real_name_status_name` | integer / string | 实名状态：`0` 未实名、`1` 已实名 |
+| `realname_policy` | string | 实名策略：`none`、`before_order`、`after_order` |
+| `effective_realname_policy` | string | 当前实际生效的实名策略 |
+| `realname_required` | boolean | 当前资产是否需要实名 |
+| `allowed_payment_methods` | string[] | 允许的支付方式：`wallet`、`wechat`、`alipay` |
+| `wallet_balance` | integer | 钱包余额，单位为分 |
+| `current_package_id` | integer | 当前主套餐 ID；无套餐时为 `0`，可用于续费 |
+| `current_package` | string | 当前套餐名称，无套餐时为空 |
+| `current_package_activated_at` | datetime / null | 当前主套餐开始时间 |
+| `current_package_expires_at` | datetime / null | 当前主套餐到期时间 |
+| `estimated_final_expires_at` | datetime / null | 预计最终到期时间 |
+| `days_until_final_expiry` | integer/null | 距预计最终到期的上海自然日天数 |
+| `expiry_estimate_status` | string | `exact` 精确、`waiting_activation` 待激活、`none` 无套餐、`invalid_data` 数据异常 |
+| `is_expiring` | boolean | 是否临期（精确推算且剩余 0～15 天） |
+| `enable_virtual_data` | boolean | 当前主套餐是否启用虚流量 |
+| `real_total_mb` / `real_used_mb` | integer | 真实总量 / 真实已用量，单位 MB |
+| `virtual_total_mb` / `virtual_used_mb` | integer / number | 业务停机阈值 / 展示已用量，单位 MB |
+| `reduction_pct` | number | 展示增幅比例：`real_total_mb / virtual_total_mb - 1` |
+| `cards` | object[] | 设备绑定卡列表，包含 ICCID、MSISDN、网络状态、实名状态、插槽位置等 |
+| `device_realtime` | object/null | 设备实时信息，包含在线状态、电量、信号、WiFi、客户端数等 |
+
+页面流量展示建议：总量使用 `real_total_mb`；已用量在 `enable_virtual_data = true` 时使用 `virtual_used_mb`，否则使用 `real_used_mb`。
+
+## 4. 充值前校验
+
+### 请求
+
+```http
+GET /api/c/v1/wallet/recharge-check?identifier=1234567890
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `identifier` | string | 是 | 资产标识符 |
+
+### `data` 返回字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `allowed_payment_methods` | string[]/null | 当前允许的支付方式：`wallet`、`wechat`、`alipay` |
+| `need_force_recharge` | boolean | 是否必须先完成强制充值 |
+| `force_recharge_amount` | integer | 强制充值金额，单位为分 |
+| `min_amount` | integer | 最小充值金额，单位为分 |
+| `max_amount` | integer | 最大充值金额，单位为分 |
+| `message` | string | 页面提示信息 |
+| `trigger_type` | string | 强制充值触发类型 |
+
+## 5. 创建套餐订单
+
+### 请求
+
+```http
+POST /api/c/v1/orders/create
+```
+
+```json
+{
+  "identifier": "1234567890",
+  "package_ids": [1001, 1002],
+  "payment_method": "wechat",
+  "app_type": "miniapp"
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `identifier` | string | 是 | 资产标识符 |
+| `package_ids` | integer[] | 是 | 套餐 ID 列表 |
+| `payment_method` | string | 是 | `wallet`、`wechat`、`alipay` |
+| `app_type` | string | 微信支付时是 | `official_account` 公众号、`miniapp` 小程序 |
+
+### `data` 返回字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `idempotent` | boolean | 是否返回了已存在的待支付订单 |
+| `order_type` | string | `package` 套餐订单、`recharge` 充值订单 |
+| `order` | object | 订单信息，见下表 |
+| `linked_package_info` | object | 关联套餐和强制充值信息 |
+| `recharge` | object/null | 自动充值信息 |
+| `pay_config` | object/null | 微信支付参数 |
+| `payment_link` | object/null | 支付宝或其他网页支付链接 |
+
+`order` 主要字段：`order_id`、`order_no`、`created_at`、`payment_method`、`payment_status`、`payment_status_name`、`total_amount`。
+
+- `payment_status`：`1` 待支付、`2` 已支付、`3` 已取消、`4` 已退款。
+- `linked_package_info`：`force_recharge_amount`、`package_names`、`total_package_amount`、`wallet_credit`，金额均为分。
+- `recharge`：`recharge_id`、`recharge_no`、`amount`、`status`、`status_name`、`auto_purchase_status`。
+- `pay_config`：`app_id`、`nonce_str`、`package`、`pay_sign`、`sign_type`、`timestamp`。
+- `payment_link`：`copy_link`、`qr_link`、`payment_no`、`pay_expire_at`。
+
+## 6. 创建充值订单
+
+### 请求
+
+```http
+POST /api/c/v1/wallet/recharge
+```
+
+```json
+{
+  "amount": 1000,
+  "identifier": "1234567890",
+  "payment_method": "wechat",
+  "app_type": "miniapp"
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `amount` | integer | 是 | 充值金额，1～10000000 分 |
+| `identifier` | string | 是 | 资产标识符 |
+| `payment_method` | string | 是 | `wechat` 微信支付、`alipay` 支付宝 |
+| `app_type` | string | 微信支付时是 | `official_account` 或 `miniapp` |
+
+### `data` 返回字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `recharge` | object | 充值信息：`recharge_id`、`recharge_no`、`amount`、`status` |
+| `pay_config` | object/null | 微信支付参数：`app_id`、`nonce_str`、`package`、`pay_sign`、`sign_type`、`timestamp` |
+| `payment_link` | object/null | 支付链接：`copy_link`、`qr_link`、`payment_no`、`pay_expire_at` |
+
+`recharge.status`：`0` 待支付、`1` 已支付、`2` 已关闭。
+
+## 7. 订单列表
+
+### 请求
+
+```http
+GET /api/c/v1/orders?identifier=1234567890&page=1&page_size=10
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `identifier` | string | 是 | 资产标识符 |
+| `payment_status` | integer | 否 | `1` 待支付、`2` 已支付、`3` 已取消、`4` 已退款 |
+| `page` | integer | 是 | 页码，从 1 开始 |
+| `page_size` | integer | 是 | 每页数量，1～100 |
+
+### `data` 返回字段
+
+```json
+{
+  "items": [],
+  "page": 1,
+  "size": 10,
+  "total": 0
+}
+```
+
+`items[]` 字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `order_id` / `order_no` | integer / string | 订单 ID / 订单号 |
+| `asset_id` / `asset_type` | integer / string | 资产 ID / `card` 或 `device` |
+| `asset_identifier` | string | 下单时资产标识快照；设备优先虚拟号，其次 IMEI |
+| `package_ids` / `package_names` | array | 套餐 ID / 名称列表 |
+| `payment_method` | string | `wallet`、`wechat`、`alipay` |
+| `payment_status` / `payment_status_name` | integer / string | 支付状态及中文名称 |
+| `total_amount` | integer | 订单总金额，单位为分 |
+| `created_at` | string | 创建时间 |
+
+## 8. 订单详情
+
+### 请求
+
+```http
+GET /api/c/v1/orders/{id}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | integer | 是 | 订单 ID，放在 URL 路径中 |
+
+### `data` 返回字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `order_id` / `order_no` | integer / string | 订单 ID / 订单号 |
+| `asset_id` / `asset_type` | integer / string | 资产 ID / `card` 或 `device` |
+| `asset_identifier` | string | 下单时资产标识快照 |
+| `packages` | object[] | 订单套餐明细 |
+| `payment_method` | string | 支付方式 |
+| `payment_status` / `payment_status_name` | integer / string | 支付状态及中文名称 |
+| `total_amount` | integer | 订单总金额，单位为分 |
+| `created_at` | string | 创建时间 |
+| `paid_at` | string/null | 支付时间 |
+| `completed_at` | string/null | 完成时间 |
+
+`packages[]` 字段：`package_id`、`package_name`、`package_type`（`formal` 正式套餐、`addon` 加油包）、`price`（分）、`quantity`。
+
+## 9. 前端调用流程
+
+1. 登录后保存 JWT，后续请求统一携带 `Authorization: Bearer <token>`。
+2. 进入资产页面调用资产信息接口，并使用返回的 `allowed_payment_methods` 渲染支付方式。
+3. 充值先调用充值前校验；若 `need_force_recharge = true`，使用后端返回的强制充值金额和提示。
+4. 套餐购买或续费调用创建订单接口，`package_ids` 使用当前资产的 `current_package_id` 或历史订单的 `package_ids`。
+5. 充值调用创建充值订单接口。微信支付时必须传 `app_type`。
+6. 页面展示支付链接或支付参数后，支付结果通过订单详情等查询接口确认；不要仅根据前端跳转结果判断已支付。