xin-procurement/docs/api/mini-report-purchase.md

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

门店端运营报表：拉取「一周 / 一月 / 任意选定时间段」内的采购总金额，以及每个单品的累计采购金额与金额占比。

示例场景：上个月我店一共采购了 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

{
  "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"，前端展示空状态即可。