# 第 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 导出由后端新增列。