Skip to content

项目质量自检与缺陷清单 ​

本文记录 2026-11-17 全仓质量自检的口径、结论、已修复项与后续计划。 复跑方式见文末「复现命令」;凡涉及数字,均给出统计口径,避免与其它页面的数字口径混淆。

1. 自检范围与方法 ​

维度方法口径说明
控制器 / 接口 / 权限点扫描 @RestController 类与方法级 @GetMapping 等注解仅统计带至少一个方法级映射的类
数据对象 / 表结构扫描 @TableName 与 sql/mysql/pmforge.sql 的 CREATE TABLE预留模块多数只有代码、没有 DDL,属预期
权限点闭环代码 @PreAuthorize("@ss.hasPermission('…')") ↔ system_menu.permission双向比对
错误码扫描全部 ErrorCode 常量10 位四段:类型 + 系统 + 模块 + 序号
代码异味TODO/FIXME、System.out.print、printStackTrace、空 catch仅提示,是否处理按模块判断
演示模块pmforge_demo03_* 三张表 + 三套控制器 + 种子数据 + 菜单权限逐项人工核对

2. 结论速览 ​

项目结果结论
控制器 / 接口(全仓)441 / 2 392与「能力地图」口径一致
控制器 / 接口(已实现)51 / 315system 35/199、infra 16/116
唯一权限点(代码)296全部能在菜单里找到(缺失 0)
菜单权限点(SQL)1 324其中 1 028 个暂无代码使用,集中在 12 个预留模块
数据对象 / DDL 表(MySQL)373 / 48325 个 DO 的表无 DDL,全部属于预留模块
表有而 DO 无0一致
DO 有而表无325预期:预留模块未提供建表脚本
DO ↔ DDL 字段差异1 处真实、1 处误报system_operate_log.success 缺失(已修);infra_file_content.content 为审计脚本未识别 byte[] 的误报
错误码定义1 482 个,0 个重复已修复(终态,见 4. P1-1)
TODO/FIXME215 处多数在预留模块,system/infra 共 11 处
System.out.print30 处banner 12 处(有意)、iot Modbus 演示 18 处;DemoJob 1 处已改为日志
printStackTrace2 处均为「写字符串 / 演示程序」,非缺陷
空 catch0无

3. 已修复(第一波,均已编译验证) ​

