报告

报告模型、HTML/Plotly/Bokeh/XLSX 渲染器，以及组合与风险报告构建器。

面向任务的示例参见使用指南。以下签名由与本站点其余内容同一提交的公共头文件生成。

struct portfolio_transaction

交易活动投影使用的一笔已成交交易。

公共成员

timestamp date = 0: UTC 纳秒时间戳；交易按日历日分组。

std::string symbol: 成交标的代码。

double amount = 0.0: 带符号数量；名义金额按 |amount| * price 计算。

double price = 0.0: 单位成交价。

struct report_artifact

一个产出产物（内存内容和/或写入路径）。

公共成员

std::string name: 逻辑名称，例如 "figure"、"file" 或 "axis:
."。

std::string path: 写入的文件路径；仅驻留内存的产物为空。

bool owned = true: 自持有的内存产物为 true；调用方提供的坐标轴以及 write_pdf 返回的文件产物为 false。

std::string content: 序列化的图形或坐标轴 JSON；对文件产物则为写入的字节。

struct report_artifact_bundle

报告渲染器返回的、带所有权的原生产物包。

与固定版本的 ArtifactBundle 结构一致：metadata 始终携带 backend 和 report_digest；artifacts 携带命名输出。

公共函数

const report_artifact *find(std::string_view name) const

按逻辑名称查找产物。

参数:: name -- Artifact name to search for.
返回:: Pointer to the first matching artifact, or nullptr when no artifact has name.

const std::string &report_digest() const

返回该产物包的报告摘要。

抛出:: input_error -- If metadata has no "report_digest" entry.
返回:: Value of the "report_digest" metadata entry.

公共成员

std::map<std::string, std::string> metadata: 产物包元数据；渲染器会设置 "backend" 和 "report_digest"。

std::vector<report_artifact> artifacts: 命名输出。

std::optional<plotly_document> plotly: 由 render_plotly 生成时的 Plotly 图形。

std::optional<bokeh_document> bokeh: 由 render_bokeh 生成时的 Bokeh 文档。

std::vector<report_static_axes> axes: 由 render_matplotlib 生成时的静态坐标轴。

struct report_cell

report_table 中的一个带类型单元格。

公共类型

enum class kind

单元格取值类型。

missing 不携带值并序列化为 null；number 使用 number，text 使用 text，boolean 使用 boolean。

取值：

enumerator missing

enumerator number

enumerator text

enumerator boolean

公共成员

kind type = kind::missing : 决定生效字段的取值类型。

double number = 0.0: 类型为 number 时使用的数值。

bool boolean = false: 类型为 boolean 时使用的布尔值。

std::string text: 类型为 text 时使用的文本值。

公共静态函数

static inline report_cell missing()

构造一个缺失单元格。

返回:: Cell whose type is kind::missing.

static inline report_cell number_cell(double value)

构造一个数值单元格。

参数:: value -- Numeric value to store.
返回:: Cell whose type is kind::number.

static inline report_cell text_cell(std::string value)

构造一个文本单元格。

参数:: value -- Text to move into the cell.
返回:: Cell whose type is kind::text.

static inline report_cell boolean_cell(bool value)

构造一个布尔单元格。

参数:: value -- Boolean value to store.
返回:: Cell whose type is kind::boolean.

struct report_document

由报告构建器和渲染器共享的带版本报告文档。

公共函数

const report_section &section(std::string_view key) const

按键查找节。

参数:: key -- Section key to search for.
抛出:: input_error -- If the document is invalid or no section has key.
返回:: Const reference to the matching section.

report_section &section(std::string_view key)

按键查找节以便就地修改。

参数:: key -- Section key to search for.
抛出:: input_error -- If the document is invalid or no section has key.
返回:: Mutable reference to the matching section.

std::string to_json() const

将校验后的文档序列化为确定性 JSON。

离线资源内容以 JSON 字符串值嵌入，映射键按排序顺序输出。

抛出:: input_error -- If the schema version is unsupported, section keys are duplicated, section metadata is invalid, or a value is non-finite or malformed.
返回:: JSON text terminated by a newline.

std::string semantic_payload() const

序列化校验后的文档，并对离线资源内容取哈希。

每个资源值替换为其 SHA-256 十六进制摘要，因此载荷反映资源身份而不嵌入字节。

抛出:: input_error -- For the same validation failures as to_json().
返回:: JSON text terminated by a newline.

std::string semantic_digest() const

计算语义载荷的来源摘要。

该摘要是对带版本的帧和 semantic_payload() 计算的 SHA-256；报告渲染器将其作为 report_digest 打包元数据公开。

抛出:: input_error -- If semantic_payload() fails validation.
返回:: Lowercase hexadecimal SHA-256 digest.

公共成员

std::string domain: 报告领域，例如 "portfolio"、"risk" 或 "factor"。

std::string title: 文档标题。

std::vector<report_section> sections: 有序节列表；键必须唯一。

std::map<std::string, std::string> metadata: 自由格式元数据。

