# 发货管理 — 前端技术方案

> **依据：** 《发货管理功能需求.md》v1.3、《发货管理技术方案.md》v1.3  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端** 履约工作台（待发货 / 已发货 / 已完成）列表、角标、详情、整单发货、物流更新、送达登记；**不含** 删除、关闭、待支付/已关闭/已删除、拆单/部分发货。  
> **实现状态：** 页面与 API 封装已落地，待菜单配置及 `/agri/seller/ship` 联调。

---

## 1. 技术栈与写法约定

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` + `sellerShopHeaders()` 携带 **`X-Shop-Id`** |
| 参考页面 | `agri/seller/order/index.vue`（列表/履约弹窗）；本模块为 **履约子集** |
| 布局 | 检索 `el-card` + `<br/>` + 列表 `el-card` + `border` 表格 |
| 详情 | 右侧 `el-drawer`（含店铺发货信息只读参考） |
| 店铺切换 | **仅 Navbar**；业务页不展示店铺选择器 |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/seller/ship/index.vue` | 页签角标、检索、列表、履约弹窗 |
| 详情抽屉 | `ruoyi-ui/src/views/agri/seller/ship/detail.vue` | 分区展示、物流轴、店铺发货参考 |
| 发货 API | `ruoyi-ui/src/api/agri/seller/ship.js` | badges、list、detail、ship、logistics、delivered |
| 店铺上下文 | `api/agri/seller/context.js` + `utils/sellerShop.js` | X-Shop-Id |

**组件 name（keep-alive）：** `AgriSellerShip`

---

## 3. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 发货管理 | `agri/seller/ship/index` | `seller/ship` | `agri:seller:ship:list` |

**上级菜单：** 店铺经营管理端 → **订单管理**

| 按钮权限 | 标识 | 说明 |
|----------|------|------|
| 列表 / 角标 | `agri:seller:ship:list` | 页签列表 |
| 详情 | `agri:seller:ship:query` | 查看详情抽屉 |
| 发货 / 物流 / 送达 | `agri:seller:ship:ship` | 去发货、更新物流、商品到货 |

> 可与 `agri:seller:order:ship` **合并授权**；与全部订单 **分菜单**。跳转全部订单需 `agri:seller:order:list`。

---

## 4. 页面结构

```text
发货管理（履约工作台）
├── 检索区（el-card）
│   ├── 订单编号 orderNo
│   ├── 商品名称 goodsName
│   ├── 收货人 consigneeName、收货手机 consigneeMobile、收货地址 consigneeAddress
│   ├── 配送方式 deliveryType（1物流/2商家配送）
│   └── 下单时间 beginTime～endTime
├── 列表区（el-card + border 表格）
│   ├── 页签（带角标）：待发货 | 已发货 | 已完成
│   ├── 工具栏：查看全部订单 → /seller/order
│   ├── 列：订单信息、订单金额、会员名称、收货人、配送方式、状态、操作
│   ├── 空状态：按页签 / 检索分场景文案
│   └── 分页
├── 详情抽屉 detail.vue
│   ├── 基本 / 商品 / 收货 / 店铺发货信息（只读）/ 物流 / 物流轴（倒序）
│   └── 操作：去发货、更新物流、商品到货（按状态）
├── 发货弹窗（待发货 · 整单 · 不预填 · 提交时后端快照配送设置）
├── 更新物流弹窗（已发货）
└── 商品到货弹窗（已发货）
```

**不提供：** 页内店铺选择、删除、关闭、待支付/已关闭/已删除页签、发货状态检索（`shipStatus`）、拆单/部分发货。

---

## 5. 状态页签与 Query

| 页签 | `statusTab` | 传参 `orderStatus`（必填） |
|------|-------------|---------------------------|
| 待发货 | `1` | `1`（**默认进入**） |
| 已发货 | `2` | `2` |
| 已完成 | `3` | `3` |

**角标：** `GET /badges` → `pendingShipCount` / `shippedCount` / `completedCount`，页签 label 展示 `(N)`。

页签与高级检索 **AND** 组合；切换页签重置 `pageNum=1`。

**深链：** 支持 `?orderStatus=1|2|3` 预设页签。

---

## 6. 店铺上下文（X-Shop-Id）

| 步骤 | 说明 |
|------|------|
| `created` | `GET /agri/seller/context` → `setSellerShopContext` |
| 列表/详情/履约 | `sellerShopHeaders()` |
| Navbar 切店 | `location.reload()` 整页刷新 |

---

## 7. API 封装

**模块：** `ruoyi-ui/src/api/agri/seller/ship.js`  
**Base URL：** `/agri/seller/ship`

| 前端方法 | HTTP | 路径 |
|----------|------|------|
| `getSellerShipBadges()` | GET | `/badges` |
| `listSellerShip(query)` | GET | `/list` |
| `getSellerShip(orderId)` | GET | `/{orderId}` |
| `shipSellerShip(orderId, data)` | POST | `/{orderId}/ship` |
| `logisticsSellerShip(orderId, data)` | POST | `/{orderId}/logistics` |
| `deliveredSellerShip(orderId, data)` | POST | `/{orderId}/delivered` |

### 7.1 列表 Query

与 `SellerOrderQuery` 对齐；**必须** 传 `orderStatus`（`1`/`2`/`3`）。**不含** `shipStatus`。

