## 一、后端规范

### 1.1 规则
- 【人工填写：一条后端通用约定，按需复制本行新增更多；无则填「无」】

**测试库 env 贯通（锁定约定，生成时原样保留）**：
- 后端 `application*.yml`（含测试 profile）JDBC URL 的 schema 段一律写成 Spring 占位 `${ERP_TEST_DB_SCHEMA:<database.schema 字面量>__test}`（如 `jdbc:mysql://localhost:3306/${ERP_TEST_DB_SCHEMA:erp_dev__test}?...`）。**缺省值必须是副本库 `<schema>__test`，绝不能是源库 `<schema>` 本身**——测试永远连一次性副本，绝不连、绝不改源库。测试/起栈链经 ERP_TEST_DB_SCHEMA env 指向本次副本（并行 lane 各自副本）；gradle test fork 的 JVM 与 bootRun 默认继承 env，无需拼 `SPRING_DATASOURCE_URL`。
- Flyway 配置 `out-of-order: true`：副本从源库复制而来、自带源库的 `flyway_schema_history`，起后端时 Flyway 只把源库还没有的**本轮新迁移**apply 到副本（历史里已有的自动跳过）。并行版本段下版本号**只保唯一、不保连续、不保合并序**；独立模块的 migration 互不引用（正是同波次并行的准入条件），乱序 apply 安全。

### 1.2 分层结构

### 1.3 命名约定

### 1.4 统一响应格式

### 1.5 异常处理

### 1.6 事务

### 1.7 认证

## 二、前端规范

### 2.1 目录约定

**测试目录隔离（锁定约定，生成时原样保留，项目专属布局写在其后）**：
- 前端交付源码 = `frontend/src/**`，**不含任何测试文件**（对齐后端 `src/main/java` ↔ `src/test/java` 的物理分离）。
- 前端单测（vitest/jest 组件测试）一律放 `frontend/tests/**`，目录结构**镜像** `frontend/src/**`（如 `src/components/AppShell.tsx` ↔ `tests/components/AppShell.test.tsx`）；smoke 类测试归 `frontend/tests/__smoke__/`，**文件名同样以 `.test.*` 结尾**（如 `tests/__smoke__/app.smoke.test.ts`，否则不被 vitest include 匹配）。
- 前端 e2e（Playwright）一律放 `frontend/e2e/**`。
- **禁止** `frontend/src/**` 内出现 `*.test.*` / `*.spec.*` / `__tests__/` / `__mocks__/` / `__smoke__/`；vitest 配置 `include` 限定 `tests/**/*.test.*`（src 内测试残留不被执行，约定漂移立即可见；tests/ 下的 helpers/fixtures 不带 `.test.` 中缀即不被当测试加载）。

### 2.2 状态管理

### 2.3 请求封装

### 2.4 错误处理

## 三、共同约定

### 3.1 Git 提交
`<type>(<scope>): <subject> <req_id>`（req_id = `<模块代码>-<子模块代码>-<功能名>`，如 `USR-UserInfo-Login`）

### 3.2 分页查询

### 3.3 日期与金额

### 3.4 数据访问规约

### 3.5 数据基线与演示种子
- 演示种子 SQL 放 `sql/seed/`，命名 `<NN>__<module_id>.sql`（NN=两位序号，按模块构建顺序；随 git 提交）。
- 注入由 `scripts/seed-demo-data.mjs` 负责：B 阶段每个后端模块完成后生成对应 seed 文件，脚本逐文件按名升序应用。
- 主键区间约定：`1–999`=初始数据（admin_init 等）/ `1000–9999`=演示种子 / `≥100000`=行为验收 sentinel；三段互不重叠，演示数据值不得含 `_S<数字>` 编码串（预留给 sentinel）。
- 注入时序恒为：`node scripts/setup-test-db.mjs`（复制源库→一次性副本）→ 起后端（Flyway apply 本轮新迁移到副本）→ `node scripts/seed-demo-data.mjs`（把源库还没有的新种子灌进副本）。
- e2e 基线 = 源库副本 + 本轮新迁移 + 补充演示种子（前端 Playwright globalSetup 走上述时序）；后端单测/集成测基线 = 源库副本 + 本轮新迁移。
- 幂等账本表 `_demo_seed_history` 由 `seed-demo-data.mjs` 自建自管：副本继承源库账本，源库已灌过的种子自动跳过、只补新种子；副本跑完即删（`scripts/drop-test-db.mjs`），**源库绝不被 drop**（数据可复现、不持久）。测试绿后由 `scripts/promote-to-source.mjs` 把本轮新迁移晋升到源库。