Fanzhi Trade

---
name: fanzhi-trade
description: 搜索番知票务订单、查询订单详情和票码核销打印状态，并汇总订单收入或票番番分销订单。当用户提供订单号、第三方订单号、支付交易号或票码，询问订单状态、金额、支付或退款事实，某张票或某个订单是否已核销、谁在何时用什么核销、是否打印过，或者要查指定期间的订单金额、票数、退款、佣金、核销与结算时使用。不用于财务结算流水、服务费、项目核销率或渠道拆分报表。
---

# 番知订单查询

只查询用户已确认且已授权的单个 `target_shop_id`。若店铺尚未确认，先调用 `mcp_access_context_list` 并让用户选择。输入字段、枚举和上限以当前工具 Schema 为准。

开始前必须先读 [总入口的最高优先级单项失败隔离、输出闸门与调用前置](../fanzhi-ticketing/SKILL.md)，用完整权限码校验目标店铺，按 JSON-RPC/`structuredContent` 处理成功与失败。订单工具没有组织汇总参数，不能添加 `report_scope` 或 `shop_ids`。

## 工具选择

- `trade_get`：用户已知内部订单号 `increment_id`、第三方订单号 `third_party_order_id` 或支付交易号 `trade_no`，需要单笔详情。
- `trade_search`：需要定位订单候选，或按会员、项目、状态、渠道及时间范围查询列表。
- `ticket_verification_get`：按订单号或票码查询演出票的核销与打印状态：每张票是否核销、逐条核销/撤销记录（时间、核销工具、核销人）和打印记录。
- `trade_filter_options`：在订单收入汇总前取得订单状态、渠道、出票类型、支付方式、发货状态和是否代销等合法选项；按需搜索分销员或出票人候选，不返回订单数据。
- `trade_order_summary`：按最长 366 天的下单、支付或完成时间汇总订单总额、支付额、订单数、销售票数、退款金额和退款票数。
- `sdp_distribution_order_summary`：按分销订单创建日汇总票番番分销的订单金额、票数、单数、佣金、核销和已结算/未结算佣金。

## 关键参数

- `trade_get`：必填整数 `target_shop_id`，并至少提供 `increment_id`、`third_party_order_id`、`trade_no` 中一个字符串标识。
- `trade_search`：必填整数 `target_shop_id`；必须提供一个精确订单/交易标识，或同时提供 `time_field`、`time_from`、`time_to`。
- `member_id`、`project_id`、订单状态、退款状态和渠道都是二次筛选条件，不能代替精确标识或时间锚点。
- `trade_search.limit` 默认 20、最大 50；翻页只传上一页返回的 `next_cursor`。游标不校验时间范围和筛选条件，翻页时这些条件必须与第一页完全一致，否则结果会错位。
- `ticket_verification_get`：必填整数 `target_shop_id`，`increment_id`（订单号）与 `ticket_no`（票码）必须且只能传一个，两个都有时先按订单号查。
- `trade_filter_options`：只需要通用枚举时仅传 `target_shop_id`；查询分销员或出票人时按需传 `include`、名称关键词和 `limit`，同名候选必须让用户确认后再使用返回的 ID。
- `trade_order_summary`：必填 `target_shop_id`、时间口径、带时区的起止时刻，跨度最长 366 天。订单状态、渠道、出票类型、支付方式、分销员、是否代销、发货状态、项目、场次、票档和出票人都是可选筛选。
- 代销筛选 `is_b2b=true` 表示“仅代销”；`false` 或不传均为“不限”，不表示“仅非代销”。用户要求仅非代销时说明该条件暂不支持，不能返回全部订单后声称已筛选。
- `sdp_distribution_order_summary`：必填 `target_shop_id` 和标准 `period`，支持自然月、自然年或最长 366 天自定义日期；可选已确认的项目 ID 数组，最多 100 项。

## 用户表达

- 工具名、字段名、枚举值、内部 ID 参数、游标、原始 JSON 和错误码仅供内部调用，普通回答中不得展示。
- 用“请提供订单号或查询时间范围”“请选择店铺”“请确认是哪笔订单”等自然语言澄清，不向用户索要参数名。
- 订单、支付和退款状态转换为可读中文；候选只展示订单号、项目、时间、状态等必要脱敏信息。无法查询时采用总入口的友好文案，并给一个可执行下一步。

## 查询规则

1. 已知唯一订单或支付标识时优先使用 `trade_get`，避免列表扫描。
2. 同时提供多个标识时，它们必须指向同一订单；返回冲突时让用户核对，不丢弃任一标识后自动重试。
3. `trade_search` 的非精确查询必须提供 `time_field`、`time_from`、`time_to`，时间跨度最长 366 天。
4. 时间范围、订单状态、退款状态和销售渠道使用当前 Schema 的枚举，不根据展示文案猜值。
   `time_field` 只允许 `created_at`（下单时间）或 `paid_at`（支付时间），日期时间用带时区的 RFC 3339。按退款状态筛选不代表按退款发生日查询；用户问“本月发生的退款”时不能把下单时间当退款时间。
