feat: 增加评审文档机器投影与 JSON 报告

2026-08-28 14:23:30 +08:00
parent dd012f4905
commit 843952b194
7 changed files with 2096 additions and 16 deletions
@@ -16,10 +16,11 @@
              │  验证并重放，不运行 Modifier
              ▼
        ReviewDocument
-          │          │
-          │          └── render_markdown_report() ──► 内存 Markdown 字符串
-          ▼
-    项目自己的界面或转换层
+          ├── render_markdown_report() ─────────────► 内存 Markdown 字符串
+          │
+          └── review_document_to_dict(detail=...)
+                         ├───────────────────────────► 项目自己的界面或转换层
+                         └── render_json_report() ──► 内存 JSON 字符串
 ```

 文件读取、保存位置、HTML 页面、权限和审核流程仍由调用项目决定。
@@ -85,3 +86,30 @@ span 和修改前后长度，不重复输出 `expected_text`、`replacement` 或
 报告有意包含完整文档、实际修改的 `before` / `after` 和 diff，可能还原敏感内容。库不会自动打印、保存、上传或缓存
 报告；持久化后的路径、访问权限、脱敏和保留周期属于调用项目。每个阶段保存完整前后快照，当前实现优先保证可复核性，
 没有声称适合无限长度文档或无限修改器链。
+
+## 6. 机器投影为什么不是 `dataclasses.asdict()`
+
+`review_document_to_dict()` 是 `ReviewDocument` 的单向公共视图，不是内部 dataclass 的机械展开。它显式转换 enum、tuple、
+modifier 参数、位置和哈希，并在根对象写入 `schema_name=mdpolish.review` 与独立的 `schema_version=1.0`。这样内部 Python
+结构可以在不改变 schema 的前提下重构，调用项目也不需要猜测 enum、数组和阶段坐标。
+
+投影有三个内容等级：
+
+| detail | 增加的内容 |
+| --- | --- |
+| `summary` | 状态、哈希、计数、modifier 身份、阶段摘要和稳定错误代码；默认不含正文承载字段 |
+| `changes` | modifier 参数和适用说明、实际修改片段、错误诊断、残留候选片段 |
+| `full` | 完整输入、当前全文和每个完整阶段的前后全文 |
+
+高等级只增加字段，不改变低等级已有字段的值和顺序。被 detail 隐藏的字段直接不存在，不使用 `null` 或空字符串假装隐藏，
+因此空文档在 `full` 中仍能明确表示为 `markdown: ""`。
+
+`summary` 不含正文，但仍包含 modifier identity、哈希和计数，只能称为“无正文投影”，不能称为脱敏或公开安全日志。
+`changes` 和 `full` 都可能还原敏感内容；库不会自动打印、保存或发送任何投影。
+
+`render_json_report()` 只把同 detail 的正式 dict 投影用标准 JSON 编码，不维护第二套字段。它返回内存字符串，使用 Unicode、
+拒绝 NaN / Infinity，不写文件或添加 BOM。Markdown reporter 继续直接读取 `ReviewDocument`：它面向人类排版并包含 diff、
+动态围栏和 residual 展示限额，不依赖机器 schema。
+
+机器投影只生产，不提供 JSON 到 `ReviewDocument` 的反序列化，也不能用于重新应用修改。完整字段、坐标、错误代码和兼容规则
+见 [`review-projection-schema-v1.md`](../reference/review-projection-schema-v1.md)。