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:
showen
2026-03-13 04:45:35 +08:00
parent 99ee78984c
commit becd200150
17 changed files with 152 additions and 108 deletions

208
docs/CODE_REVIEW.md Normal file
View 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 耗尽(限制并发数)
- [ ] 防止文件描述符耗尽
### 权限控制
- [ ] 最小权限原则
- [ ] 敏感操作需要验证
- [ ] 日志不包含敏感信息
---
## 风格审核标准
### 命名规范
- 类型名PascalCaseVideoProcessor
- 函数名snake_casehandle_message
- 常量名SCREAMING_SNAKE_CASEMAX_BUFFER_SIZE
- 模块名snake_casevideo_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)