5.7 KiB
docs/14_TEMPLATE_RENDER_INVESTIGATION.md 评估报告
评审人：BackendArchitect | 日期：2026-04-20 | 版本：已修正版
准确性评分：7/10
问题 1：座位模板表名不一致（高）
第 2.2 节数据流第 3 步写道：
"从
vr_seat_templates表查询座位模板"
但 DEVELOPMENT_LOG.md 建表 SQL 中表名为 vrt_vr_seat_templates（有 vrt_ 前缀）。同一表名在三份文档中出现两种写法，极易误导。
问题 2：GetGoodsViewData 返回值字段名存疑
第 2.2 节数据流第 5 步写道返回字段含 vr_seat_template（单数），但第 2.1 节 Goods.php 代码示例中注入的是 vr_seat_template（注入给模板变量名）和 goods_spec_data（来自返回值）。Section 2.2 描述的返回值列表是 vr_seat_template（单数）而 section 2.1 代码里注入的也是 vr_seat_template，两者一致，但与 section 2.2 描述的返回值结构 ['vr_seat_template' => [...], 'goods_spec_data' => [...]] 吻合性需要代码核实。
问题 3：section 2.3 描述仍可能有歧义
onOrderPaid() 修复描述"映射到 ShopXO 原生平表 sxo_order_detail"——这里的"原生平表"说法不够精确。sxo_ 是本项目的表前缀约定，不是 ShopXO 官方命名。建议改为"本项目对应的订单明细表 sxo_order_detail"。
轻微问题：|raw 变量输出安全性未说明
第 3.2 节提及 {$vr_seat_template.seat_map|raw} 需要 |raw 过滤器，文档未说明这是否安全。如果 seat_map 内容完全由后台管理端控制（不可由用户输入），则 |raw 无安全风险，但应在文档中注明此前提条件。
完整性评分：6/10
缺失项 1：复现前提条件未说明
文档未说明分析环境：ShopXO 版本、PHP 版本、容器配置。如果接手者想复现问题，没有这些信息几乎不可能。
缺失项 2：ticket_detail.html 模板的实际路径未记录
附录中有路径 shopxo/app/plugins/vr_ticket/view/goods/ticket_detail.html，但未说明该文件是否已存在于哪个 commit 中，也未说明文件内容结构。
缺失项 3：Phase 1 和 Phase 2 改法的关系未说明
文档将 Phase 1 的 MyView('public/../../../plugins/...') 改法（第 5.1 节 DEVELOPMENT_LOG.md）和 Phase 2 的绝对路径 View::fetch($tplFile) 改法并列，但未说明两者是替代关系还是并存关系，容易造成混淆。
缺失项 4：P1 待解决问题无验收标准
P1 列了三个问题（{include} 标签、钩子、loadSoldSeats），但没有说明"解决成功"的标准是什么。例如：{include} 标签解析成功的判断依据是"HTML 源码中不再有 ThinkTemplate 原始标签"（见 PHASE2_PLAN.md），应在此文档中也明确记录。
可操作性评分：7/10
建议 1：方向 A/B/C 应给出决策树
第 5 章三个方向有优先级（方向 A 推荐），但没有给出决策条件。例如："若 {include} 失败"的判断标准是什么？返回 HTTP 500？页面空白？ThinkTemplate 原始标签？还是部分渲染？补充判断条件可以让接手者独立决策而不需要反复确认。
建议 2：docker 操作命令应内联在文档中
文档提到"容器内实测"但命令散布在 PHASE2_PLAN.md 中。建议在 docs/14 中直接包含 curl 命令和预期输出示例，让文档自包含。
优点：附录文件路径表实用
附录清晰列出了所有相关文件路径，这是文档中做得好的部分。
一致性评分：5/10
冲突项 1（严重）：vr_seat_templates 表名
| 文档 | 表名 |
|---|---|
| docs/14 第 2.2 节 | vr_seat_templates（无前缀） |
| docs/DEVELOPMENT_LOG.md 建表 SQL | vrt_vr_seat_templates（有 vrt_ 前缀） |
| docs/PHASE2_PLAN.md | vrt_vr_seat_templates（有前缀） |
三份文档中出现了两种命名，docs/14 是唯一使用无前缀版本的，需要修正。
冲突项 2：Goods.php 文件路径基准不一致
docs/14 附录写的是 shopxo/app/index/controller/Goods.php（以 shopxo/ 为项目根），但实际项目结构是 /Users/bigemon/WorkSpace/vr-shopxo-plugin/shopxo/（shopxo/ 是子目录）。这种写法在开发环境内是约定俗成，但文档中应明确注明。
误导风险评估
高风险项
误导 1：认为 ticket_detail.html 已经正常渲染
第 2.1 节 Goods.php 改动标注"状态：✅ 已提交（7bd896764）"，但 section 4 明确说 {include file="public/head"} 是"⚠️ 待验证"。已提交的代码不等于已验证的功能。接手者可能误认为票务商品页已经完全可用。
误导 2：phase 关系混淆
Phase 1 和 Phase 2 的 Goods.php 改法不同（MyView vs 绝对路径 View::fetch），但 docs/14 报告本身没有说明这是 Phase 2 的新改法，如果只读这一份文档会以为这是唯一的解决方案。
低风险项
docs/14 的"重要修正说明"（第 9-18 行）是一个很好的自我纠正机制，后续接手者可以看到哪些内容已被修正，降低了误信旧信息的风险。
总体评价
docs/14 是一份技术价值较高的调查文档，保留了完整的 ThinkTemplate 渲染机制分析、include 标签解析链路和 Linux 路径问题记录。最值得肯定的是"重要修正说明"章节，主动暴露了已知的错误。但核心问题是表名前缀不一致（vr_seat_templates vs vrt_vr_seat_templates），这是唯一出现在已修正说明之外的重大事实错误。此外，文档未说明 Phase 1/Phase 2 两套 Goods.php 改法的替代关系，容易让新读者以为这是唯一的解决方案。加上缺少复现前提条件和验收标准，文档的可操作性低于其技术分析水平。