Fanzhi Analytics

---
name: fanzhi-analytics
description: 查询番知票务整体经营分析、退款概览和渠道统计。当用户问本月/今年销售总览、经营指标、月度趋势、同比环比、项目销售或退款排行，今天/近几天有哪些退款、退款走了哪些渠道，或者要按项目查看渠道销售、优惠结构、销售员、出票与核销进度时使用。不用于订单明细、单项目全生命周期票档库存、场次上座率或财务服务费。
---

# 番知经营分析

只在相应报表工具已出现且当前店铺有效能力包含该工具时调用。未确认目标店铺时先用 `mcp_access_context_list` 让用户选择 `target_shop_id`。输入参数与枚举以当前工具 Schema 为准。

开始前必须先读 [总入口的最高优先级单项失败隔离、输出闸门与调用前置](../fanzhi-ticketing/SKILL.md)，用完整的 `mcp:tool:<tool_name>` 检查权限。实际可调用性取工具发现与当前店铺有效权限的交集。

## 工具选择

- `sales_report`：月报、年报或最长 366 天自定义销售总览，可按日期或项目分组。
- `sales_monthly_trend`：最多 36 个自然月的指标趋势、上月环比和去年同月同比。
- `project_sales_ranking`：近 7、30、90 或 180 天按商户实际收入的项目排行。
- `project_refund_ranking`：近 7、30、90 或 180 天按退款财务事实日汇总退款总额的项目排行。
- `refund_overview_report`：目标店铺今天、近 3/7/30 天或指定期间的退款概览：按退款申请时间统计退款总额与笔数、成功与处理中金额、退票数，按退款状态、退款渠道、销售渠道和项目的分布，以及退款单明细（分页）。
- `channel_sales_stat_project_list` → `channel_sales_stat_project_detail`：先看各项目销售、退款、优惠、应收与实收合计，再下钻单项目的渠道 → 场次 → 票档明细。
- `channel_sales_detail_project_list` → `channel_sales_detail_project_detail`：先看各项目优惠结构与实收，再下钻单项目的场次 → 渠道 → 销售员 → 出票类型 → 票档及优惠政策。
- `channel_ticket_stat_project_list` → `channel_ticket_stat_project_detail`：先看各项目纸票打印、电子票和证件票核销进度，再下钻单项目的场次 → 票档 → 渠道 → 销售员；不含金额。

按期间的渠道经营统计使用上述三组列表/明细工具；已确认单项目的原始渠道与票种销售分布使用项目 Skill 的 `project_channel_sales_report`，全生命周期渠道 × 票档使用 `project_channel_sku_report`。

## 关键参数

- `sales_report`：必填整数 `target_shop_id`、对象 `period`、非空 `metrics`；期间支持自然月、自然年或最长 366 天自定义日期。可选日期/项目分组。
- `sales_monthly_trend`：必填 `YYYY-MM` 格式的 `start_month`、`end_month`，非空 `metrics`，以及至少一个 `mom` 或 `yoy` 比较方式。
- `project_sales_ranking`、`project_refund_ranking`：必填整数 `target_shop_id` 和标准 `window`；`limit` 默认 20、最大 100。
- `refund_overview_report`：必填整数 `target_shop_id`；`window`（`today`、`last_3_days`、`last_7_days`、`last_30_days`）与 `period` 必须且只能传一个，其他天数或具体日期用 `period`。可选已确认的 `project_ids`（最多 100 个）；明细 `limit` 默认 20、最大 50，翻页只传上一页的 `next_cursor` 且条件不变。按窗口查询跨过零点后旧游标会失效，从第一页重查。
- 三组渠道统计均必填 `target_shop_id`、日期类型和带时区的起止时刻，跨度最长 366 天。列表可选项目、场次、渠道筛选；明细另必填列表返回或已确认的 `project_id`。
- 渠道销售明细和渠道出票统计还可按出票人/销售员筛选；候选先用订单领域的 `trade_filter_options` 查询并确认。渠道销售明细可选择是否包含已退款券码，默认不包含。
- 渠道销售统计/明细的日期类型为项目、场次或下单时间；渠道出票统计为项目、场次或出票时间。不能跨组复用不支持的日期类型。
- 统一指标包括订单原价、优惠、退款、商户实际收入、订单数、售出票数、退款订单数、退款票数和净票数。只选择用户问题需要的指标。

