数据专家 API · 优缺点分析与优化方案

对象：现网契约 2026-06-10-aigent-AI对接说明(2).md 的数据专家部分（§1.1–1.9，9 个端点）。 范围：只针对数据专家场景（取数 / 趋势 / 环比 / 客单价 / 维度 / 导出），不含营销、会员操作。 结论：现网取数侧"能跑通但偏碎"——5 条取数端点 + 3 套指标命名 + 3 种时间格式并存，失败语义弱，部分能力被错标"无数据源"。本文先评优缺点，再给一套收敛为 2 个端点的优化方案 + 迁移对照。 真实库口径以 ai-Recs 全表分析为准（report_daily_statistics 263 店 / main_order 全量）。

一、现状概览（数据专家 9 端点）

二、优点（值得保留的设计）

优化方案保留并强化这些：以 agent-bi 为基础收口、沿用白名单 + zero + baselineExists + preview→commit。

三、缺点 / 问题（按影响排序）

P0 · 结构性

P1 · 口径一致 + 能力解锁

P2 · 规范细节

四、优化方案：数据专家收敛为 2 个端点

核心思路：以 §1.7 agent-bi 为基础，①把 query/compare/trend(旧 3 指标链) 和 report(客单价) 也收进来；②加 dimension 解锁分渠道；③统一时间/命名/错误/覆盖度。导出（§1.8/1.9）单列，下文「4.5」给精简版。

约定：前缀 /pos/ai/v1；时间一律 13 位 epoch ms（UTC+4，含头含尾）；金额 AED。

4.1 端点总览

4.2 POST /metrics:query 请求参数

参数组合 = 拿到哪种数据

4.3 POST /metrics:query 响应

响应外壳（失败回真实 HTTP 状态，纠正 D3）

{ "api_version":"v1", "code":0, "message":"ok",
  "data": { ... },
  "meta": { "currency":"AED",
            "data_basis":"DAILY_REPORT",          // 三态：DAILY_REPORT / ORDER_AGGREGATED / NONE（纠正 D8）
            "metric_basis": {"income":"DAILY_REPORT","fail_count":"ORDER_AGGREGATED"} },  // 逐指标底座
  "error": null }                                  // 失败：{error_code,category,retriable,details}

① 不带 dimension（取数 / 趋势）

② 带 dimension（维度拆分）

4.4 指标白名单（12 项，统一蛇形，纠正 D2/D5）

笔数级（refund_count/fail/success_rate）日报无、走订单聚合（与 真实库表校验确认.md 一致）。比率口径沿用 ✅4「整段累加再除、分母 0 返 null」。

4.5 导出（沿用 preview→commit，规范化）

POST /report:export-preview（>90 天→AIGENT_EXPORT_RANGE_TOO_LARGE）→ 出确认卡 → POST /report:export-commit（凭 previewToken，幂等）。沿用 §0.4 两步式 + 一次性 token；仅把错误码与时间格式对齐到下方统一规范。

4.6 统一错误模型（纠正 D3/D4）

4.7 capabilities 增强（纠正 D8）

{ "contract_version":"1.0.0", "currency":"AED", "tz_offset":"+04:00",
  "metrics":[ {"key":"avg_ticket","label":"客单价","available":true,"scope":["query"]}, ... ],
  "dimensions":[ {"dimension":"CHANNEL","available":true},
                 {"dimension":"ORDER_SOURCE","measure":"COUNT_ONLY"} ],   // 来源只有笔数
  "limits":{ "query_max_days":400, "export_max_days":90 } }               // 拆全两个上限

五、Agent 如何调用与匹配参数（消费侧，不进 API 契约）

一句话拆成几件事填到 /metrics:query：时间词→date_from/to；「日/每天/趋势」→time_granularity；指标词→metrics[]；「日均/最高」→aggregation；「比上周/同比」→compare；「分渠道/各支付」→dimension。

模糊词→指标：营业额/销售额/流水→success_amount；净收入/利润→income；营收/收入（模糊）→success_amount（商家口语优先流水）；订单/单量→order_count；客单价→avg_ticket。

例「上周的日营业额」→ date_from/to=上周一~日 + time_granularity=DAY + metrics=[success_amount] + 其余默认 → 7 天逐日营业额。

时间解析建议挪到 Agent 侧（省去 §1.2 resolveDateRange 一跳，D12）；若 Agent 不自算，可保留该端点作回退。

六、数据团队如何实现

在 /metrics:query 实现里按参数分支取真实表（§4.4 已列来源列）：

1. 三链收一端：现网 agent-bi 已合并取数/趋势/环比；再把 客单价（源 average_order_price）和维度拆分（源 dining_room/pay_by_*/member_* 列）接进同一端点，即可让 query/compare/trend/report 一并退役。这些源 ai-Recs 已确认在 report_daily_statistics 里存在（解 D6）。
2. 覆盖度三态：日报 263 店走 report_daily_statistics（data_basis=DAILY_REPORT）；其余店 main_order/daily_record 按日聚合（ORDER_AGGREGATED）；都没有→NONE，不返 0（解 D8）。
3. 性能：日报表本就是 per 店/日预聚合，直取即可，避免逐日拉下游（缓解 §1.7 自陈的性能问题）。
4. capabilities 如实：哪些指标/维度这家店真有数据就标 available，让 Agent 据此门控。

七、迁移对照（现网 → 优化后）

八、待数据团队确认（实现前先核实）

附：相关文档

• 现网契约：2026-06-10-aigent-AI对接说明(2).md（§1.1–1.9 数据专家）
• 真实库校验：数据报表API-真实库表校验确认.md（11 指标逐列、avg_ticket 源确认）
• 简版对外：数据分析API-简版（Agent调用+数据团队实现）.md