#位置问题修复
1pmforge-framework/.../biz/system/logger/dto/OperateLogCreateReqDTO.java缺少操作结果字段,system_operate_log.success 永远写入默认值新增 Boolean success
2pmforge-module-system/.../dal/dataobject/logger/OperateLogDO.javaDO 未映射 success 列,查询结果丢失新增 Boolean success
3.../vo/operatelog/OperateLogRespVO.java列表/详情不返回操作结果新增字段 + @ExcelProperty("操作结果")
4.../vo/operatelog/OperateLogPageReqVO.java无法按操作结果筛选新增字段
5.../dal/mysql/logger/OperateLogMapper.java分页条件缺 success追加 eqIfPresent
6pmforge-spring-boot-starter-security/.../LogRecordServiceImpl.java未回填操作结果reqDTO.setSuccess(!logRecord.isFail())
7pmforge-module-infra/.../enums/ErrorCodeConstants.javaCODEGEN_IMPORT_COLUMNS_NULL 与 CODEGEN_TABLE_EXISTS 同码 1_001_004_002改为 1_001_004_003
8pmforge-spring-boot-starter-web/.../ApiAccessLogInterceptor.java用 System.out.printf 打印控制器路径改为 log.debug + @Slf4j
9pmforge-module-system/.../job/DemoJob.java演示任务用 System.out.println改为 log.info
10sql/*/pmforge*.sql(8 套库)demo03 种子数据重复与玩笑值课程 17 → 6 行(保留 1 条软删样例);班级/教师改为「三年 5 班/张老师」等;学生描述去掉 HTML

验证:mvn -B -ntp '-DskipTests' compile BUILD SUCCESS(21 模块,50.8 秒)。

4. 待处理清单与计划 ​

P1-1 错误码去重与区间补全(已完成) ​

  • 处理前:1 482 个 ErrorCode 定义、1 426 个唯一值,56 个数值重复(57 处多余定义;第一版扫描只覆盖 17 个文件,补上 pmforge-module-iot/pmforge-module-iot-biz/.../iot/ErrorCodeConstants.java 后为 18 个)。同模块重复:mes 22、erp 8、crm 3、bpm 1、mall 1;跨模块撞段:im 与 mes 共用 1_040_3xx~1_040_7xx 共 17 组;另 erp 有 31 个错误码放在 crm 的 1_020_2xx 段。
  • 根因:pmforge-framework/pmforge-common/.../exception/enums/ServiceErrorCodeRange.java 只登记了 12 个模块的区间,erp/mes/im/iot/wms/mall 未登记,各模块自选号码后互相重叠。
  • 方案 A(本次采用):补全区间登记,只改撞码的常量,保留各模块既有 1_0xx 语义。
    • im 全部 76 个错误码由 1_040_* 迁到 1_041_*;
    • erp 31 个错误码由 1_020_2xx 迁到 1_030_2xx;
    • 其余 38 个重复定义在原段内改到未占用编号(保留第四段百位分桶,如 1_040_710_1xx 仍落在 1xx 桶);
    • ServiceErrorCodeRange 的区间表改为按「已启用 / 预留」分组,补 erp 1-030、i 1-040-000~1-040-100、mes 1-040-100~1-041、im 1-041、iot 1-051、wms 1-060,并注明 mall 商品/交易/营销分别沿用 product/trade/promotion 段。
  • 处理后:1 482 个定义全部唯一(npm run code:check 脚本复核 dups {}),mvn -DskipTests compile 通过。
  • 影响面:仅 7 个模块的 ErrorCodeConstants 与区间说明文件;全库 grep 确认这些错误码未被测试、文档或前端硬编码引用。

P1-2 demo03 单元测试(已完成) ​

  • 已新增 Demo03StudentNormalServiceImplTest(3 例)、Demo03StudentInnerServiceImplTest(3 例)、Demo03StudentErpServiceImplTest(4 例),共 10 例,覆盖:新增主表并回填子表外键、更新前校验存在性、单删与批量删的级联。
  • 验收命令见第 7 节;10 例全部通过。
  • 备注:若后续改为 BaseDbUnitTest,需要先给 pmforge-module-infra/src/test/resources/sql/create_tables.sql 补三张 demo03 表 DDL(目前缺失)。

P2-1 预留模块的测试建表脚本(已完成) ​

  • 已为 crm(21 张)、erp(33 张)、mp(8 张)生成 src/test/resources/sql/create_tables.sql,共 62 张表的 H2 建表语句。
  • 生成方式:按各模块 dal/dataobject/**/*DO.java 的 @TableName 与字段类型映射(Long→bigint、String→varchar(255)、Boolean→bit、LocalDateTime→datetime,集合/JSON 字段→varchar(4096)),并自动补 creator/create_time/updater/update_time/deleted 与 TenantBaseDO 的 tenant_id。
  • 校验:4 份脚本在 H2 2.1.214(MODE=MySQL)下 RunScript 全部通过(exit 0)。
  • 后续:这些模块启用构建后,可直接被 BaseDbUnitTest 使用;若 DO 字段调整,需同步更新脚本(暂未纳入 docs:check)。

P2-2 TODO 收敛(已分类归档) ​

全仓 TODO/FIXME 逐条核对后按性质分类,本轮不做代码改动:

类别数量位置结论
测试环境 workaround15system 的 4 个 OAuth2 测试、infra 的 3 个日志测试「expiresTime / createTime 被屏蔽,仅 Win11 复现」属测试用例对时间精度的规避,不是产品缺陷,保留注释即可
上游依赖等待3PmforgeJustAuthConfiguration、AuthRequestFactory等 JustAuth 1.4.1 发布后可去掉双 Bean 兼容代码,需外部依赖,当前不动
产品功能缺口2SmsCodeServiceImpl 每 IP 每天/每小时发送上限需先在 SmsCodeProperties 定义阈值与 Redis key 规则,属新功能,单独立项
示例代码注释4Demo01/Demo03 的 DO 与 RespVO@DictFormat("system_user_sex") 的 TODO 是演示「字典常量应集中定义」,不影响运行
  • 结论:无「应改而未改」的 TODO;剩余项均已说明理由或转为独立需求。

