# 我的订单 — 前端技术方案（C 端 · shop-app）

> **依据：** 《我的订单功能需求.md》v1.2、《我的订单技术方案.md》v1.3  
> **关联：** 《确认订单页（多商品）前端技术方案》、《确认订单页（单商品）前端技术方案》、《购物车前端技术方案》  
> **范围：** 消费者 APP **`shop-app`** 个人中心订单入口、订单列表/详情、续付、确认收货、评价、售后。  
> **实现状态：** v1.4 — 列表 **售后状态优先展示**（MO-L4）、待付款 **应付** 文案、全量商品行 + 行内评价已落地。

---

## 1. 技术栈与约定

| 项 | 说明 |
|----|------|
| 框架 | uni-app **Vue 3** + **uview-plus** |
| 请求 | `@/utils/request`；须会员 Token |
| 鉴权 | 进入页 **`ensureApiToken()`**；无 Token → 引导登录 |
| 分页 | 列表 `pageNum` / `pageSize`；下拉刷新 + 上拉加载 |
| 支付 v1 | **Mock 弹窗** + `payOrder`；与确认订单共用 |
| 防抖 | 列表/详情操作 `useActionGuard` |
| 再买一单 | 跳转 `subpackage/goods/detail?id={goodsId}` |

---

## 2. 页面与路由

| 页面 | 路径 | 说明 |
|------|------|------|
| 个人中心订单区 | `pages/mine/index`（区块） | 角标 + 快捷入口 |
| 订单列表 | `subpackage/order/list` | tab + 分页列表 |
| 订单详情 | `subpackage/order/detail` | 分状态展示与操作 |
| 评价列表 | `subpackage/order/review-list` | 待评价/已评价（展平商品行） |
| 评价查看 | `subpackage/order/review-view` | 全页查看评价 |
| 评价编辑 | `subpackage/order/review-edit` | 打星+图文 |
| 售后列表 | `subpackage/order/aftersale-list` | 进行中/已完结 |
| 售后详情 | `subpackage/order/aftersale-detail` | 进度+处理结果 |
| 提交售后 | `subpackage/order/aftersale-submit` | 表单页 |

**Query 示例：**

| 页面 | 参数 |
|------|------|
| 订单列表 | `tab=PENDING_PAY`（可选，默认 ALL） |
| 订单详情 | `orderId=900` |
| 评价列表 | `tab=PENDING` / `tab=DONE` |
| 评价编辑 | `orderId=900&orderItemId=10` |
| 提交售后 | `orderId=900`（整单，无需 itemId） |

**路径常量：** `utils/pageRoute.js`（`PAGE_ORDER_*`）

**分包：** `pages.json` → `pkg-order`；`pages/mine/index` 预加载 `pkg-order`。

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| API | `shop-app/api/order.js` | badges/list/detail/pay/confirm |
| API | `shop-app/api/orderReview.js` | 评价 list/submit/get |
| API | `shop-app/api/orderAftersale.js` | 售后 list/detail/submit |
| 常量 | `shop-app/constants/order.js` | tab、主状态、售后卡片文案 |
| 映射 | `shop-app/utils/orderDisplay.js` | VO → 页面模型、actions、MO-L4 |
| 操作 | `shop-app/utils/orderAction.js` | 支付弹窗、确认收货、售后入口 |
| 导航 | `shop-app/utils/orderNav.js` | 列表/详情/评价/售后跳转 |
| 列表页 | `subpackage/order/list.vue` | |
| 详情页 | `subpackage/order/detail.vue` | |
| 评价/售后页 | `subpackage/order/*.vue` | |
| 组件 | `components/order/OrderGoodsRow.vue` | 商品行 + **行内评价** |
| 组件 | `components/order/OrderStatusBar.vue` | 详情状态+倒计时 |
| 组件 | `components/order/OrderActionBar.vue` | 底部操作（无整单评价） |
| 组件 | `components/order/ReviewDoneSummaryCard.vue` | 已评价紧凑卡 |

---

## 4. 接口封装

### 4.1 订单 `api/order.js`

