主题
工程规范
1. 仓库结构
build/pmforge-bom Maven BOM(依赖版本唯一出口)
framework/ 15 个 starter(含 pmforge-common)
modules/ 业务模块:system、infra、member、bpm、pay、mp、crm、erp、wms、mes、im、report
modules/mall product / promotion / trade / trade-api / statistics
modules/iot iot-core / iot-biz / iot-gateway
apps/pmforge-server 唯一可启动应用(单端口 48080,托管前端静态资源)
web/pmforge-ui-web 前端源码(Vue3 + Vite + TS + Tailwind + shadcn 风格)
docs/ 知识库(冻结)+ engineering/(本手册)
sql/ 各数据库脚本(mysql/postgresql/oracle/sqlserver/dm/kingbase/opengauss/highgo)
tools/ 工程脚本(docs 生成、校验)
deploy/ docker / ci / scripts2. 分支与提交
- 主分支
main保持可构建、可启动;功能分支feat/<scope>-<summary>。 - 提交信息遵循 Conventional Commits:
feat|fix|docs|build|refactor|test|chore(scope): summary。 - 一个 PR 只做一件事;涉及数据库变更必须同时提供
sql/脚本与回滚说明。
3. 代码规范
- 后端:Java 8、Lombok、MapStruct;Controller 只做参数与转换,业务在 Service,SQL 在 Mapper。
- 包路径:
com.pmforge.module.<module>.<layer>;跨模块只允许依赖<module>.api包(既有违规清单见docs/reference/项目质量自检与缺陷清单.md)。 - 前端:Vue 组合式 API +
<script setup lang="ts">;组件放components/,页面放views/,状态放stores/。 - 禁止提交:密钥、真实账号、
target/、node_modules/、dist/(前端产物由构建写入apps/pmforge-server/src/main/resources/static,不手工提交)。
4. 质量门禁
| 门禁 | 命令 | 说明 |
|---|---|---|
| 后端编译 | mvn -B -ntp -DskipTests compile | 41 个 reactor 项目 |
| 后端测试 | mvn -B -ntp test | 2 080 用例(含 H2 集成测试) |
| 后端打包 | mvn -B -ntp -Dmaven.test.skip=true package | 产出 apps/pmforge-server/target/pmforge-server.jar |
| 前端构建 | cd web/pmforge-ui-web && npm run build | 产物写入 server 静态目录 |
| 知识库校验 | npm run docs:check | 扫描器 + PRD 对齐 + lint |
| 错误码唯一 | npm run code:check | 全局错误码不得重复 |
5. 文档规范
- 知识库页面遵循
docs/_meta/规范-内容与ID.md(v2.4):front-matter、功能点 ID、质量分级 A/B/C。 - 工程手册(本目录)使用「## 1. 二级标题」编号,不写 front-matter。
- 新增/修改接口后必须重跑
npm run docs:gen,否则 CI 会因生成物漂移失败。
6. 安全
- 密钥只进环境变量或配置中心,不进 Git;现有示例值已替换为占位符。
- 跨租户、数据权限、鉴权相关改动必须有测试;演示环境的写操作允许,但生产必须走审批流。