int schema_version = report_document_schema_version : 模式版本；序列化时必须等于 report_document_schema_version。

std::map<std::string, std::string> offline_assets: 嵌入的资源名称到内容映射；to_json 将内容写为字符串值，而 semantic_payload 写入其 SHA-256 摘要。

struct report_html_options

HTML 渲染选项。

公共成员

std::string language = "en": 界面语言："en" 或 "zh"。

report_chart_backend chart_backend = report_chart_backend::inline_svg : 报告序列的图表渲染器。

struct report_metric

带一个可选类型化值的命名标量指标。

公共成员

std::string key: 节元数据使用的稳定标识符。

std::string label: 显示标签。

std::string unit: 取值单位，例如 "ratio" 或 "count"。

std::optional<double> number: 数值；优先于布尔值和文本值。

std::optional<bool> boolean: number 未设置时使用的布尔值。

std::optional<std::string> text: number 与 boolean 均未设置时使用的文本值。

struct report_section

一组带标题的指标、表格、序列和说明。

公共函数

std::string semantic_payload() const

将本节序列化为确定性 JSON。

每个 units 和 legends 键都必须匹配本节中的指标、表格或序列键，且其值不能为空。

抛出:: input_error -- If section metadata references an unknown key or has an empty value, or if a number, table row or series is malformed.
返回:: JSON text terminated by a newline.

公共成员

std::string key: 文档内唯一的节键。

std::string title: 显示标题。

std::vector<report_metric> metrics: 标量指标。

std::vector<report_table> tables: 表格。

std::vector<report_series> series: 图表序列。

std::vector<std::string> notes: 自由格式说明。

std::map<std::string, std::string> units: 按本节指标、表格或序列键索引的单位覆盖。

std::map<std::string, std::string> legends: 按本节序列键索引的图例。

struct report_series

用于图表渲染的命名数值序列。

公共成员

std::string key: 图例与产物使用的稳定标识符。

std::string title: 显示标题。

std::string x_label: X 轴标签。

std::string y_label: Y 轴标签。

std::string unit: 取值单位，例如 "ratio" 或 "growth_multiple"。

std::vector<double> x: X 值；长度必须与 y 相同。

std::vector<double> y: Y 值。

struct report_static_axes

Matplotlib 坐标轴的静态原生替代实现。

Python 渲染器为每个节序列返回一个坐标轴，键为 axis:

.。原生产物携带相同的预处理值；不存在 Matplotlib 对象，也不会重新调用内核计算。

公共成员

std::string name: 形如 "axis:
." 的名称。

std::string section_key: 来源节键。

std::string series_key: 来源序列键。

std::string title: "
: "。

std::string label: 该序列的节图例；未设置图例时为序列键。

std::string x_label: 从序列复制的 X 轴标签。

std::string y_label: 该序列的节单位；未定义时为空。

std::string unit: 与 y_label 相同的值。

std::vector<double> x: 从序列复制的 X 值。

std::vector<double> y: 从序列复制的 Y 值。

bool owned = true: 当调用方提供了匹配的坐标轴键时为 false。

struct report_table

由带类型单元格构成的命名表格。

公共成员

std::string key: 节元数据与渲染器使用的稳定标识符。

std::string title: 显示标题。

std::vector<std::string> columns: 列标题。

std::vector<std::vector<report_cell>> rows: 数据行；序列化时每行必须包含 columns.size() 个单元格。

struct xlsx_render_options

render_xlsx 的工作表命名选项。

公共成员

std::string sheet_prefix: 拼接在每个节键之前以构成工作表名称的前缀。

enum class fincore::report_chart_backend

render_html 使用的图表渲染器。

取值：

enumerator inline_svg: 将每个序列绘制为内联 SVG 折线。

enumerator echarts: 嵌入固定版本的离线 ECharts 5.5.0 脚本和图表载荷。

report_document fincore::build_portfolio_report(const dataframe &returns, const dataframe *benchmark = nullptr, std::string title = "Portfolio Report", const dataframe *positions = nullptr, std::size_t rolling_window = 63U, std::span<const portfolio_transaction> transactions = {})

基于预处理收益率与持仓数据构建组合报告文档。

该文档的领域为 "portfolio"。它始终包含一个 "performance" 节；提供 benchmark 时追加 "benchmark" 节；提供 positions 时追加 "portfolio" 节；transactions 非空时追加 "transactions" 节。指标依据输入计算一次；渲染器不会重新计算。

参数:

returns -- Daily simple returns with a required "returns" double column.
benchmark -- Optional benchmark frame with a "benchmark" double column; enables the benchmark comparison section.
title -- Document title.
positions -- Optional positions frame with a "cash" column, a unique index, finite values, and a row for every return timestamp; enables the portfolio exposure section.
rolling_window -- Rolling window for the rolling Sharpe, volatility and beta series; must be positive.
transactions -- Optional transactions used for the transaction section and, with positions, for turnover.

抛出:

