04-开发-图文出图后目视复核与SVG渲染缺陷排查法
> 阶段：04 开发（流程）｜版本 v1.0｜固化日期 2026-10-25
> 一句话：渲染管线 0 报错 ≠ 图是对的；转 DOCX 之前必须逐张目视复核，缺陷一旦进 docx 返工成本成倍。
分工边界
- 本包管：图渲染出来之后的质量校验（目视复核 + 三类缺陷排查 + 文本转义）。
- 04-开发-文件存储规则图文版制作SOP 管：图文版怎么做出来（管线、排版、落点与版本）。
- 02-技术-docx图文手册纯标准库增量改写法 管：docx 侧改写；本包是它的前置质量闸门。
一、操作步骤
- 先接受一个前提：渲染成功只是及格线。
resvg不报错，图照样可能是错的。
锚点：.workbuddy/memory/2026-10-06.mdL286（4 图全部「渲染成功」，目视后仍发现 3 处缺陷）。 - 逐张目视：把 PNG 逐张打开看，不能只看生成日志。本项目实测靠这一步拦下三类缺陷。
- 三类必查项（按出现频率排序）：
- ① 超宽/截断：结论行、注释行文字超viewBox宽度被裁掉 → 拆行或加宽 viewBox。
- ② SVG 内混入 HTML 标签：<b>/<div>在 SVG 里不渲染，会显示成字面量 → 全部清掉，目标 4 图 0 残留。
- ③ 坐标碰撞：数值标签 y 与标题 y 过近（如 99 分柱标签 y=24 撞标题 y=28）→ 整体下移留白、标签移入柱内。 - 机制化兜底自查（目视之外再补一道）：
- 在 SVG 源码里检索 HTML 标签残留（<b>、<div>、<span>），要求计数 0；
- 比对text元素的x+ 估算宽度是否超出viewBox宽度；
- 检索相邻y值差 < 8 的文本对（疑似碰撞）。 - 文本转义：正文含
<>&必须写成&lt;&gt;&amp;，否则 lxml 会当真实标签吞掉。
锚点：.workbuddy/memory/2026-10-05.mdL315（未转义<div ...>被吞）。 - 路径写法：Windows 反斜杠路径进 lxml 会报
strings must be XML compatible→ 改成正斜杠。
锚点：.workbuddy/memory/2026-10-04.mdL325。 - 修完重渲并重看：确认旧缺陷消失且未引入新问题（如标签下移后是否撞到柱体/轴）。
- 缺陷清完再转 DOCX：一旦进 docx，改一处要重渲整套图 + 重排全文。
二、注意边界
- SVG 必须 inline 具体色值：resvg 不解析 CSS
var()，currentColor之类同样不可靠。 - 中文字体统一
SimHei，箭头要有marker定义，否则渲染后箭头缺失。 - 目视复核的对象是最终 PNG，不是 SVG 源码——源码看着对，渲染后可能错位。
- 图形中间产物（
*_fig）不进正式资料目录，复核完按既有规则归位。 - 本包只做「看与改」，不改动业务数据、不重启服务。
三、反例避雷
- ✗ 渲染成功就跳过目视 → 2026-10-06 HL V2.1 四张图「全渲染成功」，目视后仍发现 3 处缺陷；
若不目视就直接进 docx，缺陷会随 410KB 报告一起交付。 - ✗ SVG 里写 HTML 标签 →
<b>不渲染、直接显示字面量，图上出现「<b>闭环</b>」这类脏文本。 - ✗ 标签 y 与标题 y 贴太近 → 视觉撞车，主次不分（99 分柱标签 y=24 vs 标题 y=28）。
- ✗ 正文写未转义的尖括号 → lxml 当标签吞掉，段落内容凭空消失且不报错。
- ✗ docx 正文里写反斜杠路径 →
strings must be XML compatible直接崩在 save 前（好在未落盘）。
四、代码锚点 / 实战战绩
锚点
- .workbuddy/memory/2026-10-06.md L286（出图后目视复核，发现并修 3 处渲染缺陷）
- .workbuddy/memory/2026-10-05.md L315（<div> 未转义被 lxml 吞掉）
- .workbuddy/memory/2026-10-04.md L325（反斜杠路径触发 XML compatible 报错 → 改正斜杠）
- 程序源代码/tools/build_graphic_docx.py（venv：python-docx + lxml + resvg_py，SVG→PNG→DOCX）
战绩
- 2026-10-06 HL 功能齐全性 V2.1：4 图重绘后目视，拦下并修复 ①结论行超宽截断 ②4 图 <b> 残留清零
③图 3 柱标签下移（viewBox 380、标签移入柱内）；修完重渲确认无新缺陷，报告评分条 120/120。
- 2026-10-04《程序开发文档存储规则》同步：反斜杠改正斜杠后 save 成功，段落 65→68。
- 附包体检器 scripts/svg_render_review_check.py：对含「目视 + 三类缺陷」的记录 PASS；
对只写「渲染成功/全部通过」的记录 FAIL。
五、关联笔记
04-开发-文件存储规则图文版制作SOP：制作流程，本包是它的收尾质检。00-总纲-版本纪律规则：图改完对应的 docx 要同步升版，旧版按规则处置。02-技术-Word文档纯标准库读写与备份法：docx 侧改写与备份。
六、版本记录
- v1.0（2026-10-25）：首版。由 2026-10-04 / 10-05 / 10-06 三次「渲染成功但图是错的」事件抽象，
含三类必查缺陷、两道转义红线与机制化兜底自查三则。
七、适用场景（回溯标注）
- 图文报告 / 手册 / 测评报告出图后、转 DOCX 之前的固定质检环节；也适用于任何「机器说成功、人没看过」的图形交付。
