研发开发规范总览

规范说明

本规范域定义公司全部产品研发（当前以 EasyPro 平台为主线）的前后端统一工程约定，涵盖分支管理、提交规范、合并回流、命名接口、代码规范、SQL 版本化等完整流程。与「用户手册」（面向使用者）、「驱动设计文档」（面向驱动开发）互补——这里讲「怎么协作」。

文中示例（版本号、分支名、模块名、SQL 文件等）均取自 EasyPro 真实代码库，便于读者对照本仓库；规范本身适用于公司所有产品研发。

Git 工作流 · 入职第一周3 篇

分支与 Tag 管理

分支模型（保留版本分支模式）、分支命名规范（前后端统一）、产品线分支（line/ 子产品独立演进）、旧命名迁移映射表、分支生命周期、Tag 规范（SemVer）。

约 12 分钟入门入职首日

分支模型命名规范产品线迁移映射 Tag

Conventional Commits 提交信息格式：type/scope/subject 规则、前后端共用 scope 参考表、正例反例、Git Hooks 自动校验脚本。

约 8 分钟入门入职首日

Conventional Commits Git Hooks commit-msg

合并回流与定制隔离

五条核心规则（custom 禁回流 / 现场验证门禁 / hotfix 双向回流且禁改库 / custom-line 下行同步 / 维护性微版本）、GitLab 服务端保护、定制需求文档规范与隔离策略。

约 10 分钟进阶入职第一周

合并规则定制隔离 GitLab 保护文档备案

代码与接口 · 熟悉项目2 篇

前后端命名与接口规范

后端 Java 命名（包/Controller/Service/Mapper/DTO/VO/枚举）、前端 Vue 命名（组件/路由/变量）、通用命名（表/字段/文件）、Swagger / OpenAPI3 注解规范。

约 10 分钟进阶动手写代码前

Java 命名 Vue 命名 Swagger OpenAPI3

分层职责（Controller/Service/Mapper）、参数校验与异常处理、日志规范（@Slf4j + 占位符）、事务管理、常量枚举、注释 JavaDoc、Lombok 使用约定。

约 12 分钟进阶动手写代码前

分层规范异常处理日志事务

数据库与检查 · 动手前必读2 篇

SQL 版本化规范

目录结构（sql/ 镜像分支树：release / feature / tag）、脚本命名（<序号>_<语义>.sql，序号即执行顺序）、分支目录映射与生命周期、增量幂等原则、标准模板、CHANGELOG 登记与现场执行流程。

约 8 分钟进阶改数据库前

SQL 版本化幂等脚本 CHANGELOG 迁移清单

提交前检查清单

提交前 11 项自检清单：分支命名、提交信息、定制归属、SQL 幂等、文件误提交、接口注解、代码规范等逐项检查。附分支类型速查卡。

约 5 分钟入门每次提交前

检查清单速查卡自检

其他规范 · 进阶协同3 篇

其他建议规范

仓库卫生（目录合并、.gitignore 补全、已入库文件清理）、文档规范、发布流程 SOP、前后端协同（接口先行、版本号联动）。

约 7 分钟入门进阶了解

仓库卫生发布 SOP 前后端协同

发版与现场验证

发版检查单四阶段（冻结与验证 → SQL 定稿 → 冻结与打包 → 交付与收尾）、现场验证记录模板（回流门禁的凭证）、分支与 SQL 五条硬规则与红线速查。

约 6 分钟入门发版前必读

发版检查单现场验证红线速查

文档目录规范

doc/ 目录镜像分支树：五级判定「文档放哪」、生命周期与分支联动（创建 / 合入 / 发版 / 删除）、固定名三件套与 doc/README.md 唯一入口、与 SQL 侧同构对照。

约 6 分钟入门进阶了解

五级判定固定名三件套同构对照

历史问题1 篇

历史问题与迁移任务

项目历史遗留问题梳理（分支堆积、命名不统一、定制污染、SQL 散落）与待执行迁移任务清单（分支重命名、SQL 脚本归档）。

历史问题迁移任务负责人确认

术语表新人速查

按主题分成六张表，全部展开，遇到生词直接在本页 Ctrl+F。

Git 基础

