105 lines
5.7 KiB
Markdown
105 lines
5.7 KiB
Markdown
|
# 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 改法的替代关系，容易让新读者以为这是唯一的解决方案。加上缺少复现前提条件和验收标准，文档的可操作性低于其技术分析水平。
|