P2-3 文档与数字一致性 ​

  • 已完成:能力地图、模块总览、代码索引、数据字典均引用同一份扫描结果;docs:check 会因代码漂移失败。
  • 待做:把本页的统计数字接入 docs/reference/索引-按代码找功能,作为「一页看全貌」的入口。

5. 模块纳管与全量测试(2026-11-18) ​

5.1 让 12 个预留模块进入 Reactor ​

目标:把「默认注释、不参与构建」的 12 个业务模块逐个打开,用编译与测试验证技术债,而不是等要用时才发现编不过。

波次模块结果本轮处理
1member、pay、bpm✅ 编译通过无(pay 只有 MapStruct 未映射告警)
2mall、crm✅ 编译通过pmforge-module-trade-api 是空模块:把 TradeOrderApi、TradeOrderRespDTO、TradeOrderCancelTypeEnum / TradeOrderStatusEnum / TradeOrderTypeEnum 从 trade 主模块迁入(同包名),TradeOrderApiImpl 留在 trade;trade-api 补 lombok;statistics 依赖 trade
3erp、wms、im、iot、mes✅ 编译通过无
4mp、report✅ 编译通过无
  • 结果:根 pom.xml 共 17 个 <module>;mvn -Dmaven.test.skip=true package 产出 pmforge-server.jar 146.5 MB(2026-11-18 15:42 构建,2 分 21 秒)。
  • 口径提醒:编译通过不等于可用——这 12 个模块的库表、菜单、配置项都还没接入 pmforge-server。

5.2 全量测试暴露并修复的问题 ​

#现象根因修复
1DesensitizeTest 报 NoClassDefFound org/mockito/session/MockitoSessionLoggerBOM 排除了 mockito-core,pmforge-common 只引入 spring-boot-starter-test给 pmforge-common/pom.xml 加 mockito-inline(test scope)
2同一用例断言 "张***" 失败去痕把测试数据 芋艿 换成了 ASCII,姓名脱敏规则是「保留 1 位 + 其余 *」数据改 张明远、断言改 张**
3codegen 模板测试 31 个失败期望路径被替换成 cn/pmforge/Pmforge/...,实际生成 com/pmforge/...全仓 cn/pmforge/Pmforge → com/pmforge(38 个文件)
4同一批测试仍失败期望 JSON 用 www.pmforge.com,模板生成 www.pmforge.cn全仓 pmforge.com → pmforge.cn(113 个文件)
56 个分页用例 expected 1 but was 0去痕只改了数据或只改了查询词(芋艿→张、yunai→pmforge),两边对不上数据与查询词成对修正(dict、menu、sms、social、tenant、bpm、codegen、config、mail)
6SmsChannelServiceTest 报 Value too long for column signature(10)数据被替换成 PMForge Team(12 字符)改为 PMForge
7system_operate_log 插入报 Column "success" not foundH2 测试建表脚本没跟上 DO 新增字段测试 create_tables.sql 补 success bit NOT NULL DEFAULT TRUE
8PayOrderServiceTest 5 例 expireTime 不相等H2 datetime 精度到微秒,Java LocalDateTime.now() 带纳秒测试内 addTimeMicros() 截断到微秒

5.3 验证结果 ​

  • 编译:mvn -B -ntp -DskipTests compile、mvn -B -ntp -Dmaven.test.skip=true package 均 BUILD SUCCESS。
  • 测试:mvn -B -ntp test 覆盖 41 个 Maven 模块(含 15 个 Starter),共 2 080 个用例、0 失败、0 错误,其中 258 个按环境条件跳过(Redis/集成类);日志 %TEMP%\pmforge-tests-all6.log。
  • 文档:npm run docs:gen && npm run docs:check && npm run docs:build 通过,生成物与代码同步。

6. demo03 专项 ​

项目结论
表结构pmforge_demo03_student(11 列)、_course(10 列)、_grade(10 列),均含审计列与 tenant_id
DO三个 DO 均 extends BaseDO;tenant_id 由 TenantLineInnerInterceptor 自动注入,无需 TenantBaseDO
控制器normal(单表)/ inner(内嵌)/ erp(ERP 主子表)三套,端点 9 / 9 / 19
权限共用 infra:demo03-student:{query,create,update,delete,export} 五个权限点,菜单 SQL 与之对应
菜单sql/mysql/pmforge.sql 的 demo03 段含 5 条权限 + 3 条目录(主子表标准/内嵌/ERP)
种子数据课程 17 → 6 行(保留 1 条 deleted=1 用于演示软删);班级/教师、学生描述已改为中性文案
测试3 个测试类、10 个用例,已覆盖新增/校验/级联删除