术语	说明
`branch`分支	代码的「平行宇宙」。从主线拉出一个副本做修改，不影响主线，做完再合并回去。→ 详见 01
`merge`合并	把一个分支的改动融合到另一个分支。
`cherry-pick`摘樱桃	从一个分支「摘」某几个 commit 到另一个分支，不合并整个分支。定制复用通用修复时用。→ 详见 03
`tag`标签	给某个时刻的代码打一个不可移动的标记，用于标识发布版本（如 `v2.1.0`）。
`commit`提交	Git 保存一次改动的「快照」，需附带一条符合规范的提交信息。→ 详见 02
`MR`Merge Request 合并请求	GitLab 上的合并请求，需他人审查通过后才能合并到主线。
`Git Hook`	Git 在特定操作前自动执行的脚本，本项目用它拦截不规范的分支名和提交信息。
`GitFlow`	一种分支管理模型。我们参考它但做了简化——不设 develop 分支，release 分支直接承担集成职责。

分支类型

术语	说明
`release/`版本主线	长期保留的版本基线分支，如 `release/2.1.1`。
`feature/`功能开发	从 release 拉出，开发新功能，做完合回 release。期限 ≤2 周。
`hotfix/`现场修复	从对应 release 分支头（= 现场已验证状态）拉出，禁改库，验证后双向回流到原版本和下个版本 release。
`custom/`客户定制	从 release 分支头拉出并保持下行同步，禁止合回任何 release，单独打安装包交付该客户。
`dev/`个人临时	个人实验分支，用完即删，期限 ≤3 天。
`main`主干	项目主分支，通常只在发版时更新，日常开发不直接提交到 main。
回流	把子分支的改动合并回主线，保证主线包含所有修复。hotfix 必须双向回流。
现场验证	回流门禁：分支经现场（或等价环境）部署验证并落 `doc/branch/<分支路径>/验证记录.md` 后，才允许回流 release。→ 详见 09
维护性微版本	四段版本号（`vX.Y.Z.N`）的补丁通道：多现场通用 DB 修复的出口，允许改库、走完整验证与回流。三段 = 正式版，四段 = 微版本。

提交规范

术语	说明
`Conventional Commits`约定式提交	提交信息格式约定：`<type>(<scope>): <subject>`，统一风格便于自动生成更新日志。→ 详见 02
`type`提交类型	`feat`（新功能）、`fix`（修复）、`docs`（文档）、`refactor`（重构）、`chore`（杂项）等。
`scope`改动范围	模块标识：`bacnet`、`modbus`、`energy`、`fe`（前端）等，前后端共用。
`subject`简短描述	一句话说清改了什么，可用中文，但 type/scope 必须英文。

代码架构

术语	说明
`Controller`控制器	接收请求、校验参数、调用 Service、返回 `Result<T>`。不写业务逻辑。→ 详见 05
`Service / ServiceImpl`服务层	业务逻辑所在。Service 是接口，ServiceImpl 是实现（事务加在这层）。
`Mapper`数据访问层	负责与数据库交互，执行 SQL。不写业务判断。
`DTO`入参数据包	Data Transfer Object，前端传给后端的入参。→ 详见 04
`VO`出参数据包	View Object，后端返回给前端的出参。
`Entity`实体类	对应数据库表的 Java 类。
事务 `Transaction`	一组操作要么全成功、要么全回滚，保证数据一致性。用 `@Transactional(rollbackFor=Exception.class)`。
幂等 `Idempotent`	执行多次和执行一次效果相同，增量 SQL 脚本的核心要求。→ 详见 06

SQL 版本化

术语	说明
增量脚本	只做「加法」（新增列/表/索引），不破坏已有数据。区别于全量建库。→ 详见 06
`CHANGELOG`	变更日志，记录每个 SQL 脚本的执行情况与现场登记，现场升级的依据。
全量建库	从零建整个数据库，存于 `sql/release/2.1.0/`（首个规范化交付基线），新现场首次部署用。
`<序号>_<语义>.sql`	增量脚本的命名规范（2.1.1 起），如 `release/2.1.1/3_modbus.sql`——序号即执行顺序。

接口与框架

术语	说明
`Swagger / OpenAPI`	自动生成 API 文档的工具，通过代码注解生成可交互的接口文档页面。本项目用 springdoc-openapi。→ 详见 04
`@Tag / @Operation / @Schema`	OpenAPI3 注解：分别标注接口分组、接口功能、字段说明。必填。
`@Validated`	Spring 参数校验注解，自动校验入参是否符合 DTO 上的 JSR-303 约束。
`@Transactional`	Spring 事务注解，标记方法为事务方法，异常时自动回滚。加在 ServiceImpl 上。
`@Slf4j`	Lombok 注解，自动生成日志对象 `log`，配合 `{}` 占位符使用。
`SPI`服务发现机制	Service Provider Interface，Java 的服务发现机制，EasyPro 用它加载协议驱动。
`Result<T>`	本项目统一返回包装类，所有 Controller 方法返回它，含 code/msg/data。