## 用户表达

- 工具名、字段名、枚举值、内部 ID 参数、原始 JSON、Schema 和错误码仅供内部调用，普通回答中不得展示。
- 用“请选择店铺”“你想看哪个时间范围”“需要看销售额、商户实际收入还是票数”等自然语言澄清，不向用户索要参数名或指标代码。
- 指标、窗口、比较状态和告警转换为可读中文；不可计算值说明原因，不展示 `null` 或原始状态码。无法查询时采用总入口的友好文案，并给一个可执行下一步。

## 范围和口径

- `sales_report` 必须传 `period` 和 `metrics`；拆分使用 `group_by`，按 `date` 分组是日行，没有按月粒度参数。月度趋势使用 `sales_monthly_trend`；单项目按月使用项目 Skill 的 `project_report(granularity=month)`。分组结果最多 200 组，超出时服务端直接报错而不是截断，请用户缩小项目或日期范围；全年按日分组容易超限，优先改用月度趋势。
- 按日期分组只返回有财务日事实的日期。结果中缺少某日表示“未返回该日事实”，不等于零收入；禁止补零，也不得据此说成数据故障。
- `sales_monthly_trend` 必须传 `start_month`、`end_month`、`metrics`、`comparisons`，范围最多 36 个自然月；不能用任意等长周期冒充环比或同比。
- 本月、本年按总入口规则写“本月累计”“本年累计”，不把月末、年末或响应生成时间当成数据截止日；不例行添加未知更新时间说明。
- 未结束月、年与完整历史期间比较时注明“本期尚未结束，比较期间不等长”，不把变化直接归因于经营趋势。
- “今年”的月度趋势默认从当年 1 月到当前月，不查询尚未发生的未来月份。服务端会为无事实行的月份返回零值，不能仅凭零值推断该月没有业务；用户明确要求包含未来月份时标为“尚未发生”，不纳入实绩或增长结论。
- 趋势的每个比较都带状态：`comparable` 可比较，按服务端增幅展示；`new` 表示基期为零、本期有值；`stopped` 表示基期有值、本期为零；`unchanged` 表示两期都为零；`no_baseline` 表示基期没有数据。后四种的增幅为 `null`，按状态用中文说明“不可计算”，不能说成 `0%`，也不自行补算变化率。
- `stopped` 不代表停业或停止销售，`new` 也不代表新开业务，只描述两期数值关系。
- `project_sales_ranking` 的排序口径是商户实际收入，不是 GMV、订单原价或销售额别名。
- `project_refund_ranking` 的排序口径是退款财务事实日的退款总额，不是退款率，也不是回写原销售日。
- `refund_overview_report` 按退款申请时间统计、含全部退款状态（审核中、处理中、成功等），口径同后台退款列表；只统计目标店铺，不支持组织范围。它与退款排行（财务事实日、仅成功退款）口径不同，两边数字对不上是正常的，不能互相校正。按项目分布的金额取产品退款金额、可能不含运费，所以各项目之和可能小于退款总额。
- 退款概览依赖的查询计划可能尚未在当前环境开启，返回“查询方式不可用”时按总入口处理，不改用订单列表、财务流水或退款排行拼出退款明细。
- 渠道统计先列表后明细：列表不分页，最多返回 500 个项目；项目过多时请用户缩短时间或指定项目。不要自动逐个项目调用明细来重建总表。
- 渠道明细最多 5000 行；结果过大时缩短日期或增加场次、渠道、销售员筛选。筛选值必须来自运行时 Schema 或筛选选项，不根据展示文案猜代码。
- 渠道销售统计的“实收”与销售总览的“商户实际收入”不是同一口径；渠道销售明细默认不含已退款券码；渠道出票统计只统计打印/核销进度且不含金额。三者不能混算。
- `project_ids`、`shop_ids`、产品类型和数量上限只用于缩小范围；不得扩权。
- `report_scope=organization` 仅主店超级管理员且外部 Grant 明确授予组织动态只读时可用。
- 组织范围必须同时满足总入口规定的两个组织报表能力标记；用户要求单店时保持 `target_shop`。金额是人民币元定点字符串，保留服务端值，不重复换算分/元。

## 口径澄清

