不鸽工程队 —— 代码规范、冲刺任务与计划

目录

一、 团队代码规范

为了保证团队 4 名成员在并行开发时的代码质量，减少代码合并冲突，提高代码的可读性与可维护性，本团队严格参考《阿里巴巴 Java 开发手册（终极版）》及业界主流规范，结合本次「不鸽组队」项目的技术栈（Spring Boot + MyBatis + Vue），制定了以下开发红线与规范。

1. 命名规范

2. 代码格式规范

• 缩进：统一使用 4 个空格。
• 行宽：单行代码字符数不超过 120 个字符，超长需换行。
• 括号：左大括号 { 前不换行，右大括号 } 后需换行。
• 空行：不同逻辑块之间、方法与方法之间必须空一行。
• 魔法值：不允许任何未经定义的魔法值直接出现在代码中（如状态码 1、2），必须定义为枚举或静态常量。

// 正例：格式规范，消除魔法值
public class ActivityService {
    private static final int STATUS_RECRUITING = 1;

    public void checkStatus(Activity activity) {
        if (activity.getStatus() == STATUS_RECRUITING) {
            // 执行业务逻辑
        }
    }
}

3. 注释规范

• 类注释：所有 Controller、Service、Entity 类顶部必须使用 Javadoc 注释，说明该类的业务用途。
• 方法注释：所有 public 方法必须使用 Javadoc 说明其功能、@param 参数和 @return 返回值。
• 行内注释：复杂逻辑（如并发防超卖、定时任务扣分）必须写行内注释，且注释应放在代码上方，不放在行尾。
• 及时更新：修改代码时，必须同步修改对应的注释，杜绝“注释与代码不符”的现象。

/**
 * 报名业务服务类。
 * 负责处理用户的报名、退出及信用分校验逻辑。
 */
@Service
public class RegistrationService {

    /**
     * 用户报名活动。
     * @param activityId 活动ID
     * @param userId 用户ID
     * @return 报名结果
     */
    public Result<Void> register(Long activityId, Long userId) {
        // 1. 校验用户信用分是否低于 60
        // 2. 使用乐观锁扣减活动名额
        return Result.success(null);
    }
}

4. 异常处理与日志规范（强制）

• 全局异常拦截：业务代码中不允许出现大量的 try-catch 吞异常，统一抛出 BusinessException，交由全局异常处理器（@RestControllerAdvice）统一捕获并返回标准格式。
• **禁止 e.printStackTrace()**：所有异常必须使用 SLF4J 记录日志（如 log.error("报名失败: {}", e.getMessage())），严禁在生产环境使用 System.out.println。
• 资源释放：IO 流、数据库连接等资源，必须使用 try-with-resources 语法，防止内存泄漏。

5. Spring Boot 与数据库规范

• 分层架构：严格遵循 Controller（接收请求与校验） -> Service（业务逻辑与事务） -> Mapper（SQL 操作）三层架构，禁止跨层调用。
• 依赖注入：必须使用构造器注入（配合 @RequiredArgsConstructor），禁止使用 @Autowired 字段注入，保证依赖的不可变性。
• RESTful 路径：接口路径使用名词复数形式，如 GET /api/activities，禁止使用动词（如 /getActivity）。
• SQL 规范：MyBatis 的 Mapper 中，严禁使用 ${} 拼接 SQL（防止 SQL 注入），必须使用 #{} 预编译占位符。
• 实体类：统一使用 Lombok 的 @Data 注解简化 get/set 方法，但 VO/DTO 类建议使用 @Builder 建造者模式。

6. Git 提交与协作规范

• Git 前准备：每天开工前，先执行 git pull 拉取最新代码；推代码前，必须先测试本地能运行。
• 防冲突边界：各成员只在自己负责的包（如 com.bugedu.user）下写代码，严禁修改他人包内的文件。
• Commit Message 格式：必须遵循 <type>: <subject> 的格式。
• feat：新增功能（如：feat: 新增活动发布接口 ）
• fix：修复 Bug（如：fix: 修复报名并发超卖问题 ）
• docs：仅修改文档（如：docs: 更新接口文档 ）
• style：仅修改代码格式（不影响逻辑）
• refactor：代码重构

