跳转至

后端开发 · 角色指南

假设你已读过 docs/00_overview/ 与 docs/01_onboarding/。

你的工具箱

工具 用途
IDEA / VS Code 主 IDE
Claude Code / Codex AI 协作（均兼容，见 01_onboarding/04_multi-agent.md）
OpenSpec 新功能 change proposal
Superpowers plugin brainstorming / TDD / debug
本仓库 czerp-backend / context / workflow IFinmate 框架范式 + 项目语境
Maven 构建
Knife4j API 文档
PingCode MCP / Gitee MCP 拉故事 / PR 操作

高价值工作流（触发 → AI 做什么 → 人怎么验）

# 触发 AI 做什么 人怎么验
spec 先行 新功能 / 跨服务 需求转规格六要素，产 proposal.md/tasks.md（/openspec-new） 评审规格，定稿后才让 AI 生成代码
TDD 实现 / 改存量前 先写失败单测（Mockito，Feign 用 @Mock+R.data）→ 实现 → mvn test 绿 确认测的是 验收标准 而非实现细节
复用框架脚手架 写 CRUD/Feign/权限/字典 从对应 skill 取范式（R<T>、Feign+*-sdk、@DataAuth），不造轮子 比对是否真用了框架能力
安全重构 跨切面重构 / 迁移弃用 API 在测试护栏下小步重构 特征化测试全绿 + diff 手术刀式
Flyway 迁移 任何 DDL 产新 V*.sql（PG 方言、唯一递增、不回改旧脚本） 审可回滚性；破坏性 DDL 必人确认（🔴）
提交前双评审 开 PR 前 /pre-pr-review + code-reviewer 子代理对抗式评审 关键路径人评后再合并

新增 skill：backend-testing（两种真实测试范式）、multi-tenant-and-currency（多租户/金额精度）。

一天典型流程

站会后：
- 接故事 CZPRJ-X
- /user-story-impl CZPRJ-X 拉故事 + 定位仓库
- /openspec-new <change-name>  起 proposal
- 编辑 proposal.md / tasks.md（按 czerp 约定模板）
- /brainstorming 推敲方案（如需）

实现：
- /test-driven-development 写失败测试 → 实现
- 调用 czerp-backend 各 skill (crud-scaffold / feign-call / data-scope 等) 取范式
- 遇到调用支撑服务（system / user / dict / oss / sms / flow）→ support-services-catalog skill

提交前：
- /pre-pr-review     czerp 特有 10 项检查
- /code-review       内置命令，通用检查
- /pr-describe       生成 PR 描述
- git push + 创建 PR

PR 合并后：
- openspec archive <name>
- 看 Gitee Go 流水线（当前仅 Maven 编译）结果 / Jenkins 流水线
- ArgoCD 同步到 dev/test
- 跑功能验证

必读的 skills

  1. microservice-init — 新建服务
  2. crud-scaffold — CRUD 标准
  3. feign-call — 跨服务调用
  4. support-services-catalog — 平台支撑服务全集
  5. flyway-migration — DDL 必走 Flyway
  6. auth-and-permission — 鉴权
  7. data-scope — 数据权限

按需读：cache-and-lock / flowable-workflow / excel-import-export / oss-and-sms / data-audit-and-encrypt / sharding-and-dynamic-ds / scheduling / distributed-tx / toolkit / code-generator / dict-and-enum。

铁律

  1. R<T> 包装所有响应；调 Feign 必先 R.isSuccess(r) 再 r.getData()。
  2. 跨服务走 Feign + *-sdk，禁止跨服务依赖 Service/Mapper。
  3. 任何 DDL 同步 Flyway 脚本；版本唯一递增不回改。
  4. 不要自建 token / RBAC / 分布式锁 / 任务调度 — 框架都有，去 czerp-backend 找对应 skill。
  5. 所有模块（含 *-sdk 与业务服务）均不写自身 version，统一由根 POM ${revision} 驱动；新增模块直接继承父 POM，勿手写 version。
  6. 新功能必走 OpenSpec；fix bug / 调文案可豁免。

与各角色协作要点

  • 接 PM：故事编号 + 验收标准 必须全；模糊就立刻 @PM 补全。
  • 配 QA：实现完了在 dev 跑通后通知 QA，附测试账号 / 数据 / 已知边界条件。
  • 求运维：要发版时 → PR 合并后通知 / 钉钉 oncall 群提醒。

常见错误

  • ❌ Controller 返回原始 entity（不用 R<T> 包装）
  • ❌ 在业务服务里写 @FeignClient（应放在 *-sdk）
  • ❌ Entity 字段没用 Snowflake，用了自增
  • ❌ 没加 create_user/create_dept/create_time/update_user/update_time/is_deleted
  • ❌ 改 DDL 没提 Flyway 脚本
  • ❌ 跨服务直接 @Autowired private OtherService 引依赖
  • ❌ 大文件导出 list() 一次性拉全表

进一步