- “原销售额/订单原价”对应订单原价；“商户实际收入/净收入”对应商户实际收入。
- “售出票数”与“退款后净票数”不同；用户只说“票房数”且上下文不能唯一判断时，先确认要售出票数还是净票数。
- “退款排行”固定按退款总额，不代表退款率；用户要求退款率时说明当前排行工具不提供该口径。
- 问“有哪些退款、退了多少、退款到哪了、还有多少在处理”用退款概览；问“哪个项目退得最多”用退款排行。
- “环比”固定为上月比较，“同比”固定为去年同月比较；零基数不可计算时保留 `null` 状态。

## 典型问法与执行

以下箭头后的工具与参数只用于内部路由，不得在用户回答中复述。

- “本月订单数、售出票数和商户实际收入” → `sales_report`，自然月期间并选择对应三个指标。
- “今年每个月销售趋势和同比” → `sales_monthly_trend`，使用当年 1 月至当前月和 `yoy`；用户没说指标时先确认。
- “近 30 天卖得最好的 10 个项目” → `project_sales_ranking(window=last_30_days, limit=10)`，说明排序口径为商户实际收入。
- “近 90 天退款最多的项目” → `project_refund_ranking(window=last_90_days)`，说明按退款事实日退款总额排序。
- “今天有哪些退款”“近 7 天退款多少、走了哪些渠道、还有多少在处理” → `refund_overview_report(window=today)` 或 `window=last_7_days`；需要逐笔时按明细分页展示。
- “项目各渠道、票种票房” → 转入项目 Skill：先搜索确认项目，再 `project_channel_sales_report`。
- “近一年各项目渠道销售统计” → `channel_sales_stat_project_list`；用户选择项目后，按相同条件调用 `channel_sales_stat_project_detail`。
- “哪些项目用了会员价、学生优惠或促销，最终实收多少” → `channel_sales_detail_project_list`；需要销售员和票档明细时再下钻对应项目。
- “近 30 天哪些项目纸票未打印、电子票未核销” → `channel_ticket_stat_project_list`；需要场次、票档、渠道和销售员拆分时再查项目明细。

## 多工具场景

- 总览→异常项目：先 `sales_report` 或排行定位，再由用户选择项目后调用单项目报表；不自动遍历所有项目。
- 渠道列表→单项目明细：沿用完全相同的日期口径、时间区间和筛选条件，只增加用户确认的项目；不能在下钻时悄悄改变范围。
- 销售排行+退款排行：使用相同标准窗口分别查询，按两个独立榜单展示；不能直接相除生成退款率。
- 本期与历史趋势：总览和月趋势分别调用，确认指标、项目和店铺范围一致后再比较。

## 输出

- 读取 `result.structuredContent`，明确指标定义、统计窗口、分组、排序口径、时区、新鲜度和警告。
- 日明细按服务端实际返回日期展示，不补齐日历；本月、本年标为累计，对未结束期间与完整历史期间的比较注明期间不等长。
- 比较不同窗口或项目时先确认指标与范围一致；不混用销售、商户实际收入、服务费、退款额等口径。
- 总览按“范围 → 核心指标 → 分组变化 → 口径/告警”组织；趋势按月份展示指标、环比/同比及不可计算状态；排行展示名次、完整项目名、排序指标和辅助指标；渠道统计先展示全店合计和项目列表，明细再按服务端层级展开；退款概览按“范围与时间口径 → 总额/笔数/成功与处理中 → 按状态、退款渠道、销售渠道、项目分布 → 明细（注明是否还有后页）”组织。
- 空排行表示当前条件下没有可排行数据，不代表所有项目指标为零。
- 不根据聚合结果披露未授权店铺、项目或个人明细。

## 失败处理

- 任一工具失败后只跳过该查询项及依赖步骤，继续其他独立经营分析查询，最后按总入口的“最高优先级：单项失败隔离与输出闸门”补充一条错误提示；不得展开工具、参数、Schema、权限详情或自动生成修改报告/文件。
- 按总入口 Skill 的错误映射恢复并输出用户友好文案；普通回答不得展示错误码、请求 ID 或底层异常。
- 当前授权未开放报表时不用订单或财务明细批量模拟；查询或数据不可用时不降低查询门禁；限流仅在服务端允许时按指定时间自动重试一次。