2026山东大学项目实训5月6日

一、项目背景

在前面一系列工作完成之后，CodeGuard AI 已经逐步从“能跑通”的审查原型，走向“能按仓库策略、团队策略稳定运行”的阶段。这个阶段我继续负责的重点，已经不只是分析链路本身，而是围绕团队治理、权限边界、真实登录和本地数据库兼容做稳定性补强。

相比前面的功能开发，这一阶段更关注两个问题：一是系统在引入团队角色、真实身份和准入流程之后，权限判断是否准确；二是本地开发和测试环境在新增表结构、登录方式变化之后，是否还能保持稳定运行。对一个代码审查平台来说，这些问题看起来不像“新功能”，但它们直接决定系统能不能持续迭代、能不能安全使用。

二、团队权限与策略继承的补强

这一阶段我最先处理的是团队权限相关的稳定性问题。因为团队治理这类功能和普通页面展示不一样，它直接涉及“谁能做什么”。一旦权限判断写得不清楚，就很容易产生错误行为，甚至让不该有权限的人修改到团队策略或者仓库归属。

因此，我重点补充了自动化测试，覆盖了 owner、editor、viewer 三种角色的行为边界。测试重点主要放在三个方面：

第一，owner 是否可以创建成员、维护团队配置。
第二，editor 是否可以更新团队共享策略，但不能新增成员。
第三，viewer 是否完全不能修改团队策略。

这些测试的意义在于，团队权限不再只是页面上的按钮显示问题，而是后端真实权限模型的一部分。只有把这些边界测清楚，后面团队治理相关的功能才有基础。

除了角色权限，我还补了一个更贴近业务链路的场景：自定义技能和规则挂在团队共享策略上之后，当仓库没有启用仓库级定制时，触发 PR 审查能不能真正生成对应 findings，并且在审计日志中记录这次审查使用的是团队策略，而不是全局策略或仓库定制策略。

这个测试很关键，因为它证明团队治理不是页面展示，而是会真实参与审查流程。也就是说，团队共享策略不是挂在后台看的，而是实际会影响分析结果的。

三、数据库兼容问题的处理

这一阶段还遇到一个很现实的工程问题：项目当前的数据库初始化仍然主要依赖create_all()，而不是完整的 Alembic 迁移链路。这个方式在早期开发时比较方便，但当数据表结构继续扩展，尤其是新增 Team 相关表和repository_bindings.team_id这种字段时，就会出现兼容性问题。

如果不处理，旧数据库直接启动就可能报错，影响本地联调和演示。因此我补了一个轻量级兼容逻辑，在启动时自动检查并补齐缺失列，尽量让已有的本地 MySQL 环境可以平滑进入新的结构。

这不是长期最优方案，但对当前 MVP 和课程项目来说是比较务实的处理方式。它的目标不是替代正式迁移机制，而是保证现阶段的本地环境能持续运行，不会因为表结构升级而直接断掉。

四、真实登录改造后的测试回归

在后续改造中，系统从 fake auth 切到了真实登录态。这看起来像是加了一个登录页，但实际上影响的是整条链路：后端依赖注入、测试客户端、OAuth 流程、仓库绑定、团队管理和 webhook 接口都会受到波及。

所以这一阶段我重点做的是测试回归和兼容性验证，确保系统从 mock 登录切到真实登录态之后，不会把前面已经做好的功能一起带坏。

为了让测试环境更稳定，我专门处理了测试客户端的自动登录问题，让测试客户端在 mock GitHub 模式下可以自动获得系统会话，而不是每个测试都手动走一遍复杂登录流程。这样测试就能继续保持可重复执行，也不会因为身份切换而导致大量测试失败。

这一阶段我重点增加和修正了三类场景：

第一类是 GitHub 登录链路本身，包括 OAuth 回调后是否能生成系统用户、是否能恢复当前登录态、是否还能继续拉取仓库列表和绑定仓库。

第二类是团队治理相关的权限边界，比如团队 owner 是否仍能管理成员，viewer 是否仍不能修改团队策略。

第三类则是更关键的新场景：只有团队权限、没有仓库管理员权限的人，不能把仓库强行加入团队。这个测试很重要，因为它直接说明真实登录之后，团队权限模型不是表面上换了身份，而是实际把权限边界补牢了。

五、webhook 入口的兼容性处理

真实登录改造之后，另一个容易出问题的地方是 webhook 入口。因为系统后台现在要求先登录，但 GitHub webhook 本身是来自外部平台的回调入口，它不能被新的会话鉴权拦住。

所以在这一阶段，我也验证并保留了这样的结构：后台页面和业务接口要求登录，webhook 入口继续公开。这样既保证了后台安全，也不影响系统接收真实 PR 事件。

这部分看起来像是一个兼容处理，但它其实很重要。因为如果 webhook 入口被登录机制误伤，系统就会出现“后台能看，事件进不来”的情况，整个审查链路会断掉。把这一点处理好之后，真实登录才算真正融入了原有链路，而不是额外加了一套互相割裂的机制。

六、团队准入流程的测试与回归验证

在团队治理继续往前推进之后，又新增了团队准入流程，也就是申请审批机制。这个功能虽然从页面上看只是“加一个申请”，但它实际上会影响权限判断、仓库归属更新和审计记录，所以测试策略不能只看接口通不通，而要看状态流转和权限边界是否准确。

为此，我新增了针对团队准入流程的测试文件，覆盖三组核心场景：

第一组是申请创建并通过。这里主要验证互补权限是否真实工作，也就是申请人具备团队管理权限、审批人具备仓库管理员权限时，申请可以通过，且仓库团队归属会被正确更新。

第二组是申请撤销与拒绝。这里主要验证状态流转是否完整，申请发起后可以撤销；重新发起后可以由团队侧拒绝；每个结束态都不能重复操作。

第三组是无权限用户发起申请被拒绝。这里主要验证安全边界，既没有仓库管理员权限、又不是团队管理角色的用户，不能发起申请，系统会返回明确的权限错误。

这一阶段的测试重点不是“接口有没有返回”，而是状态机和权限边界有没有被真正守住。只有把这些链路打稳，后面的团队治理功能才不会在权限上出现漏洞。

七、本阶段完成的任务

这一阶段主要补齐了以下内容：

• 增加 owner、editor、viewer 三种角色的权限测试
• 验证团队共享策略是否能被仓库真实继承
• 验证审查结果是否会记录团队策略来源
• 处理create_all()启动路径下的新表和新字段兼容问题
• 补充真实登录切换后的测试回归
• 处理测试客户端在 mock GitHub 模式下的自动登录问题
• 验证 OAuth 回调、系统用户生成、登录态恢复、仓库列表拉取和仓库绑定链路
• 验证 webhook 入口在真实登录模式下仍保持可用
• 新增团队准入流程的测试，覆盖申请通过、撤销、拒绝和无权限申请被拦截等场景
• 补充后端测试和前端构建回归，确保新增能力没有破坏已有主流程

这些工作看起来不像某个单点功能那样显眼，但它们决定了系统能不能在真实开发和真实使用中保持稳定。

八、小结

这一阶段主要做的事情，可以概括为把团队权限、真实登录、准入流程和数据库兼容补齐，做成一套可回归、可验证、可持续运行的稳定基础。

如果说前面的工作重点是让 CodeGuard AI 具备分析和审查能力，那么这一阶段做的，就是把这些能力放到更真实的团队和权限环境里，让它能够真正按角色、按策略、按准入流程稳定运行。