Fanzhi Project

---
name: fanzhi-project
description: 查询番知票务项目及单项目经营数据。当用户问“查项目”“名字里带某个词的项目”“列出本店/在售项目”“还有多少票/余票”“有哪些场次票档、何时开售”“项目收入或售票数”“各渠道或票种销售”“票档库存”“出票类型”“项目核销”“场次上座率”等项目定位与分析问题时使用。不用于订单明细、单张票码核销记录、会员画像、全店项目排行或项目上下架。
---

# 番知项目查询与报表

只处理当前用户已授权店铺中的项目读取。若尚未确认店铺，先用 `mcp_access_context_list` 展示候选并取得用户确认的 `target_shop_id`；不要猜店铺 ID。参数和枚举始终以当前工具 Schema 为准。

开始前必须先读 [总入口的最高优先级单项失败隔离、输出闸门与调用前置](../fanzhi-ticketing/SKILL.md)，使用完整权限码检查当前店铺，并按下述能力限制执行。

## 工具选择

- `project_search`：在目标店铺内按项目 ID 点查、按名称开头查、按名称关键词包含匹配，或不带名称条件列出本店项目；可叠加项目类型、销售状态和开始日期筛选。
- `project_stock_get`：查询一个已确认项目（或其中一个场次）当前的场次、票档、售卖时间和实时余票，给出场次小计与项目合计；不含销售金额。
- `project_report`：查询一个已确认项目的统一财务指标。
- `project_channel_sales_report`：查询一个项目按原始渠道并下钻票种的销售与退款分布。
- `project_sku_sales_report`：查询一个项目全生命周期按场次、票档拆分的销售、退款、支付构成、剩余可售和预计金额。
- `project_ticket_type_report`：查询一个项目全生命周期按场次、票档拆分的出票类型、净出票金额、预留和剩余可售。
- `project_channel_sku_report`：查询一个项目全生命周期按场次拆分的渠道 × 票档净数量、优惠与实收。
- `project_verification_report`：查询 1～50 个已确认票务项目的当前票码状态快照，按项目汇总并拆分到场次；不提供时间区间或渠道票种核销事件统计。
- `project_screening_verification_report`：分页查询已结束场次，或查询一个指定已结束场次的核销与上座率。

不要调用连接器已隐藏的 `project_set_sale_state`。

## 项目确认

1. 已知项目 ID 时，优先用 `project_search.project_id` 精确定位。
2. 用户明确说“以某词开头”时用 `name_prefix`；给出名称片段、简称或关键词时用 `query` 做包含匹配。关键词有明显的等价写法（如“海洋馆”与“海洋公园”）时，可在 `search_terms` 补充最多 8 个拆词，与 `query` 按“任一命中”召回；不要把拆词当成必须同时满足的条件。
3. 用户要“列出本店项目”“看看有哪些在售项目”时，不传 `project_id`、`name_prefix`、`query`，只按需加销售状态、类型或开始日期筛选，并按服务端 `next_cursor` 翻页。
4. 搜索结果只用于确认项目。用户已明确完整名称且结果唯一匹配时直接继续；存在多项或只有相似名称时，展示完整项目名和区分信息后等待选择。包含匹配命中多个时尤其不能默认第一项。
5. 后续报表只传已确认的项目 ID。报表不会因项目不存在而报错，可能返回名为“项目 N”的零值结果，所以未经搜索确认的 ID 不直接进报表。核销快照使用 `project_ids` 数组，其余单项目报表使用 `project_id`；不要因为它们都叫报表而复用同一参数对象。

## 关键参数

