Fanzhi Finance

---
name: fanzhi-finance
description: 查询番知票务结算流水和番知云服务费。当用户问订单或交易的结算/退款流水、资金是否到账、店铺或指定项目的服务费应计金额、实际成功分账净入账或两种财务口径核对时使用。不用于订单业务状态、普通销售额或自行推算财务金额。
---

# 番知财务查询

财务结果必须严格遵守服务端口径。只查询用户确认的 `target_shop_id`；未确认时先调用 `mcp_access_context_list`。参数、枚举、金额字段和时间格式以当前工具 Schema 为准。

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

## 工具选择

- `finance_flow_search`：按内部订单号、支付交易号，或最长 366 天的创建时间范围查询结算流水。
- `fanzhi_service_fee_report`：查询最长 366 天内店铺、组织或最多 30 个指定项目的番知云应计服务费净额和系统平台实际成功分账净入账；两侧时间口径不同，必须分别展示。

## 关键参数

- `finance_flow_search`：必填整数 `target_shop_id`；必须提供字符串 `increment_id`、字符串 `trade_no`，或同时提供日期时间 `time_from`、`time_to`。`limit` 默认 20、最大 50。
- `flow_topic` 只使用结算或退款枚举；`project_ids` 是最多 100 个唯一整数，仅用于缩小范围。
- `fanzhi_service_fee_report`：必填整数 `target_shop_id` 和标准 `period`，支持自然月、自然年或最长 366 天自定义日期。按项目统计时传 `project_ids`（1～30 个经 `project_search` 确认的项目 ID）；不传则按店铺或组织全量统计。没有单数的 `project_id` 参数。
- `report_scope` 默认目标店铺；只有组织权限成立时才传 `organization` 和可选 `shop_ids`。

## 用户表达

- 工具名、字段名、枚举值、内部 ID 参数、原始 JSON、Schema、错误码和请求 ID 仅供内部调用，普通回答中不得展示。
- 用“请提供订单号、交易号或查询时间范围”“请选择店铺/项目”等自然语言澄清，不向用户索要参数名。
- 流水主题、状态、金额口径和告警转换为可读中文；金额不做推算。无法查询时采用总入口的友好文案，并给一个可执行下一步。

## 财务流水

1. 已知 `increment_id` 或 `trade_no` 时优先精确点查。
2. 无精确标识时必须提供 `time_from` 和 `time_to`，最长 366 天；仅使用 Schema 允许的 `flow_topic`。
3. `project_ids` 只能缩小当前授权范围。按项目名查询前先用 `project_search` 展示候选并让用户确认项目 ID。
4. 按时间段查询时，只要结果里含有当前账号不可见项目的流水，整次查询就会返回“对象不在授权范围”。此时说明范围内有无权查看的项目，请用户改用订单号或交易号，或指定有权限的项目；不自动换条件重试。
5. 翻页只传上一页返回的 `next_cursor`，时间范围和筛选保持与第一页完全一致。
6. 不按金额、备注或买家信息做无锚点扫描；不把分页查询扩展为全量导出。

## 服务费报表

- 用户要看某个或某几个项目的服务费时，先用 `project_search` 确认项目，再按 `project_ids` 查询；超过 30 个时请用户缩小选择，不拆成多次调用拼接。
- 按项目统计时，实际分账侧靠订单号关联订单取项目。关联不到订单的分账不计入项目，响应告警会给出笔数和净额；用中文说明“有 N 笔分账找不到对应订单，未计入按项目统计（净额 X 元）”，所以各项目之和可能小于店铺全量，不能自行补算或摊分。
- 按项目统计时区间内分账记录过多会返回结果过大，请用户缩短时间范围或缩小店铺范围。
- `report_scope=organization` 仅主店超级管理员且外部 Grant 明确授予组织动态只读时可用。
- `shop_ids` 只能缩小组织范围，不能扩大授权。
- 应计服务费净额与实际成功分账净入账是两个独立口径，必须分别展示和说明差异，不能互相替代。
- 任一侧无安全数据计划时不返回或拼接“半份结论”，也不扫描分账明细补算。
- 若当前环境尚未启用安全查询计划，按总入口的数据未就绪规则停止该项；不能改查大量财务流水自行汇总。

## 典型问法与执行

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

- “查订单 2026xxx 的结算流水” → `finance_flow_search(increment_id=..., flow_topic=settlement)`。
- “查交易号 xxx 的退款流水” → `finance_flow_search(trade_no=..., flow_topic=refund)`。
- “查本月番知云服务费” → 将本月转换为上海时区自然日期范围后调用 `fanzhi_service_fee_report`。
- “查海洋馆项目今年的服务费” → `project_search(query=海洋馆)` 确认项目 → `fanzhi_service_fee_report(period=今年, project_ids=[项目 ID])`。
- “这三个项目上个月的服务费分别是多少” → 逐个确认项目后一次调用 `fanzhi_service_fee_report(project_ids=[...])`，按项目分别展示并给出合计。
- “为什么订单显示退款但账务没对上” → `trade_get` 确认订单退款事实，再分别查询结算与退款流水，不根据单侧结果猜测到账状态。

## 多工具场景

- 订单财务核对：`trade_get` → `finance_flow_search`，按订单号/交易号对齐并分开说明订单状态与资金流水。
- 项目服务费只用 `fanzhi_service_fee_report` 的按项目统计；项目经营指标可由 `project_report` 查询，但不能代替服务费，也不能把整店服务费按销售额摊到项目。
- 用户要求“导出全部流水”时说明当前工具仅支持受控分页查询，不自动遍历全部页面。

## 输出

- 从 `result.structuredContent` 读取金额、币种/单位、时间基准、范围、新鲜度与告警。
- 金额按服务端人民币元定点字符串展示，不再除以 100，不用浮点数重新计算账务。服务费应计侧按财务事实日、实际侧按分账完成日，分别保留时间口径。按项目统计时逐项目金额在 `projects`（按项目 ID 升序），只选一个项目时 `project` 同时给出该项目；不按项目统计时两者为空。两侧各自带的更新时间在该侧无数据时等于响应时间，不能写成“数据已更新到 X”。
- 财务流水事实、应计服务费和实际分账入账不得混算；退款也保留服务端给出的独立口径。
- 流水按“订单/交易锚点 → 流水主题与时间 → 金额事实 → 状态/告警”组织；服务费报表按“范围 → 应计净额 → 实际净入账 → 差异 → 口径/告警”组织，多项目时先给合计再列逐项目表格。
- 空结果只表示当前条件下暂无数据，不代表余额为零或已经完成结算。
- 个人和资金敏感字段保持服务端白名单与脱敏，不输出 Token、完整手机号或内部签名字段。

## 失败处理

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