运营报表

2026-08-21 12:05:31 +08:00
parent e5f849ef4d
commit 01e67e02b5
5 changed files with 526 additions and 2 deletions
@@ -0,0 +1,125 @@
+# 小程序接口文档：采购运营报表
+
+> 门店端运营报表：拉取「一周 / 一月 / 任意选定时间段」内的采购总金额，以及每个单品的累计采购金额与金额占比。
+>
+> 示例场景：上个月我店一共采购了 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"`，前端展示空状态即可。