8.1 KiB
8.1 KiB
name, overview, todos
| name | overview | todos | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 前端对齐后端退款流程重构（订单状态6） | 前端唯一未同步的后端变更是最新提交 b94dd6d（退款全流程重构 + 新增订单状态 6「申请退款中」）。需在订单页补齐状态 6 的筛选、文案、样式与提示，并按设计文档补充退款状态轮询；其余近期后端改动前端均已同步。 |
|
需求概述
用户修改了衣橱小程序的后端代码（退款流程重构），需要检查配套小程序前端是否需要同步修改，并给出具体修改方案。
补充业务约束（用户强调）：处于「6 申请退款中」的订单，用户不可再次发起退款，只能等待审核/退款结果。
排查结论
- 经逐提交核对，前端此前已同步后端近期绝大多数改动：通知「全部已读」接口、通过社区公开穿搭只读查看衣物、衣物处理失败原因与处理状态字段等，均已在现有前端代码中落地。
- 唯一尚未同步的是后端最新的退款流程重构：订单新增「6 申请退款中」状态（申请退款后进入待审核、退款失败回到「已支付」可重新申请、退款成功变为「已退款」）。前端订单页目前缺少该状态的展示与退款结果跟踪能力，需要补齐。
核心功能
- 订单列表状态徽标新增「申请退款中」（进行中语义），并在「已支付」与「已取消」之间新增对应筛选标签
- 申请退款提交后，订单显示「申请退款中」及审核中提示；前端周期性跟踪退款结果：成功显示「已退款」并提示、失败回到「已支付」并提示可重新申请
- 「申请退款中」订单为纯等待态：不展示任何退款/取消等操作入口，用户不可再次发起退款，只能等待结果（后端同样拒绝：
RefundApply仅接受订单状态2 已支付，状态 6 再次申请返回 71001「当前状态不允许退款」） - iOS 虚拟支付订单不展示「申请退款」入口（按后端规则需走 App Store 退款）
- 其余交互（退款原因填写与长度限制、提交成功提示、退款相关错误码文案）已满足新契约，无需调整
排查范围与结论
对比前端最新提交（98c45f2）与后端仓库 /root/zt-closet-backend 最新提交（b94dd6d）：
- 已同步：
89b59c7通知全部已读（前端 notification.ts 已调用POST /notification/read-all，并处理返回的 unread_count）、c2519c4社区公开穿搭只读查看衣物（clothes-detail/outfit-detail 已携带outfit_uuid）、e9b9754衣物处理失败原因（upload/clothes-detail 已使用image_process_status/fail_reason）。 - 未同步：
b94dd6d退款全流程重构 —— 订单状态枚举扩展为oneof=1 2 3 4 5 6，OrderStatusRefunding = 6，退款申请原子流转 2→6 并落待审核流水，退款成功→5、失败→回2。前端需对齐。
技术栈
- 微信小程序原生（TypeScript + WXML + WXSS），沿用现有
utils/request封装、utils/logger日志、STATUS_*常量映射模式与全局 pill 胶囊样式体系，无新增依赖。 - 类型校验：
npx tsc --noEmit（仓库无 npm scripts）。
实现方案
- 状态契约对齐：
utils/config.ts的OrderStatus枚举新增REFUNDING = 6 // 申请退款中；types/models.ts中order_status注释补充6=申请退款中。 - 订单页展示（对齐 Stitch.md 设计约定）：
STATUS_TEXT增加6: '申请退款中'；STATUS_CLS增加6: 'pill--ink'（遵循 app.wxss「进行中/强调 = pill--ink」约定）；STATUS_FILTERS在「已支付」之后插入{ name: '申请退款中', value: 6 }（索引与数组同步，筛选逻辑不受影响）。- wxml 操作区新增
wx:elif="{{item.order_status === 6}}"分支：仅渲染灰字等待提示（如「退款审核中，审核结果将通过站内通知告知」），不提供任何可点击操作项——不显示「申请退款」，也不显示「取消订单」，用户只能等待轮询/通知给出结果。优先复用.od-countdown同类灰字样式，必要时新增等价小类。
- iOS 虚拟支付退款入口收敛：
RefundApply对 iOS 虚拟订单返回 71004（错误码文案前端已具备兜底）。订单响应无平台字段，页面用wx.getSystemInfoSync().platform判定（与 mall.ts 的 normalizePlatform 同一数据源，需 try/catch 兜底），新增_canRefund= 状态2且非（pay_channel === 2且 iOS），wxml 按钮改用该标记（状态 6 天然不在_canRefund范围，不会再出现退款入口）。 - 退款状态轮询（设计文档明确约定「前端轮询 GET /order」）：列表存在状态 6 订单时，每约 10 秒静默请求
GET /order?status=6&page=1&page_size=50（showError: false，独立于 fetchList 的 reqSeq 机制，避免干扰列表与闪烁）；被跟踪订单从响应中消失即表示已离开退款中 → 触发一次refresh()，并按刷新结果提示：5→「退款成功」、2→「退款未通过，可重新申请」（找不到时用通用文案）；仍为 6 继续等待。无状态 6 订单不发请求；onHide/onUnload清理定时器（与既有倒计时 timer 分开管理，避免互相覆盖）。 - 不改动项（经核实）：退款提交交互与文案已满足新契约；状态 6 期间前端无退款入口、后端也拒绝重复申请，天然不会触发 71001；
mall.ts支付轮询终态判断（3/4/5）在支付场景不会遇到状态 6；错误码 71000-71004 文案已齐备。
实现说明（执行要点）
- 性能与请求量：轮询为单用户轻量查询（page_size 50 封顶），仅在存在状态 6 订单时触发；失败静默降级（
logger.warn）等待下一轮重试，不阻塞 UI。 - 日志：复用
logger（模块名order），仅状态流转与请求失败时记录，成功轮询走 debug，避免日志刷屏。 - 影响面控制：改动仅限订单页与类型/枚举注释，其余页面与接口无波及；若后端未上线新版本（不返回状态 6），前端行为与现状完全一致，可安全先行发布。
目录结构（仅列出改动文件）
zt-closet-wxmini-frontend/
└── miniprogram/
├── utils/
│ └── config.ts # [MODIFY] OrderStatus 枚举新增 REFUNDING = 6；错误码区已含 71000-71004，无需改动
├── types/
│ └── models.ts # [MODIFY] OrderItem.order_status 注释补充「6 申请退款中」
└── pages/
└── order/
├── order.ts # [MODIFY] STATUS_TEXT/STATUS_CLS/STATUS_FILTERS 增加状态 6；新增 _canRefund（含 iOS 判定）；实现退款状态轮询与生命周期清理
├── order.wxml # [MODIFY] 状态 6 操作区仅渲染等待提示（无任何操作按钮）；「申请退款」按钮改用 _canRefund
└── order.wxss # [MODIFY/可选] 仅在需要新提示样式时补充，优先复用既有灰字样式
Agent Extensions
Skill
- lsp-code-analysis
- Purpose: 利用语义化引用分析核查
order_status、OrderStatus、STATUS_TEXT/STATUS_CLS等符号的全部引用，确认状态 6 同步无遗漏（区别于文本搜索的补充验证） - Expected outcome: 输出完整的引用清单，确认所有订单状态消费点均已覆盖，无遗漏文件