主题
开发指南
1. 环境
| 组件 | 版本 | 说明 |
|---|---|---|
| JDK | 8(可编译运行) | 当前机器默认 17 也可编译,但生产按 8 对齐 |
| Maven | 3.9+ | 41 个 reactor 项目 |
| MySQL | 8.0 | 库名 pmforge-jdk8 |
| Redis | 3.x+ | 缓存与消息(IoT 消息总线用 local 时不依赖 5.0) |
| Node | 20+ | 前端与文档站 |
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. 新增模块/接口的流程
- 在
modules/<module>建 Controller / Service / Mapper / DO,遵循既有分层。 - 加权限点 → 同步
sql/*/pmforge.sql的system_menu。 - 若需在演示站可见:在
apps/pmforge-server/pom.xml加依赖,web/pmforge-ui-web/src/modules.ts打开status: 'live'。 - 若要在演示站开放写能力:在
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 的contractjob 会跑它。 - 演示数据可随时重置:
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 里执行。 - 跑
mvn compile、npm run docs:gen && npm run docs:check、npm run build(前端)、npm run code:write-config(写配置契约)。 - 提交并附验证证据(接口 200 / 截图 / 日志)。
5. 常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
启动报 Unknown database | 没有建库 | 执行第 2 步 |
| 启动报 Redis 版本不足 | IoT 消息总线为 redis | demo profile 已改为 local |
| 登录 401 | 未初始化菜单/用户 | 重新导入 sql/mysql/pmforge.sql |
| 前端 404 | 未构建静态资源 | npm run build 后重新打包 jar |
docs:check 失败 | 生成物漂移 | npm run docs:gen 后重试 |