one-pipe-system/openspec/changes/update-october-batch-one-admin-integration/proposal.md

Change: 十月第 1 批后台前端对接修正

Why

依据 第 1 批前端对接说明，后台现有代码仍使用旧密码校验、旧审批业务状态和旧预警规则字段，缺少订单在线支付记录与换货手机号冲突反馈。后端已部署测试环境，后台需要同步契约与交互，避免失败单据继续显示审批恢复操作、导入提示误导以及已删除字段显示异常。

用户已于 2026-10-13 批准实施。后台代码已完成适配，本地验证与真实后端联调状态分开记录在 实施记录。原范围只管后台；2026-10-14 用户明确追加代理扫码注册页及同一注册接口的密码校验和失败提示，其余 /api/c/v1 接口及 C 端页面仍不在范围内。

What Changes

• M3：后台订单列表和详情展示 third_party_trade_no、payment_channel、payment_merchant_name；详情新增支付记录表，详情类型与列表/创建类型分离，支付单状态独立于订单支付状态。
• M8、M14：六类后台业务补充各自的「审批提交失败」终态、筛选、标签和操作判断；显式失败不再恢复原审批，结果未知保留原有恢复资格与权限判断。
• M8：核销申请列表和详情使用真实的 approval_submission_status 展示审批提交状态，不能只依赖当前可能为空的名称字段；账单详情中的申请状态同步扩展。
• M1：BREAKING：按 2026-10-14 用户修正，后台七个密码接口相关表单、服务和类型统一到「8～12 位，大写、小写、数字、半角特殊符号至少三类，无空格或中文」，包括后台 PUT /api/auth/password；账号独立改密使用 new_password。本人改密弹窗挂载到 body，使遮罩覆盖侧栏。旧密码输入、操作密码和 WiFi 密码不套用新规则。
• 用户追加 M1：代理扫码注册页与 POST /api/c/v1/agent-distribution-registrations 的 password 复用相同校验；同步 12 位输入上限、可见规则及强度反馈，其他注册字段、短信、接口路径和免 Token 行为不变。
• 用户追加注册反馈：仅原公开代理注册请求关闭公共错误消息，页面将 1050/1001 映射为「注册失败, 请联系管理员」且每次失败只提示一次，其他业务错误按其具体原因展示；不修改公共 HTTP 处理或其他接口。
• 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	后台七个密码接口；用户追加代理扫码注册页面及原注册接口的密码校验、失败提示	其他 C 端页面/接口与非登录密码
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 服务或页面；不改变公开注册请求路径、字段和免 Token 行为。
• 不新增后端接口、权限编码、审批实例或财务冻结/释放逻辑。
• 不因密码接口清单存在而补建目前没有的账号改密页面；覆盖既有页面和服务契约，新增入口须另行确认。
• 不修改 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/agent-registration/index.vue、src/api/modules/agentDistribution.ts 的注册密码校验与类型注释。
  • 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. 用户于 2026-10-14 修正为允许特殊符号，恢复说明中的「四类至少三类」口径，长度 8～12 位、禁止空白和中文；半角可打印 ASCII 特殊符号均可用。此前禁止特殊符号的确认不再适用。
3. 除 2026-10-14 明确追加的代理扫码注册页/同一注册接口的密码规则与失败提示外，其他 /api/c/v1 和 C 端页面仍排除。

以上需求疑问已消除。详见 设计说明、任务清单 与 实施记录；如联调发现实际接口与说明或用户确认不符，先向用户反馈，不自行改变口径。