review

/review — 代码审查

对指定模块进行结构化代码审查，输出中文评审报告。

触发方式

• /review <模块/文件路径> — 审查指定模块或文件
• 用户说"审查 XXX 子模块"

审查流程

Step 1: 确认审查范围

1. 根据用户指定，搜索相关源文件 (.h, .hpp, .cpp)
2. 列出完整文件清单（含行数）
3. 等待用户确认后再继续
4. 如果范围过大（>20 个文件），建议拆分为子模块逐个审查

Step 2: 读取全部代码

• 读取范围内所有 .h, .hpp, .cpp 文件
• 读取对应 CMakeLists.txt 了解构建上下文
• 查找并读取对应测试文件（test/ 目录下）

Step 3: 五维分析

3.1 性能关注点

• 不必要的拷贝（缺少 std::move，大类型按值传递）
• 多余的 QString/QByteArray 转换
• 过多的堆分配（优先栈分配、std::array、small buffer optimization）
• 虚调度开销（可用静态分派替代的场景）
• Signal/Slot 连接类型（auto vs direct vs queued 的合理性）
• 循环中的重复计算
• 不必要的 Q_OBJECT 宏（非 QObject 子类使用）

3.2 模块间依赖检查

参考 .claude/commands/architecture.md 的层级规则：

• base 不得 include ui/desktop
• ui 不得 include desktop
• CMake target_link_libraries 依赖方向正确

3.3 类级耦合分析

检查项	阈值	说明
继承深度	> 3	标记过深的继承链
friend 使用	任何	需要合理理由，否则标记
Signal 数量	> 10	过多 Signal 可能是设计异味
类行数	> 500	考虑拆分为多个类
公共方法数	> 30	检查是否违反接口隔离原则
依赖类数量	> 8	高耦合信号

3.4 C++23 现代性

• 缺少 [[nodiscard]]（const getter、工厂函数、返回 expected<T> 的函数）
• 可 constexpr 化但未标注的函数和变量
• 裸指针（可用智能指针或引用替代的场景）
• 缺少 override/final（重写虚方法时）
• 缺少 noexcept（不抛异常的移动构造/赋值）
• 可用 std::span 替代指针+长度参数
• 可用 using enum 简化枚举使用
• 可用结构化绑定简化返回值处理

3.5 文档完整性

对照 document/DOXYGEN_REQUEST.md 规范：

• 未文档化的公共 API
• @param 方向标记缺失
• @return 与实际返回类型不匹配
• 风格不一致（/** */ 和 /// 混用）

Step 4: 输出报告 (中文)

# 代码审查报告: <module_name>

## 审查范围
| 文件 | 类型 | 行数 |
|------|------|------|
| ... | .h/.cpp | N |

模块层次位置: base/ui/desktop — Layer N

## 性能关注点
1. **[严重/中等/建议]** 文件:行号 — 问题描述

## 依赖违规
(层级违规详情，或 "无违规")

## 类级耦合分析
- 继承深度: ...
- friend 使用: ...
- Signal/Slot 合理性: ...
- 类职责评估: ...
- 上帝类检测: ...

## 现代 C++ 改进建议
1. **[类别]** 文件:行号 — 具体建议

## 文档完整性
- 缺失文档的公共 API: ...
- Doxygen 标签问题: ...

## 综合评估
- 健康度评分: X/10
- 主要风险: ...
- 优先改进项:
  1. ...
  2. ...
  3. ...

## 改进指南
(可对接 /optimize 的具体改进项列表)

规则

• 始终读取实际代码，不做假设
• 引用具体文件路径和行号
• 区分严重问题、中等问题和建议
• 报告中的严重问题必须附带修复方案