# 小程序接口文档：采购运营报表

> 门店端运营报表：拉取「一周 / 一月 / 任意选定时间段」内的采购总金额，以及每个单品的累计采购金额与金额占比。
>
> 示例场景：上个月我店一共采购了 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"`，前端展示空状态即可。