agent-foundation/docs/ngp-monthly-weekly-api.md

NGP 本月每周业绩统计接口

请求

POST /api/ngp/performance/monthly-weekly

{
  "month": "2026-09",
  "storeNames": [
    "跃动内容电商（抖店）",
    "跃动工厂（淘宝1）"
  ]
}

month 可省略，省略时使用 Asia/Shanghai 时区的当前月份。不能查询未来月份。 storeNames 可省略或传空数组，此时查询所有网店；传入后仅返回指定网店，并按传入顺序展示。 只查询一个网店时也可以传 storeName 字符串；该字段同样支持逗号或顿号分隔多个名称。

周区间

按周一至周日切分，月初和月末使用当月实际边界。例如 2026 年 9 月：

• 9/1-9/6
• 9/7-9/13
• 9/14-9/20
• 9/21-9/27
• 9/28-9/30

当前月份只读取截至今天的日期，未来周金额返回 null。

缓存

接口复用 ngp_performance_daily_total 和 ngp_performance_daily_status：

• 已缓存且未过期的日期直接从 MySQL 读取。
• 只为缺失或过期的日期启动后台 NGP 查询。
• 同一日期同时只运行一个刷新任务。
• 缓存补齐期间返回 HTTP 202 和 retryAfterSeconds。
• 缓存就绪后返回 HTTP 200，不再查询 NGP 全量数据。

传入 storeNames 时，即使指定网店当月没有业绩，响应中仍保留该网店，金额返回 null，以便表格显示 -。不传时返回缓存中所有有数据的网店。

成功响应示例

{
  "success": true,
  "month": "2026-09",
  "monthLabel": "九月",
  "title": "2026年九月业绩周统计",
  "weeks": [
    {
      "index": 0,
      "startDate": "2026-09-01",
      "endDate": "2026-09-06",
      "label": "9/1-9/6",
      "complete": true
    }
  ],
  "stores": [
    {
      "storeName": "跃动内容电商（抖店）",
      "weeklyAmounts": [506482.76, null, null, null, null],
      "subtotal": 506482.76
    }
  ],
  "weekTotals": [1691720.10, null, null, null, null],
  "grandTotal": 1691720.10,
  "formattedGrandTotal": "1,691,720.10",
  "currency": "CNY"
}