5. 分页只沿用响应中的签名 `next_cursor`。游标失效时按原条件从第一页重新查。`trade_search` 按精确标识查不到时返回空列表而不是报错，按“当前店铺未找到该订单”处理，请用户核对标识。
6. `trade_order_summary` 是订单页毛额口径，未扣除三方服务费与支付手续费；用户问商户净收入或财务入账时转入经营/财务工具，不能把订单支付额当净收入。部分账号的订单汇总会被设置为不可见，此时服务端返回全零；汇总全部为零时不要断言期间没有订单，可建议用订单列表抽查或联系管理员确认权限。
7. 订单汇总的筛选值以 `trade_filter_options` 返回为准；渠道筛选中的 H5 同时包含微信网页与 PC 网页。项目名先经 `project_search` 确认，不能直接把名称当 ID。
8. 分销汇总按分销订单创建日统计，佣金包含云账户服务费；不用于分销员明细或单笔分销订单，也不能用普通订单汇总替代。
9. 票码核销查询只覆盖演出票。按订单号返回该订单下全部票，订单尚未出票时是空列表，说明“该订单暂未出票”而不是未找到；按票码查时票码只在项目内唯一，同店多个项目可能命中多张，全部列出并附订单号让用户区分。命中的任一张票不在当前账号项目权限内时整体拒绝；超过 300 张时请用户改用单个票码。
10. 核销以逐条记录为准：撤销核销不会改写票的最近核销时间，所以看到“已撤销”时以记录顺序说明当前状态。核销工具按 PDA、核销小程序、后台、闸机、系统自动等中文展示，系统自动核销的核销人写“系统”。
11. 不用于全量导出、票码日志扫描、渠道拆分或跨店订单拼接；项目或场次的核销率转入项目 Skill。

## 典型问法与执行

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

- “查订单 2026xxx” → `trade_get(increment_id=...)`。
- “查微信/渠道订单号 xxx” → `trade_get(third_party_order_id=...)`；用户说的是支付流水号时改用 `trade_no`。
- “查项目 123 最近 30 天的已退款订单” → `trade_search`，同时传项目、退款状态及完整时间锚点。
- “查会员 456 今年的订单” → `trade_search`，同时传会员 ID 和最长 366 天的时间范围。
- “订单 2026xxx 的票核销了没”“这张票谁核销的、打印过没” → `ticket_verification_get(increment_id=...)` 或 `ticket_verification_get(ticket_no=...)`。
- “这笔订单为什么金额对不上” → 先 `trade_get` 确认订单事实；用户需要结算或退款流水时，再以订单号或交易号调用 `finance_flow_search`。
- “近 30 天订单收入、订单数和退款是多少” → 确认下单/支付/完成时间口径后调用 `trade_order_summary`。
- “只看某渠道、某分销员或某出票人的订单汇总” → 先用 `trade_filter_options` 取得合法选项并确认同名候选，再调用 `trade_order_summary`。
- “本月票番番分销销售、核销和佣金结算” → `sdp_distribution_order_summary`；涉及项目名称时先搜索确认项目。

## 多工具场景

- 项目名称未确定：先 `project_search` 并确认项目 ID，再查该项目订单。
- 订单与财务核对：订单详情和财务流水分别调用、按订单/交易标识对齐，明确两者是业务订单事实与财务结算事实，不能混成一个状态。
- 订单汇总与渠道分析：订单汇总只给整组筛选条件下的合计；用户要按项目或渠道拆分时转入经营分析 Skill，不通过多次订单汇总自行拼表。
- 列表中出现多个候选：展示订单号、项目、时间、状态等脱敏字段，用户选择后再用 `trade_get` 查看详情。

## 输出

- 从 `result.structuredContent` 读取结果，明确订单状态、退款状态、金额单位、渠道与时间口径；汇总结果同时保留筛选条件和服务端口径版本。
- 买家手机号等个人信息保持服务端脱敏；不尝试还原或联表补全。
- 多条候选时展示订单号、项目、时间、状态等足以区分的非敏感字段，让用户选择后再查详情。
- 单笔详情按“订单标识与项目 → 当前状态 → 金额与票品 → 支付/退款事实 → 告警”组织，只展示响应真实存在的字段。
- 票码核销按“订单/票码 → 每张票是否核销与最近核销时间 → 核销记录（时间、工具、核销人）→ 打印次数与打印记录”组织；票多时先给已核销/未核销张数，再列明细。
- 订单列表会在分页后过滤退款状态和项目权限，可能出现空页但仍有后页。先检查 `page.has_more`，按总入口区分“本页无匹配”与“完整范围无结果”；不把当前页条数当订单总数，不推断订单存在于其他店铺。

## 失败处理

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