朱子纯 / erp-workflow-plugin

一、后端规范

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-USR-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 重建后按上述时序重新注入即可（数据可复现、不持久）。