96 lines
8.1 KiB
Markdown
96 lines
8.1 KiB
Markdown
---
|
||
name: 前端对齐后端退款流程重构（订单状态6）
|
||
overview: 前端唯一未同步的后端变更是最新提交 b94dd6d（退款全流程重构 + 新增订单状态 6「申请退款中」）。需在订单页补齐状态 6 的筛选、文案、样式与提示，并按设计文档补充退款状态轮询；其余近期后端改动前端均已同步。
|
||
todos:
|
||
- id: sync-order-status-def
|
||
content: 补充 config.ts OrderStatus 枚举与 models.ts 注释的状态 6「申请退款中」
|
||
status: completed
|
||
- id: order-page-status-6
|
||
content: order.ts 增加状态 6 文案、胶囊、筛选 tab 与 iOS 退款判定；order.wxml 增加审核中提示
|
||
status: completed
|
||
dependencies:
|
||
- sync-order-status-def
|
||
- id: refund-status-polling
|
||
content: order.ts 实现退款状态轮询：6→5/6→2 提示并刷新，页面隐藏即停止
|
||
status: completed
|
||
dependencies:
|
||
- order-page-status-6
|
||
- id: verify-order-sync
|
||
content: 用 [skill:lsp-code-analysis] 核查订单状态引用覆盖，运行 npx tsc --noEmit 并手工验证退款全流程
|
||
status: completed
|
||
dependencies:
|
||
- refund-status-polling
|
||
---
|
||
|
||
## 需求概述
|
||
|
||
用户修改了衣橱小程序的后端代码（退款流程重构），需要检查配套小程序前端是否需要同步修改，并给出具体修改方案。
|
||
|
||
补充业务约束（用户强调）：**处于「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）。
|
||
|
||
## 实现方案
|
||
|
||
1. **状态契约对齐**：`utils/config.ts` 的 `OrderStatus` 枚举新增 `REFUNDING = 6 // 申请退款中`；`types/models.ts` 中 `order_status` 注释补充 `6=申请退款中`。
|
||
2. **订单页展示**（对齐 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` 同类灰字样式，必要时新增等价小类。
|
||
|
||
3. **iOS 虚拟支付退款入口收敛**：`RefundApply` 对 iOS 虚拟订单返回 71004（错误码文案前端已具备兜底）。订单响应无平台字段，页面用 `wx.getSystemInfoSync().platform` 判定（与 mall.ts 的 normalizePlatform 同一数据源，需 try/catch 兜底），新增 `_canRefund` = 状态 `2` 且非（`pay_channel === 2` 且 iOS），wxml 按钮改用该标记（状态 6 天然不在 `_canRefund` 范围，不会再出现退款入口）。
|
||
4. **退款状态轮询**（设计文档明确约定「前端轮询 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 分开管理，避免互相覆盖）。
|
||
5. **不改动项（经核实）**：退款提交交互与文案已满足新契约；状态 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: 输出完整的引用清单，确认所有订单状态消费点均已覆盖，无遗漏文件 |