game-review

游戏审查 — 代码审计员

前置条件

• 根据检测到的代码领域应用相关的工程和设计技能（见阶段 0）

---

阶段 0 — 加载上下文（静默）

1. 如果 docs/mvp-first-draft.md 存在，则读取它（提供用于比较的架构意图）
2. 如果 docs/build-registry.md 存在，则读取它（记录已构建与模拟实现的内容）
3. 根据用户消息确定范围：
   • 如果提供了组件名称或路径：聚焦于 src/[component]/ 或指定路径
   • 如果未提供：审查整个 src/
4. 扫描目标范围，识别其中包含的技术领域（身份验证、支付、WebSocket、Redis、BullMQ、任务等）
5. 仅应用与检测到的领域相关的技能：
   • 检测到身份验证 → 应用 betterauth-integration 技能
   • 检测到支付/Stripe → 应用 stripe-game-payments 技能
   • 检测到 WebSocket/游戏状态 → 应用 game-state-sync 技能
   • 检测到 Redis → 应用 redis-game-patterns 技能
   • 检测到 BullMQ → 应用 bullmq-game-queues 技能
   • 检测到任务/叙事代码 → 应用 quest-narrative-coherence 技能
   • 检测到数据库/Drizzle → 应用 postgres-game-schema 技能
   • 检测到匹配系统 → 应用 matchmaking-system 技能
   • 检测到分析功能 → 应用 gameplay-analytics 技能

阶段 1 — 工程审查

读取目标范围中的所有 TypeScript 文件。应用以下检查。对于每项发现，记录：严重级别、文件路径、行号（近似值）、描述、修复建议，以及违反的技能。

状态权威性（多人游戏/WebSocket 代码）

• 🔴 严重：任何信任客户端提供的 message.userId 或 message.playerId 的 WebSocket 处理程序 — 必须从服务端会话中确定身份
• 🔴 严重：任何由客户端消息直接触发、未经服务端验证的游戏状态变更
• 🟡 警告：游戏循环的 Tick 频率超过 60Hz，且没有合理说明

数据库 / 架构

• 🔴 严重：在 Drizzle 的 sql 标签辅助函数之外使用原始 SQL 模板字面量（sql\SELECT...``）— 必须使用 Drizzle 类型化查询构建器
• 🟡 警告：面向玩家的表（players、inventory、characters）缺少 deletedAt 软删除列
• 🟡 警告：将本应放在 JSONB 中的游戏专属属性硬编码为列名（例如，将 manaPoints、fireResistance 设为顶层列）
• 🟢 建议：事件/日志表缺少 (playerId, type) 复合索引

身份验证与会话

• 🔴 严重：任何通过读取 req.body.userId 或 req.query.userId 来识别操作者的端点 — 必须使用 auth.api.getSession() 并从会话中确定身份
• 🔴 严重：验证 JWT 时未检查是否过期
• 🟡 警告：/auth/login 或 /auth/signup 路由没有速率限制
• 🟡 警告：将管理员/版主角色存储在 Cookie 或 JWT 声明中（每次请求都必须从数据库中获取）

支付（Stripe）

• 🔴 严重：任何在结账成功重定向（GET /success）时触发的购买发放逻辑 — 必须由 Webhook 驱动
• 🔴 严重：Webhook 处理程序未调用 stripe.webhooks.constructEvent() 来验证签名
• 🔴 严重：客户端代码中引用了 Stripe 密钥（public/、client/、frontend/ 中的任何文件）
• 🟡 警告：缺少对 checkout.session.completed 事件的幂等性检查 — Webhook 重放可能导致奖励重复发放

作业队列（BullMQ）

• 🟡 警告：BullMQ 处理器未配置 attempts — 所有作业都应有重试策略
• 🟡 警告：BullMQ 处理器未配置 backoff — 应使用指数退避
• 🟢 建议：考虑添加 removeOnComplete 和 removeOnFail 选项，以防止队列膨胀

Redis

• 🟡 警告：Redis 键不符合 {entity}:{id}:{field} 命名约定
• 🟡 警告：Redis 中存储的会话键没有设置 EXPIRE — 临时状态必须设置 TTL
• 🟢 建议：排行榜有序集合应使用 ZADD NX 或 GT，仅在分数提升时更新

常规安全

• 🔴 严重：在源文件中硬编码任何 .env 值或机密
• 🔴 严重：使用用户输入调用 eval() 或 Function() 构造函数
• 🟡 警告：接受用户控制数据的 API 端点缺少输入验证

Phase 2 — 叙事一致性检查

如果 docs/world-lore.md 和 docs/quest-registry.md 均不存在，则输出： 📋 叙事一致性检查：已跳过（未找到 docs/quest-registry.md — 运行 game-quest 技能以创建该文件） 然后跳到 Phase 3。

如果其中任一文件存在：

1. 读取 docs/world-lore.md 和 docs/quest-registry.md
2. 扫描源文件中的任务 ID、角色名称、阵营名称和地点名称
3. 检查：代码中是否有任何硬编码的任务／角色／阵营／地点字符串与世界设定中登记的信息相矛盾？
4. 标记：⚠️ 设定冲突：src/quests/main.ts 中引用了角色 "Mira"，但该角色未登记在 quest-registry.md 中

Phase 3 — MVP 范围偏移检查

如果 docs/mvp-first-draft.md 不存在，则输出： 📋 范围审查：已跳过（未找到 docs/mvp-first-draft.md — 请先运行 game-architect 技能） 然后跳到 Phase 4。

1. 读取 docs/mvp-first-draft.md 中的第 10 节（不在范围内）
2. 扫描 src/，查找明确延期的功能是否已实现
3. 标记：⚠️ 范围偏移：[功能] 在 [文件] 中实现，但在 MVP 计划第 10 节中列为不在范围内

同时检查 docs/build-registry.md，查找标记为“已构建”但未出现在 MVP 构建顺序（第 9 节）中的组件——这些可能属于过度设计。

Phase 4 — 报告输出

输出结构化审查报告：

# Game Review Report
Scope: [path reviewed]
Generated: [timestamp]

## Summary
🔴 Critical: X | 🟡 Warning: Y | 🟢 Suggestion: Z

然后按类别（工程、叙事、范围）列出所有发现。对于每项发现：

### [🔴/🟡/🟢] [Title]
**File:** `src/path/to/file.ts` (line ~42)
**Issue:** [what's wrong]
**Fix:** [concrete fix description]
**Skill ref:** [→ stripe-game-payments: webhook-first fulfillment]

最后以以下内容结尾：

## Next Steps
- Fix all 🔴 CRITICAL issues before committing
- Review the [top-violation-category] skill for correct patterns
- Run the game-build skill to rebuild any component with critical violations

如果某个类别未发现问题，则输出：

### ✅ [Category] — No issues found

---

严格约束

1. 绝不修改代码——这是只读审计命令。仅输出发现。
2. 绝不报告误报——如果某种模式看似违规，但结合上下文可以接受，则跳过或降级为 🟢
3. 始终链接到技能——每项发现都必须引用定义正确模式的技能
4. 具体明确——每项发现都必须包含文件路径和大致行号
5. 优先保证信号质量——5 个真实的严重问题比 30 条噪声建议更有价值