## 一、后端规范

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

### 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`（DROP+CREATE 空库）→ 起后端（Flyway 建 schema）→ `node scripts/seed-demo-data.mjs`。
- e2e 基线 = 演示种子已注入（前端 Playwright globalSetup 走上述时序）；后端单测/集成测基线 = 空库，不注入种子。
- 幂等账本表 `_demo_seed_history` 由 `seed-demo-data.mjs` 自建自管，已应用文件自动跳过；库被各测试闸门 DROP+CREATE 重建后按上述时序重新注入即可（数据可复现、不持久）。