| 方法 | HTTP | 路径 |
|------|------|------|
| `getOrderBadges()` | GET | `/api/order/badges` |
| `listOrders(params)` | GET | `/api/order/list` |
| `getOrderDetail(orderId)` | GET | `/api/order/{orderId}` |
| `payOrder(orderId)` | POST | `/api/order/{orderId}/pay` |
| `cancelPay(orderId)` | POST | `/api/order/{orderId}/pay/cancel` |
| `confirmReceive(orderId)` | POST | `/api/order/{orderId}/confirm-receive` |

**listOrders params：**

```javascript
{ tab: 'ALL', pageNum: 1, pageSize: 10 }
```

**列表行新增字段（v1.2）：**

| 字段 | 说明 |
|------|------|
| `aftersaleStatus` | `null` / `1` 进行中 / `2` 已完结 |
| `orderStatusText` | 订单主状态文案（待付款/待发货…） |
| `items[]` | 全部商品行 |

### 4.2 评价 `api/orderReview.js`

| 方法 | HTTP | 路径 |
|------|------|------|
| `listReviews(params)` | GET | `/api/order/review/list` |
| `getOrderReview(orderId, orderItemId)` | GET | `/api/order/{orderId}/review?orderItemId=` |
| `submitReview(orderId, data)` | POST | `/api/order/{orderId}/review` |

### 4.3 售后 `api/orderAftersale.js`

| 方法 | HTTP | 路径 |
|------|------|------|
| `listAftersales(params)` | GET | `/api/order/aftersale/list` |
| `getAftersaleDetail(aftersaleId)` | GET | `/api/order/aftersale/{aftersaleId}` |
| `submitAftersale(data)` | POST | `/api/order/aftersale/submit` |

---

## 5. 订单列表（`list.vue`）

### 5.1 页签与入口

| 页签 | `ORDER_TAB` | 说明 |
|------|-------------|------|
| 全部 | `ALL` | |
| 待付款 | `PENDING_PAY` | 续付入口 |
| 待发货 | `PENDING_SHIP` | |
| 待收货 | `PENDING_RECEIVE` | 平台已发货 |
| 已完成 | `COMPLETED` | 交易成功 |
| 已关闭 | `CLOSED` | |

顶栏链接：**评价** → `review-list`；**退款/售后** → `aftersale-list`。

### 5.2 卡片结构

```text
order-card
├── 店头：头像 + 店名 + statusText（MO-L4）
├── 商品区：OrderGoodsRow × items.length（全量）
│   └── 已完成：行内「评价」/「查看评价」
├── 下单时间 + amountLabel + payAmountText
├── 待付款：支付倒计时 payRemainSeconds
└── OrderActionBar（无 REVIEW / VIEW_REVIEW）
```

### 5.3 列表状态文案（MO-L4）

`mapOrderCardStatusText(orderStatusText, aftersaleStatus)`：

| aftersaleStatus | 卡片 statusText |
|-----------------|-----------------|
| `1` | **售后处理中** |
| `2` | **售后已完成** |
| `null` / 无 | **orderStatusText**（待付款/待发货/交易成功…） |

- 保留字段 `orderStatusText`、`aftersaleStatus` 供调试；**展示用 `statusText`**
- 有售后态时 `statusIsAftersale=true`，样式蓝色区分
- **详情页**仍展示订单主状态（不套用 MO-L4）

### 5.4 金额文案

| orderStatus | amountLabel |
|-------------|-------------|
| `0` 待支付 | **应付** |
| 其它 | **实付** |

---

## 6. 订单详情（`detail.vue`）

- `OrderStatusBar`：主状态 + 待付款倒计时 / 关闭原因 / 最新物流摘要
- 收货快照、全部 `items[]`（含服务保障、行小计、行备注）
- 行内评价按钮（同列表）
- 底部 `OrderActionBar`：过滤整单评价按钮
- 分状态字段：支付时间、成交时间、关闭原因、物流节点（无地图）

---

## 7. 评价模块

### 7.1 评价列表 `review-list.vue`

| Tab | 展示 | 点击 |
|-----|------|------|
| 待评价 | 展平 `PENDING` 商品行 +「评价」 | 商品区→订单详情；评价→`review-edit` |
| 已评价 | `ReviewDoneSummaryCard` 紧凑卡 | → `review-view` |