- `project_search`：必填整数 `target_shop_id`；`project_id`、`name_prefix`、`query` 按意图至多选一种（`query` 不能与前两者同传，`search_terms` 必须随 `query` 一起传）；`limit` 默认 20、最大 50。翻页只传上一页返回的 `next_cursor`，且保持原名称条件和筛选不变；游标 15 分钟内有效，过期后从第一页重查。
- `project_stock_get`：必填整数 `target_shop_id` 和已确认的 `project_id`；只看一个场次时加整数 `screening_id`。项目场次超过 100 个时不指定场次会报结果过大，此时请用户给出场次日期，并从已查到的场次中确认场次 ID，不猜 ID。
- `project_report`：必填整数 `project_id`、对象 `period` 和非空 `metrics`；`granularity` 默认为 `day`。
- `project_channel_sales_report`：必填整数 `project_id` 和 `period`；明确起止时间使用最长 366 天的 `type=custom`，用户明确要求项目全部历史时可使用 `type=all`。
- `project_sku_sales_report`、`project_ticket_type_report`、`project_channel_sku_report`：仅必填整数 `target_shop_id` 和已确认的 `project_id`，都是项目全生命周期口径，不传 `period` 或起止时间。
- `project_verification_report`：仅传 `target_shop_id`、非空唯一整数数组 `project_ids`（最多 50 项）。不传旧版的 `project_id`、`period`、`include_current_snapshot`，也不传 `time_from/time_to`。
- `project_screening_verification_report`：`screening_scope` 使用 `all_ended`，或使用带整数 `screening_id` 的 `single`；列表 `limit` 默认 100、最大 200。
- 所有报表均必填已确认的整数 `target_shop_id`。字段结构和可用指标以运行时 Schema 为准。

## 用户表达

- 本节及下文出现的工具名、字段名、枚举值和 ID 传参方式仅供 AI 内部调用，回答用户时不得复述，也不得展示原始 JSON、Schema 或错误码。
- 用“请选择店铺/项目”“你想查询哪个时间范围”“需要看哪项指标”等自然语言澄清；项目候选只展示完整名称、日期、状态等必要脱敏信息。
- 销售状态、项目类型、指标和告警转换为可读中文。无法查询时说明业务原因并给一个可执行下一步，不输出底层技术错误。

## 报表规则

- `project_report` 必须传 `target_shop_id`、`project_id`、`period`、`metrics`。仅支持自然月、自然年或最长 366 天自定义周期，时间基准为结算流水创建日。
- `project_report` 按日期分组只返回有财务日事实的日期。缺少某日不等于该日为零；禁止补零，也不得据此说成数据故障。
- `project_channel_sales_report` 必须传 `period`；用户给出明确期间时使用最长 366 天的自定义范围，只有用户明确要求“全部历史”时才使用全量范围，不得把未给期间自动解释为全部或近一年。已支付与退款分列，不能互相抵消后冒充单一口径。
- `project_sku_sales_report` 的金额分现金、储值卡和积分；同时返回已售、退款、合计、剩余可售、预计金额和出票率。不能把积分金额混入人民币实收，也不能把剩余可售当作物理座位容量。
- `project_ticket_type_report` 按正常票、媒体票、工作票、赠送票等出票类型展示净出票数与金额，并展示预留和剩余可售；金额只含现金与储值卡，不含积分。
- `project_channel_sku_report` 的微信网页与 PC 网页合并为 H5，大麦新版并入大麦；净数量为 0 的渠道不展示。合计包含未单列渠道，可能大于可见渠道行之和，不能自行改算。
- `project_stock_get` 是实时余票，与下单库存校验同口径：选座项目可售 = 总库存 − 已售 − 锁定预留（锁座、预留座、待接受邀请票），非选座项目取票档可售库存。套票和学生票占用成员票档库存，只罗列、不计入小计与合计；合计包含已下架或停用的票档，回答“还能卖多少”时要结合票档的上架与启用状态说明。它回答“现在还剩多少、何时开售”，不回答销售金额；全生命周期销售与退款仍用 `project_sku_sales_report`，两者的剩余可售可能因锁座和实时变化而不同，不能互相校正。
- 上述三张项目报表都是全生命周期快照。用户要求某月或某段时间时，改用支持期间的 `project_report` 或 `project_channel_sales_report`，不能给全生命周期结果冒充期间结果。
- `project_verification_report` 固定为票务产品的当前状态快照。结果在 `data.projects[]`，各项包含 `project`、`summary`、`screenings`；用 `data.as_of` 标注快照时间。用户问“上月/某天核销了多少”时说明当前工具不支持历史区间统计，不能去掉日期后冒充原问题的答案。
- 核销快照分别展示已核销票数、部分核销、未核销、过期、锁定、作废及核销次数；应核销票数不含锁定和作废。核销次数不等于核销票数，比例使用服务端值，空分母不能写成 0%。
- `project_screening_verification_report` 必须传 `screening_scope`。全部模式只包含已结束场次；响应告警提示已排除未结束场次时，用中文注明“已排除 N 个尚未结束的场次”。指定场次尚未结束时服务端返回场次未结束错误（`SCREENING_NOT_ENDED`），告知用户上座率需在场次结束后统计，不改查其他场次，也不用核销快照代替。
- 已结束场次的 `summary` 和 `selection.ended_screening_count` 每次只汇总当前页，不是全项目总数。未取完时标注“已查询场次，非全量”；用户需要全部结果时，在查询预算内沿原条件的服务端游标取完并按场次去重，不能直接平均各页上座率，也不能把最后一页汇总当全量汇总。未取得完整数据时不输出全项目总上座率。
- 结果过大、查询计划不可用或聚合数据未就绪时缩小用户已同意的范围；不能自动拆成大量明细扫描。

