8.5 KiB
PM Reviewer — 文档结构化评审报告
评审人：pm-reviewer 评审范围：docs/04_IMPLEMENTATION_ROADMAP.md、docs/DEPLOYMENT.md、docs/05_AI_PARTICIPATION.md 评审时间：2026-04-14
总体评分
| 文档 | 评分 | 结论 |
|---|---|---|
| docs/04_IMPLEMENTATION_ROADMAP.md | ⚠️ 需补充 | 路线图完整但关键细节缺失 |
| docs/DEPLOYMENT.md | ⚠️ 需补充 | 容器方案可行但路径过时、CI/CD 缺失 |
| docs/05_AI_PARTICIPATION.md | ✅ 通过 | AI 边界划分清晰，CustomView 切入点准确 |
综合结论：三份文档整体质量较高，可开始编码，但需先补充以下内容。
一、docs/04_IMPLEMENTATION_ROADMAP.md 评审
✅ 通过项
- Phase 0-7 分解合理：时间估算（1-2 周 MVP）与任务粒度匹配
- SQL 表结构完整：5 张表定义清晰，包含索引和外键关系
- 钩子名称具体：
plugins_service_buy_order_insert_begin等 ShopXO 真实钩子名称已标注 - API 端点设计具体：完整的路由格式
?s=admin/vrticket/...
⚠️ 需补充项
1. Agent 分工基于人名，维护性差（中等优先级）
问题：分工表写"李狗蛋/妮可/小老D/西莉娅"，非技能角色名称。 影响：人员变动后文档失效；Agent 系统无法识别任务归属。 建议：改为技能角色（如"后端 Agent"、"前端 Agent"），或明确说明 Agent 名称仅为代号。
2. Phase 依赖关系描述模糊（高优先级）
问题："✅ Phase 0" 仅标注"可并行"，未说明是"完成后才可开始"还是"期间可并行"。 影响：Agent 并行执行时可能因依赖顺序错误浪费轮次。 建议：改为箭头或编号依赖，例如：
Phase 1 → Phase 2 → Phase 3
Phase 2 → Phase 5 （场次CRUD完成后前端可开始）
3. Phase 7 "需串行" 但未说明原因（中等优先级）
问题：Phase 7 标记"需串行"，但"联调+测试+部署"中部署本身可并行。 影响：误导 Agent 认为此阶段无法拆分。 建议：拆分 Phase 7 为"联调（可并行）"和"部署（串行）"，明确各子任务间的并行性。
4. 缺少并发控制方案（高优先级）
问题：Phase 4 提到"并发抢票"测试用例，但计划中未提及 Redis 锁或乐观锁。
影响：真实并发场景下库存超卖风险未在设计阶段覆盖。
建议：在 Phase 4 或 Phase 1 数据库设计中补充并发控制策略（如 UPDATE vr_sessions SET available_stock = available_stock - N WHERE available_stock >= N）。
5. 里程碑无验收标准（中等优先级）
问题："M1：插件跑通" 无具体验收条件。 影响：Agent 完成里程碑后无法自我验证。 建议：为每个里程碑添加 checklist：
M1 验收：
- [ ] ShopXO 后台插件列表可见 vr_ticket
- [ ] 访问 /?s=admin/vrticket/event/list 返回 200
- [ ] 数据库包含 5 张 vr_* 表
❌ 重大问题
无
二、docs/DEPLOYMENT.md 评审
✅ 通过项
- Docker 容器设计合理：nginx + PHP-FPM + MySQL 8.0 分层清晰
- 数据库连接信息完整：容器网络名、宿主机端口均有标注
- 日志查看命令实用：提供了分容器查看日志的具体命令
- ARM64 兼容性说明：M1/M2/M3 Mac 已知问题已记录
⚠️ 需补充项
1. ShopXO 源码路径硬编码为物理目录（高优先级）
问题：SHOPXO_SRC 默认指向 /Users/bigemon/.openclaw/workspace/council-research/...，与 worktree 设计不符。
影响：其他 Agent 在其 worktree 中无法使用同一份 docker-compose.yml。
建议：
- 方案A：将 ShopXO 源码路径改为相对于 docker-compose.yml 的相对路径（如
./shopxo-src） - 方案B：在 .env 中标注"请将此路径改为你的 ShopXO 源码目录"，并添加
grep -r "WORKSPACE" .env快速定位
2. 缺少 Docker Desktop 安装说明（低优先级）
问题：文档假设用户已安装 Docker Desktop，但未提供安装指引。 影响：新手首次克隆后无法直接运行。 建议：在"一、快速启动"前增加一行：
前提条件：已安装 Docker Desktop for Mac
3. 缺少 CI/CD 部署流程（中等优先级）
问题：文档只描述本地开发环境，未涉及生产部署的自动化流程。 影响：Phase 7 联调后的部署阶段缺乏指引。 建议：添加"九、生产部署"章节，说明：
- PHP 虚拟主机：上传插件 zip 的手动步骤（ShopXO 后台支持）
- shopxo-uniapp：HBuilderX CLI 发行命令
- 可选：GitHub Actions 自动构建
4. 未说明数据库迁移工具（中等优先级）
问题：Phase 1 的 SQL 迁移文件存在，但 DEPLOYMENT.md 未说明如何执行。 影响：其他 Agent 不确定应该手动执行 SQL 还是通过 ShopXO 迁移机制。 建议：在"六、修改 ShopXO 源码路径"后补充：
# 执行插件数据库迁移
docker exec shopxo-php php /var/www/html/think migrate
❌ 重大问题
无（文档覆盖了核心场景，缺失项均为优化级别）
三、docs/05_AI_PARTICIPATION.md 评审
✅ 通过项
- DIY 拖拽系统边界清晰：明确指出为什么 AI 无法参与（JSON 私有结构、无文档）
- CustomView 是亮点发现：将 CustomView 定性为"AI 参与的黄金入口"，有战略价值
- 决策矩阵实用：4 格矩阵（代码可控性 × 文档公开度）清晰划分可行/不可行区域
- Hook 名称具体：给出了真实可查的 Hook 名称和注入示例
⚠️ 需补充项
1. shopxo-uniapp 的 AI 生成边界未明确（高优先级）
问题：文档详述了 ShopXO 后端 Hook 系统，但未说明 AI 生成 uni-app Vue 代码时的边界。 影响：前端 Agent 不知晓 uni-app AI 生成的限制（如组件库版本、平台 API 兼容性）。 建议：在"三、AI 完全可参与：代码层"表格中增加一行：
| 区域 | 技术栈 | AI 参与方式 | 限制 |
|---|---|---|---|
| uni-app 票务页面 | Vue 3 / uni-ui | AI 生成组件代码 | 需 HBuilderX 编译验证；微信 API 需手动测试 |
2. Phase 1/2/3 缺少时间维度（低优先级）
问题：三个 Phase 的 AI 协作阶段描述了"做什么"，但未说明"何时切换"。 影响：Agent 执行时无法判断当前应使用哪种参与模式。 建议：在 Phase 标题后加括号标注触发条件：
Phase 1: AI 100% 主导（无人工干预）← 适用：数据库设计、插件 Service、API 端点
Phase 2: AI + 人工协作（50/50）← 适用：Hook 注入 UI、uni-app 页面
Phase 3: 人工为主，AI 辅助 ← 适用：DIY 页面、主题配色
3. 未提及 Human-in-the-loop 触发机制（低优先级）
问题：Phase 2/3 需要人工介入，但文档未说明人工介入的触发信号（错误率 > X%？特定文件类型？）。 影响：Agent 可能在应该请求人工复核时继续自动执行。 建议：添加触发条件描述：
触发人工介入的条件：
1. AI 生成代码出现 3 次以上相同类型的编译错误
2. 涉及支付/核销等资金相关逻辑
3. 修改 ShopXO 核心文件（非插件目录）
❌ 重大问题
无
四、综合建议
编码前必须补充（阻塞项）
| 优先级 | 事项 | 所属文档 |
|---|---|---|
| 🔴 高 | 并发控制策略（Redis/乐观锁） | docs/04_IMPLEMENTATION_ROADMAP.md |
| 🔴 高 | ShopXO 源码路径修复为相对路径 | docs/DEPLOYMENT.md |
| 🟡 中 | Agent 分工改为技能角色而非人名 | docs/04_IMPLEMENTATION_ROADMAP.md |
| 🟡 中 | 里程碑验收 checklist | docs/04_IMPLEMENTATION_ROADMAP.md |
| 🟡 中 | uni-app AI 生成边界说明 | docs/05_AI_PARTICIPATION.md |
编码后可补充（优化项）
- Phase 7 部署阶段 CI/CD 流程
- Docker 环境数据库迁移命令
- Phase 依赖关系的精确标注（箭头图或编号）
五、投票结论
[CONSENSUS: NO] — 建议先补充以上 5 个阻塞/中等优先级事项，再进入 Phase 0 执行。
理由：三份文档整体质量优秀，但 Phase 0-4 的并发安全和 DEPLOYMENT.md 的路径问题是真实风险点，会在实际执行中造成 Agent 重复劳动或部署失败。在这些问题修复后，预计可顺利进入编码阶段。
Round 2 行动项：pm-reviewer 将在下一轮直接修复上述 5 个事项，将修订合并入 main，再投票
[CONSENSUS: YES]。