.. _qpro_performance_guide:

.. rst-class:: qpro-docs-page

================================================================
历史绩效分析与导出
================================================================

.. container:: qpro-docs-meta

   应用指南 · 结算后的历史数据

本指南从准备数据开始，演示如何查看历史权益、导出资金与交易记录，并制作 HTML 绩效看板。使用 ``8815`` 的绩效分析服务；HTTP 契约见 :ref:`qpro_performance_api`，字段定义见 :ref:`qpro_performance_schema`。

先让 AI 使用绩效分析 Skill
--------------------------------------------------

按 :ref:`qpro-api-ai-agent` 安装或更新 QPro Skills 后，Agent 可以使用 ``analyse-server-settlement-data`` 查询本服务。可以直接提出以下需求：

.. code-block:: text

    请使用 QPro 绩效分析 Skill，列出可查询的账户，让我选择账户和日期区间。
    根据已解析的结算数据，生成每日客户权益、出入金、手续费和保证金报表，
    并按合约汇总成交手续费。保留缺失值，展示实际数据覆盖日期。
    如果做成 HTML 页面，请支持账户与日期筛选，以及导出查询结果。

页面可按 :ref:`extensions` 加入 QPro 的扩展板块。需要导入最新数据时，可以再明确要求 Agent “先同步并解析最新结算数据，再重新查询”。已有本地数据的查询无需每次刷新。

启用与首次使用
--------------------------------------------------

#. 使用包含此功能的 QPro 版本，按 :ref:`qpro_httpserver` 启用 ``本地 Api 接口``，重启并重新登录。
#. 在 ``账户持仓监控`` 中确认 ``绩效分析 Api 服务端口``，默认是 ``8815``；修改后需要重启。
#. 检查服务是否可用。首次使用或需要最新数据时，依次执行同步、解析，再查询可用账户与历史记录。

.. code-block:: text

    检查服务 → 同步结算数据 → 解析结算数据 → 选择账户 → 查询历史记录

只读取已经准备好的历史数据时，可直接从“选择账户”开始。QPro 负责启动服务和访问上游所需的登录身份，调用方不需要填写访问令牌。服务仅监听本机，详细访问边界见 :ref:`qpro_httpserver` 的安全说明。

.. note::

   可查范围取决于上游已有的结算数据以及本地同步、解析结果。启动服务或健康检查成功，不代表历史数据已经完整。若上游没有某个账户或交易日的数据，本接口也无法补出这些记录。

刷新与选择账户
----------------------------------------------------------------

首次导入或需要最新数据时，按 :ref:`qpro_performance_refresh` 依次调用同步和解析接口，并检查返回的失败计数。然后用 ``GET /account-infos`` 获取可查询账户，原样使用期货公司名称和客户号。

已有本地数据时可以直接查询，不必每次筛选都同步。下面的三个示例分别适合临时查看、批量导出和制作页面。

示例一：用 PowerShell 查看历史权益与资金占用
--------------------------------------------------

先调用 ``/account-infos``，从结果中选定账户，再替换下方名称、客户号和日期。示例将 JSON 显式编码为 UTF-8，兼容包含中文期货公司名称的请求。

.. code-block:: powershell

    $baseUrl = "http://127.0.0.1:8815"
    $query = @{
        start_date = "2026-08-01"
        end_date = "2026-08-31"
        accounts = @(@{
            futures_company_name = "示例期货公司"
            client_id = "000001"
        })
    }
    $body = [System.Text.Encoding]::UTF8.GetBytes(($query | ConvertTo-Json -Depth 4))
    $result = Invoke-RestMethod -Method Post -Uri "$baseUrl/accounts/query" `
        -ContentType "application/json; charset=utf-8" -Body $body
    if ($result.code -ne 0) { throw $result.message }
    $result.data.accounts | Select-Object trading_day, currency, client_equity, `
        deposit_withdrawal, commission, margin_occupied, fund_available, risk_degree

这些列可以用来制作每日权益与保证金曲线。``risk_degree`` 是小数比例，例如 ``0.2`` 应显示为 ``20%``。资金、手续费等缺失值应保留为空，不要在展示或计算时直接补零。

示例二：用 Python 导出历史数据并汇总手续费
--------------------------------------------------

下载 :download:`完整 Python 示例 <examples/settlement_export.py>`。脚本只依赖 Python 3 标准库，无需安装第三方包。首先列出可查询账户：

.. code-block:: powershell

    python settlement_export.py --list-accounts

首次使用且需要导入最新数据时，可以添加 ``--refresh``。它会依次同步、解析，检查本轮失败计数后再读取账户列表：

.. code-block:: powershell

    python settlement_export.py --refresh --list-accounts

选定账户后导出一个日期区间，示例账户需要替换为实际返回值：

