# 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 评审

### ✅ 通过项

1. **Phase 0-7 分解合理**：时间估算（1-2 周 MVP）与任务粒度匹配
2. **SQL 表结构完整**：5 张表定义清晰，包含索引和外键关系
3. **钩子名称具体**：`plugins_service_buy_order_insert_begin` 等 ShopXO 真实钩子名称已标注
4. **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 评审

### ✅ 通过项

1. **Docker 容器设计合理**：nginx + PHP-FPM + MySQL 8.0 分层清晰
2. **数据库连接信息完整**：容器网络名、宿主机端口均有标注
3. **日志查看命令实用**：提供了分容器查看日志的具体命令
4. **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](https://www.docker.com/products/docker-desktop)

#### 3. 缺少 CI/CD 部署流程（中等优先级）
**问题**：文档只描述本地开发环境，未涉及生产部署的自动化流程。
**影响**：Phase 7 联调后的部署阶段缺乏指引。
**建议**：添加"九、生产部署"章节，说明：
- PHP 虚拟主机：上传插件 zip 的手动步骤（ShopXO 后台支持）
- shopxo-uniapp：HBuilderX CLI 发行命令
- 可选：GitHub Actions 自动构建

#### 4. 未说明数据库迁移工具（中等优先级）
**问题**：Phase 1 的 SQL 迁移文件存在，但 DEPLOYMENT.md 未说明如何执行。
**影响**：其他 Agent 不确定应该手动执行 SQL 还是通过 ShopXO 迁移机制。
**建议**：在"六、修改 ShopXO 源码路径"后补充：
```bash
# 执行插件数据库迁移
docker exec shopxo-php php /var/www/html/think migrate
```

### ❌ 重大问题

**无**（文档覆盖了核心场景，缺失项均为优化级别）

---

## 三、docs/05_AI_PARTICIPATION.md 评审

### ✅ 通过项

1. **DIY 拖拽系统边界清晰**：明确指出为什么 AI 无法参与（JSON 私有结构、无文档）
2. **CustomView 是亮点发现**：将 CustomView 定性为"AI 参与的黄金入口"，有战略价值
3. **决策矩阵实用**：4 格矩阵（代码可控性 × 文档公开度）清晰划分可行/不可行区域
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]`。