suretool

软件研发小组工作流（TEAM-WORKFLOW）

suretool 的迭代由「软件研发小组」负责，按 研发小组长统筹 → 产品经理定需求 → 软件架构师做设计 → 研发工程师实现 → 全栈代码质检官把关 → 研发小组长验收 的五步闭环推进。本文件是该团队协作协议在仓库中的落地版，适用于一切功能迭代、缺陷修复与发布。

1. 团队角色

角色	职责	在仓库中的落点
研发小组长（统筹）	澄清目标、范围、依赖、风险与验收标准；汇总进度、裁决冲突、给出交付结论	迭代计划、验收结论、发布决策
产品经理	需求梳理、方案取舍、Roadmap、PRD、验收设计	docs/prd/ 下的 PRD 文档与对应 Issue
软件架构师	模块归属、API/接口设计、架构可视化、技术方案评审	架构评审记录（PR 评审或 docs/architecture/）
研发工程师	功能实现、排错、测试证据、可运行交付	代码 + JUnit 测试 + CHANGELOG
全栈代码质检官	代码正确性、安全性、性能审查，问题分级与修复方案	CodeQL / SpotBugs / 覆盖率门禁 + 审查结论

2. 协作原则（源自团队协议）

1. 按需委派：只选择会改变结果的必要环节；能由一步完成的工作不扩大范围、不按名单机械走完五步。
2. 先定输入输出：每项工作明确负责人、输入、产出与依赖；互不依赖的工作可并行。
3. 证据驱动：后续环节必须读取并使用前序已完成的结果；前序失败或缺失时说明阻塞，不猜测、不重造结论。
4. 独立质检：质检由专业成员独立执行，不代写、不橡皮图章；冲突按用户目标、可靠证据与风险裁决。
5. 统一交付：交付至少包含目标与范围、采纳的专业结论、可访问产物、已验证/未验证/阻塞/待确认事项、P0/P1/P2 风险分级与整改建议、下一步建议。

3. suretool 五步闭环

第 1 步 · PRD（产品经理）

• 输入：用户需求 / Issue / 迭代目标。
• 产出：docs/prd/<功能名>.md 或 Issue 中的需求说明，包含：目标与范围、用户场景、验收标准、不做的边界。
• 门禁：无明确验收标准的需求不得进入实现阶段。
• 裁剪：小范围修改（单方法、缺陷修复）可跳过独立 PRD，直接以 Issue 描述为准，但验收标准必须在 Issue/PR 描述中写清。

第 2 步 · 架构评审（软件架构师）

• 输入：已确认的 PRD / Issue。
• 产出：模块归属结论、新增 API 签名设计、依赖边界（是否引入第三方依赖、是否归属核心零依赖域）。
• 门禁：
  • 新增 public API 必须符合既有命名与设计原则（XxxUtil、静态方法、私有构造器、@since）；
  • 新模块或跨模块依赖调整须在 PR 描述中说明并获评审通过。
• 裁剪：不影响模块归属、API 形状与依赖边界的改动（如内部实现优化）可跳过。

第 3 步 · 实现（研发工程师）

• 输入：PRD + 架构结论。
• 产出：实现代码 + JUnit 4 测试（正常/边界/异常路径）+ CHANGELOG 条目。
• 硬约束：
  • JDK 25+，写法直接使用现代特性，不考虑低版本兼容；
  • Tab 缩进、UTF-8、中文 Javadoc；
  • 核心模块零第三方运行期依赖；工具类只依赖自家 sure-core；
  • 测试先行：新增/修改方法必须有对应测试。

第 4 步 · 质检（全栈代码质检官）

• 输入：实现代码与测试。
• 执行：mvn -B verify 全量门禁 + 代码审查。
• 门禁表：

门禁	标准
编译与测试	Tests run 全部通过
Checkstyle	0 违规（含测试源码）
SpotBugs	0 个 bug（1 个即失败）
JaCoCo 覆盖率	不低于各模块 jacoco.line.min（sure-core ≥ 0.70，sure-http ≥ 0.86，sure-poi ≥ 0.85）
安全扫描	CodeQL（push/PR/每周）+ Dependabot 依赖升级

• 问题分级：P0（安全/正确性/数据风险，必须关闭）、P1（功能缺陷/性能隐患，合入前修复）、P2（改进建议，可后续处理）。
• 红线：P0 未关闭不得判定通过；安全、隐私、权限相关 P0 未关闭不得发布。

第 5 步 · 验收（研发小组长）

• 输入：实现 + 质检结论。
• 产出：验收结论（通过 / 需返工 / 待确认），核对跨产物一致性（代码 ↔ 测试 ↔ CHANGELOG ↔ README/文档）。
• 标准：门禁全绿 + 验收标准逐条核验 + 风险清单闭环。

4. 与 CI 的映射

环节	CI 检查（.github/workflows/ci.yml）
实现	编译、单测、Checkstyle、SpotBugs、JaCoCo 覆盖率
质检	CodeQL 安全扫描（ci.yml + 独立 CodeQL workflow）
验收	上述全部通过 + PR 评审 + 维护者 Squash Merge

5. 高影响动作红线

以下动作必须先给出影响与验证方案，等待用户确认后执行，不得擅自进行：

• 发布新版本到 Maven Central / 打标签 / 创建 Release；
• 删除或迁移仓库文件、分支、标签；
• 权限变更、Secret/凭据操作；
• 破坏性 API 变更（进入 1.x 后仅允许在 minor 版本进行，且须在 ROADMAP/CHANGELOG 记录）。

6. 迭代入口

• 新功能：新建 Issue（或 PRD）→ 团队按五步闭环推进。
• 缺陷修复：Issue 描述复现步骤与期望行为 → 直接进入实现 + 质检两步。
• 发布：按 RELEASING.md 执行，发布前由质检官确认安全门禁、由组长确认验收结论。

7. 示例裁剪

场景	执行的步骤
新增一个工具方法（如 StrUtil.xxx）	第 3 步实现 + 第 4 步质检（第 1/2 步以 Issue 验收标准代替）
新增一个模块（如 sure-extra）	第 1 步 PRD + 第 2 步架构评审 + 第 3 步实现 + 第 4 步质检 + 第 5 步验收
安全漏洞修复	第 4 步质检定位分级 → 第 3 步修复 → 第 4 步复检 → 第 5 步验收
纯文档更新	直接 docs: 提交，质检仅做编译级验证

This site is open source. Improve this page.