refactor: 整理项目文件夹结构 + 更新项目状态
- docs/: 团队流程文档 (10个md) - .showen/: 管理状态文件 (CEO_BACKUP, RECOVERY, TEAM_CHAT, CEO_LOOP) - 根目录只保留 README.md + PROGRESS.md - 更新 RECOVERY.md/CEO_BACKUP.md/PROGRESS.md 反映自测机制完成 - 更新 souls/liu-jianguo.md 当前状态
This commit is contained in:
208
docs/CODE_REVIEW.md
Normal file
208
docs/CODE_REVIEW.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# ShowenV2 代码审核标准
|
||||
|
||||
## 审核流程
|
||||
|
||||
### 两级审核制度
|
||||
```
|
||||
开发者提交 → PM 初审 → CEO 终审 → git commit
|
||||
```
|
||||
|
||||
### PM 初审职责
|
||||
1. **编译检查**: cargo check 必须通过,零 warning
|
||||
2. **基本逻辑**: 代码逻辑正确,无明显 bug
|
||||
3. **风格一致**: 符合项目代码风格
|
||||
4. **测试验证**: 关键功能手动测试通过
|
||||
|
||||
### CEO 终审职责
|
||||
1. **架构审核**: 是否符合整体架构设计
|
||||
2. **性能审核**: 是否有性能问题
|
||||
3. **安全审核**: 是否有安全隐患
|
||||
4. **质量审核**: 代码质量是否达标
|
||||
|
||||
---
|
||||
|
||||
## 代码质量标准
|
||||
|
||||
### 必须满足(P0)
|
||||
- [ ] cargo check 零 warning
|
||||
- [ ] cargo clippy 零 warning
|
||||
- [ ] 无 unsafe 代码(除非有充分理由并注释说明)
|
||||
- [ ] 无 unwrap/expect(使用 ? 或 match 处理错误)
|
||||
- [ ] 无 panic(除非是不可恢复的错误)
|
||||
- [ ] 所有 public API 有文档注释
|
||||
- [ ] 关键逻辑有注释说明
|
||||
|
||||
### 应该满足(P1)
|
||||
- [ ] 函数长度 < 100 行
|
||||
- [ ] 圈复杂度 < 10
|
||||
- [ ] 嵌套层级 < 4
|
||||
- [ ] 变量命名清晰(避免 a/b/tmp 等)
|
||||
- [ ] 错误信息有上下文
|
||||
- [ ] 日志级别合理(debug/info/warn/error)
|
||||
|
||||
### 建议满足(P2)
|
||||
- [ ] 单元测试覆盖关键逻辑
|
||||
- [ ] 性能敏感代码有 benchmark
|
||||
- [ ] 复杂算法有示例和图解
|
||||
- [ ] 使用 trait 抽象而非具体类型
|
||||
|
||||
---
|
||||
|
||||
## 架构审核标准
|
||||
|
||||
### 插件设计
|
||||
- [ ] 插件之间零耦合,只通过消息通信
|
||||
- [ ] 插件不直接访问其他插件的状态
|
||||
- [ ] 插件可独立编译和测试
|
||||
- [ ] 插件配置通过 Config 传入
|
||||
|
||||
### 消息设计
|
||||
- [ ] 消息类型语义清晰
|
||||
- [ ] 消息字段最小化(避免冗余)
|
||||
- [ ] 消息实现 Clone(如果需要 Broadcast)
|
||||
- [ ] 消息处理无阻塞(长时间操作用独立线程)
|
||||
|
||||
### 并发设计
|
||||
- [ ] 避免共享可变状态
|
||||
- [ ] 使用消息传递而非锁
|
||||
- [ ] 阻塞操作在独立线程
|
||||
- [ ] 异步代码用 tokio,同步代码用 std::thread
|
||||
|
||||
### 错误处理
|
||||
- [ ] 使用 Result 而非 panic
|
||||
- [ ] 错误类型有上下文信息
|
||||
- [ ] 错误向上传播,在合适的层级处理
|
||||
- [ ] 用户可见的错误有友好提示
|
||||
|
||||
---
|
||||
|
||||
## 性能审核标准
|
||||
|
||||
### 内存管理
|
||||
- [ ] 避免不必要的 clone
|
||||
- [ ] 大对象用引用传递
|
||||
- [ ] 及时释放资源(文件句柄、网络连接)
|
||||
- [ ] 避免内存泄漏(检查循环引用)
|
||||
|
||||
### 计算效率
|
||||
- [ ] 避免重复计算(缓存结果)
|
||||
- [ ] 选择合适的数据结构(HashMap vs Vec)
|
||||
- [ ] 热点路径优化(避免分配、减少拷贝)
|
||||
- [ ] 考虑并行化(rayon、tokio)
|
||||
|
||||
### IO 效率
|
||||
- [ ] 网络 IO 用异步(tokio)
|
||||
- [ ] 文件 IO 用 BufReader/BufWriter
|
||||
- [ ] 避免频繁的小 IO(批量处理)
|
||||
- [ ] 考虑零拷贝(sendfile、mmap)
|
||||
|
||||
---
|
||||
|
||||
## 安全审核标准
|
||||
|
||||
### 输入验证
|
||||
- [ ] 所有外部输入必须验证
|
||||
- [ ] 配置文件解析有错误处理
|
||||
- [ ] HTTP 请求参数有校验
|
||||
- [ ] 文件路径防止目录遍历
|
||||
|
||||
### 资源限制
|
||||
- [ ] 防止无限循环
|
||||
- [ ] 防止内存耗尽(限制缓冲区大小)
|
||||
- [ ] 防止 CPU 耗尽(限制并发数)
|
||||
- [ ] 防止文件描述符耗尽
|
||||
|
||||
### 权限控制
|
||||
- [ ] 最小权限原则
|
||||
- [ ] 敏感操作需要验证
|
||||
- [ ] 日志不包含敏感信息
|
||||
|
||||
---
|
||||
|
||||
## 风格审核标准
|
||||
|
||||
### 命名规范
|
||||
- 类型名:PascalCase(VideoProcessor)
|
||||
- 函数名:snake_case(handle_message)
|
||||
- 常量名:SCREAMING_SNAKE_CASE(MAX_BUFFER_SIZE)
|
||||
- 模块名:snake_case(video_processor)
|
||||
|
||||
### 注释规范
|
||||
```rust
|
||||
/// 公共 API 文档注释(三斜杠)
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `config` - 配置对象
|
||||
///
|
||||
/// # Returns
|
||||
/// 成功返回 Ok(()),失败返回错误
|
||||
pub fn init(config: Config) -> Result<()> {
|
||||
// 实现细节注释(双斜杠)
|
||||
// 解释为什么这样做,而不是做了什么
|
||||
}
|
||||
```
|
||||
|
||||
### 格式规范
|
||||
- 使用 rustfmt 自动格式化
|
||||
- 行宽 100 字符
|
||||
- 缩进 4 空格
|
||||
- 导入按字母排序
|
||||
|
||||
---
|
||||
|
||||
## 审核检查清单
|
||||
|
||||
### PM 初审清单
|
||||
```
|
||||
[ ] cargo check 通过
|
||||
[ ] cargo clippy 通过
|
||||
[ ] 手动测试基本功能
|
||||
[ ] 代码风格一致
|
||||
[ ] 无明显逻辑错误
|
||||
[ ] 错误处理完善
|
||||
[ ] 注释清晰
|
||||
```
|
||||
|
||||
### CEO 终审清单
|
||||
```
|
||||
[ ] 符合架构设计
|
||||
[ ] 插件边界清晰
|
||||
[ ] 消息设计合理
|
||||
[ ] 无性能问题
|
||||
[ ] 无安全隐患
|
||||
[ ] 代码质量达标
|
||||
[ ] 可维护性好
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 不合格处理
|
||||
|
||||
### 初审不合格
|
||||
- PM 在 TEAM_CHAT.md 记录问题
|
||||
- 开发者修复后重新提交
|
||||
- 连续 3次不合格 → 绩效扣分
|
||||
|
||||
### 终审不合格
|
||||
- CEO 在 TEAM_CHAT.md 详细说明问题
|
||||
- 可能需要重新设计
|
||||
- 严重问题 → 考虑换人
|
||||
|
||||
### 绩效影响
|
||||
- 一次不合格:-1 分
|
||||
- 严重问题(架构/安全):-3 分
|
||||
- 优秀代码(超出预期):+2 分
|
||||
|
||||
---
|
||||
|
||||
## 审核时间要求
|
||||
|
||||
- PM 初审:2小时内完成
|
||||
- CEO 终审:24小时内完成
|
||||
- 紧急 bug 修复:1小时内完成
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
Reference in New Issue
Block a user