Files
device-voice-h5/docs/10月份修改/第1批-8-9月迭代前端对接说明.md
luo da95a914e3
All checks were successful
构建并部署前端到生产环境 / build-and-deploy (push) Successful in 2m59s
fix: some
2026-10-13 14:53:19 +08:00

336 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 第 1 批(8-9 月迭代缺陷修复)前端对接说明
| 项目 | 内容 |
|---|---|
| 日期 | 2026-10-12 |
| 范围 | 分支 `Iteration/8-11` 上第 1 批 12 项(M1~M6、M8、M9、M12~M14、M16、M23、F1) |
| 用途 | 前端工程师对照修改:哪些接口变了、怎么变的、前端要做什么 |
| 接口细节以 | `docs/admin-openapi.yaml`(已重新生成)为准;本文来自代码与该文档的核对 |
| 环境 | 已部署测试环境,未上生产 |
> 路径前缀:后台接口为 `/api/admin/...`,H5(C 端)接口为 `/api/c/v1/...`。
> 所有改动都向后兼容:只新增字段 / 枚举值,**唯一的删除字段是 M16 的 `real_data_mb`**;唯一的校验收紧是密码规则与 CSV 表头。
---
## 一、前端必须改动的清单(速查)
| # | 项 | 端 | 动作 | 优先级 |
|---|---|---|---|---|
| 1 | M3 订单详情/列表 | 后台 | 加 3 个字段;详情加支付单列表 | 必改 |
| 2 | M8、M14 新状态「审批提交失败」 | 后台 + H5 | 5+1 个业务的状态枚举、筛选、标签、按钮显隐 | 必改 |
| 3 | M1 密码规则 | 后台 + H5 | 7 处设置密码的页面校验与提示文案 | 必改 |
| 4 | M12 换货被拒 | 后台 | 读取错误响应 `data.phone` 拼接提示 | 必改 |
| 5 | F1 绑定手机号 | H5 | 登录响应新增 2 个布尔字段,绑定流程判断改变 | 必改 |
| 6 | M9 临期提醒 | H5 | 资产详情新增 `expiry_reminder` 弹窗;通知中心已按资产过滤 | 必改 |
| 7 | M16 预警页面 | 后台 | 规则页去掉流量额度;预警列表加阈值流量 | 必改 |
| 8 | M2 批量换绑业务员 | 后台 | CSV 模板表头改名(若前端内置模板/文案) | 视情况 |
| 9 | M23 设备导入 | 后台 | 导入说明文案:IMEI 必填 | 文案 |
| 10 | M4~M6 导出补列 | — | 前端无需改动 | 无 |
---
## 二、逐项说明
### 1. M3 后台订单显示 C 端在线支付信息
**涉及接口**
| 方法 | 路径 | 变化 |
|---|---|---|
| GET | `/api/admin/orders` | 每条订单新增 3 个字段 |
| POST | `/api/admin/orders` | 返回体同为 `OrderResponse`,同样带 3 个字段 |
| GET | `/api/admin/orders/{id}` | 3 个字段 + 新增 `payments` 数组(响应类型变为 `OrderDetailResponse`) |
**新增字段(均始终返回,无值为空串)**
| 字段 | 类型 | 说明 |
|---|---|---|
| `third_party_trade_no` | string | 交易流水号 |
| `payment_channel` | string | 支付渠道:`wechat` 微信直连 v3 / `wechat_v2` 微信直连 v2 / `fuiou` 富友 |
| `payment_merchant_name` | string | 收款商户名称 |
- 只有「个人客户 + 微信或支付宝 + 已支付(含之后已退款)」的订单有值;代理购买、钱包、线下、未支付订单一律为空串。
**详情新增 `payments`(订单详情专有,列表不返回)**
仅个人客户微信/支付宝订单有数据,其余为 `[]`;按创建时间倒序(最新在前)。每项:
| 字段 | 说明 |
|---|---|
| `payment_no` | 支付单号 |
| `payment_method` | `wechat` / `alipay` |
| `payment_channel` | 同上 |
| `payment_merchant_name` | 商户名称 |
| `third_party_trade_no` | 交易流水号(未支付为空串) |
| `amount` | 金额(分) |
| `status` / `status_name` | 0 待支付 / 1 已支付 / 2 已失败 / 3 已退款 |
| `created_at` / `paid_at` / `expire_at` | 创建 / 支付 / 过期时间(后两者可为 null) |
**前端要做**:订单列表、详情加三个字段列;详情页加「支付记录」表格(可看出「付了钱没成功」、重复支付、换过支付方式)。
---
### 2. M8、M14 新状态「审批提交失败」(影响 6 个业务)
企微审批没能提交成功时,业务单不再卡在「审批中」,而是变为**终态**「审批提交失败」。各业务新增状态值如下(**数值各业务不同,不要共用一个枚举**):
| 业务 | 新状态值 | 字段 | 涉及接口 | 重新发起方式 |
|---|:-:|---|---|---|
| 核销申请(员工代收款) | **4** | `status` / `application_status` | `GET/POST /api/admin/employee-collection-applications`、`GET/PUT /api/admin/employee-collection-applications/{id}`、`GET /api/admin/employee-collection-bills/{id}` | `PUT /api/admin/employee-collection-applications/{id}`(重新提交,生成新审批) |
| 退款 | **7** | `status` | `GET/POST /api/admin/refunds`、`GET /api/admin/refunds/{id}`、`/{id}/trigger-approval`、`/{id}/offline-settlement` | `POST /api/admin/refunds/{id}/resubmit` |
| 扫码注册代理 | **3** | `status` | `GET /api/admin/agent-distribution-registrations`、`.../{id}`;H5 `POST /api/c/v1/agent-distribution-registrations` | 申请人重新申请(走原申请入口,生成新的注册申请) |
| 线下充值(代理自充) | **7** | `status` | `GET/POST /api/admin/agent-recharges`、`.../{id}`、`/{id}/offline-pay`、`/{id}/payment-status`、`/{id}/trigger-approval` | 重新发起(后端没有对原单的单独接口,前端调 `POST /api/admin/agent-recharges` 新建线下充值单) |
| 佣金提现 | **5** | `status` | `GET /api/admin/commission/withdrawal-requests`、`/{id}/approve`、`/{id}/reject`;`GET /api/admin/shops/{shop_id}/withdrawal-requests` | `PUT /api/admin/shops/{shop_id}/withdrawal-requests/{id}`(重新提交,按新金额重新冻结) |
| 提现资料资格 | **4** | `status` | `GET/POST /api/admin/shops/{shop_id}/withdrawal-qualifications` | 重新提交资料版本 |
**列表筛选参数的取值范围同步放宽**:
- 退款 `status` 查询:`min=1,max=6` → `max=7`
- 佣金提现 `status`:`max=4` → `max=5`
- 核销 `status`:`oneof 0 1 2 3` → 加 `4`
- 扫码注册代理 `status`:`oneof 0 1 2` → 加 `3`
- 提现资料资格 `status`:`oneof 0 1 2 3` → 加 `4`
- 线下充值 `status` 过滤:说明增加 `7`
**行为变化(前端按钮显隐)**
- 状态为「审批提交失败」的单据**不能再点「恢复审批」**(接口会拒绝):
- `POST /api/admin/refunds/{id}/recover-approval`
- `POST /api/admin/employee-collection-applications/{id}/recover-approval`
- `POST /api/admin/agent-distribution-registrations/{id}/recover-approval`
只显示「重新发起」。
- 「提交结果未知」不是失败,仍显示「恢复审批」,由后台任务确认。
- 佣金提现变为 5 后,**冻结金额已自动释放**;重新发起时重新冻结。
- 核销申请:释放预占金额,账单可再次核销。
**核销申请额外变化(M8)**:`approval_submission_status` 以前恒为空,现在返回真实值:
`0 待提交 / 1 提交中 / 2 已提交 / 3 提交失败 / 4 结果未知`(无审批上下文为 0)。列表与详情都有。
**前端要做**:
1. 6 处状态枚举/标签/颜色补充新值(建议红色或灰色,标注「终态」);
2. 列表筛选下拉加该选项;
3. 操作按钮:该状态隐藏「恢复审批」,保留「重新发起」;
4. 核销申请列表/详情展示「审批提交状态」。
---
### 3. M1 登录密码统一规则
**新规则(后端强制)**:长度 **8~12 位**;大写字母、小写字母、数字、特殊符号**至少包含三类**;不能有空格和中文。
例:`Abc12345` ✅,`abcd1234` ❌(只有两类)。
**涉及的 7 个入口**
| 场景 | 方法与路径 | 字段 | 旧规则 → 新规则 |
|---|---|---|---|
| 本人修改密码 | `PUT /api/auth/password` | `new_password` | 8~32 → 8~12 + 三类 |
| 创建后台账号 | `POST /api/admin/accounts` | `password` | 8~32 → 8~12 + 三类 |
| 修改账号 | `PUT /api/admin/accounts/{id}` | `password`(可选) | 同上 |
| 修改账号密码 | `PUT /api/admin/accounts/{id}/password` | `new_password` | 同上 |
| 创建店铺(含初始账号) | `POST /api/admin/shops` | `init_password` | 8~32 → 8~12 + 三类 |
| 创建企业客户 | `POST /api/admin/enterprises` | `password` | 6~20 → 8~12 + 三类 |
| 修改企业密码 | `PUT /api/admin/enterprises/{id}/password` | `password` | 6~20 → 8~12 + 三类 |
| 扫码注册代理(H5) | `POST /api/c/v1/agent-distribution-registrations` | `password` | 6~64 → 8~12 + 三类 |
**错误提示变化**:修改密码以前只返回「参数验证失败」,现在是字段级提示,直接展示 `message` 即可,例如:
- `修改密码参数不合法:新密码长度不能小于 8`
- `修改密码参数不合法:密码须包含大写字母、小写字母、数字、特殊符号中的至少三类`
**不变**:已在用的旧密码照常登录,不强制改;超级管理员操作密码、WiFi 密码不受影响。
**前端要做**:上述页面的前端校验、输入框 `maxlength`、占位/提示文案同步为新规则;错误提示直接显示后端返回的 `message`。
---
### 4. M12 换货:新资产已绑手机号时被拒
**涉及接口**
| 方法 | 路径 | 场景 |
|---|---|---|
| POST | `/api/admin/exchanges` | 创建换货单 |
| POST | `/api/admin/exchanges/{id}/complete` | 物流换货确认完成 |
**变化**
- 旧逻辑「新资产被人扫过码就拒绝」**取消**。
- 新逻辑:新资产存在**有效手机号关联**才拒绝,错误码 **1202**,`message`:
`新资产已绑定手机号,请先在后台解除该资产的手机号绑定,再重新提交换货申请`
- 完整手机号放在错误响应的 **`data.phone`**(message 与日志中都不含号码)。
- `complete` 接口被拒时,换货单停在「已发货待确认」,解除后可重新确认。
**响应示例**
```json
{
"code": 1202,
"msg": "新资产已绑定手机号,请先在后台解除该资产的手机号绑定,再重新提交换货申请",
"data": { "phone": "138xxxxxxxx" }
}
```
**前端要做**:捕获 1202 时读取 `data.phone`,弹窗提示「新资产已绑定手机号 {phone},请先到『手机号资产关联』解除后再提交」,并可跳转/引导到解除入口。解除使用已有接口(无新增):
- `DELETE /api/admin/phone-asset-associations/{id}`(单条)
- `POST /api/admin/phone-asset-associations/batch-unbind`(按资产批量)
- `POST /api/admin/phone-asset-associations/unbind-imports`(CSV)
- `GET /api/admin/phone-asset-associations`(查询)
**换货完成后的副作用(供前端提示参考)**:旧资产的手机号关联和客户绑定都被清空,原客户已打开的旧资产页面会失效,需重新扫码。
---
### 5. F1 一个资产只能绑一个手机号
**涉及接口(H5)**
| 方法 | 路径 | 变化 |
|---|---|---|
| POST | `/api/c/v1/auth/wechat-login` | 响应新增 2 个字段,`need_bind_phone` 语义改变 |
| POST | `/api/c/v1/auth/miniapp-login` | 同上 |
| POST | `/api/c/v1/auth/bind-phone` | 资产已绑其他号时返回 **1192** |
| POST | `/api/c/v1/auth/change-phone` | 只换客户手机号,不再连带改资产 |
**登录响应新增字段**
| 字段 | 说明 |
|---|---|
| `asset_phone_bound` | 当前资产是否已绑定手机号(不返回号码) |
| `asset_phone_is_own` | 资产绑定的号码是否为当前客户自己的号(不返回号码) |
| `need_bind_phone`(语义变更) | 强制绑定开关开启时:客户无手机号,**或**当前资产尚无有效手机号关联 → `true`;开关关闭恒为 `false`。仅前端提示用 |
**四种场景对应的前端流程**
| 客户 | 资产 | 前端应该 |
|---|---|---|
| 无号 | 无号 | 验证一次手机号,客户和资产都写入这个号 |
| 有号 | 无号 | 要求给资产绑号,可以和客户的号不同 |
| 无号 | 已有号 | 只要求客户绑自己的号,资产不动 |
| 有号 | 已有号 | 不用绑 |
**新错误**:`bind-phone` 资产已绑定其他号码时,返回 **1192**「该资产已绑定手机号,如需更换请联系管理员」(不含号码)。前端提示用户联系管理员,不要重试。手机号已被其他客户绑定的 **1184** 不变。
**前端要做**:绑定页根据 `asset_phone_bound` / `asset_phone_is_own` / `need_bind_phone` 决定是否展示绑定入口;处理 1192;客户换号后不要假设资产号码跟着变。
---
### 6. M9 套餐临期提醒:按资产、扫码进入时触发
**涉及接口(H5)**
| 方法 | 路径 | 变化 |
|---|---|---|
| GET | `/api/c/v1/asset/info` | 新增可选字段 `expiry_reminder` |
| GET | `/api/c/v1/notifications` | 临期提醒只返回当前资产的(入参不变) |
| GET | `/api/c/v1/notifications/unread-count` | 未读数只计当前资产的临期提醒 |
| POST | `/api/c/v1/notifications/read-all` | 其他资产的临期提醒保持未读 |
**`expiry_reminder`(可选,无则不返回该字段)**
| 字段 | 说明 |
|---|---|
| `remaining_days` | 剩余自然日(0~15,按上海时区) |
| `expires_at` | 预计最终到期时间 |
| `level` | `red`(0~3 天)/ `purple`(4~7 天)/ `pink`(8~15 天) |
| `level_name` | 等级中文名 |
**规则**:同一客户、同一资产、同一天(北京时间)**只返回一次**;返回的同时后端已写一条通知。当天再次进入不再返回。
**前端要做**:资产详情页判断到 `expiry_reminder` 存在时弹窗/横幅提醒;不要用旧的「每日推送的临期通知」做弹窗依据(已不再给个人客户发);通知中心无需改,后端已按当前资产过滤。
---
### 7. M16 真流量预警页面口径整理
| 方法 | 路径 | 变化 |
|---|---|---|
| GET | `/api/admin/package-traffic-alert-rules` | 规则列表**删除字段 `real_data_mb`** |
| GET | `/api/admin/package-traffic-alert-rules/{id}` | 规则详情**删除字段 `real_data_mb`** |
| GET | `/api/admin/package-traffic-alerts` | 预警列表新增 `threshold_mb` |
| GET | `/api/admin/package-traffic-alerts/{id}` | 预警详情新增 `threshold_mb` |
| 导出 | 预警导出任务 | 新增列「阈值流量」,放在**最后一列** |
- `threshold_mb`(float,保留两位小数)= 额度快照 × 阈值百分比 ÷ 100,口径为「主套餐 + 加油包」。
- `used_mb`、`limit_mb` 字段不变,说明改为「主套餐与加油包汇总」。
- 规则页现在只返回:`id`、`package_id`、`package_name`、`threshold_percent`、`enabled`、`enabled_name`、`remark`、`updated_at`。
**前端要做**:规则列表/详情去掉「套餐流量额度」列及相关引用(否则显示 `undefined`);预警列表/详情加「阈值流量(MB)」;已用/总量列标题可注明「含加油包」。
> 注意:`/api/admin/packages` 等套餐接口里的 `real_data_mb` 是套餐本身字段,**没有变化**,不要误删。
---
### 8. M2 批量换绑业务员 CSV 表头改名
| 方法 | 路径 |
|---|---|
| POST | `/api/admin/shops/business-owner-imports` |
- CSV 固定表头改为:`店铺编码`、`操作类型`、**`平台登录账号`**、`备注`(原为「业务员登录账号」)。
- **「平台登录账号」这一列只填手机号**;填用户名会失败,原因提示「请填写手机号」。
- 旧表头整批失败(提示表头不符),不做新旧并存。
- 失败原因分开:格式不对、手机号不存在、不是平台用户、账号已禁用、匹配到多个账号。
- 接口路径、请求体不变;逐行独立处理,成功行与失败行互不影响。
**前端要做**:如果前端内置/下载模板或有填写说明,改为新表头并注明「填写平台用户的登录手机号」;失败明细按后端返回的原因原样展示即可。
---
### 9. M23 设备导入 IMEI 必填
| 方法 | 路径 |
|---|---|
| POST | `/api/admin/devices/import` |
- 请求结构、模板列名/列数/列序**都不变**。
- `imei` 为空(含只填空格)的行**导入失败**,失败原因「设备IMEI(imei)不能为空」,出现在任务详情的 `failed_items`(带行号)。
- 同一文件内 IMEI 齐全的行照常导入;整份文件都失败时任务状态为「失败」。
- 只校验非空,不校验格式与重复。
**前端要做**:导入页说明文案标注「IMEI 必填」;任务详情照常展示 `failed_items`。
---
### 10. M4~M6 三类导出补列(前端无需改动)
| 导出 | 新增 |
|---|---|
| 订单导出 | 最后一列「操作人」 |
| IoT 卡导出 | 最后一列「套餐到期时间」(算不准留空) |
| 设备导出 | 流量表头注明「(MB)」,最后一列「设备合计(GB)」 |
只有**新建**的导出任务带新列,历史任务重新下载仍是旧表头,不会错位。
---
### 11. M13:企微拒绝/撤销/删除后退款单结束(后端修复,前端关注点)
**无接口字段变化**。修复后,企微侧「拒绝/撤销/删除」会让退款单正确变为「已拒绝」(status = 3),资产可再换货。
**前端关注**:
- 不支持在企微里「重新提交」(企微新审批单卡管不关联);已拒绝的退款单请在卡管用 `POST /api/admin/refunds/{id}/resubmit` 重新发起。
- 如页面有提示「可在企微重新提交」之类文案,请去掉。
---
## 三、新增 / 变化的错误码
| 码 | 接口 | 含义 | 前端处理 |
|---|---|---|---|
| 1202 | `POST /api/admin/exchanges`、`.../{id}/complete` | 新资产已绑定手机号 | 读 `data.phone`,引导去后台解除 |
| 1192 | `POST /api/c/v1/auth/bind-phone` | 资产已绑定其他手机号 | 提示联系管理员,不重试 |
| 参数不合法 | 密码相关 7 个入口 | 带字段级原因的 `message` | 直接展示 `message` |
---
## 四、联调自测建议
1. 订单:用 C 端微信已支付订单看详情,`payments` 有记录、三个字段与支付单一致;代理/钱包订单三个字段为空串、`payments=[]`。
2. 状态枚举:造一个提交失败的单据(缺必填控件映射可复现),检查 6 类业务列表、筛选、按钮显隐。
3. 密码:`Abc12345` 通过;`abcd1234`、`Abc1234`(7 位)、`Abc123456789X`(13 位)被拒且提示文案可读。
4. 换货:对已绑手机号的资产发起换货,应弹出含号码的提示;后台解除后重新提交成功。
5. H5:同一客户绑定两个临期资产,进入 A 只看到 A 的提醒,当天再进不再出现。
6. 预警:规则页无流量额度;预警列表有阈值流量。
## 五、不需要前端改动的内容
- C 端订单接口、H5 退款接口无变化。
- 预警判定逻辑、套餐接口(`real_data_mb` 在套餐里仍存在)无变化。
- M13 无字段变化;M4~M6 导出由后端新增列。