| 字段 | 说明 |
|------|------|
| orderStatus | 页签状态（必填） |
| orderNo, goodsName | 模糊 |
| consigneeName, consigneeMobile, consigneeAddress | 模糊 |
| deliveryType | `1` / `2` |
| beginTime, endTime | 下单时间区间 |
| pageNum, pageSize | 分页 |

### 7.2 列表行

复用 `OrderListRowVO`（与全部订单相同列展示逻辑）。

### 7.3 详情扩展

**订单快照字段（已发货/已完成 · v1.3）：** `shipperName`、`shipperMobile`、`shipRegionName`、`shipDetailAddress`。

**待发货参考：** 后端附加 **`shopDelivery`**（`ShopDeliverySettingVO | null`）：

| 场景 | 前端 |
|------|------|
| 已有发货快照 | 「发货信息（订单快照）」区 |
| 待发货 + 已配置配送 | 「店铺发货信息（参考）」只读区 |
| 待发货 + 未配置 | 提示 + 跳转 `/seller/delivery` |


> 弹窗 **不预填**（DS6）；提示 **发货时将按配送设置快照至订单**。


### 7.4 履约 Body

与全部订单相同：

| 操作 | Body |
|------|------|
| 发货 | `OrderShipDTO`：shipTime、deliveryType、物流/配送员字段、shipRemark；**整单一次发完**（O5 / FM4） |
| 更新物流 | `OrderLogisticsDTO`：traceTime、content |
| 登记送达 | `OrderDeliveredDTO`：traceTime、content（选填） |

---

## 8. 整单发货弹窗（v1.2）

| 项 | 说明 |
|----|------|
| 商品清单 | 打开弹窗前 `GET /{orderId}` 取 `items`，**只读** 表格展示全部行 |
| 数量 | 不可编辑、不可勾选子集；提示「须整单一次发完，不可拆单」 |
| 配送字段 | 商家 **手动填写**；**不读取** `shopDelivery` 预填（DS6） |
| 配送方式切换 | `deliveryType=1` 显物流字段；`=2` 显配送员字段 |
| 提交 | `POST /{orderId}/ship`；成功后关闭弹窗并 `refreshData()` |

---

## 9. 操作与状态矩阵

| orderStatus | 列表/详情操作 |
|-------------|---------------|
| `1` 待发货 | 详情、去发货 |
| `2` 已发货 | 详情、更新物流、商品到货 |
| `3` 已完成 | 仅详情 |

**不提供删除**（见全部订单 `/agri/seller/order`）。

---

## 10. 空状态与错误处理

### 10.1 列表空状态

表格 `:empty-text="emptyTableText"`，由 `hasSearchFilter` + 当前页签决定：

| 条件 | 文案 |
|------|------|
| 有检索条件且无结果 | 未找到符合条件的订单 |
| 待发货页签无数据 | 暂无待发货订单 |
| 已发货页签无数据 | 暂无已发货订单 |
| 已完成页签无数据 | 暂无已完成订单 |

### 10.2 并发冲突

平台或其他端已变更订单状态时，履约接口返回业务错误（`request` 拦截器已 toast）。前端在 **发货 / 更新物流 / 登记送达 / 打开发货弹窗** 失败时：

1. 关闭对应弹窗（若已打开）  
2. 调用 `refreshData()`（角标 + 列表）  
3. 若详情抽屉打开，调用 `shipDetail.reload()`

---

## 11. 与全部订单分工

| 维度 | 全部订单 | 发货管理 |
|------|----------|----------|
| API 基路径 | `/agri/seller/order` | `/agri/seller/ship` |
| 页签 | 含 0/4/5 | 仅 1/2/3 |
| 角标 | 无 | `/badges` |
| 删除 | ✓ | **无** |
| 检索 shipStatus | ✓ | **无** |
| 详情 shopDelivery | 无 | **有**（只读参考） |
| 拆单 | **禁止** | **禁止**（整单 O5） |

列表页工具栏 **「查看全部订单」**：

```javascript
this.$router.push({ path: '/seller/order' })
```

需权限 `agri:seller:order:list`；用于查看待支付、已关闭等非履约单。

---

## 12. 联调检查清单

- [ ] 菜单 `agri/seller/ship/index` 及按钮权限
- [ ] 默认进入待发货页签；角标与列表数量一致
- [ ] 待发货 → 整单发货（商品只读、不预填配送设置）→ 已发货页签
- [ ] 已发货 → 更新物流 / 登记送达 → 状态仍为已发货
- [ ] 买家确认收货后 → 已完成页签只读
- [ ] 详情 shopDelivery 有/无两种展示；未配置可跳转配送设置
- [ ] 物流时间轴倒序（后端 `traceList` DESC）
- [ ] 各页签空状态文案正确
- [ ] 「查看全部订单」跳转 `/seller/order`
- [ ] 平台抢先发货时后端报错并自动刷新列表/详情


## 13. 修订记录

| 版本 | 说明 |
|------|------|
| v1.1 | 发货快照展示；详情优先 `shipper*` 订单字段 |
| v1.0 | 首版：履约三页签 + 角标 + 详情 shopDelivery + 履约三弹窗 |
| v1.2 | 对齐需求 v1.2：整单发货（移除拆单）、去发货不预填 DS6、无 shipStatus 检索、启用「查看全部订单」、页签空状态、履约失败并发刷新 |

---

*文档版本：v1.2 · 关联《发货管理功能需求.md》v1.2、《发货管理技术方案.md》v1.2 · 并列见《全部订单前端技术方案.md》*