input_error -- If rolling_window is zero, a required column is missing or has the wrong type, positions are empty, duplicated, not finite or do not cover the return timestamps, or a transaction has a non-finite amount or price.

返回:

Report document with observations, daily period and rolling-window metadata.

report_document fincore::build_risk_report(const risk_validation_report &report, std::string title = "Risk Validation Report")

基于滚动前向 VaR 报告构建风险验证报告文档。

该文档的领域为 "risk"，包含一个 "risk_validation" 节，其中有滚动前向状态、预测与重新拟合计数、可选诊断与回测指标、预测事件表和重新拟合表，以及以说明形式给出的报告披露。

参数:

report -- Native walk-forward risk validation report to project.
title -- Document title.

返回:

Report document using report_document_schema_version.

report_artifact_bundle fincore::render_bokeh(const report_document &document)

将预处理的报告序列投影为一个兼容 Bokeh 的文档。

每个序列一个线图元，y 字段为序列键，图例标签为节图例或 "

: "。数值是复制而来，并非重新计算。

参数:: document -- Prepared report document.
抛出:: input_error -- If a series has mismatched x and y lengths or the document fails semantic digest validation.
返回:: Bundle whose metadata identifies the bokeh backend and whose "figure" artifact contains the document JSON.

std::string fincore::render_html(const report_document &document, const report_html_options &options = {})

将报告文档渲染为一个自包含的 HTML 页面。

文本经过 HTML 转义，样式内嵌，不引用任何外部资源 URL；ECharts 后端会嵌入固定版本的图表脚本。相同文档与选项的输出是确定性的。

参数:

document -- Prepared report document.
options -- Language and chart backend selection.

抛出:

input_error -- If the language or chart backend is unknown, a numeric or series value is non-finite, a table row does not match its column count, or an ECharts series has mismatched x and y lengths.

返回:

Complete HTML text starting with "<!doctype html>".

report_artifact_bundle fincore::render_matplotlib(const report_document &document, const std::vector<std::string> &supplied_axes = {})

将预处理的报告序列投影为兼容 Matplotlib 的静态坐标轴。

supplied_axes 列出调用方已拥有的 "

." 键；这些产物被标记为 owned = false，与 Python 的 axes 参数所有权规则一致。

参数:

document -- Prepared report document.
supplied_axes -- Axis keys in the form "<section>.<series>" already owned by the caller.

抛出:

input_error -- If the document fails semantic digest validation.

返回:

Bundle whose metadata identifies the matplotlib backend, with one "axis:<section>.<series>" artifact per series and matching entries in axes.

std::string fincore::render_pdf_bytes(const report_document &document)

为报告文档渲染确定性的原生 PDF 1.4 字节。

包含文本、标题、表格以及简单的折线序列矢量路径。使用 base-14 Helvetica 字体；WinAnsi 之外的字符替换为 ?（相对基于 Chromium 的 Python 写入器已声明的格式差异）。

参数:: document -- Report document to render.
返回:: PDF 1.4 bytes ending with "%%EOF\n".

report_artifact_bundle fincore::render_plotly(const report_document &document)

将预处理的报告序列投影为一个兼容 Plotly 的文档。

每个 report_section::series 条目对应一个散点轨迹；轨迹名称为节图例或 "

: "。数值是复制而来，并非重新计算。原生模型中 report_series::x 为数值，因此 Python 的 DatetimeIndex X 轴属于已声明的日期轴格式差异。

参数:: document -- Prepared report document.
抛出:: input_error -- If a series has mismatched x and y lengths or the document fails semantic digest validation.
返回:: Bundle whose metadata identifies the plotly backend and whose "figure" artifact contains the figure JSON.

std::string fincore::render_xlsx(const report_document &document, const xlsx_render_options &options = {})

将报告文档渲染为内存中的 XLSX 工作簿。

每个节生成一个工作表。工作表名称由 options.sheet_prefix 与节键组合而成，非法字符替换为 '_'，并截断至 31 个字符；重复名称追加 "_2"、"_3" 等后缀。空文档只生成一个名为 "report" 的工作表，若设置了前缀则为该前缀。不会写入文件。

参数:

document -- Prepared report document.
options -- Worksheet naming options.

抛出:

input_error -- If a numeric value is non-finite, a table row does not match its column count, or a series has mismatched x and y lengths.

返回:

ZIP-compressed XLSX bytes, deterministic for the same document and options.

report_artifact_bundle fincore::write_pdf(const report_document &document, const std::string &target)

将原生 PDF 写入 target 并返回产物包。

与 Python 写入器一样创建父目录，并截断 target 处的已有文件。不声称与 Python PDF 后端字节一致。

参数:

document -- Report document to render.
target -- Output path; must not be empty.

抛出:

input_error -- If target is empty, its parent directory cannot be created, the file cannot be opened or written, or the document fails semantic digest validation.

返回:

Bundle whose metadata identifies the pdf backend and whose "file" artifact records target, owned = false and the written bytes.

constexpr int fincore::report_document_schema_version = 2: report_document 校验与序列化接受的模式版本。