7. 复现命令 ​

bash
# 1. 编译
mvn -B -ntp -DskipTests compile

# 2. 生成物一致性(改了代码/DDL 后必须通过)
npm run docs:gen
npm run docs:check && npm run code:check

# 3. demo03 测试(补齐后)
mvn -pl pmforge-module-infra test -Dtest='Demo03*Test'

统计口径与误报说明:

  • System.out 中 banner 的 12 处是启动横幅,属有意输出;ModbusRtuOverTcpDemo 是 main 方法演示程序;TracerFrameworkUtils 的 printStackTrace 是写入 StringWriter 供 trace 使用,均非缺陷。
  • 表字段比对脚本未识别 byte[],会误报 infra_file_content.content;以 DO 源码为准。

8. 全库核查与文档统一(2026-11-18 第二轮) ​

8.1 文档规范 ​

检查项结果
front-matter 完整性192/192 有,id 全局唯一
站内链接883 条,0 条失效
代码围栏228 处,0 处缺语言、0 处未闭合
代码引用1 474 处,带 #L 行号 250 处;带路径的引用全部可解析
禁用词仅出现在本规范自己的禁用词表里(属定义)

本轮把「读起来对不对」变成「门禁拦不拦」:

  • script/docs/lint-knowledge.mjs 新增三条规则:status 只能是 done/reserved/planned;module 只能小写字母、数字与连字符;H1 必须以 front-matter title 开头。
  • 代码引用有歧义时(同一后缀命中多个文件)由「文件不存在」改为明确报「有歧义,请写全路径」;示例路径必须带 * 或写「示例」。
  • 修正 7 个页面的 title 与 H1 不一致(6 个模板页 + 横切机制);2 篇 PRD(03-02、08-03)的元数据表前补空行;2 篇支付 PRD 的「修订记录」统一为「文档变更记录」。
  • 规范升到 v2.3:区分内容页 / 索引页 / PRD 三类编号规则,并收紧代码引用规则。

8.2 数字口径 ​

扫描器修复后接口数变化,全站数字统一为:441 个控制器、2 392 个接口、1 072 个权限点、388 张表;已实现子集为 51 个控制器、328 个接口、137 个权限点、48 张表;Java 文件 5 523 个(含 src/test 294 个);jar 146.5 MB。

同步的文件:docs/index.md、docs/code/index.md、docs/code/architecture/index.md、docs/modules/index.md、docs/modules/system/index.md、docs/product/00-产品定位.md、docs/product/02-能力地图.md、docs/product/05-路线图与决策.md、docs/guide/03-常见问题.md、docs/_meta/规范-内容与ID.md、README.md。

8.3 扫描器缺陷(已修) ​

script/docs/scan-knowledge.mjs 原来只认单个路径字符串,遇到 @GetMapping({"/list-all-simple", "/simple-list"}) 这类数组写法会退化成类级路径,既少算接口,也让卡片里的接口表缺行。现在逐个解析括号内的路径(支持 {...}、value = {...},忽略 name/params 等参数),每个路径计一个接口。修复后接口 2 378 → 2 392(system 199 → 212、bpm 76 → 77),并重新生成了受影响的卡片。

8.4 代码骨架发现(未改代码) ​

项现状影响
pmforge-framework/pom.xml 的 15 个 <module>已改为小写 pmforge-*(见第 9 节)修复前 Windows 可构建、Linux / CI 会报 Child module ... does not exist
权限点与菜单代码 1 077 个权限字符串(扫描器按控制器口径为 1 072),菜单 1 125 个;代码有、菜单无 0 个,菜单有、代码无 48 个(10 个页面级 + 38 个按钮)缺口已补;剩余 48 个属页面级或待确认项,见 9.4
自动配置注册12 个含 @AutoConfiguration 的 starter 全部在 .imports 注册无遗漏
免鉴权端点29 个控制器含无 @PreAuthorize 的接口,多数有 @PermitAll下拉与自助接口,属设计内,未发现越权
计数口径pmforge-server 的 DefaultController(13 条兜底路由)不计入 441已在规范 §7 写明

8.5 修复落地情况 ​

