docs-04-skeleton-template.md 3.91 KB

Edit Raw Blame History



一、后端规范


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 把本轮新迁移晋升到源库。