6.9 KiB
文档评审综合报告
评估时间：2026-04-20 | 评估人：council/Architect 评审范围：docs/14_TEMPLATE_RENDER_INVESTIGATION.md、docs/PHASE2_PLAN.md、docs/DEVELOPMENT_LOG.md（十一、十二章）
各文档评分汇总
| 文档 | 准确性 | 完整性 | 可操作性 | 一致性 | 综合 |
|---|---|---|---|---|---|
| docs/14_TEMPLATE_RENDER_INVESTIGATION.md | 7/10 | 6/10 | 8/10 | 8/10 | 7.3 |
| docs/PHASE2_PLAN.md | 7/10 | 7/10 | 7/10 | 8/10 | 7.3 |
| docs/DEVELOPMENT_LOG.md（十一、十二章） | 6/10 | 7/10 | 7/10 | 5/10 | 6.3 |
Top 3 最需要修正的问题
🔴 问题 1：{include} 标签验证状态未闭环（高风险）
涉及文档：doc14（Section 2.1/4）、PHASE2_PLAN.md（Section 2）
问题描述：
doc14 在 Section 2.1 标题标注"✅ 已验证（已提交 7bd896764）"，Section 6 "关联提交"也声称代码已提交。但在 Section 4 模板渲染现状表格中，{include file="public/head"} 明确标注"⚠️ 待验证"，Section 5 列出了方向 A/B/C 作为待实测方案。PHASE2_PLAN.md Section 2 也将 {include} 解析列为"待实测项"。
核心矛盾：已提交 ≠ 已验证成功。这两件事被混淆在同一份文档里，读者无法判断票务商品详情页的 {include} 标签当前是否工作。
实际状态：根据 commit 7bd896764 的描述，该提交仅完成了" Goods.php 绝对路径方案 + SeatSkuService::GetGoodsViewData() + TicketService::onOrderPaid() 修复"，{include} 标签解析从未在容器内被实测验证。这是 Phase 2 当前最大的未闭环风险点。
修正建议：
- doc14 Section 2.1 标题的"✅ 已验证"改为"✅ 代码已提交（P0：容器内实测待完成）"
- Section 4 状态表格提升优先级标注：标记
{include}解析为 P0，而非普通"待验证"项 - 在 PHASE2_PLAN.md Section 3 Step 1 补充：执行 curl 之前必须先确认测试数据存在（goods_id=118 + 对应座位模板 + 场次 spec_base）
🔴 问题 2：DEVELOPMENT_LOG 存在两条未衔接的 Git 时间线（高风险）
涉及文档：docs/DEVELOPMENT_LOG.md
问题描述：
Chapter 8.1（"当前状态快照 2026-04-15"）记录 commit 历史截止 7508bed（Phase 0/1 完成）。Chapter 11（"Phase 2 前台展示层完成 2026-04-20"）直接引用 commit 7bd896764 作为当前 HEAD，但该 commit 未出现在 Chapter 8.1 的历史列表中。同时，Chapter 5.1 的 Goods.php 代码示例（Phase 1 版本）与 doc14 Section 2.1（Phase 2 最终版本）存在根本性差异（相对路径 vs 绝对路径），后者没有在 DEVELOPMENT_LOG 中记录。
风险：接手者无法从 DEVELOPMENT_LOG 独立重建"Phase 1 → Phase 2"的代码演进路径。Chapter 5.1 的 Goods.php 代码示例是已被替换的旧版本，但没有任何注释说明。
修正建议：
- 将 DEVELOPMENT_LOG 的 Git 历史合并为单一时间线，从
34f7045（Phase 0）到7bd896764（Phase 2 前台），在 Chapter 11.3 中补充完整的 commit 序列 - 在 Chapter 5.1 或新增 Chapter 10.5 中记录 Phase 1 → Phase 2 Goods.php 代码的演进原因（为什么从相对路径 MyView 改为绝对路径 View::fetch）
- 清理 Chapter 8.3 失效路径信息（
~/.openclaw/workspace/...），改为当前 vr-shopxo-plugin 的实际目录结构
🟡 问题 3：测试数据 goods_id 在四份文档中出现三个不同值（误导风险）
涉及文档：DEVELOPMENT_LOG.md（Chapter 4/5）、doc14（Section 1）、PHASE2_PLAN.md（Section 3 Step 1）
问题描述：
| 来源 | goods_id | 含义 |
|---|---|---|
| DEVELOPMENT_LOG Chapter 4 | 112 | Phase 0 测试数据："VR演唱会电子票 2024" |
| DEVELOPMENT_LOG Chapter 5.2 | 1 | Phase 1 URL 测试：id/1 |
| doc14 Section 1 | 118 | 调查对象 URL：id/118.html |
| PHASE2_PLAN.md Step 1 | 118 | Step 1 实测 URL：id/118.html |
没有任何文档解释：goods_id 112 和 118 是否是同一商品的不同 ID？goods_id=1 是什么商品？Phase 1 和 Phase 2 是否使用不同的测试商品？
风险：读者无法判断当前哪个 goods_id 是有效的测试入口，容易在调研过程中以错误的 ID 访问到不相关商品，进而对系统行为产生误判。
修正建议：
- 在 DEVELOPMENT_LOG Chapter 4 测试数据节中，明确列出所有 Phase 0-2 使用过的测试商品 ID 及其用途（如 goods_id=112 是 Phase 0 场次模板绑定测试商品，goods_id=118 是 Phase 2 票务详情页渲染测试商品）
- PHASE2_PLAN.md Step 1 补充"当前有效测试商品"清单（只保留 goods_id=118，标注为 Phase 2 唯一有效测试入口）
- 删除或标注 goods_id=1 的 Phase 1 测试记录（因为它与当前代码版本不对应）
次要问题（建议修复，但不阻塞）
| # | 问题 | 涉及文档 | 优先级 |
|---|---|---|---|
| A | spec_base_id_map JSON 结构未记录（座位图渲染核心字段） |
doc14 Section 2.2 | 高 |
| B | Step 4 核销 API 缺少认证/权限上下文 | PHASE2_PLAN.md Section 3 | 高 |
| C | vrt_vr_tickets.order_no 无 NOT NULL 约束，缺少空值防御 |
DEVELOPMENT_LOG Chapter 4 | 中 |
| D | "第十二章"在任务要求中出现但文档中不存在 | DEVELOPMENT_LOG.md | 中 |
| E | 决策点3（Layui 是否继续使用）已过时（后台已用 Layui） | PHASE2_PLAN.md Section 6 | 低 |
| F | doc14 Section 3.1 缺少根因总结（view_path 拼接错误） | doc14 Section 3.1 | 低 |
文档间一致性总览
| 检查项 | 状态 | 说明 |
|---|---|---|
| 表名前缀（vrt_vr_ vs sx_/sxo_） | ✅ 一致 | 插件表 vrt_vr_，ShopXO 原生平表 sxo_ |
commit 7bd896764 引用 |
✅ 一致 | 三份文档均引用 |
goods.vr_goods_config JSON 字段 |
✅ 一致 | 三份文档均正确 |
sxo_order_detail 表名 |
✅ 一致 | 三份文档均一致 |
| Goods.php 方法名（Index vs detail） | ❌ 不一致 | DEVELOPMENT_LOG 写 detail()，doc14 写 Index() |
| Goods.php 路径方案（相对 vs 绝对） | ❌ 不一致 | Phase 1 相对路径 vs Phase 2 绝对路径 |
| goods_id 测试数据 | ❌ 不一致 | 1 / 112 / 118 三个不同值 |
| Git 时间线 | ❌ 不一致 | Chapter 8.1 截止 Phase 1，Chapter 11 从 Phase 2 开始 |
总体结论
三份文档的修正意识值得肯定（doc14 修正说明表格、Chapter 11 清理记录），但在"已提交 vs 已验证"的闭环性、多时间线合并、以及测试数据的唯一性方面存在系统性问题。最紧迫的是立即在容器内实测 {include} 标签解析（Top 1），这是整个 Phase 2 前台展示层是否真正完成的关键验证节点；其次是整理 DEVELOPMENT_LOG 的时间线（Top 2），使项目历史可以被独立追溯；最后统一测试数据 goods_id（Top 3），避免后续开发者在错误的测试数据上浪费时间。