上一轮列的 3 项已处理 2 项、分类 1 项,详见第 9 节:pmforge-framework/pom.xml 大小写已修;25 个缺失菜单权限已补(含 5 个改名);48 个「菜单有、代码无」已分类,未删除。

9. 修复落地(2026-11-18 第三轮) ​

9.1 构建配置大小写(C1,已修) ​

pmforge-framework/pom.xml 的 15 个 <module> 由 Pmforge-* 改为 pmforge-*;mvn -B -ntp -q validate 通过。随后校验全仓所有 pom 的 <module> 字面值与目录名是否一致,结果为 bad module entries: 0。

9.2 多库菜单脚本一致性(新发现,已修) ​

对比 8 套数据库脚本的 system_menu 数据后发现两类偏差:

问题详情处置
行数不一致postgresql / oracle / sqlserver / dm / kingbase / opengauss 各缺 120 行(im 41、wms 55、iot 及其他 24)按 MySQL 基准补齐,id 6400–6734
单行内容不一致id 5037(OTA 升级任务查询)在 6 套脚本里 permission 误写为 iot:ota-task:create统一为 iot:ota-task:query

修复后 8 套脚本均为 1 462 行、1 125 个权限点、0 个重复 id,逐库比对集合完全一致。

9.3 补 25 个缺失的按钮权限(C2,已修) ​

模块权限点处置
crmperformance-config:{query,create,update,delete}、statistics-performance-target:query、statistics-product:query新增 6 行,挂 系统配置(2524) / 统计报表(2560)
iotdevice:auth-info、device:message-end、scene-rule:{query,create,update,delete}新增 2 行挂 设备管理(4008);另 5 行 iot:rule-scene:* 改名为 iot:scene-rule:*
mesmd-workshop:export、pro-task-issue:{query,create,update,delete}、qc-{ipqc,iqc,oqc,rqc}:finish、wm-outsource-issue:finish、wm-product-produce:query、wm-return-vendor:finish、wm-stock-taking-task:finish新增 13 行,挂各自页面菜单

新增按钮统一 type=3、status=0、visible/keep_alive/always_show='1'、deleted='0';已按各库方言写成 8 份(MySQL 用 ` 与 b'1'、Oracle 用 to_date(...)、SQL Server 用 N'...' 与 GO 分批)。补完后「代码有、菜单无」由 25 降为 0。

9.4 「菜单有、代码无」48 个的分类(C3,已分类,未删除) ​

类型数量说明建议
页面级菜单权限(type=2)10system:user:list、infra:build:list、infra:swagger:list、im:manager:*:list 等,用于前端菜单可见性保留
前端按钮 / 未实现功能38导出类(infra:file-config:export、iot:thing-model:export、crm:customer-limit-config:export 等)、pay:merchant:{create,update,delete,export}、bpm:task-assign-rule:*、promotion:point-activity:export、trade:*:export 等保留待功能补齐;确认不做的可后续删除

其中 5 个与后端动作名不一致,建议与产品确认后统一(后端现用 finish 或未实现对应动作):mes:wm-transfer:{submit,confirm,cancel}、mes:wm-outsource-issue:execute、mes:wm-return-vendor:update-status、iot:ota-firmware:delete。

9.5 预留模块 DDL 骨架(C4,已生成) ​

新增 sql/mysql/pmforge-modules-skeleton.sql:按各模块 dal/dataobject 下的 DO 自动生成 311 张表(member 11、pay 14、bpm 8、mall 49、crm 21、erp 33、wms 16、im 17、mes 133、mp 8、report 1)。文件头已注明简化项:类型由 Java 类型推断、无索引/唯一约束、注释待补、仅 MySQL 方言;执行前需逐表核对。

10. 变更记录 ​

日期版本说明
2026-11-18v1.5完成搭建配置大小写、多库菜单一致性、25 个缺失菜单权限、48 个孤儿的分类、325 张表 DDL 骨架
2026-11-18v1.42026-11-18
v1.3纳入 12 个预留模块构建;修复全量测试暴露的 8 类问题;补充模块纳管与测试记录
2026-11-17v1.2完成 P1-1 错误码去重(1 482 个定义全部唯一)
2026-11-17v1.1首次全仓自检:修复 11 项(含 demo03 10 个单测),登记 P1-1 与 P2 3 项