Skip to content

开发指南 ​

1. 环境 ​

组件版本说明
JDK8(可编译运行)当前机器默认 17 也可编译,但生产按 8 对齐
Maven3.9+41 个 reactor 项目
MySQL8.0库名 pmforge-jdk8
Redis3.x+缓存与消息(IoT 消息总线用 local 时不依赖 5.0)
Node20+前端与文档站

2. 首次启动 ​

bash
# 1) 建库并导入
mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS \`pmforge-jdk8\` DEFAULT CHARACTER SET utf8mb4"
mysql -uroot -p pmforge-jdk8 < sql/mysql/pmforge.sql

# 2) 构建后端
mvn -B -ntp -Dmaven.test.skip=true package

# 3) 构建前端(产物进 server 静态目录)
cd web/pmforge-ui-web && npm install && npm run build

# 4) 以 demo profile 启动(启用 Quartz、演示模式、IoT 本地总线)
java -jar apps/pmforge-server/target/pmforge-server.jar --spring.profiles.active=demo

访问:http://localhost:48080/(门户)、/login(admin / admin123)、/doc.html(Knife4j)。

3. 本地开发 ​

  • 后端热启动:mvn -pl apps/pmforge-server -am spring-boot:run -Dspring-boot.run.profiles=demo
  • 前端热更新:cd web/pmforge-ui-web && npm run dev(Vite 代理 /admin-api 到 48080)
  • 代码生成:/app/infra/codegen 从库表生成 CRUD 代码;模板在 modules/infra/src/main/resources/codegen/。

4. 新增模块/接口的流程 ​

  1. 在 modules/<module> 建 Controller / Service / Mapper / DO,遵循既有分层。
  2. 加权限点 → 同步 sql/*/pmforge.sql 的 system_menu。
  3. 若需在演示站可见:在 apps/pmforge-server/pom.xml 加依赖,web/pmforge-ui-web/src/modules.ts 打开 status: 'live'。
  4. 若要在演示站开放写能力:在 web/pmforge-ui-web/src/bizModules.ts 的对应页面加 write 配置 (apiCreate/apiUpdate/apiDelete + perm* + fields + vo;只做启停/删除时用 statusToggle + apiDelete), BizListView 会自动显示「可编辑演示 / 可启停 / 只读演示」徽标,按钮可见性由后端权限点决定。 目前已开放的页面(9 个完整 CRUD):CRM 客户、WMS 仓库、MES 车间、会员等级、会员标签、 商品分类、商品品牌、文章分类、轮播图;优惠券模板只开放「启停 + 删除」。 后端只提供 /list(返回数组、不分页)的页面,在页面配置里写 apiList,CrudPage 会自动切到列表模式并隐藏分页器。 vo 写后端对应的 *SaveReqVO/*BaseVO 路径,node tools/arch/check-write-config.mjs 会校验 「VO 上的 @NotNull/@NotBlank 字段是否都在表单里」「表单字段是否都在 VO 里」「createDefaults 是否是表单字段」, 这类漂移的典型表现是页面正常、点保存才 500。CI 的 contract job 会跑它。
  5. 演示数据可随时重置:node tools/demo/reset-demo.mjs(删除主键 900000–929999 的演示行后重新导入三批种子), --dry-run 只看 SQL,--no-seed 只清理不导入。改过种子数据后记得同步 sql/demo/README.md。 写能力改完后跑一次 node tools/demo/smoke-write.mjs(每个可写页面走 创建→更新→列表可见→删除), 它和只读冒烟 node tools/demo/smoke.mjs --strict 一起在 CI 的 demo-smoke job 里执行。
  6. 跑 mvn compile、npm run docs:gen && npm run docs:check、npm run build(前端)、npm run code:write-config(写配置契约)。
  7. 提交并附验证证据(接口 200 / 截图 / 日志)。

5. 常见问题 ​

现象原因处理
启动报 Unknown database没有建库执行第 2 步
启动报 Redis 版本不足IoT 消息总线为 redisdemo profile 已改为 local
登录 401未初始化菜单/用户重新导入 sql/mysql/pmforge.sql
前端 404未构建静态资源npm run build 后重新打包 jar
docs:check 失败生成物漂移npm run docs:gen 后重试