### 7.2 评价编辑 `review-edit.vue`

`orderId` + `orderItemId` → `submitReview`；顶部展示评价商品。

### 7.3 一行一评

- `reviewStatus` per `orderItemId`：`PENDING` / `DONE` / `NONE`
- 底部 actions **不含** `REVIEW`、`VIEW_REVIEW`

---

## 8. 售后模块

- 列表：`aftersale-list` 进行中/已完结（文案：商家处理中/售后完结）
- 详情：`aftersale-detail` 进度 + 凭证图（`normalizePicList`）
- 提交：`aftersale-submit` 类型/原因/凭证

**与订单列表文案区分：** 订单卡片用「售后处理中/售后已完成」；售后专区用「商家处理中/售后完结」。

---

## 9. 页面流程

### 9.1 个人中心角标

```text
onShow → getOrderBadges()
    → pendingPayCount / pendingShipCount / pendingReceiveCount / aftersaleInProgressCount
    → 点击快捷入口带 tab 进 list 或 aftersale-list
```

### 9.2 续付（待付款）

```text
「去支付」→ openPayModal → payOrder
    ├── 成功 → 刷新列表/详情
    └── 失败/超时 → Toast + 刷新
```

### 9.3 确认收货

```text
showModal → confirmReceive → 可选 goReviewEdit
```

### 9.4 提交售后（整单）

```text
详情/列表「申请售后」
    → goAftersaleSubmit(orderId)（不选商品、不弹 ActionSheet）
    → aftersale-submit 展示订单全部 items[]
    → 申请金额默认订单实付；退货数量上限为整单件数之和
    → submitAftersale({ orderId, orderItemId: 首行ID, ... })
         ※ orderItemId 为接口兼容字段，业务口径为整单售后
    → aftersale-detail 或 aftersale-list
```

---

## 10. 展示映射 `orderDisplay.js`

| 函数 | 用途 |
|------|------|
| `mapOrderListRow` | 列表卡片；`items[]` 全量；MO-L4 `statusText`；`amountLabel` |
| `mapOrderCardStatusText` | 列表售后态优先 |
| `mapOrderDetail` | 详情；主状态 `orderStatusText` |
| `getItemReviewAction` | 行内评价按钮 |
| `mapActions` | 过滤整单评价 |
| `flattenPendingReviewItems` / `mapReviewDoneRow` | 评价列表 |
| `mapAftersaleListRow` / `mapAftersaleDetail` | 售后专区 |

---

## 11. 与确认订单衔接

| 场景 | 行为 |
|------|------|
| 支付成功 | `pay-result` 或进 `list?tab=PENDING_SHIP` |
| 取消支付 | `list?tab=CLOSED` 或详情已关闭 |
| 购物车结算 | `checkout-cart` → 支付后进订单列表 |

---

## 12. 联调检查清单

- [ ] 未登录引导登录
- [ ] 角标与列表 tab 一致
- [ ] 多商品订单列表展示全部 items
- [ ] 行内评价；底部无整单评价
- [ ] `aftersaleStatus=1` → 列表「售后处理中」；`=2` →「售后已完成」
- [ ] 无售后 → 显示 orderStatusText
- [ ] 待付款显示「应付」+ 倒计时 + 去支付
- [ ] 确认收货 → 交易成功 + 可评价
- [ ] 评价列表待评价/已评价交互
- [ ] 售后提交后进进行中列表

---

## 13. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.5** | 售后改为 **整单申请**：去掉多商品选择；`aftersale-submit` 展示全量商品；路由仅 `orderId` |
| **v1.4** | 对齐需求 **v1.2**：`mapOrderCardStatusText`（MO-L4）、待付款「应付」、常量 `ORDER_AFTERSALE_CARD_*`；文档补全评价/售后/确认订单边界 |
| **v1.3** | 文档规划 aftersaleStatus 映射（代码待落地） |
| **v1.2** | 列表/详情全量 items；行内评价；底部去整单评价 |
| **v1.1** | 落地分包页、个人中心角标、公共组件 |
| **v1.0** | 首版路由与 API |

---

*文档版本：v1.5 · 关联《我的订单功能需求.md》v1.2、《我的订单技术方案.md》v1.3*
