# abacus.springboot.example — 开发规范（CONVENTIONS）

> 命名、目录、提交、风格、测试的权威（本仓库视角）。前后端共享约束见工作区 `docs/coding-standards.md`（`../../../../docs/coding-standards.md`），本文只写后端特有内容 + 指针，**禁止复制 docs/ 正文**。

## 0. 阅读指引

- 适用范围：`src/main/java/abacus/springboot.<应用名>/**` 业务开发（模板基础结构 pom/assembly/config 原则上不动）。
- 分工：ARCHITECTURE 管"拆成什么模块"；本文管"怎么命名/写"；共享编码规范、接口契约、SQL 约定、AI 生成工作流在 `docs/coding-standards.md` §5~§7。

## 1. 命名

### 1.1 标识符

- 类：PascalCase；接口带后缀 `IF`（pi 层 `XxxAccessIF`、wsi 层 `XxxServiceIF`）；编排服务 `XxxBizService`；实现 `XxxAccess`。
- Controller：`XxxController`（api 对外 / controller 内部）；基类 `BaseServlet`。
- 实体：表名小写下划线（`jc_bill`），类名驼峰（`JcBill`）；DTO：请求 `ApiReqXxx`、响应 `ApiRespXxx` 或 `ApiXxx`（api/view）。
- 配置：`XxxConfiguration`、`XxxConfigKey`（常量类）。

### 1.2 模块命名（语义禁区）

- 禁止 `Manager` / `Helper` / `Util` / `Common` / `Misc` / `Tools` 这类语义为空的名字；用"动词+名词"。
- **util/ vo/ 兼容**：既有 `util/DateUtil`、`vo/BaiduToken` 等**可引不可增**——新代码禁止在 `util/`、`vo/` 包新增文件（共享规范 §8.4）。

### 1.3 文件 / 1.4 目录 / 1.5 资产命名

- 文件按类名命名（一文件一公共类）；目录即包名（分层见 ARCHITECTURE §6）。
- SQL：`sql/table/{mysql,sqlserver}.sql`、`sql/upgrade.xml`、`sql/data/`；版本号 `yyyy-MM-dd[.count]`。

### 1.6 字符串与本地化

- 异常消息中文、可行动（"参数[x]为空！"）；不硬编码无意义字符串；状态常量用 `public final static int STATUS_*`。

## 2. 代码风格

### 2.1 排版

- Java 4 空格缩进、行宽 ≤ 120；分号/括号按 Java 惯例。
- 不使用 Lombok（手写 getter/setter，与示例一致）。

### 2.2 分层纪律

- Controller 只做参数校验 + 调编排，不写 SQL、不碰 Repository；esb 只编排不做 SQL。
- 原生 SQL 在 `impl/`，**全量 `?` 参数化**；标准 CRUD/派生查询用 `repository`。
- 业务主键一律 `DaoIdGenerator`，禁止手拼。

### 2.3 并发 / 2.4 错误处理

- 事务边界在 esb 编排方法（按需 `@Transactional`）；JPA 乐观锁用 `@Version`。
- 业务错误抛 `BusinessException`（中文消息）；Controller 方法级 try/catch(Throwable) 记日志后 rethrow；**禁止吞异常**。

### 2.5 注释

- 每个方法必须写注释（一行职责说明，复杂方法补充入参/出参/边界，便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。

## 3. 提交规范

### 3.1 Commit message 风格

Conventional Commits：`type(scope): subject`。允许 type：`feat` / `fix` / `docs` / `refactor` / `test` / `chore`。例：`feat(jcbill): 新增稽查收货保存接口`。

### 3.2 提交粒度 / 3.3 工作区纪律 / 3.4 分支模型

- 一次提交一个目的；不在脏工作区叠加不相关改动。
- 分支模型：主干 + 短命功能分支（按需，单人开发可直推主干）。
- 本仓库属于工作区单一 git 仓库（`D:\workBuddySpace\member`）；纯后端改动 commit 限定本目录，跨项目改动（docs/）单独 commit。

### 3.5 实施日志

- 规则见 `VIBECODING_GUIDE §5`：每个可独立验收的部分写 `.project.agents/log/YYYY-MM-DD-<slug>.md`。
- 功能更新同步追加 `src/main/resources/doc/升级日志.md`（共享规范 §5.11 格式）。

## 4. 测试策略

### 4.1 框架 / 4.2 必须有测试的模块

- 无自动化测试框架（PRD 决策）；接口人工冒烟。

### 4.3 必须真机/真环境验证

- **必须真机验证**（mock/模拟器不算数）：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移。

## 5. 与上游文档的同步矩阵

| 变更点 | 必须同步更新 |
|---|---|
| 新增/改动业务功能 | `PRD.md`（功能定义）；共享规范如有涉及先改 `docs/coding-standards.md` |
| 新增包/模块/依赖方向 | 本仓库 `ARCHITECTURE.md` §2+§3 |
| 新增 SQL/表结构 | `sql/table/` 双份 + `sql/upgrade.xml`；`ARCHITECTURE.md §1` 实体清单 |
| 配置项变更 | `config/{dev,test,prod}/` 三套同步 |
| 依赖版本变更 | `pom.xml` + `doc/升级日志.md` |

## 6. 不在本文范围（明确划清）

- 模块拆分归 `ARCHITECTURE.md`；行为/范围归 `PRD.md`；前后端共享约束（响应体/异常码/分页/APP_NAME/打包）归 `docs/coding-standards.md`。