## 典型问法与执行

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

- “项目 ID 123 的基本情况” → `project_search(project_id=123)`，返回唯一项目后直接概括。
- “查一下海洋馆这个项目”“名字里带海洋的项目” → `project_search(query=海洋馆)` 或 `query=海洋`；多候选时列出完整项目名并等待确认。
- “名称以‘2026 春季’开头的项目” → `project_search(name_prefix=2026 春季)`。
- “列出本店在售的项目” → `project_search(sale_state=on_sale)`，不带名称条件；未取完时说明“已列出部分项目”，用户需要时再翻页。
- “这个项目还有多少票”“有哪些场次和票档、什么时候开售” → 先确认项目，再用 `project_stock_get`；只问某一场时带该场次的 `screening_id`。
- “这个项目本月收入和售票数” → 先确认项目，再用 `project_report`；“收入”映射商户实际收入，“售票数”映射售出票数，仍有歧义时先确认。
- “这个项目各渠道、各票种卖了多少” → `project_channel_sales_report`，分别展示已支付与退款。
- “这个项目各票档卖了多少、退了多少、还剩多少” → `project_sku_sales_report`，按场次和票档展示全生命周期销售与库存。
- “这个项目各类票出了多少、预留多少” → `project_ticket_type_report`，按出票类型展示全生命周期净出票与库存。
- “这个项目各渠道分别卖了哪些票档” → `project_channel_sku_report`，展示全生命周期渠道 × 票档交叉结果。
- “这两个项目现在核销情况” → 逐个搜索确认项目后，用 `project_verification_report(project_ids=[...])` 查询当前快照；“某场上座率”或“所有已结束场次上座率” → `project_screening_verification_report`。

## 多工具场景

- 用户只给项目名并要求报表：先搜索、再确认、最后报表；不能把搜索候选直接当成已确认项目。
- 用户要求“销售加核销”：销售按所选期间，核销明确为当前快照；先说明两者的时间口径不同。用户接受这两种范围后分区展示，不能声称是同一期间的销售和核销。
- 用户要求“项目订单明细”：项目确认后转入 `trade_search`，并要求最长 366 天的时间锚点；若用户实际只要汇总，优先使用项目报表。
- 用户问某个订单或某张票“核销了没、谁核销的、打印过没”：转入订单 Skill 的票码核销查询；项目核销快照和场次上座率只回答整体比例，不回答单张票。

## 输出

- 读取 `result.structuredContent`，保留指标单位、统计时间、时区、新鲜度、警告和分页信息。
- 项目财务、期间渠道销售、全生命周期票档/出票/渠道报表、核销快照、已结束场次上座率属于不同口径；回答时用业务语言明确口径，不能混算或复述工具名。
- 候选列表只展示服务端返回的项目 ID、完整名称、类型、销售状态和日期等必要字段；报表按“项目与期间 → 核心结论 → 分组明细 → 口径/告警”组织。
- 项目列表和搜索结果只含当前账号可见的项目；某页条数少于 `limit` 甚至为空但 `has_more=true` 时，只表示本页没有可见项，不能说店里没有更多项目。
- 无结果时说明当前项目和条件下暂无数据。
- 保持名称和敏感信息的服务端脱敏，不展示签名引用或内部授权字段。

## 失败处理

- 任一工具失败后只跳过该查询项及依赖步骤，继续其他独立项目查询，最后按总入口的“最高优先级：单项失败隔离与输出闸门”补充一条错误提示；不得展开工具、参数、Schema、权限详情或自动生成修改报告/文件。
- 权限或目标店铺错误按总入口 Skill 的授权流程恢复，并使用总入口的用户友好文案。
- `QUERY_PLAN_UNAVAILABLE`、`DATA_NOT_READY`：停止当前维度，不换表或改查大量订单；普通回答不展示错误码。
- 分页游标失效（`CURSOR_INVALID`）：按相同条件从第一页重新查询一次；不得构造游标。