90 lines
9.9 KiB
Markdown
90 lines
9.9 KiB
Markdown
# Change: 十月第 1 批后台前端对接修正
|
||
|
||
## Why
|
||
|
||
依据 [第 1 批前端对接说明](../../../docs/产品迭代10月份修改/第1批-8-9月迭代前端对接说明.md)，后台现有代码仍使用旧密码校验、旧审批业务状态和旧预警规则字段，缺少订单在线支付记录与换货手机号冲突反馈。后端已部署测试环境，后台需要同步契约与交互，避免失败单据继续显示审批恢复操作、导入提示误导以及已删除字段显示异常。
|
||
|
||
用户已于 2026-10-13 批准实施。后台代码已完成适配，本地验证与真实后端联调状态分开记录在 [实施记录](./implementation.md)。用户已确认：只管后台，所有 `/api/c/v1` 接口及 C 端页面均不在范围内。
|
||
|
||
## What Changes
|
||
|
||
- M3：后台订单列表和详情展示 `third_party_trade_no`、`payment_channel`、`payment_merchant_name`；详情新增支付记录表，详情类型与列表/创建类型分离，支付单状态独立于订单支付状态。
|
||
- M8、M14：六类后台业务补充各自的「审批提交失败」终态、筛选、标签和操作判断；显式失败不再恢复原审批，结果未知保留原有恢复资格与权限判断。
|
||
- M8：核销申请列表和详情使用真实的 `approval_submission_status` 展示审批提交状态，不能只依赖当前可能为空的名称字段；账单详情中的申请状态同步扩展。
|
||
- M1：**BREAKING**：按用户最新确认，后台七个密码接口相关的既有表单、服务和类型统一到「8～12 位、只允许英文字母和数字，必须同时包含大写字母、小写字母和数字，不允许特殊符号」，包括后台 `PUT /api/auth/password`；账号独立改密服务按文档将请求字段修正为 `new_password`。旧密码登录、本人改密的旧密码输入、操作密码、WiFi 密码不套用新密码规则。
|
||
- M12：创建换货与确认完成捕获错误码 `1202`，从错误响应 `data.phone` 读取手机号，在弹窗中引导到已有「手机号资产关联」入口；不自动解绑、不新增扫码/退款前置拦截，失败时保留表单及原单状态。
|
||
- 用户追加 M12 快捷处理：跳转携带本次新资产标识与关联手机号，关联页面自动预填筛选并勾选匹配有效记录；复用原批量解绑权限和二次确认，结果表布尔值改为中文成功/失败，不自动执行解绑。
|
||
- M16：**BREAKING**：删除预警规则响应类型、规则列表及规则详情展示中对 `real_data_mb` 的依赖；预警列表和详情补齐 `used_mb`、`limit_mb` 及新增 `threshold_mb`，以 MB 展示触发时快照，说明包含加油包。套餐接口和套餐选项中的 `real_data_mb` 保留。
|
||
- M2：**BREAKING**：店铺业务员批量换绑说明及前端内置模板（如有）改用固定表头 `店铺编码,操作类型,平台登录账号,备注`，注明换绑时只填写平台用户登录手机号、清空时该列留空；不兼容旧表头，保留逐行失败原因。
|
||
- M23：设备导入文案将 IMEI 列从可选改为必填，不改变现有模板列名、列序、请求结构，也不新增 IMEI 长度、格式或重复校验；失败详情继续展示后端行号和原因。
|
||
- M13：保留退款状态 3 的重新发起入口；若存在引导在企微重新提交的文案则移除，统一指向后台退款重提流程。
|
||
- M4～M6 及 M16 导出补列：仅安排新建/历史导出任务下载回归，文件列由后端生成，不增加前端导出模板或修改历史文件。
|
||
|
||
## Scope
|
||
|
||
| 项目 | 后台纳入内容 | 不纳入内容 |
|
||
| --- | --- | --- |
|
||
| M1 | 本人改密、账号创建/修改/独立改密、店铺初始密码、企业创建/改密，共七个接口 | 扫码注册代理页面的密码校验 |
|
||
| M3 | `/api/admin/orders` 列表/创建响应与详情支付记录 | C 端订单请求、支付流程 |
|
||
| M8、M14 | 核销、退款、代理注册审核、线下充值、佣金提现、提现资料资格 | C 端注册申请及其他 `/api/c/v1` 调用 |
|
||
| M12、M13 | 换货冲突提示、退款重提引导及回归 | 后端手机号解绑规则、企微回调实现 |
|
||
| M16 | 预警规则与记录的展示契约、导出回归 | 预警计算、套餐商品额度调整 |
|
||
| M2、M23 | 导入说明/已有模板表头及任务失败原因 | 后端 CSV/Excel 解析器实现 |
|
||
| F1、M9 | 无 | H5 手机号绑定、登录响应、资产临期提醒、通知中心 |
|
||
|
||
### 审批失败状态与后台处理
|
||
|
||
| 后台业务 | 新业务状态 | 失败后的后台处理 |
|
||
| --- | --- | --- |
|
||
| 核销申请 | `4` | 有修改权限时，通过原 `PUT /api/admin/employee-collection-applications/{id}` 重新提交；账单重新读取可核销金额 |
|
||
| 退款 | `7` | 有重提权限时，通过原 `POST /api/admin/refunds/{id}/resubmit` 重新发起 |
|
||
| 代理注册审核 | `3` | 隐藏恢复审批，提示「请申请人重新扫码申请」；后台不代申请人发起 C 端注册请求 |
|
||
| 线下充值 | `7` | 复用现有线下新建表单，通过 `POST /api/admin/agent-recharges` 新建单，不给原单补发审批 |
|
||
| 佣金提现 | `5` | 在有操作资格的店铺提现入口，通过原 `PUT /api/admin/shops/{shop_id}/withdrawal-requests/{id}` 重新提交 |
|
||
| 提现资料资格 | `4` | 复用已有资料提交表单，通过原 `POST /api/admin/shops/{shop_id}/withdrawal-qualifications` 提交新版本 |
|
||
|
||
### 不新增的能力
|
||
|
||
- 不修改任何 `/api/c/v1` 服务封装或页面，包括本仓库已有的公开扫码注册页。
|
||
- 不新增后端接口、权限编码、审批实例或财务冻结/释放逻辑。
|
||
- 不因密码接口清单存在而补建目前没有的账号改密页面；覆盖既有页面和服务契约，新增入口须另行确认。
|
||
- 不修改 `src/types/components.d.ts` 的用户已有改动。
|
||
|
||
## Impact
|
||
|
||
- Affected specs: `order-management`、`admin-authentication`、`employee-collection`、`refund-management`、`agent-distribution-registration`、`agent-recharge`、`commission-management`、`exchange-management`、`phone-asset-association-management`、`package-traffic-alert`、`shop-management`、`device-batch-import`。
|
||
- Affected code:
|
||
- `src/types/api/{order,account,employeeCollection,refund,agentDistributionRegistration,agentRecharge,commission,packageTrafficAlert}.ts` 及相关类型导出。
|
||
- `src/api/modules/{order,account,exchange}.ts`；其余审批相关服务仅按既有接口复用，不扩展 C 端请求。
|
||
- `src/views/order-management/order-list/{index,detail}.vue`。
|
||
- `src/components/core/layouts/art-header-bar/ChangePasswordDialog.vue`、`src/views/account-management/{account,enterprise-customer}/index.vue`、`src/views/common/account-list.vue`、`src/views/shop-management/list/index.vue`。
|
||
- `src/views/finance/employee-collection/`、`src/views/finance/refund/`、`src/views/finance/agent-recharge/`、`src/views/shop-management/agent-distribution-registrations/`。
|
||
- `src/views/commission-management/{withdrawal-approval,my-commission}/index.vue` 及使用相同提现状态的其他后台视图。
|
||
- `src/views/asset-management/exchange-management/{index,detail}.vue`。
|
||
- `src/views/package-management/traffic-alert-rules/index.vue`、`src/views/package-management/traffic-alerts/{index,detail}.vue`。
|
||
- `src/views/shop-management/business-owner-import/index.vue`、`src/views/asset-management/task-management/device-task/index.vue`。
|
||
- `src/config/constants/{refund,commission}.ts`、新密码专用校验工具、`src/utils/business/apiError.ts`、必要的中英文文案。
|
||
- 不引入新依赖；复用现有 Vue、Element Plus、权限、表单、错误处理和异步任务机制。
|
||
|
||
### 与现有提案的关系
|
||
|
||
当前 `openspec/specs/` 无已发布能力规范，相关功能仅存在于历史未归档提案与业务代码中，因此本次沿用既有 capability 名称，以 `ADDED Requirements` 记录本批次的独立适配约束，不伪造 `MODIFIED` 基线。
|
||
|
||
- 订单：承接 `update-order-management-response-semantics`，保持操作者/销售店铺/佣金语义。
|
||
- 核销：承接 `update-employee-collection-approval-recovery`、`update-writeoff-application-and-superadmin-commission`，不回退抽屉和账单筛选优化。
|
||
- 退款：承接 `update-refund-management`、`add-refund-approval-recovery`。旧提案允许显式提交失败恢复原审批的描述，在新业务终态 `7` 下不再适用；保留结果未知的恢复路径。
|
||
- 代理注册：承接 `add-agent-registration-approval-management`，仅扩展后台审核状态和反馈。
|
||
- 充值：承接 `update-agent-self-recharge-and-offline-approval`，保留线下凭证、OCR、收款方式等已有字段。
|
||
- 佣金：承接 `add-commission-management`，保留既有店铺范围和超管选店逻辑。
|
||
- 换货：承接 `update-exchange-refund-interception-feedback`、`update-exchange-migration-and-shop-import`，`1202` 为独立定制反馈，非 `1202` 错误继续按原逻辑展示。
|
||
- 预警：承接 `add-package-traffic-alert`，其旧「规则展示当前真流量额度」描述被本批次规则响应契约取代。
|
||
- 导入：承接 `update-exchange-migration-and-shop-import`、`update-device-batch-import-contract`，保留任务字段与设备模板结构。
|
||
|
||
## 已确认的实施依据
|
||
|
||
1. 用户确认没有最新 `admin-openapi.yaml`，本次不要求提供，也不将其作为实施前置条件；接口适配以第 1 批对接说明为依据，仓库中的八月 OpenAPI 不作为十月最新版。
|
||
2. 用户确认密码不允许特殊符号，因此新密码只接受 ASCII 英文字母和数字，长度 8～12 位，必须同时包含大写、小写和数字；这一确认优先于原说明的「四类至少三类」规则。
|
||
3. 只实施后台，所有 `/api/c/v1` 和 C 端页面仍排除。
|
||
|
||
以上需求疑问已消除。详见 [设计说明](./design.md)、[任务清单](./tasks.md) 与 [实施记录](./implementation.md)；如联调发现实际接口与说明或用户确认不符，先向用户反馈，不自行改变口径。
|