OVAPortableText 0.5.0__tar.gz → 0.6.0__tar.gz

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 **All notable changes to this project will be documented in this file.**  ** **本项目的重要变更会记录在此文件中。
 
+## [0.6.0] - 2026-09-27
+
+### Protocol and Python SDK
+
+* froze `report.v1.5` with native `valuation_result` banners for point and range estimates
+* added typed valuation amounts, currency base-unit semantics, display scale/precision, valuation/capital basis, date and sample-data classification
+* added strict helpers, known-type dispatch, full-document diagnostics, reference/grid support and JSON round trips
+* default new documents to v1.5 while preserving explicit v1.4 and older documents without implicit migration
+* preserve historical custom `valuation_result` payloads under their original schema; require explicit conversion before upgrading
+* added a runnable example, a protocol fixture, a renderer contract and migration guidance
+
+The package creates JSON. The downstream renderer must implement the valuation banner; no silent fallback is provided.
+
 ## [0.5.0] - 2026-09-21
 
 ### Protocol

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: OVAPortableText
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python builder for generating OVAPortableText / Report Profile v1 JSON documents
 Author: FENG QU
 License-Expression: MIT
@@ -23,10 +23,10 @@ Description-Content-Type: text/markdown
 
 # OVAPortableText
 
-> Python **0.5.0** 已实现 [`report.v1.4`](PROTOCOL.md) 的生成、读取和校验，默认新建 v1.4 文档并兼容读取 v1.3。新增五种图表、共享图表语义和组合 `figure`。见 [新版使用指南](docs/PYTHON_V14.md) 与 [完整 Python 示例](examples/v14_report.py)。渲染效果由下游渲染器独立验收。
+> Python **0.6.0** 已实现 [`report.v1.5`](PROTOCOL.md)，新增 `valuation_result` 原生估值结果横幅。支持单值/区间、币种、估值口径、投前/投后、基准日及显示倍率；默认新建 v1.5，兼容旧版本。见 [v1.5 使用指南](docs/PYTHON_V15.md) 与 [可运行示例](examples/v15_valuation_result.py)。渲染端需独立实现横幅。
 
-**OVAPortableText** is a Python authoring package for building JSON documents that conform to the **OVA Report Profile v1.4** protocol.
-**OVAPortableText** 是一个 Python 端的协议生成包，用于创建符合 **OVA Report Profile v1.4** 协议的 JSON 文档。
+**OVAPortableText** is a Python authoring package for building JSON documents that conform to the **OVA Report Profile v1.5** protocol.
+**OVAPortableText** 是一个 Python 端的协议生成包，用于创建符合 **OVA Report Profile v1.5** 协议的 JSON 文档。
 
 It is **not** a PDF renderer. Its job is to help Python code produce a typed, validated, protocol-aligned document payload that can be handed off to a downstream renderer.  
 它**不是** PDF 渲染器。它的职责是帮助 Python 代码以强类型、可校验、可维护的方式生成协议 JSON，再交给下游渲染器处理。

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/PROTOCOL.md

@@ -1,6 +1,6 @@
-# OVA Portable Text v1.4 正式协议
+# OVA Portable Text v1.5 正式协议
 
-状态：正式冻结；冻结日期：2026-09-21。协议版本与 SDK 发布版本独立：Python 包 0.5.0 已实现 v1.4 的生成、读取与校验；渲染器仍需独立实现和验收。
+状态：正式冻结；冻结日期：2026-09-27。Python 包 0.6.0 实现 report.v1.5；v1.4 冻结归档保持不变。渲染器仍需独立实现和验收。
 
 ## 1. 文档定位与阅读方式
 
@@ -22,7 +22,7 @@
 - 协议维护者
 - 校验器开发者
 
-本版新增图表与组合实例的完整规范见第 21 节；它是正式合同，不是候选扩展。
+本版新增 valuation_result 的完整合同见第 22 节；第 21 节的 v1.4 图表与组合能力由本版完整继承。
 
 ### 1.1 本文推荐阅读顺序
 
@@ -54,7 +54,7 @@
 * 一组最小可用的块级对象类型
 * `assets.images` 的双来源图片资源模式
 * `datasets.tables` 的基础结构
