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

18 KiB
Raw Permalink Blame History

第 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 接口被拒时,换货单停在「已发货待确认」,解除后可重新确认。

响应示例

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