126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# 小程序接口文档：采购运营报表
|
||
|
||
> 门店端运营报表：拉取「一周 / 一月 / 任意选定时间段」内的采购总金额，以及每个单品的累计采购金额与金额占比。
|
||
>
|
||
> 示例场景：上个月我店一共采购了 10 万元，其中土豆 8764 元（占比 8.8%）、洋葱 3664 元（占比 3.7%）。
|
||
|
||
## 接口信息
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 请求方式 | `GET` |
|
||
| 路径 | `/mini/report/purchase` |
|
||
| 鉴权 | 门店 token（`Authorization: Bearer <token>`），与其他小程序接口一致 |
|
||
| 数据范围 | 仅当前登录门店自身的订货数据 |
|
||
|
||
## 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `preset` | string | 否 | 周期预设：`week` 本周 / `last_week` 上周 / `month` 本月 / `last_month` 上月。**缺省为 `month`** |
|
||
| `start_date` | string | 否 | 自定义开始日期，格式 `Y-m-d`（如 `2026-07-01`）。需与 `end_date` 成对出现 |
|
||
| `end_date` | string | 否 | 自定义结束日期，格式 `Y-m-d`，不能早于 `start_date` |
|
||
|
||
规则：
|
||
|
||
- 同时传 `start_date` + `end_date` 时为**自定义区间，优先于 `preset`**（响应中 `preset` 返回 `custom`）；
|
||
- 只传其中一个日期、日期格式错误、结束日期早于开始日期、preset 非枚举值，均返回参数错误；
|
||
- 进行中的周期（本周/本月）结束日期自动**封顶为今天**；周以**周一**为起点。
|
||
|
||
## 响应示例
|
||
|
||
`GET /mini/report/purchase?preset=last_month`
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"preset": "last_month",
|
||
"start_date": "2026-07-01",
|
||
"end_date": "2026-07-31",
|
||
"total_amount": "100000.00",
|
||
"total_quantity": 1700,
|
||
"order_count": 20,
|
||
"item_count": 2,
|
||
"items": [
|
||
{
|
||
"product_id": 11,
|
||
"product_name": "土豆",
|
||
"product_spec": "50斤/袋",
|
||
"unit": "斤",
|
||
"quantity": 500,
|
||
"weight": "0.000",
|
||
"amount": "8764.00",
|
||
"percent": 8.8
|
||
},
|
||
{
|
||
"product_id": 12,
|
||
"product_name": "洋葱",
|
||
"product_spec": "20斤/袋",
|
||
"unit": "斤",
|
||
"quantity": 200,
|
||
"weight": "0.000",
|
||
"amount": "3664.00",
|
||
"percent": 3.7
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 响应字段
|
||
|
||
### 顶层（`data`）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `preset` | string | 实际生效的周期预设（`week`/`last_week`/`month`/`last_month`/`custom`） |
|
||
| `start_date` | string | 实际统计开始日期 `Y-m-d` |
|
||
| `end_date` | string | 实际统计结束日期 `Y-m-d` |
|
||
| `total_amount` | string | 周期内采购总金额（元，2 位小数；金额一律以字符串返回防精度丢失） |
|
||
| `total_quantity` | number | 周期内订货总量（各单品数量之和） |
|
||
| `order_count` | number | 周期内有效订货单数 |
|
||
| `item_count` | number | 单品个数（= `items` 长度） |
|
||
| `items` | array | 单品累计列表，**按金额降序** |
|
||
|
||
### 单品行（`data.items[]`）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `product_id` | number | 商品 ID |
|
||
| `product_name` | string | 品名（下单时快照，商品档案改名/删除不影响历史统计） |
|
||
| `product_spec` | string | 规格/包规（快照） |
|
||
| `unit` | string | 计价单位（快照） |
|
||
| `quantity` | number | 周期内累计订货量 |
|
||
| `weight` | string | 周期内累计重量（3 位小数，未称重为 `0.000`） |
|
||
| `amount` | string | 周期内累计采购金额（元，2 位小数） |
|
||
| `percent` | number | 金额占比（%，1 位小数，四舍五入；如 `8.8` 表示 8.8%。周期内无数据时为 `0`） |
|
||
|
||
## 统计口径
|
||
|
||
- 数据源为**门店订货单明细**（下单时快照的等级单价 × 数量），即门店视角的应付采购金额；
|
||
- **已取消**订单与后台**已删除**订单不计入统计，其余状态（待接单/已接单/采购中/配送中/已完成）全部计入；
|
||
- 单品按 `product_id` 聚合，同一商品在周期内多次下单会累计为一行；
|
||
- 占比 = 单品金额 ÷ 总金额 × 100，保留 1 位小数（四舍五入），各行占比之和可能因舍入存在 ±0.1 的误差，属正常现象。
|
||
|
||
## 错误响应
|
||
|
||
与小程序其他接口一致：`success: false` + `msg` 描述原因。
|
||
|
||
| 场景 | msg 示例 |
|
||
|---|---|
|
||
| 未登录 / token 失效 | `Unauthenticated`（按全局鉴权约定） |
|
||
| 账号被停用 | `账号不存在或已被停用` |
|
||
| preset 非法 | `preset 参数只能是 week/last_week/month/last_month` |
|
||
| 日期格式错误 | `开始日期格式为 Y-m-d` |
|
||
| 结束早于开始 | `结束日期不能早于开始日期` |
|
||
| 自定义区间只传一侧 | `自定义区间需同时提供开始与结束日期` |
|
||
|
||
## 前端对接建议
|
||
|
||
- 顶部放周期切换 Tab（本周 / 上周 / 本月 / 上月 / 自定义），自定义时弹出日期选择器，选中后传 `start_date` + `end_date`；
|
||
- 头部卡片展示 `total_amount`（总金额）与 `order_count`（单数）；
|
||
- 列表直接渲染 `items`（已按金额降序），每行展示品名、规格、累计金额与 `percent`%；如需饼图可直接用 `items[].percent`；
|
||
- 区间无数据时 `items` 为空数组、`total_amount` 为 `"0.00"`，前端展示空状态即可。
|