-* `datasets.charts` 中十种图表的正式结构：`pie / doughnut / bar / line / matrix_bubble / timeline / stage_progress / flow / funnel / range`
+* `datasets.charts` 中十一种图表的正式结构：`pie / doughnut / bar / line / matrix_bubble / timeline / stage_progress / flow / funnel / range / valuation_result`
 * 第 21 节的数据性质、坐标注释、量表、百分比归一化、圆环中心内容和组合 figure 实例
 * section 级目录参与控制、章节角色、分页提示与展示提示
 * bibliography / footnotes / glossary 的基础条目结构
@@ -62,7 +62,7 @@
 
 当前版本不细化：
 
-* 第 10.4.3 节十种正式图型之外的图表结构（包括误差棒、转化漏斗、双轴图）
+* 第 10.4.3 节十一种正式图型之外的图表结构（包括误差棒、转化漏斗、双轴图）
 * 视觉主题细节
 * 页面级排版算法（除 section 起始前的显式分页提示外）
 * 页眉页脚
@@ -623,7 +623,7 @@ Portable Text 负责提供通用富文本骨架。
 
 ```json
 {
-  "schemaVersion": "report.v1.4",
+  "schemaVersion": "report.v1.5",
   "meta": {},
   "theme": {},
   "assets": {},
@@ -665,11 +665,11 @@ Portable Text 负责提供通用富文本骨架。
 
 `schemaVersion` 表示当前文档所遵循的协议版本。渲染器必须按该值分发解析逻辑。
 
-当前版本固定值： `report.v1.4`
+当前版本固定值： `report.v1.5`
 
 ### 6.3 渲染器要求
 
-- 必须识别 `report.v1.4`
+- 必须识别 `report.v1.5`
 - 遇到未知版本时，应返回清晰错误，而不是静默按旧版本解析
 
 ---
@@ -1400,7 +1400,7 @@ value 为：
 
 #### 10.4.3 当前版本正式支持范围
 
-当前版本中，`datasets.charts` 正式定义十种图表类型：
+当前版本中，`datasets.charts` 正式定义十一种图表类型：
 
 * `chartType = "pie"`
 * `chartType = "doughnut"`
@@ -1413,8 +1413,9 @@ value 为：
 * `chartType = "flow"`
 * `chartType = "funnel"`
 * `chartType = "range"`
+* `chartType = "valuation_result"`
 
-前五种的基础结构见本节，新增类型及扩展字段见第 21 节。除上述十种类型外：
+前五种的基础结构见本节，v1.4 新增类型及扩展字段见第 21 节，valuation_result 见第 22 节。除上述十一种类型外：
 
 * 其他图表类型可以保留在 `datasets.charts` registry 中
 * 不构成稳定字段合同。可保留并诊断；正文实际引用时，正式输出必须确认能力，不得静默忽略。未引用的未知 registry 项不阻止输出。
@@ -1430,7 +1431,7 @@ value 为：
 | `anchor`    | string | 否       | 图表数据锚点     | 省略时可回退为`id`                    |
 | `label`     | string | 否       | 人类可读标签     | 普通字符串                            |
 | `meta`      | object | 否       | 附加元信息       | 当前不商定内部字段                    |
-| `chartType` | string | 是       | 图表类型         | 枚举值：`pie` 饼图，`doughnut` 圆环图，`bar` 柱状图 / 条形图，`line` 折线图，`matrix_bubble` 分类矩阵气泡图；新增 `timeline / stage_progress / flow / funnel / range` 见第 21 节 |
+| `chartType` | string | 是       | 图表类型         | 枚举值：`pie` 饼图，`doughnut` 圆环图，`bar` 柱状图 / 条形图，`line` 折线图，`matrix_bubble` 分类矩阵气泡图；新增 `timeline / stage_progress / flow / funnel / range` 见第 21 节；`valuation_result` 见第 22 节 |
 | `valueUnit` | string | 否       | 数值单位         | 普通字符串                            |
 
 `valueUnit` 当前版本不强制固定枚举，通常可以用它决定：
@@ -4262,7 +4263,7 @@ table_caption
 
 ## 18. 渲染器最低实现要求
 
-为保证 v1.4 能真正落地，渲染器至少应实现以下能力：
+为保证 v1.5 能真正落地，渲染器至少应实现以下能力：
 
 1. 识别顶层结构并遍历 `sections`
 2. 识别 `content` 与 `subsection` 两类 body item
@@ -4273,7 +4274,7 @@ table_caption
 7. 支持 `image / chart / figure / table / math_block / callout`
 8. 支持 `assets.images` 的 `url` 与 `embedded` 两种来源模式
 9. 支持 `datasets.tables`
-10. 支持 `datasets.charts` 中十种正式图型及第 21 节实际使用的扩展能力
+10. 支持 `datasets.charts` 中十一种正式图型及第 21、22 节实际使用的能力
 11. 支持 `bar.categories[]`、`bar.series[]` 与 `series[].data[]` 的基础解析
 12. 支持 `bar.orientation`、`barMode` 与 `xAxis/yAxis` 的兼容性解析
 13. 支持 `orientation = "horizontal"` 时将分类数据源解释为视觉 y 轴、数值序列解释为视觉 x 轴
@@ -5148,6 +5149,90 @@ band 说明区间，不覆盖边界点显式声明的 observed 身份。
 
 
 
+## 22. v1.5 `valuation_result` 估值结果横幅
+
+本节为 v1.5 新增的正式合同。v1.5 完整继承第 21 节的 v1.4 能力；该节的“必须声明 v1.4”对 v1.5 文档解释为“至少具备 v1.4 能力的已支持版本”。本节新类型必须声明 `schemaVersion: "report.v1.5"`，不得写入声称 v1.4 的新生成文档。
+
+### 22.1 用途与实例
+
+`valuation_result` 是单个估值结论的原生图表，默认表现为横向结果横幅：上方标题及估值主体、中部醒目的金额或金额区间、下方估值口径和基准日。它不是带轴的区间比较图，不是自动运行的估值模型，也不执行汇率换算。
+
+数据存放在 `datasets.charts[]`，正文通过 `_type="chart"` 的 `chartRef` 引用；也可作为 grid 中的匿名 ChartBlock 使用。沿用既有 chart 的编号、图注和引用合同，不增加新块类型。横幅可不附图注，不得强制要求 FigureBlock。多个方法的范围比较仍使用 `range`。
+
+```json
+{
+  "id": "valuation-result",
+  "chartType": "valuation_result",
+  "subject": {"en": "Clean Food Group Limited"},
+  "title": {"en": "Valuation range"},
+  "valuation": {"kind": "range", "low": 20100000, "high": 28400000},
+  "currency": "GBP",
+  "valueBasis": "equity_value",
+  "capitalBasis": "pre_money",
+  "asOf": "2026-08-05",
+  "dataBasis": "illustrative",
+  "displayScale": "million",
+  "displayPrecision": 1,
+  "notes": {"en": "Illustrative design sample; not an independently verified valuation."}
+}
+```
+
+### 22.2 数据字段
+
+除通用 registry 字段 `id / anchor / label / meta` 外，正式字段如下。`label` 是资源管理标签，不能替代显示用 `title` 或 `subject`。
+
+| 字段 | 必须 | 类型及规则 |
+| --- | --- | --- |
+| `chartType` | 是 | 固定 `valuation_result` |
+| `subject` | 是 | 非空多语言文本，估值公司或资产名称 |
+| `title` | 否 | 非空多语言文本；省略时按当前语言和 kind 生成“估值区间 / 估值结果” |
+| `valuation` | 是 | 22.3 的判别联合，禁止混合点值和区间字段 |
+| `currency` | 是 | 三位大写 ASCII 字母的币种代码，如 GBP、USD、CNY；生产数据应使用 ISO 4217 代码，SDK 校验形式、不内置随时间变化的币种名录 |
+| `valueBasis` | 是 | `equity_value / enterprise_value / asset_value`，股权价值／企业价值／资产价值 |
+| `capitalBasis` | 否 | `pre_money / post_money`，仅当 valueBasis=equity_value 时允许；缺省表示未声明，不得自动推断投前或投后 |
+| `asOf` | 是 | 真实公历日期，严格 `YYYY-MM-DD`，不是报告生成时间；拒绝部分日期和时间戳 |
+| `dataBasis` | 是 | `evidence_based / illustrative`；表示作者声明，不代表 SDK 审计或认证 |
+| `displayScale` | 否 | `unit / thousand / million / billion`，默认 unit；倍率分别为 1、1000、1000000、1000000000 |
+| `displayPrecision` | 否 | 严格 JSON 整数 0…6，默认 1，期望显示的小数位数；不改变存储精度 |
+| `notes` | 否 | 非空多语言说明，不得覆盖结构化币种、日期、金额及口径 |
+
+多语言文本沿用第 21 节：至少一个非空语言 key 和非空字符串值。新增字段显式 null、空白字符串、未知枚举、未定义字段都应拒绝，optional 字段不使用时省略。显示颜色、字体、宽高、边距不属于本类型的数据字段；`meta` 也不能成为隐含必需的样式合同。
+
+### 22.3 点估值与区间估值
+
+- 点估值：`{"kind":"point","value":24100000}`，value 必须是有限 JSON number。
+- 区间估值：`{"kind":"range","low":20100000,"high":28400000}`，两个端点必须是有限 JSON number，low <= high。
+- 不接受字符串数字、boolean、NaN、Infinity。允许零和负值；不能截断负值或隐瞒负股权价值。负值不等于 SDK 对该估值结论的认可。
+- 区间端点可以相等，应保留 kind=range 的原始语义；不得修改输入或自动推算“中值”。没有 center 字段，也不推断概率、置信区间或估值方法。
+- 所有金额均以 currency 的基本货币单位保存。例如 GBP 的 20100000 表示 £20.1m；displayScale=million 只影响显示时除以 1000000，不能把原值改成 20.1。不得把输入解释成便士。
+- kind 必须显式存在；point 不允许 low/high，range 不允许 value。两种模式都不接受中心点、开区间或单侧无界值。
+
+### 22.4 必须实现的渲染语义
+
+1. 标题区显示 subject，以及显式 title 或默认标题；标题可大写，但不得修改数据或丢失主体。主体过长允许折行。
+2. 主值区显示 point 的 value，或 range 的 low–high；将 displayScale 与小数位用于格式化，原数据保持不变。区间两端使用同一个币种与倍率。示例主值可显示 `£20.1m – £28.4m`。
+3. 上下文区必须显示 currency、valueBasis、asOf，以及存在的 capitalBasis。例：`Pre-money · Equity value · GBP · Base date: 5 August 2026`。GBP 代码必须可见，不能仅靠可能歧义的货币符号识别币种。
+4. dataBasis=illustrative 时提供可见的“示例 / Illustrative”提示；notes 存在时保留为可见附注，不只放入不可访问的悬浮提示。未提供的资本口径不得补造。
+5. displayPrecision 是首选格式：若舍入会把不同端点显示成相同金额，或把非零显示成零，必须增加显示精度或回到基本单位保留差异，不能悄悄改变区间含义。不能仅输出一个预格式化字符串替代上述结构化值。
+6. 无坐标轴、刻度或伪造的误差线。版面使用可用内容宽度；建议居中、主值最大字号、标题次之、附注较小。可采用用户设计中的深蓝底、浅蓝标题与白色主值，但颜色属于主题模板实现，不是估值语义。字体缩放与折行不得裁掉金额、日期或口径。
+7. 若渲染器尚不支持本图型，应在能力预检或正式输出时明确失败；不得忽略、改为普通 range、图片或普通文本后声称等价支持。无障碍的伴随文字可以提供，但不替代横幅实现验收。
+
+### 22.5 版本、兼容与 SDK
+
+Python 0.6.0 默认创建 report.v1.5；显式创建 report.v1.4 继续可用。读取既有版本不自动升级。v1.5 中已知 valuation_result 缺字段或语义错误必须报错，不能落入 GenericChartDataset。
+
+历史 v1.4 及更早版本允许保存未知自定义图型；其中若已存在名为 valuation_result 的自定义数据，应按旧版合同原样保留，不能追溯强套新模型。旧作者对象添加新的强类型 ValuationResultChartDataset 必须报版本错误。将历史文档改成 v1.5 前，必须显式转换同名自定义数据；只改 schemaVersion 应拒绝。
+
+公开 API：`ValuationResultChartDataset`、`ValuationPoint`、`ValuationRange`、`ValuationAmount`；helper：`valuation_result_chart_dataset(...)`、`valuation_point(value)`、`valuation_range(low, high)`。helper 使用 snake_case 参数，输出使用本节 camelCase 字段。模型、版本边界、整文档校验、引用及 JSON 往返均须验证。
+
+完整示例见 [v1.5 JSON](docs/protocol/v1.5-example.json)，Python 创建与渲染接入说明见 [使用指南](docs/PYTHON_V15.md)。SDK 生成和校验通过，不代表任何现有编辑器或渲染器已经实现横幅。
+
+## v1.5 更新说明（相对于 v1.4）
+
+- 新增 valuation_result 原生结果横幅，支持点估值和区间估值、明确的币种单位、显示倍率、估值口径及基准日。
+- v1.4 的十种图型和组合能力保持不变；现为十一种正式图型。
+- 新增 report.v1.5 版本边界；不隐式升级旧文档、不静默降级新图。
+
 ## v1.4 更新说明（相对于 v1.3）
 
 - 新增 timeline、stage_progress、flow、funnel、range 五种图型；完整字段和约束见第 21 节。

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/README.md

@@ -1,9 +1,9 @@
 # OVAPortableText
 
-> Python **0.5.0** 已实现 [`report.v1.4`](PROTOCOL.md) 的生成、读取和校验，默认新建 v1.4 文档并兼容读取 v1.3。新增五种图表、共享图表语义和组合 `figure`。见 [新版使用指南](docs/PYTHON_V14.md) 与 [完整 Python 示例](examples/v14_report.py)。渲染效果由下游渲染器独立验收。
+> Python **0.6.0** 已实现 [`report.v1.5`](PROTOCOL.md)，新增 `valuation_result` 原生估值结果横幅。支持单值/区间、币种、估值口径、投前/投后、基准日及显示倍率；默认新建 v1.5，兼容旧版本。见 [v1.5 使用指南](docs/PYTHON_V15.md) 与 [可运行示例](examples/v15_valuation_result.py)。渲染端需独立实现横幅。
 
-**OVAPortableText** is a Python authoring package for building JSON documents that conform to the **OVA Report Profile v1.4** protocol.
-**OVAPortableText** 是一个 Python 端的协议生成包，用于创建符合 **OVA Report Profile v1.4** 协议的 JSON 文档。
+**OVAPortableText** is a Python authoring package for building JSON documents that conform to the **OVA Report Profile v1.5** protocol.
+**OVAPortableText** 是一个 Python 端的协议生成包，用于创建符合 **OVA Report Profile v1.5** 协议的 JSON 文档。
 
 It is **not** a PDF renderer. Its job is to help Python code produce a typed, validated, protocol-aligned document payload that can be handed off to a downstream renderer.  
 它**不是** PDF 渲染器。它的职责是帮助 Python 代码以强类型、可校验、可维护的方式生成协议 JSON，再交给下游渲染器处理。

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/docs/API_REFERENCE.md

@@ -1,7 +1,7 @@
 # API Reference / API 参考
 
-This page is a practical map of the public API in OVAPortableText `v0.5.0`, aligned to `report.v1.4`.
-本文档是 OVAPortableText `v0.5.0` 的实用 API 地图，对齐 `report.v1.4`。
+This page is a practical map of the public API in OVAPortableText `v0.6.0`, aligned to `report.v1.5`.
+本文档是 OVAPortableText `v0.6.0` 的实用 API 地图，对齐 `report.v1.5`。
 
 ---
 
@@ -17,7 +17,7 @@ This page is a practical map of the public API in OVAPortableText `v0.5.0`, alig
 
 Default schema version:
 
-- `Document.schemaVersion == "report.v1.4"`
+- `Document.schemaVersion == "report.v1.5"`
 
 Common arguments / 常用参数：
 
@@ -385,3 +385,7 @@ Use the resolver when you need to inspect what is globally addressable in the do
 ## v1.4 additions
 
 See [Python v1.4 guide](PYTHON_V14.md) for the new typed models, helpers, version gates, figure captions, and `validate_document_payload`.
+
+## v1.5 valuation_result
+
+Python 0.6.0 adds native valuation-result banners and defaults to report.v1.5. Explicit report.v1.4 remains supported. See [v1.5 guide](PYTHON_V15.md) for typed amounts, base currency units, helpers and the renderer contract.

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/docs/PROTOCOL_ALIGNMENT.md

@@ -1,7 +1,7 @@
 # Protocol Alignment / 协议对齐说明
 
-This page describes OVAPortableText 0.5.0, aligned to Report Profile v1.4.
-本文档说明 Python 包 0.5.0 的协议能力。新增图表、共享语义和 figure 的生成、读取与校验已实现；新建文档默认 report.v1.4，读取 v1.3 保留原版本。见 [v1.4 使用指南](PYTHON_V14.md)。渲染端独立验收。
+This page describes OVAPortableText 0.6.0, aligned to Report Profile v1.5.
+本文档说明 Python 包 0.6.0 的协议能力。新增图表、共享语义和 figure 的生成、读取与校验已实现；新建文档默认 report.v1.5，读取旧版本保留原版本。估值横幅见 [v1.5 使用指南](PYTHON_V15.md)，其余图表见 [v1.4 指南](PYTHON_V14.md)。渲染端独立验收。
 
 ---
 
@@ -20,8 +20,8 @@ The package aligns to this top-level shape:
 - `glossary`
 - `sections`
 
-`schemaVersion` defaults to `report.v1.4`.
-`schemaVersion` 默认值为 `report.v1.4`。
+`schemaVersion` defaults to `report.v1.5`.
+`schemaVersion` 默认值为 `report.v1.5`。
 
 ---
 
@@ -192,3 +192,7 @@ The package should be understood as:
 - 已知图型明确分发，版本门控、旧自定义类型保留；无自动图型或图片降级。
 
 范围不包含误差棒／中心连线、图形布局算法、PDF 输出或渲染能力协商。所有渲染器仍需按正式协议完整呈现声明的语义。
+
+## v1.5 valuation_result
+
+Python 0.6.0 adds native valuation-result banners and defaults to report.v1.5. Explicit report.v1.4 remains supported. See [v1.5 guide](PYTHON_V15.md) for typed amounts, base currency units, helpers and the renderer contract.

ovaportabletext-0.6.0/docs/PYTHON_V15.md

@@ -0,0 +1,65 @@
+# Python 0.6.0 / report.v1.5：估值结果横幅
+
+`valuation_result` 是正式 chartType，面向标题、估值主值和上下文三层布局。原来的单格 grid 卡片仍合法；需要原生估值横幅时显式切换到本类型。包生成 JSON，不绘制图片。
+
+```bash
+python -m pip install --upgrade "OVAPortableText==0.6.0"
+```
+
+```python
+import ova_portable_text as o
+
+report = o.create_document(title="Valuation report", language="en")
+chart = o.valuation_result_chart_dataset(
+    id="valuation-result",
+    subject={"en": "Clean Food Group Limited"},
+    title={"en": "Valuation range"},
+    valuation=o.valuation_range(20_100_000, 28_400_000),
+    currency="GBP",
+    value_basis="equity_value",
+    capital_basis="pre_money",
+    as_of="2026-08-05",
+    data_basis="illustrative",
+    display_scale="million",
+    display_precision=1,
+    notes={"en": "Illustrative design sample."},
+)
+report.add_chart_dataset(chart)
+section = report.new_section(id="summary", level=1, title="Summary")
+section.append_to_last_content(o.ChartBlock(id="result-banner", chartRef=chart.id))
+report.validate().raise_for_errors()
+report.save_json("valuation_result.json")
+```
+
+渲染主值为 `£20.1m – £28.4m`；必须保留主体、股权价值口径、投前属性、GBP、基准日及示例提示。主值放大、居中、深蓝背景等由渲染器实现；不要添加 `backgroundColor` 等非协议字段。
+
+## 两种金额结构
+
+- 区间：`o.valuation_range(low, high)`，有限数值，low <= high；允许相等、零及负值。
+- 单值：`o.valuation_point(value)`，不会自动推断区间。
+
+金额始终按 GBP、USD 等基本货币单位存储。`display_scale="million"` 仅在显示时除以百万；不是说输入 20.1 就表示 20.1m。display_precision 为整数 0…6；舍入不能隐藏非零值或把不同端点合并为一个值。
+
+`value_basis` 必填：equity_value / enterprise_value / asset_value。`capital_basis` 只有股权价值允许 pre_money / post_money。未声明投前/投后时省略，不要默认为投前。
+
+`as_of` 为完整公历日期，`data_basis` 必填 evidence_based 或 illustrative。SDK 不验证业务证据真伪。可选 title、notes、subject 采用多语言字典；显式 null 不合法，helper 会省略其默认 None。
+
+## 模型与引用
+
+`ValuationResultChartDataset` 输出与 helper 相同，直接模型使用 `valueBasis / capitalBasis / asOf / dataBasis / displayScale / displayPrecision`。嵌套模型为 `ValuationPoint`、`ValuationRange`，联合别名 `ValuationAmount` 使用 kind 判别。
+
+图表位于 datasets.charts；正文使用 ChartBlock，组合布局可以在 GridTableCell.blocks 放匿名 ChartBlock。需要图注时使用 `append_chart_with_caption`；不需要额外 FigureBlock 或图注。单个类型只表达一个主体的一项估值结论，多方法区间比较继续使用 range。
+
+## 兼容与错误处理
+
+默认 schemaVersion 是 report.v1.5；`create_document(schema_version="report.v1.4")` 仍可生成旧文档。新版包读取旧文件后保留原 schemaVersion。给旧作者对象添加新强类型横幅会报错，不自动升级。
+
+历史 v1.4 或更早文件中曾存在的同名自定义图型继续原样保留。若改为 v1.5，必须先显式构建新强类型结构，不能只改版本号。v1.5 已知图型的缺字段、非法枚举、逆序金额等不会回退为 GenericChartDataset。
+
+`report.validate()` 会重新检查已修改的 builder 对象、金额语义、版本与引用；发布前必须调用。金额、日期、字段和版本错误可由 `validate_document_payload` 转成结构化诊断。
+
+## 渲染器验收
+
+按 [正式协议第 22 节](../PROTOCOL.md#22-v15-valuation_result-估值结果横幅) 实现三层横幅。覆盖点值、范围、负值、零值、相等端点、长公司名、两种语言、不同倍率、舍入边界、无投前/投后属性及 notes。拒绝未知能力，不静默转为图片或文字。包单元测试不代表渲染器截图测试已通过。
+
+完整示例：[Python](../examples/v15_valuation_result.py) / [JSON](protocol/v1.5-example.json)。v1.4 的旧指南和旧样例保持历史用途。

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/docs/QUICKSTART.md

@@ -188,4 +188,8 @@ restored.assert_valid()
 
 ## v1.4 图表与组合图
 
-新建文档默认 report.v1.4。新增图型和组合图用法见 [新版使用指南](PYTHON_V14.md) 和 [可执行示例](../examples/v14_report.py)。
+新建文档默认 report.v1.5。新增图型和组合图用法见 [新版使用指南](PYTHON_V14.md) 和 [可执行示例](../examples/v14_report.py)。
+
+## v1.5 valuation_result
+
+Python 0.6.0 adds native valuation-result banners and defaults to report.v1.5. Explicit report.v1.4 remains supported. See [v1.5 guide](PYTHON_V15.md) for typed amounts, base currency units, helpers and the renderer contract.

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/docs/protocol/v1.4-draft.md

@@ -1,9 +1,9 @@
 # OVA Portable Text v1.4 协议设计草稿
 
-状态：历史设计记录（Draft 04）。v1.4 已正式冻结，请以 [v1.4 正式协议](v1.4.md) 为准；以下保留当时的提案与决策过程。  
-日期：2026-09-21。  
-目标 SDK：OVAPortableText 0.5.0。  
-目标协议：`report.v1.4`。  
+状态：历史设计记录（Draft 04）。v1.4 已正式冻结，请以 [v1.4 正式协议](v1.4.md) 为准；以下保留当时的提案与决策过程。
+日期：2026-09-21。
+目标 SDK：OVAPortableText 0.5.0。
+目标协议：`report.v1.4`。
 基线：[v1.3 正式协议](v1.3.md)。
 
 ## 1. 目标与边界

{ovaportabletext-0.5.0 → ovaportabletext-0.6.0}/docs/protocol/v1.4-freeze.md

@@ -3,7 +3,7 @@
 状态：正式协议已冻结。
 日期：2026-09-21。
 开发分支：dev-v0.5.0。
-冻结交付：协议、规范示例和实现边界。后续 Python 0.5.0 已在本分支实现并构建，本地交付不等于已发布到包索引。
+冻结交付：协议、规范示例和实现边界。后续 Python 0.5.0 已在本分支实现，并通过 TestPyPI 验收后发布到正式 PyPI。
 
 ## 规范文件
 
@@ -39,7 +39,7 @@
 | --- | --- |
 | report.v1.4 字段与语义合同 | 已冻结 |
 | Python 包 | 0.5.0，默认 report.v1.4；已实现图表模型、语义校验和组合 figure |
-| 发布状态 | 本地构建与验收，不执行包索引发布 |
+| 发布状态 | 已发布 [PyPI 0.5.0](https://pypi.org/project/OVAPortableText/0.5.0/)，正式索引安装验证通过 |
 | 编辑器／正式报告渲染器 | 不因协议冻结自动升级，需独立验收 |
 | 本地报告设计材料 | 继续被 Git 忽略，不纳入示例或发布内容 |
 
@@ -66,6 +66,6 @@ Python 0.5.0 实施清单（1–4 已实现；第 5 项属于下游验收）：
 4. 同步 API 文档、包版本和 schema 默认值，再构建包供新报告生成端使用。
 5. 单独协调下游渲染能力；正式报告不允许静默丢图或改变关键语义。
 
-本次不执行提交、推送或发布；保留工作区结果供后续开发。
+后续发布验收：188 项测试和 17 个 Python 示例通过；TestPyPI 与正式 PyPI 的 wheel、sdist 哈希均与验收产物一致。本地报告设计材料未包含在发布产物中。
 
 Python 交付用法与具体边界见 [新版使用指南](../PYTHON_V14.md)。上面的“本次检查结果”记录协议冻结当时的状态，SDK 验收以仓库测试及构建结果为准。

ovaportabletext-0.6.0/docs/protocol/v1.5-example.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": "report.v1.5",
+  "meta": {
+    "title": "Valuation result",
+    "language": "en"
+  },
+  "theme": {
+    "blockStyleDefaults": {}
+  },
+  "assets": {
+    "images": [],
+    "logos": [],
+    "backgrounds": [],
+    "icons": [],
+    "attachments": []
+  },
+  "datasets": {
+    "charts": [
+      {
+        "id": "valuation-result",
+        "anchor": "valuation-result",
+        "meta": {},
+        "chartType": "valuation_result",
+        "subject": {
+          "en": "Clean Food Group Limited"
+        },
+        "valuation": {
+          "kind": "range",
+          "low": 20100000,
+          "high": 28400000
+        },
+        "currency": "GBP",
+        "valueBasis": "equity_value",
+        "asOf": "2026-08-05",
+        "dataBasis": "illustrative",
+        "capitalBasis": "pre_money",
+        "title": {
+          "en": "Valuation range"
+        },
+        "notes": {
+          "en": "Illustrative design sample; not an independently verified valuation."
+        },
+        "displayScale": "million",
+        "displayPrecision": 1
+      }
+    ],
+    "tables": [],
+    "metrics": []
+  },
+  "bibliography": [],
+  "footnotes": [],
+  "glossary": [],
+  "sections": [
+    {
+      "id": "summary",
+      "level": 1,
+      "title": "Valuation conclusion",
+      "numbering": "auto",
+      "anchor": "summary",
+      "body": [
+        {
+          "itemType": "content",
+          "blocks": [
+            {
+              "id": "valuation-banner",
+              "anchor": "valuation-banner",
+              "_type": "chart",
+              "chartRef": "valuation-result"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

ovaportabletext-0.6.0/docs/protocol/v1.5-freeze.md

@@ -0,0 +1,25 @@
+# Report Profile v1.5 冻结记录
+
+冻结日期：2026-09-27。实现分支：dev-v0.6.0。配套 Python 版本：0.6.0。
+
+- [正式协议归档](v1.5.md)：完整继承 v1.4，第 22 节新增 valuation_result。
+- [规范 JSON 示例](v1.5-example.json)：原生估值结果横幅，包含可见示例提示所需数据。
+- [Python 指南](../PYTHON_V15.md) / [可执行示例](../../examples/v15_valuation_result.py)。
+- v1.4 归档及既有结构保持不变；新文档默认 v1.5，旧文档不隐式升级。
+
+## 冻结决定
+
+1. 使用正式 chartType=valuation_result，复用 ChartBlock 和 grid 引用，不新增正文块。
+2. 金额必须结构化，kind 为 point 或 range；货币基本单位与显示倍率明确分离。
+3. 主体、币种、估值口径、基准日期和数据性质必填；投前/投后仅适用于股权价值。
+4. 颜色、字号和边距由渲染器模板负责；三层横幅及语义显示要求是正式合同。
+5. 不支持的渲染器必须明确失败；不将图片/普通文本回退声明为原生支持。
+6. 历史同名自定义数据按原版本保留，升级时必须显式转换。
+
+## SDK 验收
+
+- 241 项测试通过，包括 53 项新增估值、版本边界、错误路径与往返测试。
+- 18 个 Python 示例及 v1.5 使用指南代码通过。
+- 发行 wheel 在干净环境及最低声明依赖 Pydantic 2.8.0 下，241 项测试通过。
+- 构建与发布遵循仓库发布清单：wheel/sdist、元数据、干净环境、TestPyPI、正式 PyPI。
+- 本记录是协议与 SDK 冻结记录，不声称下游编辑器/渲染器已实现或通过截图验收。