18 KiB
第 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-approvalPOST /api/admin/employee-collection-applications/{id}/recover-approvalPOST /api/admin/agent-distribution-registrations/{id}/recover-approval只显示「重新发起」。
- 「提交结果未知」不是失败,仍显示「恢复审批」,由后台任务确认。
- 佣金提现变为 5 后,冻结金额已自动释放;重新发起时重新冻结。
- 核销申请:释放预占金额,账单可再次核销。
核销申请额外变化(M8):approval_submission_status 以前恒为空,现在返回真实值:
0 待提交 / 1 提交中 / 2 已提交 / 3 提交失败 / 4 结果未知(无审批上下文为 0)。列表与详情都有。
前端要做:
- 6 处状态枚举/标签/颜色补充新值(建议红色或灰色,标注「终态」);
- 列表筛选下拉加该选项;
- 操作按钮:该状态隐藏「恢复审批」,保留「重新发起」;
- 核销申请列表/详情展示「审批提交状态」。
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接口被拒时,换货单停在「已发货待确认」,解除后可重新确认。
响应示例
{
"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 |
四、联调自测建议
- 订单:用 C 端微信已支付订单看详情,
payments有记录、三个字段与支付单一致;代理/钱包订单三个字段为空串、payments=[]。 - 状态枚举:造一个提交失败的单据(缺必填控件映射可复现),检查 6 类业务列表、筛选、按钮显隐。
- 密码:
Abc12345通过;abcd1234、Abc1234(7 位)、Abc123456789X(13 位)被拒且提示文案可读。 - 换货:对已绑手机号的资产发起换货,应弹出含号码的提示;后台解除后重新提交成功。
- H5:同一客户绑定两个临期资产,进入 A 只看到 A 的提醒,当天再进不再出现。
- 预警:规则页无流量额度;预警列表有阈值流量。
五、不需要前端改动的内容
- C 端订单接口、H5 退款接口无变化。
- 预警判定逻辑、套餐接口(
real_data_mb在套餐里仍存在)无变化。 - M13 无字段变化;M4~M6 导出由后端新增列。