fix: some

docs/10月份修改/第1批-8-9月迭代前端对接说明.md

@@ -0,0 +1,335 @@
+# 第 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 导出由后端新增列。