428 lines
15 KiB
Markdown
428 lines
15 KiB
Markdown
# 小程序订单与账单接口文档
|
||
|
||
> 适用端：微信小程序（h5 仓库，Taro）
|
||
> 覆盖接口：订单列表 / 订单详情、账单列表 / 账单详情
|
||
> 更新日期：2026-08-14
|
||
|
||
## 通用约定
|
||
|
||
| 项 | 说明 |
|
||
|---|---|
|
||
| 根地址 | `BASE_URL`（见 `src/utils/request.ts`，如 `http://localhost:8000/index.php`） |
|
||
| 认证 | 请求头 `Authorization: Bearer {token}`，token 来自登录接口，本地存储 key `auth_token` |
|
||
| 响应包络 | `{ success: boolean, data: T, msg?: string, showType?: number }` |
|
||
| 分页结构 | `{ data: T[], total: number, pageSize: number, current: number }`（账单列表在此结构上附加 `summary`） |
|
||
| 失败处理 | `success=false` 时 `msg` 为中文错误信息（含参数校验失败）；HTTP 401 表示登录过期，需重新登录 |
|
||
| 金额字段 | 一律为**字符串**（decimal 序列化，如 `"140.00"`），直接展示即可；参与计算需自行转 number |
|
||
| 门店隔离 | 两个列表均强制按当前用户绑定门店过滤，无需也不能传门店参数 |
|
||
|
||
## 状态枚举
|
||
|
||
**订单状态（status）**
|
||
|
||
| 值 | 名称 | 说明 |
|
||
|---|---|---|
|
||
| 0 | 待接单 | 下单成功待后台接单，**仅此状态可取消** |
|
||
| 1 | 已接单 | 后台已接单，等待归集生成采购单 |
|
||
| 2 | 采购中 | 已归集进采购单 |
|
||
| 3 | 配送中 | |
|
||
| 4 | 已完成 | |
|
||
| 9 | 已取消 | |
|
||
|
||
**账单支付进度（pay_state）**——由后端推导，覆盖原始支付状态（status）的展示口径
|
||
|
||
| 值 | 名称 | 推导条件 | 说明 |
|
||
|---|---|---|---|
|
||
| 0 | 待支付 | status=0 且 payment_id=0 | `can_pay=true`，可发起合并付款 |
|
||
| 1 | 审核中 | status=0 且 payment_id>0 | 已提交合并付款凭证，待后台审核；**审核拒绝后自动回到待支付** |
|
||
| 2 | 已支付 | status=1 | 线上审核通过或后台线下收款登记 |
|
||
|
||
---
|
||
|
||
## GET /mini/order
|
||
|
||
门店历史订单列表，按订货日期倒序（同日期按 ID 倒序）分页。行数据附带**商品预览**（前 3 条明细），完整明细请调订单详情。
|
||
|
||
- **权限**：需登录且已绑定正常门店
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| status | number | 否 | 订单状态（见枚举表），不传=全部 |
|
||
| start_date | string | 否 | 订货日期起，`Y-m-d`；可配合 `/mini/order/summary` 返回的 `period_label` 下钻 |
|
||
| end_date | string | 否 | 订货日期止，`Y-m-d`，不得早于 start_date |
|
||
| page | number | 否 | 页码，默认 1 |
|
||
| pageSize | number | 否 | 每页数量，默认 10，**最大 50** |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"data": [
|
||
{
|
||
"id": 1024,
|
||
"order_no": "SO202608140001",
|
||
"order_date": "2026-08-14",
|
||
"status": 0,
|
||
"status_name": "待接单",
|
||
"can_cancel": true,
|
||
"total_quantity": 8,
|
||
"total_weight": "0.000",
|
||
"total_amount": "44.00",
|
||
"remark": "下午送到",
|
||
"purchase_id": 0,
|
||
"bill_id": 0,
|
||
"created_at": "2026-08-14 09:30:00",
|
||
"item_count": 4,
|
||
"items": [
|
||
{ "product_name": "白菜", "quantity": 2, "unit": "件" },
|
||
{ "product_name": "土豆", "quantity": 2, "unit": "件" },
|
||
{ "product_name": "番茄", "quantity": 2, "unit": "件" }
|
||
]
|
||
}
|
||
],
|
||
"total": 36,
|
||
"pageSize": 10,
|
||
"current": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 字段说明（列表行）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | number | 订单 ID |
|
||
| order_no | string | 订单编号（SO 前缀） |
|
||
| order_date | string | 订货日期 `Y-m-d` |
|
||
| status | number | 订单状态（见枚举表） |
|
||
| **status_name** | string | 状态中文名，**直接展示，前端不要再硬编码映射** |
|
||
| **can_cancel** | boolean | 是否可取消（=待接单）；取消按钮据此渲染 |
|
||
| total_quantity | number | 订货总数量（件/包数） |
|
||
| total_weight | string | 总称重（斤，手动录入参考值，常为 0） |
|
||
| total_amount | string | 订单金额 |
|
||
| remark | string | 订单备注，可能为空字符串 |
|
||
| purchase_id | number | 关联采购单 ID，0=未归集 |
|
||
| bill_id | number | 关联账单 ID，0=未出账（>0 可跳账单详情） |
|
||
| created_at | string | 下单时间 `Y-m-d H:i:s` |
|
||
| **item_count** | number | 明细种数（如「共 4 种」） |
|
||
| **items** | array | 商品预览，**仅前 3 条**（`product_name` / `quantity` / `unit`），完整明细走详情接口 |
|
||
|
||
---
|
||
|
||
## GET /mini/order/{id}
|
||
|
||
订单详情（校验本店归属），返回订单全部字段 + 完整明细（`items` 数组，含下单时商品快照）。
|
||
|
||
- **权限**：需登录且已绑定正常门店；非本店订单返回 `success=false`「订单不存在」
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"id": 1024,
|
||
"order_no": "SO202608140001",
|
||
"store_id": 3,
|
||
"order_date": "2026-08-14",
|
||
"total_quantity": 8,
|
||
"total_weight": "0.000",
|
||
"total_amount": "44.00",
|
||
"status": 0,
|
||
"remark": "下午送到",
|
||
"purchase_id": 0,
|
||
"bill_id": 0,
|
||
"created_at": "2026-08-14 09:30:00",
|
||
"items": [
|
||
{
|
||
"id": 501,
|
||
"order_id": 1024,
|
||
"product_id": 11,
|
||
"product_name": "白菜",
|
||
"product_spec": "约30斤/件",
|
||
"unit": "件",
|
||
"price": "5.50",
|
||
"quantity": 2,
|
||
"weight": "0.000",
|
||
"amount": "11.00",
|
||
"remark": ""
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
订单本体字段同列表行（无 `status_name` / `can_cancel` / 预览字段，状态展示沿用列表行数据或自行映射）；`items` 为完整明细：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| product_name / product_spec / unit | string | 下单时商品快照（品名/规格包规/单位），商品档案后续变更不影响 |
|
||
| price | string | 下单时门店等级实际价快照 |
|
||
| quantity | number | 订货量（件/包数） |
|
||
| weight | string | 称重（斤，参考值） |
|
||
| amount | string | 明细金额 = price × quantity |
|
||
|
||
---
|
||
|
||
## GET /mini/bill
|
||
|
||
门店账单列表（采购单完成后由后台按门店生成，门店端只读），按账单日期倒序分页。响应在分页结构上**附加 `summary` 待支付汇总**（仅按门店口径统计，不受筛选参数影响），供页面头部与合并付款入口展示。
|
||
|
||
- **权限**：需登录且已绑定正常门店
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| status | number | 否 | 原始支付状态：0 未支付（含审核中）/ 1 已支付，不传=全部 |
|
||
| payable | number | 否 | 传 `1` = 仅可发起付款的账单（未支付且未在审核中），**合并付款选择页专用** |
|
||
| start_date | string | 否 | 账单日期起，`Y-m-d` |
|
||
| end_date | string | 否 | 账单日期止，`Y-m-d`，不得早于 start_date |
|
||
| page | number | 否 | 页码，默认 1 |
|
||
| pageSize | number | 否 | 每页数量，默认 10，**最大 50** |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"data": [
|
||
{
|
||
"id": 88,
|
||
"bill_no": "ZD202608140001",
|
||
"bill_date": "2026-08-14",
|
||
"purchase_id": 31,
|
||
"purchase": { "id": 31, "purchase_no": "PO202608130001", "purchase_date": "2026-08-13" },
|
||
"product_amount": "100.00",
|
||
"delivery_fee": "10.00",
|
||
"box_num": 2,
|
||
"tray_num": 1,
|
||
"box_price": "5.00",
|
||
"tray_price": "20.00",
|
||
"added_amount": "30.00",
|
||
"total_amount": "140.00",
|
||
"status": 0,
|
||
"status_name": "未支付",
|
||
"pay_state": 0,
|
||
"pay_state_name": "待支付",
|
||
"can_pay": true,
|
||
"payment_id": 0,
|
||
"settlement_date": "2026-08-17",
|
||
"paid_at": null,
|
||
"pay_remark": "",
|
||
"remark": "",
|
||
"created_at": "2026-08-14 03:17:01"
|
||
}
|
||
],
|
||
"total": 12,
|
||
"pageSize": 10,
|
||
"current": 1,
|
||
"summary": { "unpaid_count": 3, "unpaid_amount": "420.50" }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 字段说明（列表行）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | number | 账单 ID |
|
||
| bill_no | string | 账单编号（ZD 前缀） |
|
||
| bill_date | string | 账单日期（出账日）`Y-m-d` |
|
||
| purchase_id | number | 关联采购单 ID |
|
||
| purchase | object \| null | 关联采购单 `{ id, purchase_no, purchase_date }` |
|
||
| product_amount | string | 商品金额（订单汇总快照，不可修改） |
|
||
| delivery_fee | string | 配送费 |
|
||
| box_num / tray_num | number | 周转筐 / 周转托盘数量 |
|
||
| box_price / tray_price | string | 筐 / 托盘单价（出账时快照） |
|
||
| added_amount | string | 附加金额 = box_num×box_price + tray_num×tray_price |
|
||
| total_amount | string | **账单总金额 = 商品金额 + 配送费 + 附加金额** |
|
||
| status | number | 原始支付状态：0 未支付 / 1 已支付（展示用 pay_state 系列字段） |
|
||
| status_name | string | 支付状态中文名 |
|
||
| **pay_state** | number | 支付进度：0 待支付 / 1 审核中 / 2 已支付（见枚举表） |
|
||
| **pay_state_name** | string | 支付进度中文名，**列表状态标签直接用它** |
|
||
| **can_pay** | boolean | 是否可勾选发起合并付款（=待支付） |
|
||
| payment_id | number | 关联支付记录 ID，0=未发起付款；审核中时可跳支付记录详情查看进度 |
|
||
| **settlement_date** | string | 应结算日期 = 账单日期 + 门店回款周期天数 |
|
||
| paid_at | string \| null | 付款时间（已支付时非空） |
|
||
| pay_remark | string | 付款备注（如「微信支付（支付单号 ZF…）」、线下收款说明） |
|
||
| remark | string | 账单备注 |
|
||
| created_at | string | 出账时间 |
|
||
|
||
### summary 字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| unpaid_count | number | 待支付账单笔数（**含审核中**） |
|
||
| unpaid_amount | string | 待支付金额合计（含审核中） |
|
||
|
||
---
|
||
|
||
## GET /mini/bill/{id}
|
||
|
||
账单详情（校验本店归属）：账单信息（字段同列表行）+ 合并后的商品明细 + 关联订单。
|
||
|
||
- **权限**：需登录且已绑定正常门店；非本店账单返回 `success=false`「账单不存在」
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"bill": { "id": 88, "bill_no": "ZD202608140001", "...": "（字段同列表行）" },
|
||
"items": [
|
||
{
|
||
"product_id": 11,
|
||
"product_name": "白菜",
|
||
"product_spec": "约30斤/件",
|
||
"unit": "件",
|
||
"price": "5.50",
|
||
"quantity": 20,
|
||
"weight": "0.000",
|
||
"amount": "110.00"
|
||
}
|
||
],
|
||
"orders": [
|
||
{
|
||
"id": 1024,
|
||
"order_no": "SO202608130001",
|
||
"order_date": "2026-08-13",
|
||
"total_quantity": 8,
|
||
"total_weight": "0.000",
|
||
"total_amount": "44.00",
|
||
"status": 4
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
- **bill**：与列表行完全一致（含 `pay_state_name` / `can_pay` / `settlement_date` 等派生字段）
|
||
- **items**：按商品聚合的合并明细（跨本账单全部订单），`price` 为加权平均口径（Σ金额÷Σ数量，保证 单价×数量=金额）；`quantity` 为合计数量（number）、`amount` 为合计金额
|
||
- **orders**：本账单关联的门店订单（单价明细可继续下钻 `GET /mini/order/{id}`），`status` 为订单状态枚举
|
||
|
||
---
|
||
|
||
## 前端接入示例
|
||
|
||
`src/types/order.ts` 关键类型（列表行替换为接口返回，**删除本地 `ORDER_STATUS_MAP` 硬编码**）：
|
||
|
||
```ts
|
||
/** 订单列表行（状态名/可取消/商品预览均由后端给出） */
|
||
export interface OrderListItem {
|
||
id: number
|
||
order_no: string
|
||
order_date: string
|
||
status: number
|
||
status_name: string
|
||
can_cancel: boolean
|
||
total_quantity: number
|
||
total_weight: string
|
||
total_amount: string
|
||
remark: string
|
||
purchase_id: number
|
||
bill_id: number
|
||
created_at: string
|
||
item_count: number
|
||
items: Array<{ product_name: string; quantity: number; unit: string }>
|
||
}
|
||
```
|
||
|
||
`src/services/bill.ts`（**替代旧 `statement.ts`——旧 `/mini/statement` 已下线**）：
|
||
|
||
```ts
|
||
import { get } from '@/utils/request'
|
||
import type { PaginatedData } from '@/types/api'
|
||
|
||
/** 账单（列表行与详情的 bill 字段一致） */
|
||
export interface Bill {
|
||
id: number
|
||
bill_no: string
|
||
bill_date: string
|
||
purchase_id: number
|
||
purchase: { id: number; purchase_no: string; purchase_date: string } | null
|
||
product_amount: string
|
||
delivery_fee: string
|
||
box_num: number
|
||
tray_num: number
|
||
box_price: string
|
||
tray_price: string
|
||
added_amount: string
|
||
total_amount: string
|
||
status: 0 | 1
|
||
status_name: string
|
||
/** 支付进度：0 待支付 / 1 审核中 / 2 已支付 */
|
||
pay_state: 0 | 1 | 2
|
||
pay_state_name: string
|
||
can_pay: boolean
|
||
payment_id: number
|
||
settlement_date: string
|
||
paid_at: string | null
|
||
pay_remark: string
|
||
remark: string
|
||
created_at: string
|
||
}
|
||
|
||
export interface BillSummary {
|
||
unpaid_count: number
|
||
unpaid_amount: string
|
||
}
|
||
|
||
export interface BillDetail {
|
||
bill: Bill
|
||
items: Array<{
|
||
product_id: number; product_name: string; product_spec: string
|
||
unit: string; price: string; quantity: number; weight: string; amount: string
|
||
}>
|
||
orders: Array<{
|
||
id: number; order_no: string; order_date: string
|
||
total_quantity: number; total_weight: string; total_amount: string; status: number
|
||
}>
|
||
}
|
||
|
||
/** 账单列表：GET /mini/bill（payable=1 为合并付款选择页口径） */
|
||
export function getBillListApi(
|
||
params: { status?: number; payable?: 1; start_date?: string; end_date?: string; page?: number; pageSize?: number } = {},
|
||
) {
|
||
return get<PaginatedData<Bill> & { summary: BillSummary }>('/mini/bill', { data: params })
|
||
}
|
||
|
||
/** 账单详情：GET /mini/bill/{id} */
|
||
export function getBillDetailApi(id: number) {
|
||
return get<BillDetail>(`/mini/bill/${id}`)
|
||
}
|
||
```
|
||
|
||
订单列表行商品预览渲染建议：
|
||
|
||
```tsx
|
||
<Text className='order-item__preview'>
|
||
{order.items.map(i => `${i.product_name}×${i.quantity}`).join('、')}
|
||
{order.item_count > 3 ? ` 等${order.item_count}种` : ''}
|
||
</Text>
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **状态文案一律用接口返回的 `status_name` / `pay_state_name`**：订单状态为 6 态（0/1/2/3/4/9），h5 现有 `ORDER_STATUS_MAP` 是旧 5 态（缺采购中/配送中），继续硬编码会显示异常。
|
||
2. **账单状态标签用 `pay_state_name` 而非 `status`**：`status=0` 同时覆盖「待支付」与「审核中」两种展示；`payable=1` 筛选与 `can_pay` 同口径（待支付），合并付款页直接用它。
|
||
3. **审核拒绝后账单自动回到待支付**（payment_id 归零），列表刷新即可重新勾选付款，无需额外处理。
|
||
4. `summary` 统计的是**全部门店口径**（含审核中），与列表筛选参数无关；筛选「已支付」时 summary 仍返回待支付汇总。
|
||
5. 订单列表 `items` 仅为前 3 条预览（`item_count` 为总种数），完整明细必须调详情接口；两个详情接口均校验门店归属，跨店访问返回「不存在」。
|
||
6. `settlement_date` 由门店回款周期实时计算（门店改周期后历史账单随之变化），如需固化口径请后续提需求加快照列。
|
||
7. 参数校验失败与业务失败一样返回 `success=false` + 中文 `msg`（HTTP 200），无需特殊分支处理。
|