本文档自 2026 年 10 月 23 日 α 冲刺启动之日起执行。

二、 α 冲刺任务与计划

本次 α 冲刺周期为 7 天（10月23日 - 10月29日）。我们的核心目标是：跑通“登录 → 发布活动 → 报名 → 云端联调”的主流程，并完成进阶功能开发与系统测试。

为了保证前后端并行开发的效率，避免互相干等，团队制定了详细的每日排期、明确的成员分工以及敏捷协作机制。

1. 团队分工安排

在本次编码冲刺阶段，具体分工如下：

2. 冲刺排期表（每日计划）

3. 敏捷协作机制

为了在 7 天高压冲刺下保持高效产出，减少沟通内耗，团队确立了以下三大协作机制：

1. 每日站立式会议：每晚 21:00 准时在腾讯会议召开，同步“昨日进展、今日计划、遇到的困难”，会议上会进行截图打卡，作为每日冲刺博客的素材。
2. 接口契约先行（Apifox）：后端开发人员需优先在 Apifox 上定义好接口文档；前端利用 Apifox 的 Mock 数据功能并行开发页面。避免“前端干等后端接口”或“字段对不上”的问题。
3. 云端部署联调：冲刺第四天（Day 4）将前后端代码统一打包，部署至华为云服务器，并连接云端 MySQL。确保大家能在真实的云端环境下进行集成测试，提前暴露并解决跨域、网络请求等环境问题。

三、 引入 AI 技术员

为了在 7 天的冲刺中提高效率、降低开发门槛，团队引入 “AI 技术员” 参与我们的开发流程。我们不仅把 AI 当作搜索引擎，也将其视为团队的“虚拟结对编程伙伴”。根据团队成员的技术栈与工具偏好，我们为 AI 分配了以下三大具体岗位：

1. AI 程序员（辅助编码）

• 选用工具：通义灵码、WorkBuddy（后端使用）、Seed-Code（前端使用）
• 具体职责：
  • 模板代码生成：利用 IDEA 插件（如通义灵码）快速生成 Java 实体类、Mapper 接口等重复度高的代码；前端利用 Seed-Code 辅助生成复杂的 Vue 组件代码。
  • 架构适配与重构：在多端协作时，利用 WorkBuddy 辅助进行代码迁移、包名批量重写以及返回格式适配。
  • Bug 代码诊断：遇到框架版本冲突、依赖报错或跨域拦截时，将错误日志抛给 AI 快速定位并给出修复方案。

2. AI 测试员（辅助测试）

• 选用工具：DeepSeek、WorkBuddy
• 具体职责：
  • 边界测试用例生成：在测试“报名防超卖”和“信用分<60限制报名”等核心逻辑时，利用 AI 快速生成覆盖各种边界情况的测试用例。
  • 自动化压测脚本编写：借助 AI 辅助编写并发自测脚本（如模拟高并发报名），并辅助排查脚本本身的逻辑漏洞。
  • 环境部署与排错：利用 AI 辅助排查本地环境问题（如数据库部署、Git 推送凭据问题），辅助编写一键建库导表的自动化流程。

3. AI 设计师（辅助设计）

• 选用工具：Seed-Code、DeepSeek
• 具体职责：
  • UI 组件辅助实现：前端开发时，借助 AI 快速实现如“报名进度条（el-progress）”、“状态自动隐藏”等复杂的交互逻辑与样式设计。
  • 技术选型与版本兼容：利用 AI 辅助评估前端依赖库的版本兼容性（如规避过新的 UI 库引发的崩溃），给出合理的版本降级建议。

四、 冲刺决心

在接下来的 7 天里，不鸽工程队将严格执行本次制定的代码规范，在开发过程中充分借助 AI 工具来提升效率。面对时间紧、任务重的 α 冲刺阶段，团队成员会保持顺畅的沟通与紧密的配合，做到遇到问题及时反馈、当天任务当天推进。

我们将用扎实的代码和严谨的态度，努力交付一个功能完整、运行稳定、体验流畅的校园搭子平台。