From 9674e0d0d9981392f9228cef30c1105969e53c7d Mon Sep 17 00:00:00 2001 From: huang Date: Thu, 30 Apr 2026 10:54:29 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 19 + docs/admin-openapi.yaml | 51 + docs/client-wechat-appid/功能总结.md | 30 + docs/前端接口变更说明.md | 1901 -------------------------- 4 files changed, 100 insertions(+), 1901 deletions(-) create mode 100644 docs/client-wechat-appid/功能总结.md delete mode 100644 docs/前端接口变更说明.md diff --git a/.gitignore b/.gitignore index c68a025..4651095 100644 --- a/.gitignore +++ b/.gitignore @@ -87,3 +87,22 @@ docs/admin-openapi.yaml .opencode/skills/defuddle # CocoIndex Code (ccc) /.cocoindex_code/ +.omx/hud-config.json +.omx/metrics.json +.omx/setup-scope.json +.omx/cache/codebase-map.json +.omx/state/current-task-baseline.json +.omx/state/notify-fallback-authority-owner.json +.omx/state/notify-fallback-state.json +.omx/state/notify-fallback.pid +.omx/state/session.json +.omx/state/subagent-tracking.json +.omx/state/team-leader-nudge.json +.omx/state/tmux-hook-state.json +.omx/state/update-check.json +.omx/state/sessions/omx-1777517355305-tzivrd/AGENTS.md +.omx/state/sessions/omx-1777517355305-tzivrd/hud-state.json +.omx/state/sessions/omx-1777517489966-oo3g37/AGENTS.md +.omx/state/sessions/omx-1777517489966-oo3g37/hud-state.json +.omx/state/sessions/omx-1777517489966-oo3g37/notify-hook-state.json +.omx/state/tmux-extended-keys/private-tmp-tmux-501-default.json diff --git a/docs/admin-openapi.yaml b/docs/admin-openapi.yaml index 45e5e84..2164dad 100644 --- a/docs/admin-openapi.yaml +++ b/docs/admin-openapi.yaml @@ -8356,6 +8356,12 @@ components: description: 总数 type: integer type: object + DtoWechatAppIDResponse: + properties: + app_id: + description: 当前生效的公众号 AppID + type: string + type: object DtoWechatConfigListResponse: properties: items: @@ -25442,6 +25448,51 @@ paths: summary: 钱包流水列表 tags: - 个人客户 - 钱包 + /api/c/v1/wechat/appid: + get: + description: 用于 C 端免登录场景获取当前生效微信配置中的公众号 AppID，响应仅返回 app_id 字段 + responses: + "200": + content: + application/json: + schema: + properties: + code: + description: 响应码 + example: 0 + type: integer + data: + $ref: '#/components/schemas/DtoWechatAppIDResponse' + msg: + description: 响应消息 + example: success + type: string + timestamp: + description: 时间戳 + format: date-time + type: string + required: + - code + - msg + - data + - timestamp + type: object + description: 成功 + "400": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 请求参数错误 + "500": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 服务器内部错误 + summary: 获取当前生效的公众号 AppID + tags: + - 个人客户 - 微信 /api/c/v1/wechat/jssdk-config: get: description: 前端调用 wx.config() 初始化微信 JS-SDK 时所需的签名参数，需传入当前页面完整 URL diff --git a/docs/client-wechat-appid/功能总结.md b/docs/client-wechat-appid/功能总结.md new file mode 100644 index 0000000..6e37d8e --- /dev/null +++ b/docs/client-wechat-appid/功能总结.md @@ -0,0 +1,30 @@ +# C 端微信 AppID 获取接口功能总结 + +## 功能概述 + +新增 C 端免登录接口 `GET /api/c/v1/wechat/appid`，用于返回当前生效微信配置中的公众号 `AppID`。 + +## 接口行为 + +- 无需登录即可访问 +- 统一从当前生效微信配置读取 `oa_app_id` +- 响应 `data` 中仅返回 `app_id` 字段 +- 当不存在生效配置或公众号 `AppID` 为空时，返回 `微信配置不可用` + +## 适用场景 + +- 前端在发起公众号授权前，先获取当前环境应使用的 `AppID` +- 前端在初始化微信相关能力时，避免硬编码 `AppID` + +## 返回示例 + +```json +{ + "code": 0, + "msg": "success", + "data": { + "app_id": "wx1234567890abcdef" + }, + "timestamp": 1745999999 +} +``` diff --git a/docs/前端接口变更说明.md b/docs/前端接口变更说明.md deleted file mode 100644 index 451c99b..0000000 --- a/docs/前端接口变更说明.md +++ /dev/null @@ -1,1901 +0,0 @@ -# 前端接口变更说明 - -> 最后更新：2026-03-20 - ---- - -## 目录 - -1. [接口变更概览](#一接口变更概览) -2. [删除的接口](#二删除的接口) -3. [修改的后台接口](#三修改的后台接口) -4. [新增的后台接口](#四新增的后台接口) -5. [新增的 C 端接口](#五新增的-c-端接口) -6. [认证方式说明](#六认证方式说明) -7. [统一响应格式](#七统一响应格式) - ---- - -## 一、接口变更概览 - -**C 端接口统一前缀**：`/api/c/v1/` -**后台接口统一前缀**：`/api/admin/` - -### 删除 - -| 接口 | 说明 | -|------|------| -| `POST /api/personal/login` | 旧个人客户登录，已下线 | -| `POST /api/personal/send-code` | 旧验证码发送，已下线 | -| `POST /api/personal/wechat-oauth-login` | 旧微信登录，已下线 | -| `POST /api/personal/bind-wechat` | 旧微信绑定，已下线 | -| `GET /api/personal/profile` | 旧个人信息，已下线 | -| `/api/h5/*` 下所有路由 | 旧 H5 接口全部下线 | - -### 修改（后台） - -| 接口 | 变更内容 | -|------|----------| -| `POST /api/admin/shop-package-batch-pricing/batch-update` | 仅支持批量调整成本价（移除 `pricing_target`） | -| 所有返回 `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` 字段 | - -### 新增（后台） - -| 接口 | 说明 | -|------|------| -| `PATCH /api/admin/packages/:id/retail-price` | 代理修改自己的套餐零售价 | -| `PATCH /api/admin/iot-cards/:id/deactivate` | 手动停用 IoT 卡 | -| `PATCH /api/admin/devices/:id/deactivate` | 手动停用设备 | -| `POST /api/admin/exchanges` | 发起换货单 | -| `GET /api/admin/exchanges` | 换货单列表 | -| `GET /api/admin/exchanges/:id` | 换货单详情 | -| `POST /api/admin/exchanges/:id/ship` | 发货 | -| `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 端） - -| 接口 | 说明 | -|------|------| -| `POST /api/c/v1/auth/verify-asset` | 资产验证 | -| `POST /api/c/v1/auth/wechat-login` | 公众号登录 | -| `POST /api/c/v1/auth/miniapp-login` | 小程序登录 | -| `POST /api/c/v1/auth/send-code` | 发送验证码 | -| `POST /api/c/v1/auth/bind-phone` | 绑定手机号 | -| `POST /api/c/v1/auth/change-phone` | 换绑手机号 | -| `POST /api/c/v1/auth/logout` | 退出登录 | -| `GET /api/c/v1/asset/info` | 资产基本信息 | -| `GET /api/c/v1/asset/packages` | 可购套餐列表 | -| `GET /api/c/v1/asset/package-history` | 历史套餐列表 | -| `POST /api/c/v1/asset/refresh` | 手动刷新资产状态 | -| `GET /api/c/v1/wallet/detail` | 钱包详情 | -| `GET /api/c/v1/wallet/transactions` | 钱包流水列表 | -| `GET /api/c/v1/wallet/recharge-check` | 充值预检 | -| `POST /api/c/v1/wallet/recharge` | 创建充值订单 | -| `GET /api/c/v1/wallet/recharges` | 充值记录列表 | -| `POST /api/c/v1/orders/create` | 创建套餐购买订单 | -| `GET /api/c/v1/orders` | 订单列表 | -| `GET /api/c/v1/orders/:id` | 订单详情 | -| `GET /api/c/v1/realname/link` | 获取实名跳转链接 | -| `GET /api/c/v1/device/cards` | 设备卡列表 | -| `POST /api/c/v1/device/reboot` | 设备重启 | -| `POST /api/c/v1/device/factory-reset` | 恢复出厂设置 | -| `POST /api/c/v1/device/wifi` | WiFi 配置 | -| `POST /api/c/v1/device/switch-card` | 切卡 | -| `GET /api/c/v1/exchange/pending` | 查询进行中的换货通知 | -| `POST /api/c/v1/exchange/:id/shipping-info` | 填写收货信息 | - ---- - -## 二、删除的接口 - -以下接口已全部下线，请停止调用： - -**旧 H5 接口（`/api/h5/` 下所有路由）** - -**旧个人客户接口（`/api/personal/` 下）：** -- `POST /api/personal/login` -- `POST /api/personal/send-code` -- `POST /api/personal/wechat-oauth-login` -- `POST /api/personal/bind-wechat` -- `GET /api/personal/profile` - -以上接口由新 C 端认证接口（`/api/c/v1/auth/`）替代。 - ---- - -## 三、修改的后台接口 - -### 批量调价接口移除 `pricing_target` 字段 - -``` -POST /api/admin/shop-package-batch-pricing/batch-update -``` - -**移除请求字段：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `pricing_target` | string | 否 | 已移除，不再支持通过该接口调整零售价 | - -**变更说明**：该接口现仅支持批量调整成本价，零售价调整改为独立接口 `PATCH /api/admin/packages/:id/retail-price`。 - ---- - -### 套餐响应新增字段（`PackageResponse`） - -所有返回 `PackageResponse` 的套餐接口，响应体新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `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 | 累计充值金额（分） | - ---- - -### 运营商管理 DTO 新增实名相关字段 - -运营商创建/编辑接口新增以下字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `realname_link_type` | string | 实名链接类型：`none`（无需实名）/ `template`（模板实名）/ `gateway`（网关实名） | -| `realname_link_template` | string | 实名链接模板（`realname_link_type` 为 `template` 时使用） | - ---- - -## 四、新增的后台接口 - -### 资产停用 - -#### 手动停用 IoT 卡 - -``` -PATCH /api/admin/iot-cards/:id/deactivate -``` - -- **认证**：需要后台 Bearer Token -- **路径参数**：`id`（IoT 卡 ID） -- **说明**：将卡的 `asset_status` 设为 4（已停用） - ---- - -#### 手动停用设备 - -``` -PATCH /api/admin/devices/:id/deactivate -``` - -- **认证**：需要后台 Bearer Token -- **路径参数**：`id`（设备 ID） -- **说明**：将设备的 `asset_status` 设为 4（已停用） - ---- - -### 换货管理 - -#### H1 发起换货单 - -``` -POST /api/admin/exchanges -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `old_asset_type` | string | 是 | 旧资产类型：`iot_card`（物联网卡）/ `device`（设备） | -| `old_identifier` | string | 是 | 旧资产标识符（ICCID/虚拟号/IMEI/SN），1~100 字符 | -| `exchange_reason` | string | 是 | 换货原因，1~100 字符 | -| `remark` | string | 否 | 备注，最多 500 字符 | - ---- - -#### H2 换货单列表 - -``` -GET /api/admin/exchanges -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `page` | int | 否 | 页码，最小 1 | -| `page_size` | int | 否 | 每页数量，1~100 | -| `status` | int | 否 | 换货状态：1（待填写信息）/ 2（待发货）/ 3（已发货待确认）/ 4（已完成）/ 5（已取消） | -| `identifier` | string | 否 | 资产标识符模糊搜索（旧资产/新资产均可） | -| `created_at_start` | string | 否 | 创建时间起始 | -| `created_at_end` | string | 否 | 创建时间结束 | - -**响应体（list 中每项）**：见下方 `ExchangeOrderResponse` 字段说明。 - ---- - -#### H3 换货单详情 - -``` -GET /api/admin/exchanges/:id -``` - -**路径参数**：`id`（换货单 ID） - -**响应体（`ExchangeOrderResponse`）：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | uint | 换货单 ID | -| `exchange_no` | string | 换货单号 | -| `old_asset_type` | string | 旧资产类型 | -| `old_asset_id` | uint | 旧资产 ID | -| `old_asset_identifier` | string | 旧资产标识符 | -| `new_asset_type` | string | 新资产类型 | -| `new_asset_id` | uint | 新资产 ID（可为空） | -| `new_asset_identifier` | string | 新资产标识符 | -| `recipient_name` | string | 收件人姓名 | -| `recipient_phone` | string | 收件人电话 | -| `recipient_address` | string | 收货地址 | -| `express_company` | string | 快递公司 | -| `express_no` | string | 快递单号 | -| `migrate_data` | bool | 是否执行全量迁移 | -| `migration_completed` | bool | 迁移是否已完成 | -| `migration_balance` | int64 | 迁移转移金额（分） | -| `exchange_reason` | string | 换货原因 | -| `remark` | string | 备注（可为空） | -| `status` | int | 换货状态（1~5） | -| `status_text` | string | 换货状态文本 | -| `shop_id` | uint | 所属店铺 ID（可为空） | -| `created_at` | string | 创建时间 | -| `updated_at` | string | 更新时间 | -| `creator` | uint | 创建人 ID | -| `updater` | uint | 更新人 ID | - ---- - -#### H4 发货 - -``` -POST /api/admin/exchanges/:id/ship -``` - -**路径参数**：`id`（换货单 ID） - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `express_company` | string | 是 | 快递公司，1~100 字符 | -| `express_no` | string | 是 | 快递单号，1~100 字符 | -| `new_identifier` | string | 是 | 新资产标识符（ICCID/虚拟号/IMEI/SN），1~100 字符 | -| `migrate_data` | bool | 是 | 是否执行全量迁移（true：执行，false：不执行） | - ---- - -#### H5 确认完成 - -``` -POST /api/admin/exchanges/:id/complete -``` - -**路径参数**：`id`（换货单 ID） - -**请求体**：无 - -**说明**：若发货时 `migrate_data=true`，确认完成时会执行全量数据迁移（钱包余额、套餐记录等从旧资产迁移到新资产）。 - ---- - -#### H6 取消换货 - -``` -POST /api/admin/exchanges/:id/cancel -``` - -**路径参数**：`id`（换货单 ID） - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `remark` | string | 否 | 取消备注，最多 500 字符 | - -**限制**：仅 `status=1`（待填写信息）或 `status=2`（待发货）时可取消。 - ---- - -#### H7 旧资产转新（generation+1） - -``` -POST /api/admin/exchanges/:id/renew -``` - -**路径参数**：`id`（换货单 ID） - -**请求体**：无 - -**说明**：将旧资产的 `generation` 字段加 1，使其可重新销售。 - ---- - -### 换货业务流程 - -```mermaid -flowchart TD - A["后台发起换货\nH1 POST /admin/exchanges"] --> B[换货单创建\nstatus=1 待填写信息] - B --> C["客户端轮询通知\nG1 GET /exchange/pending"] - C --> D["客户端填写收货信息\nG2 POST /exchange/:id/shipping-info"] - D --> E[status=2 待发货] - E --> F["后台发货\nH4 POST /exchanges/:id/ship\n填写快递信息和新资产标识符"] - F --> G[status=3 已发货待确认] - G --> H["后台确认完成\nH5 POST /exchanges/:id/complete"] - H --> I{migrate_data=true?} - I -->|是| J[执行全量数据迁移\n钱包余额、套餐记录迁移到新资产] - I -->|否| K[直接完成] - J --> L[status=4 已完成] - K --> L - L --> M{需要回收旧资产?} - M -->|是| N["后台转新\nH7 POST /exchanges/:id/renew\n旧资产 generation+1 可重新销售"] - M -->|否| O[流程结束] - N --> O -``` - -**取消流程：** - -```mermaid -flowchart TD - A[status=1 待填写信息] -->|H6 取消| C[status=5 已取消] - B[status=2 待发货] -->|H6 取消| C -``` - -### 换货状态机 - -| 状态值 | 状态名 | 可执行操作 | -|--------|--------|-----------| -| 1 | 待填写信息 | 客户端填写收货信息（G2）、后台取消（H6） | -| 2 | 待发货 | 后台发货（H4）、后台取消（H6） | -| 3 | 已发货待确认 | 后台确认完成（H5） | -| 4 | 已完成 | 后台转新（H7，可选） | -| 5 | 已取消 | 无 | - ---- - -### 微信支付配置管理 - -> 权限：仅超级管理员和平台用户可访问。 - -#### 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 | 当前套餐名称（无套餐时为空） | -| `current_package_usage_id` | uint | 当前主套餐的套餐使用记录 ID（无主套餐时为 null） | -| `real_total_mb` | int64 | 当前主套餐真实总量(MB) | -| `real_used_mb` | int64 | 当前主套餐真实已用量(MB) | -| `virtual_total_mb` | int64 | 当前主套餐业务停机阈值(MB) | -| `virtual_used_mb` | float64 | 当前主套餐展示已用量(MB) | -| `reduction_pct` | float64 | 展示增幅比例，公式为 `(real_total_mb / virtual_total_mb) - 1` | -| `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/:identifier/realtime-status -``` - -- **认证**：需要后台 Bearer Token - -**路径参数：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符（虚拟号/ICCID/IMEI/SN/MSISDN） | - -**响应体（`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/:identifier/refresh -``` - -- **认证**：需要后台 Bearer Token -- **路径参数**：同 Z2 -- **请求体**：无 -- **响应体**：`AssetRealtimeStatusResponse`（字段同 Z2） - ---- - -#### Z4 资产套餐列表 - -``` -GET /api/admin/assets/:identifier/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 | 状态名称 | -| `real_total_mb` | int64 | 套餐真实总量(MB) | -| `real_used_mb` | int64 | 套餐真实已用量(MB) | -| `virtual_total_mb` | int64 | 套餐业务停机阈值(MB) | -| `virtual_used_mb` | float64 | 套餐展示已用量(MB) | -| `reduction_pct` | float64 | 展示增幅比例，公式为 `(real_total_mb / virtual_total_mb) - 1` | -| `activated_at` | string | 激活时间（待生效套餐为空） | -| `expires_at` | string | 到期时间（待生效套餐为空） | -| `master_usage_id` | uint | 主套餐ID（加油包时有值） | -| `priority` | int | 优先级 | -| `created_at` | string | 创建时间 | - ---- - -#### Z5 当前生效套餐 - -``` -GET /api/admin/assets/:identifier/current-package -``` - -- **认证**：需要后台 Bearer Token -- **路径参数**：同 Z2 -- **响应体**：`AssetPackageResponse`（字段同 Z4） -- **无主套餐时**：返回 `200 + null` - ---- - -#### 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 `）。 - ---- - -### 认证（/api/c/v1/auth/） - -#### A1 资产验证（无需认证） - -``` -POST /api/c/v1/auth/verify-asset -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN），1~50 字符 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `asset_token` | string | 资产令牌，5 分钟有效，用于后续登录接口 | -| `expires_in` | int | 过期时间（秒），固定 300 | - ---- - -#### A2 公众号登录（无需认证） - -``` -POST /api/c/v1/auth/wechat-login -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `code` | string | 是 | 微信 OAuth 授权码 | -| `asset_token` | string | 是 | A1 返回的资产令牌 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `token` | string | 登录 JWT 令牌 | -| `need_bind_phone` | bool | 是否需要绑定手机号（true 时引导用户完成 A4+A5） | -| `is_new_user` | bool | 是否新注册用户 | - ---- - -#### A3 小程序登录（无需认证） - -``` -POST /api/c/v1/auth/miniapp-login -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `code` | string | 是 | 小程序登录凭证 | -| `asset_token` | string | 是 | A1 返回的资产令牌 | -| `nickname` | string | 否 | 用户昵称（前端授权后传入） | -| `avatar_url` | string | 否 | 用户头像 URL（前端授权后传入） | - -**响应体**：同 A2（`token` / `need_bind_phone` / `is_new_user`） - ---- - -#### A4 发送验证码（无需认证） - -``` -POST /api/c/v1/auth/send-code -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `phone` | string | 是 | 手机号，固定 11 位 | -| `scene` | string | 是 | 业务场景：`bind_phone`（绑定手机）/ `change_phone_old`（换绑旧手机验证）/ `change_phone_new`（换绑新手机验证） | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `cooldown_seconds` | int | 冷却秒数，期间不可重复发送 | - ---- - -#### A5 绑定手机号（需 JWT 认证） - -``` -POST /api/c/v1/auth/bind-phone -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `phone` | string | 是 | 手机号，固定 11 位 | -| `code` | string | 是 | 验证码，固定 6 位 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `phone` | string | 已绑定手机号 | -| `bound_at` | string | 绑定时间 | - ---- - -#### A6 换绑手机号（需 JWT 认证） - -``` -POST /api/c/v1/auth/change-phone -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `old_phone` | string | 是 | 旧手机号，固定 11 位 | -| `old_code` | string | 是 | 旧手机号验证码，固定 6 位 | -| `new_phone` | string | 是 | 新手机号，固定 11 位 | -| `new_code` | string | 是 | 新手机号验证码，固定 6 位 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `phone` | string | 换绑后手机号 | -| `changed_at` | string | 换绑时间 | - ---- - -#### A7 退出登录（需 JWT 认证） - -``` -POST /api/c/v1/auth/logout -``` - -**请求体**：无 - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `success` | bool | 是否成功 | - ---- - -### 认证登录完整流程 - -```mermaid -flowchart TD - A[用户打开客户端] --> B[输入资产标识符\nSN/IMEI/ICCID/虚拟号] - B --> C["A1 POST /auth/verify-asset\n获得 asset_token（5分钟有效）"] - C --> D{选择登录方式} - D -->|公众号| E["A2 POST /auth/wechat-login\n传入 code + asset_token"] - D -->|小程序| F["A3 POST /auth/miniapp-login\n传入 code + asset_token"] - E --> G{need_bind_phone?} - F --> G - G -->|true 需要绑定| H["A4 POST /auth/send-code\nscene=bind_phone"] - H --> I["A5 POST /auth/bind-phone\n传入 phone + code"] - I --> J[进入主页面] - G -->|false 已绑定| J -``` - -**换绑手机号流程：** - -```mermaid -flowchart TD - A[用户申请换绑] --> B["A4 POST /auth/send-code\nscene=change_phone_old\n发送旧手机验证码"] - B --> C["A4 POST /auth/send-code\nscene=change_phone_new\n发送新手机验证码"] - C --> D["A6 POST /auth/change-phone\n传入 old_phone+old_code+new_phone+new_code"] - D --> E[换绑成功] -``` - ---- - -### 资产（/api/c/v1/asset/） - -#### B1 资产基本信息 - -``` -GET /api/c/v1/asset/info?identifier=xxx -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `asset_type` | string | 资产类型：`card`（卡）/ `device`（设备） | -| `asset_id` | uint | 资产 ID | -| `identifier` | string | 资产标识符 | -| `virtual_no` | string | 虚拟号 | -| `status` | int | 状态：0（禁用）/ 1（启用） | -| `real_name_status` | int | 实名状态：0（未实名）/ 1（已实名） | -| `carrier_name` | string | 运营商名称 | -| `generation` | string | 制式 | -| `wallet_balance` | int64 | 钱包余额（分） | - ---- - -#### B2 可购套餐列表 - -``` -GET /api/c/v1/asset/packages?identifier=xxx -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | - -**响应体：** - -```json -{ - "packages": [ - { - "package_id": 1, - "package_name": "月套餐30G", - "package_type": "formal", - "retail_price": 2900, - "cost_price": 2000, - "validity_days": 30, - "is_addon": false, - "data_allowance": 30720, - "data_unit": "MB", - "description": "每月30G流量" - } - ] -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `package_id` | uint | 套餐 ID | -| `package_name` | string | 套餐名称 | -| `package_type` | string | 套餐类型：`formal`（正式套餐）/ `addon`（加油包） | -| `retail_price` | int64 | 零售价（分） | -| `cost_price` | int64 | 成本价（分） | -| `validity_days` | int | 有效天数 | -| `is_addon` | bool | 是否加油包 | -| `data_allowance` | int64 | 流量额度 | -| `data_unit` | string | 流量单位 | -| `description` | string | 套餐说明 | - ---- - -#### B3 历史套餐列表 - -``` -GET /api/c/v1/asset/package-history?identifier=xxx&page=1&page_size=20 -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符 | -| `page` | int | 是 | 页码，最小 1 | -| `page_size` | int | 是 | 每页数量，1~100 | - -**响应体**：分页列表，包含 `list` / `total` / `page` / `page_size`。 - ---- - -#### B4 手动刷新资产状态 - -``` -POST /api/c/v1/asset/refresh -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `refresh_type` | string | 刷新类型：`card`（卡）/ `device`（设备） | -| `accepted` | bool | 是否已受理 | -| `cooldown_seconds` | int | 冷却秒数（期间不可重复刷新） | - ---- - -### 钱包（/api/c/v1/wallet/） - -#### C1 钱包详情 - -``` -GET /api/c/v1/wallet/detail?identifier=xxx -``` - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `wallet_id` | uint | 钱包 ID | -| `resource_type` | string | 资源类型：`iot_card`（物联网卡）/ `device`（设备） | -| `resource_id` | uint | 资源 ID | -| `balance` | int64 | 可用余额（分） | -| `frozen_balance` | int64 | 冻结余额（分） | -| `updated_at` | string | 更新时间 | - ---- - -#### C2 钱包流水列表 - -``` -GET /api/c/v1/wallet/transactions?identifier=xxx&page=1&page_size=20 -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符 | -| `transaction_type` | string | 否 | 流水类型筛选 | -| `start_time` | string | 否 | 开始时间 | -| `end_time` | string | 否 | 结束时间 | -| `page` | int | 是 | 页码 | -| `page_size` | int | 是 | 每页数量，1~100 | - -**响应体（list 中每项）：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `transaction_id` | uint | 流水 ID | -| `type` | string | 流水类型 | -| `amount` | int64 | 变动金额（分） | -| `balance_after` | int64 | 变动后余额（分） | -| `created_at` | string | 创建时间 | -| `remark` | string | 备注 | - ---- - -#### C3 充值预检 - -``` -GET /api/c/v1/wallet/recharge-check?identifier=xxx -``` - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `need_force_recharge` | bool | 是否需要强制充值 | -| `force_recharge_amount` | int64 | 强制充值金额（分） | -| `trigger_type` | string | 触发类型 | -| `min_amount` | int64 | 最小充值金额（分） | -| `max_amount` | int64 | 最大充值金额（分） | -| `message` | string | 提示信息 | - ---- - -#### C4 创建充值订单 - -``` -POST /api/c/v1/wallet/recharge -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | -| `amount` | int64 | 是 | 充值金额（分），100~10000000 | -| `payment_method` | string | 是 | 支付方式，目前仅支持 `wechat` | -| `app_type` | string | 是 | 应用类型：`official_account`（公众号）/ `miniapp`（小程序） | - -**响应体：** - -```json -{ - "recharge": { - "recharge_id": 1, - "recharge_no": "RC20260319001", - "amount": 10000, - "status": 0 - }, - "pay_config": { - "app_id": "wx...", - "timestamp": "1710000000", - "nonce_str": "abc123", - "package": "prepay_id=wx...", - "sign_type": "RSA", - "pay_sign": "..." - } -} -``` - -`pay_config` 字段直接传给微信 JSAPI 调起支付。 - ---- - -#### C5 充值记录列表 - -``` -GET /api/c/v1/wallet/recharges?identifier=xxx&page=1&page_size=20 -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符 | -| `status` | int | 否 | 充值状态：0（待支付）/ 1（已支付）/ 2（已关闭） | -| `page` | int | 是 | 页码 | -| `page_size` | int | 是 | 每页数量，1~100 | - -**响应体（list 中每项）：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `recharge_id` | uint | 充值 ID | -| `recharge_no` | string | 充值单号 | -| `amount` | int64 | 充值金额（分） | -| `status` | int | 状态：0（待支付）/ 1（已支付）/ 2（已关闭） | -| `payment_method` | string | 支付方式 | -| `created_at` | string | 创建时间 | -| `auto_purchase_status` | string | 自动购包状态 | - ---- - -### 钱包充值流程 - -```mermaid -flowchart TD - A[用户进入充值页] --> B["C3 GET /wallet/recharge-check\n预检是否需要强充"] - B --> C{need_force_recharge} - C -->|true 需要强充| D[展示强制充值金额\n用户确认] - C -->|false 自由充值| E[用户输入充值金额] - D --> F["C4 POST /wallet/recharge\n创建充值订单"] - E --> F - F --> G[调起微信支付\n使用 pay_config] - G --> H[支付成功] - H --> I[后端回调处理\n余额增加] - I --> J[充值完成] -``` - ---- - -### 订单（/api/c/v1/orders/） - -#### D1 创建套餐购买订单（核心接口） - -``` -POST /api/c/v1/orders/create -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | -| `package_ids` | []uint | 是 | 套餐 ID 列表，至少 1 个 | -| `app_type` | string | 是 | 应用类型：`official_account`（公众号）/ `miniapp`（小程序） | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `order_type` | string | 订单类型：`package`（套餐订单）/ `recharge`（充值订单） | -| `order` | object | 套餐订单信息（`order_type=package` 时有值） | -| `recharge` | object | 充值订单信息（`order_type=recharge` 时有值） | -| `pay_config` | object | 微信支付配置，直接传给 JSAPI | -| `linked_package_info` | object | 关联套餐信息（强充场景下有值） | - -`order` 字段结构： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `order_id` | uint | 订单 ID | -| `order_no` | string | 订单号 | -| `total_amount` | int64 | 订单总金额（分） | -| `payment_status` | int | 支付状态：0（待支付）/ 1（已支付）/ 2（已取消） | -| `created_at` | string | 创建时间 | - -`recharge` 字段结构： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `recharge_id` | uint | 充值 ID | -| `recharge_no` | string | 充值单号 | -| `amount` | int64 | 充值金额（分） | -| `status` | int | 状态：0（待支付）/ 1（已支付）/ 2（已关闭） | -| `auto_purchase_status` | string | 自动购包状态 | - -`linked_package_info` 字段结构（强充场景）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `package_names` | []string | 套餐名称列表 | -| `total_package_amount` | int64 | 套餐总金额（分） | -| `force_recharge_amount` | int64 | 强制充值金额（分） | -| `wallet_credit` | int64 | 钱包抵扣金额（分） | - -> **注意**：当余额不足时，后端会自动创建充值订单（`order_type=recharge`），用户支付充值后系统自动购买套餐，前端无需二次调用购买接口。 - ---- - -#### D2 订单列表 - -``` -GET /api/c/v1/orders?identifier=xxx&page=1&page_size=20 -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符 | -| `payment_status` | int | 否 | 支付状态：0（待支付）/ 1（已支付）/ 2（已取消） | -| `page` | int | 是 | 页码 | -| `page_size` | int | 是 | 每页数量，1~100 | - -**响应体（list 中每项）：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `order_id` | uint | 订单 ID | -| `order_no` | string | 订单号 | -| `total_amount` | int64 | 订单总金额（分） | -| `payment_status` | int | 支付状态 | -| `created_at` | string | 创建时间 | -| `package_names` | []string | 套餐名称列表 | - ---- - -#### D3 订单详情 - -``` -GET /api/c/v1/orders/:id -``` - -**路径参数**：`id`（订单 ID） - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `order_id` | uint | 订单 ID | -| `order_no` | string | 订单号 | -| `total_amount` | int64 | 订单总金额（分） | -| `payment_status` | int | 支付状态：0（待支付）/ 1（已支付）/ 2（已取消） | -| `payment_method` | string | 支付方式 | -| `created_at` | string | 创建时间 | -| `paid_at` | string | 支付时间（可为空） | -| `completed_at` | string | 完成时间（可为空） | -| `packages` | array | 订单套餐列表 | - -`packages` 中每项： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `package_id` | uint | 套餐 ID | -| `package_name` | string | 套餐名称 | -| `package_type` | string | 套餐类型：`formal`（正式套餐）/ `addon`（加油包） | -| `price` | int64 | 单价（分） | -| `quantity` | int | 数量 | - ---- - -### 套餐购买流程 - -```mermaid -flowchart TD - A[用户选择套餐] --> B["D1 POST /orders/create\n传入 identifier + package_ids + app_type"] - B --> C{响应 order_type} - C -->|package 套餐订单| D[调起微信支付\n使用 pay_config] - C -->|recharge 充值订单| E[提示用户需要充值\n显示 linked_package_info 中的金额说明] - E --> F[调起微信支付\n使用 pay_config] - D --> G[支付成功] - F --> G - G --> H[后端支付回调处理] - H -->|套餐订单| I[直接激活套餐] - H -->|充值订单| J[余额到账后自动购买套餐] - I --> K[套餐激活完成] - J --> K -``` - -> **强充两阶段说明**：当用户钱包余额不足时，后端自动创建充值订单（`order_type=recharge`）。用户支付充值金额后，系统自动扣款购买套餐，前端无需再次调用购买接口。`linked_package_info` 字段包含套餐名称和金额明细，可用于向用户展示说明。 - ---- - -### 实名（/api/c/v1/realname/） - -#### E1 获取实名跳转链接 - -``` -GET /api/c/v1/realname/link?identifier=xxx&iccid=xxx -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | -| `iccid` | string | 否 | 物联网卡 ICCID（设备场景下指定具体卡） | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `realname_mode` | string | 实名模式：`none`（无需实名）/ `template`（模板实名）/ `gateway`（网关实名） | -| `realname_url` | string | 实名跳转链接 | -| `card_info` | object | 卡片简要信息 | -| `expire_at` | string | 链接过期时间（可为空） | - -`card_info` 字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `iccid` | string | 物联网卡 ICCID | -| `msisdn` | string | 手机号 | -| `virtual_no` | string | 虚拟号 | - ---- - -### 设备（/api/c/v1/device/） - -#### F1 设备卡列表 - -``` -GET /api/c/v1/device/cards?identifier=xxx -``` - -**响应体：** - -```json -{ - "cards": [ - { - "card_id": 1, - "iccid": "898600...", - "msisdn": "1380000...", - "carrier_name": "中国移动", - "network_status": "online", - "real_name_status": 1, - "slot_position": 1, - "is_active": true - } - ] -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `card_id` | uint | 卡 ID | -| `iccid` | string | 物联网卡 ICCID | -| `msisdn` | string | 手机号 | -| `carrier_name` | string | 运营商名称 | -| `network_status` | string | 网络状态 | -| `real_name_status` | int | 实名状态：0（未实名）/ 1（已实名） | -| `slot_position` | int | 插槽位置 | -| `is_active` | bool | 是否当前激活卡 | - ---- - -#### F2 设备重启 - -``` -POST /api/c/v1/device/reboot -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `accepted` | bool | 是否已受理 | -| `request_id` | string | 请求 ID | - ---- - -#### F3 恢复出厂设置 - -``` -POST /api/c/v1/device/factory-reset -``` - -**请求体**：同 F2（`identifier` 字段） - -**响应体**：同 F2（`accepted` / `request_id`） - ---- - -#### F4 WiFi 配置 - -``` -POST /api/c/v1/device/wifi -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | -| `ssid` | string | 是 | WiFi 名称，1~32 字符 | -| `password` | string | 是 | WiFi 密码，1~64 字符 | -| `enabled` | bool | 是 | 是否启用 WiFi | - -**响应体**：同 F2（`accepted` / `request_id`） - ---- - -#### F5 切卡 - -``` -POST /api/c/v1/device/switch-card -``` - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~50 字符 | -| `target_iccid` | string | 是 | 目标 ICCID，1~30 字符 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `accepted` | bool | 是否已受理 | -| `target_iccid` | string | 目标 ICCID | - ---- - -### 换货（/api/c/v1/exchange/） - -#### G1 查询进行中的换货通知 - -``` -GET /api/c/v1/exchange/pending?identifier=xxx -``` - -**Query 参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `identifier` | string | 是 | 资产标识符，1~100 字符 | - -**响应体：** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | uint | 换货单 ID | -| `exchange_no` | string | 换货单号 | -| `status` | int | 换货状态（1~5） | -| `status_text` | string | 换货状态文本 | -| `exchange_reason` | string | 换货原因 | -| `created_at` | string | 创建时间 | - -> 若无进行中的换货单，返回空数据（非报错）。 - ---- - -#### G2 填写收货信息 - -``` -POST /api/c/v1/exchange/:id/shipping-info -``` - -**路径参数**：`id`（换货单 ID） - -**请求体：** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `recipient_name` | string | 是 | 收件人姓名，1~50 字符 | -| `recipient_phone` | string | 是 | 收件人电话，1~20 字符 | -| `recipient_address` | string | 是 | 收货地址，1~500 字符 | - ---- - -## 六、认证方式说明 - -| 端 | 认证方式 | Header 格式 | -|----|----------|-------------| -| 后台（`/api/admin/`） | Bearer Token（Redis 存储） | `Authorization: Bearer ` | -| C 端（`/api/c/v1/`） | JWT | `Authorization: Bearer ` | - -**C 端 JWT 获取方式**：通过 A2 公众号登录或 A3 小程序登录接口获取，有效期请参考接口返回。 - ---- - -## 七、统一响应格式 - -所有接口均返回以下格式： - -```json -{ - "code": 0, - "msg": "success", - "data": { ... }, - "timestamp": 1710000000 -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `code` | int | 业务状态码，0 表示成功 | -| `msg` | string | 提示信息 | -| `data` | object | 业务数据 | -| `timestamp` | int64 | 服务器时间戳（秒） | - -**常见错误码：** - -| 错误码 | 说明 | -|--------|------| -| 1001 | 缺失认证令牌 | -| 1002 | 无效或过期令牌 | -| 1003 | 权限不足 | -| 1200 | 换货单不存在 | -| 1201 | 换货单状态不允许此操作 | -| 1202 | 旧资产不存在或已停用 | -| 1203 | 新资产标识符无效 | -| 1204 | 换货单已取消，无法操作 | -| 1205 | 数据迁移失败 | -| 1206 | 收货信息填写超时 | -| 4000 | 参数错误 | -| 5000 | 服务器内部错误 |