主题
项目质量自检与缺陷清单
本文记录 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 / 315 | system 35/199、infra 16/116 |
| 唯一权限点(代码) | 296 | 全部能在菜单里找到(缺失 0) |
| 菜单权限点(SQL) | 1 324 | 其中 1 028 个暂无代码使用,集中在 12 个预留模块 |
| 数据对象 / DDL 表(MySQL) | 373 / 48 | 325 个 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/FIXME | 215 处 | 多数在预留模块,system/infra 共 11 处 |
System.out.print | 30 处 | banner 12 处(有意)、iot Modbus 演示 18 处;DemoJob 1 处已改为日志 |
printStackTrace | 2 处 | 均为「写字符串 / 演示程序」,非缺陷 |
空 catch | 0 | 无 |
3. 已修复(第一波,均已编译验证)
| # | 位置 | 问题 | 修复 |
|---|---|---|---|
| 1 | pmforge-framework/.../biz/system/logger/dto/OperateLogCreateReqDTO.java | 缺少操作结果字段,system_operate_log.success 永远写入默认值 | 新增 Boolean success |
| 2 | pmforge-module-system/.../dal/dataobject/logger/OperateLogDO.java | DO 未映射 success 列,查询结果丢失 | 新增 Boolean success |
| 3 | .../vo/operatelog/OperateLogRespVO.java | 列表/详情不返回操作结果 | 新增字段 + @ExcelProperty("操作结果") |
| 4 | .../vo/operatelog/OperateLogPageReqVO.java | 无法按操作结果筛选 | 新增字段 |
| 5 | .../dal/mysql/logger/OperateLogMapper.java | 分页条件缺 success | 追加 eqIfPresent |
| 6 | pmforge-spring-boot-starter-security/.../LogRecordServiceImpl.java | 未回填操作结果 | reqDTO.setSuccess(!logRecord.isFail()) |
| 7 | pmforge-module-infra/.../enums/ErrorCodeConstants.java | CODEGEN_IMPORT_COLUMNS_NULL 与 CODEGEN_TABLE_EXISTS 同码 1_001_004_002 | 改为 1_001_004_003 |
| 8 | pmforge-spring-boot-starter-web/.../ApiAccessLogInterceptor.java | 用 System.out.printf 打印控制器路径 | 改为 log.debug + @Slf4j |
| 9 | pmforge-module-system/.../job/DemoJob.java | 演示任务用 System.out.println | 改为 log.info |
| 10 | sql/*/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 逐条核对后按性质分类,本轮不做代码改动:
| 类别 | 数量 | 位置 | 结论 |
|---|---|---|---|
| 测试环境 workaround | 15 | system 的 4 个 OAuth2 测试、infra 的 3 个日志测试 | 「expiresTime / createTime 被屏蔽,仅 Win11 复现」属测试用例对时间精度的规避,不是产品缺陷,保留注释即可 |
| 上游依赖等待 | 3 | PmforgeJustAuthConfiguration、AuthRequestFactory | 等 JustAuth 1.4.1 发布后可去掉双 Bean 兼容代码,需外部依赖,当前不动 |
| 产品功能缺口 | 2 | SmsCodeServiceImpl 每 IP 每天/每小时发送上限 | 需先在 SmsCodeProperties 定义阈值与 Redis key 规则,属新功能,单独立项 |
| 示例代码注释 | 4 | Demo01/Demo03 的 DO 与 RespVO | @DictFormat("system_user_sex") 的 TODO 是演示「字典常量应集中定义」,不影响运行 |
- 结论:无「应改而未改」的 TODO;剩余项均已说明理由或转为独立需求。
P2-3 文档与数字一致性
- 已完成:能力地图、模块总览、代码索引、数据字典均引用同一份扫描结果;
docs:check会因代码漂移失败。 - 待做:把本页的统计数字接入
docs/reference/索引-按代码找功能,作为「一页看全貌」的入口。
5. 模块纳管与全量测试(2026-11-18)
5.1 让 12 个预留模块进入 Reactor
目标:把「默认注释、不参与构建」的 12 个业务模块逐个打开,用编译与测试验证技术债,而不是等要用时才发现编不过。
| 波次 | 模块 | 结果 | 本轮处理 |
|---|---|---|---|
| 1 | member、pay、bpm | ✅ 编译通过 | 无(pay 只有 MapStruct 未映射告警) |
| 2 | mall、crm | ✅ 编译通过 | pmforge-module-trade-api 是空模块:把 TradeOrderApi、TradeOrderRespDTO、TradeOrderCancelTypeEnum / TradeOrderStatusEnum / TradeOrderTypeEnum 从 trade 主模块迁入(同包名),TradeOrderApiImpl 留在 trade;trade-api 补 lombok;statistics 依赖 trade |
| 3 | erp、wms、im、iot、mes | ✅ 编译通过 | 无 |
| 4 | mp、report | ✅ 编译通过 | 无 |
- 结果:根
pom.xml共 17 个<module>;mvn -Dmaven.test.skip=true package产出pmforge-server.jar146.5 MB(2026-11-18 15:42 构建,2 分 21 秒)。 - 口径提醒:编译通过不等于可用——这 12 个模块的库表、菜单、配置项都还没接入
pmforge-server。
5.2 全量测试暴露并修复的问题
| # | 现象 | 根因 | 修复 |
|---|---|---|---|
| 1 | DesensitizeTest 报 NoClassDefFound org/mockito/session/MockitoSessionLogger | BOM 排除了 mockito-core,pmforge-common 只引入 spring-boot-starter-test | 给 pmforge-common/pom.xml 加 mockito-inline(test scope) |
| 2 | 同一用例断言 "张***" 失败 | 去痕把测试数据 芋艿 换成了 ASCII,姓名脱敏规则是「保留 1 位 + 其余 *」 | 数据改 张明远、断言改 张** |
| 3 | codegen 模板测试 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 个文件) |
| 5 | 6 个分页用例 expected 1 but was 0 | 去痕只改了数据或只改了查询词(芋艿→张、yunai→pmforge),两边对不上 | 数据与查询词成对修正(dict、menu、sms、social、tenant、bpm、codegen、config、mail) |
| 6 | SmsChannelServiceTest 报 Value too long for column signature(10) | 数据被替换成 PMForge Team(12 字符) | 改为 PMForge |
| 7 | system_operate_log 插入报 Column "success" not found | H2 测试建表脚本没跟上 DO 新增字段 | 测试 create_tables.sql 补 success bit NOT NULL DEFAULT TRUE |
| 8 | PayOrderServiceTest 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-mattertitle开头。- 代码引用有歧义时(同一后缀命中多个文件)由「文件不存在」改为明确报「有歧义,请写全路径」;示例路径必须带
*或写「示例」。 - 修正 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,已修)
| 模块 | 权限点 | 处置 |
|---|---|---|
| crm | performance-config:{query,create,update,delete}、statistics-performance-target:query、statistics-product:query | 新增 6 行,挂 系统配置(2524) / 统计报表(2560) |
| iot | device:auth-info、device:message-end、scene-rule:{query,create,update,delete} | 新增 2 行挂 设备管理(4008);另 5 行 iot:rule-scene:* 改名为 iot:scene-rule:* |
| mes | md-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) | 10 | system: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-18 | v1.5 | 完成搭建配置大小写、多库菜单一致性、25 个缺失菜单权限、48 个孤儿的分类、325 张表 DDL 骨架 |
| 2026-11-18 | v1.4 | 2026-11-18 |
| v1.3 | 纳入 12 个预留模块构建;修复全量测试暴露的 8 类问题;补充模块纳管与测试记录 | |
| 2026-11-17 | v1.2 | 完成 P1-1 错误码去重(1 482 个定义全部唯一) |
| 2026-11-17 | v1.1 | 首次全仓自检:修复 11 项(含 demo03 10 个单测),登记 P1-1 与 P2 3 项 |