.. code-block:: powershell

    python settlement_export.py --company "示例期货公司" --client "000001" `
        --start-date 2026-08-01 --end-date 2026-08-31

修改服务端口时传入 ``--base-url http://127.0.0.1:你的端口``。默认只查询已解析数据；只有显式添加 ``--refresh`` 才会同步和解析。刷新耗时较长时，脚本为每个刷新请求设置了 600 秒超时。

脚本自动新建带时间戳的输出目录，产生以下文件：

.. list-table:: 示例输出
   :class: qpro-api-table
   :header-rows: 1
   :widths: 30 70

   * - 文件
     - 用途
   * - ``records.json``
     - 保存查询条件、导出时间和三类完整记录，保留字符串标识符与 ``null``
   * - ``accounts.csv``
     - 每日账户资金，可用于制作权益、出入金和资金占用曲线
   * - ``trades.csv``
     - 取齐分页后的历史成交明细
   * - ``positions.csv``
     - 取齐分页后的日终持仓汇总
   * - ``fees_by_contract.csv``
     - 按账户、币种、数据来源、交易所和合约汇总成交手续费，并记录缺失手续费的行数

手续费汇总中，只要某组存在缺失手续费，``commission_total`` 就留空，避免把不完整金额作为总额。``trade_rows`` 表示成交记录条数，不是成交手数或完整往返交易次数；币种由同日账户记录关联，缺失时留空，不合并不同币种的金额。

分页实现如下，也可以在自己的程序中复用：

.. literalinclude:: examples/settlement_export.py
   :language: python
   :start-at: def query_pages
   :end-before: def write_csv

导出时保持查询区间的数据不变。脚本能发现翻页过程中总数变化或提前返回空页，但无法检测总数不变的内容更新。CSV 的缺失值为空白；导入 Excel 时请将客户号、成交编号等列设为文本，以保留前导零。需要精确保留原始类型时使用 ``records.json``。

.. _qpro_performance_html_example:

示例三：生成历史绩效 HTML 扩展
--------------------------------------------------

可以让 Agent 组合本服务与 HTML 扩展能力，制作适合自己的复盘页面。下面两张 AI 生成的效果图使用虚构示例数据，展示可实现的布局与分析方式。

.. figure:: ../images/ai_editor/performance-overview-demo.png
   :alt: 历史绩效看板效果图，包含账户与日期筛选、客户权益与风险度曲线、按合约汇总的成交手续费，以及数据覆盖说明
   :align: center
   :width: 100%

   资金概览：按账户与日期查看客户权益、出入金和风险度，并按合约比较成交费用；同步解析与查询分别操作。

.. figure:: ../images/ai_editor/performance-positions-demo.png
   :alt: 日终持仓效果图，包含选定交易日的多空持仓对比、账户保证金占用及持仓明细，并将缺失均价标为空值
   :align: center
   :width: 100%

   日终持仓：选择交易日查看各合约的多空数量、账户保证金和持仓明细，缺失字段保留为空，不补成零。

可以把下面的需求交给 Agent，再按自己的复盘习惯调整展示内容：

.. code-block:: text

    使用 QPro 的 analyse-server-settlement-data 和 build-qpro-extension-html Skills，
    生成一个单文件 HTML 历史绩效看板。
    从 /account-infos 读取账户，允许选择日期区间。
    展示每日客户权益、出入金、手续费和风险度，按合约汇总成交费用，
    并支持查看某个交易日的多空持仓及保证金。
    成交和持仓必须取完全部分页；缺失数据展示为缺失，不补成零。
    显示实际覆盖日期、数据来源与币种。
    提供单独的“同步并解析”按钮，完成后重新查询，不在每次筛选时刷新。

浏览器调用查询接口时使用 JSON ``POST``，例如：

.. code-block:: javascript

    async function queryAccounts(selectedAccounts, startDate, endDate) {
      const response = await fetch("http://127.0.0.1:8815/accounts/query", {
        method: "POST",
        headers: {"Content-Type": "application/json; charset=utf-8"},
        body: JSON.stringify({
          start_date: startDate, end_date: endDate, accounts: selectedAccounts
        })
      });
      const result = await response.json();
      if (!response.ok || result.code !== 0) {
        throw new Error(result.message || `HTTP ${response.status}`);
      }
      return result.data.accounts;
    }

如何理解历史数据
--------------------------------------------------

* **数据来源**：``source_type`` 为 ``ObserveSettlement`` 时来自结算单；为 ``ObserveSnap`` 时来自支持的快期模拟日快照。两类来源的字段覆盖可能不同，应保留来源并检查所需字段是否存在。
* **权益与收益**：客户权益变化可能包含出入金，不能直接当作交易收益或净值回报。绘制收益率、回撤或计算风险调整指标前，应明确现金流处理、币种、期权市值、费用和缺失交易日口径。
* **费用与盈亏**：账户手续费与成交手续费汇总是不同层级的统计，不要重复扣减。单独的成交平仓盈亏不能代表整个账户的每日盈亏，也不能直接用于计算完整交易胜率。
* **合约标识**：``instrument_id``、``exchange`` 保留来源中的表示，合约不保证带 ``交易所.`` 前缀。连接行情 API 前，应按交易所和合约核对映射；持仓记录本身不包含 ``exchange`` 字段，不要直接假设合约代码在各服务中完全相同。
* **缺失与零**：空成交、空持仓可能是当天确实没有相应业务，也可能是数据尚未齐全。应结合账户记录、同步解析计数和原始结算数据确认，不能仅凭空列表推断账户没有交易。