PotatoChat 的代码审查流程是一套可复制、可度量的工作流：从分支与提交规范、自动化检测（CI、静态扫描、单元测试）到人工逐行审阅、角色化审批与合并策略，每一步都有清晰的责任人、时间窗口和回滚机制，既保证代码质量与安全，也兼顾开发效率与知识共享，方便追溯与持续改进。
先说为什么要有这种流程
把代码审查想成饭馆的出菜流程会更直观：配料要规范（分支、提交），火候要把控（自动化测试与性能检查），出菜前客观品尝（人工审查），若口味出问题能立刻撤回（回滚与补丁）。没有流程就像没有厨房标准，节奏乱、出错难查。
PotatoChat 的总体架构概览
流程由若干环节组成，每个环节都有明确目标和验收标准——这不是形式，而是为了回答三个问题：代码能跑吗？会不会影响别人？有没有安全或合规问题？
主要角色与职责
- 提交者（Author）：负责分支、提交信息、初步自测与填充 PR 模板。
- 审阅者（Reviewer）：逐行阅读、功能逻辑、边界条件、可维护性与安全提示。
- 批准者/合并者（Approver/Maintainer）：有合并权限，核查合规后完成合并并触发发布流程。
- CI 系统：自动运行测试、静态分析、依赖扫描与性能烟雾测试。
- 安全团队（按需）：对敏感模块或高风险 PR 做深入审计。
分支策略与提交规范（小而清晰）
好的分支策略能把审查范围缩小到合理尺寸，避免“巨无霸”PR。
- 主分支（main/master）：始终保持可发布状态，受保护分支规则约束。
- 开发分支（develop/feature/*）：每个功能或修复使用独立 feature 分支，命名规则如 feature/ISSUE-123-brief-desc。
- 热修复分支（hotfix/*）：直接从主分支出来，变更尽量小且附带回归测试。
- 提交信息规范：使用简洁前缀（feat/fix/docs/test/refactor/chore），正文说明为什么而不是仅写做了什么。
PR 模板要包含
- 变更类型与简单描述
- 相关 issue 或需求链接（或编号）
- 如何手工验证（步骤、示例数据）
- 测试覆盖情况与影响范围
- 是否需要安全审计或数据库变更
自动化检测（CI）的角色与标准）
自动化是第一道关卡，把明显的错误在人工之前挡住。CI 不只是跑测试，它是质量的传递带。
| 阶段 | 工具/类型 | 触发时机 | 通过标准 |
| 静态检查 | linter、格式化器（ESLint/Prettier、gofmt 等） | 每次提交/PR | 无阻塞性错误；格式化警告自动修复或拒绝合并 |
| 单元测试 | pytest/Jest/go test 等 | 每次 PR 与合并前 | 关键路径覆盖率门槛（例如 80% 可配置）与无失败用例 |
| 集成/端到端 | CI pipeline 测试集 | PR 合并前或 nightly | 核心业务链路无回归 |
| 依赖与安全扫描 | Dependabot/Snyk/自研脚本 | PR/定时 | 高危漏洞阻塞，低危列任务 |
| 性能烟雾 | 简单性能测试 | 关键改动或发布前 | 不超过预定回退阈值 |
人工审查的具体步骤（一步步来）
把人工审查拆成“看表面”“看逻辑”“看边界”“看影响”四个子步骤，会更容易做到既细致又高效。
步骤详解
- 创建 PR：填写模板，标明需要的审阅人数与特殊审阅者（如安全负责人）。
- 初步自动验证完成后指派审阅者：使用轮值或领域专家负责制。
- 审阅者逐项检查：按审查清单逐条确认，并在 PR 中留下简洁、建设性的评论。
- 问题修正并迭代：提交者响应评论并在必要时重新运行 CI。
- 批准与合并：满足审批人数与 CI 通过后，由有权限者合并并触发后续流程。
审查清单示例（必查项）
- 功能正确性：边界条件与异常分支是否覆盖。
- 可读性与可维护性：命名、注释、模块划分是否清晰。
- 测试覆盖：关键路径是否有单元或集成测试。
- 性能影响：是否引入高复杂度操作或热路径分配。
- 安全：是否输入校验、鉴权、敏感信息处理合规。
- 依赖与许可证：是否引入新依赖，许可证是否合规。
合并策略与发布控制
合并并不是终点，而是另一个开始：部署与监控。
- 保护分支策略：强制 PR、至少 1-2 名审批、CI 通过方可合并。
- 合并方式：特性分支 favor squash 或 rebase 保持主分支历史清晰；重要库用 merge commit 保留上下文。
- 发布流水线：合并触发构建、制品上传、灰度发布与回滚演练。
- 回滚与补丁：事先准备热修模板与回滚脚本，保证 15-30 分钟内可恢复到安全状态（根据 SLA）。
安全与合规的深度审计（按需加强）
对外接口、认证、密钥管理、依赖漏洞等是高风险点，触发条件包括引入第三方依赖、处理敏感数据或修改认证逻辑。
- 静态应用安全测试（SAST）在 CI 中自动运行。
- 秘密扫描（secret scanning）禁止密钥上传。
- 对高级别风险 PR 安排安全工程师做手动审计，并写入审计记录。
审查礼仪与典型评论示例（人比技术更重要）
好的评论是帮助而不是指责，保持具体、尊重并提供改进方向。
- 差评示例（不要做）：”这代码太烂了，重写吧。”
- 好评示例（要做）：”这里逻辑在边界 X 下会返回空，建议在函数开始加入非空检查，或写一条测试覆盖该情况。”
- 建议格式：问题描述 + 为什么重要 + 改进建议 + （可选）代码片段
衡量指标与持续改进
数据会告诉你流程是否有效。不要只看主观感受。
- 平均审查时间（从 PR 打开到第一次审阅、从打开到合并）
- 缺陷泄露率（合并后被发现的 bug 数）
- CI 失败率与修复时间
- PR 大小分布：鼓励小而频繁的变更，避免超大 PR。
遇到冲突与例外的处理方式
现实会有例外：紧急修复、跨团队依赖或大规模重构。流程要有弹性但不破坏原则。
- 紧急热修复：简化审批（例如 1 名批准 + 运维联动），事后补齐审计记录与测试。
- 大重构：先提 RFC/设计文档获得共识，再分小步实现并在每一步做审查。
- 跨团队变更：要求相关团队代表为审阅者，提前沟通影响面。
几个常见问题（快速回答）
- PR 太多没人审怎么办？ 设定审查 SLA、轮值制与自动提醒，关键路径由负责人推动。
- 怎样避免审查流于形式？ 明确拒绝只看样式的“通过”，把重点放在逻辑、测试与安全上，定期抽查审查质量。
- 新成员如何快速上手审查？ 提供审查培训、范例 PR 与新手任务，由资深工程师带审阅第一批。
一些小贴士（容易被忽视但有效）
- 把 PR 控制在 200-400 行改动为宜，太大就拆分。
- 审查者使用“建议修改”功能并附代码片段，比只留下问题更有效率。
- 建立常见错误库（FAQ）供提交者自检，减少重复反馈。
- 定期回顾失败案例，把原因写进团队知识库。
把流程当成活的东西来维护：它既要有规则，也需要随团队节奏迭代。你会发现，起初看起来繁琐的步骤，会把未来那些“半夜爆炸”的紧急修复变成可预期的工作量——这才是真正能让团队稳健、可扩展地前进的地方。