避坑清单 — 星云 ERP
持续补充:每次解决一个新坑,追加一条(编号递增),写清「坑 → 后果 → 正确做法」。 开发前通读,开发中怀疑踩坑时回来对照。
1. 同一功能的多个查询接口口径必须一致
坑:弹窗查询用 process_status = 'COMPLETED' + frozen = 0,而提交校验用 approval_status = 'PASS',且校验不查 frozen。
后果:前端能选出来的计划,提交时被后端拒绝;或被冻结的计划能通过校验。
正确做法:同一业务对象的所有查询/校验路径统一同一筛选口径(过磅码单已统一为:未删除 + 未冻结 + process_status='COMPLETED' + 不在变更/补单中);新增接口时先 Grep 该表已有查询条件。
2. PageHelper 分页只拦截 startPage 后的第一条 SQL
坑:PageHelperUtil.startPage 与目标查询之间插入了其他查询(如校验用的 count),分页作用到错误的 SQL 上。
正确做法:startPage 紧贴目标查询;需要预校验的逻辑放在 startPage 之前。返回统一 PageResultUtil.convert(new PageInfo<>(datas))。改完接口响应结构会从数组变 {datas, total, ...},必须提醒前端。
3. 逻辑删除 + 唯一键(如 uk_pwt_code)
坑:作废是 deleted=1 逻辑删除,行不物理删除;若取号/查重过滤了 deleted,作废单编号会被复用,撞数据库唯一键。
正确做法:编号类查询(findMaxCodeByPrefix、唯一性 count)不过滤 deleted,并写注释说明"避免与作废单据编号重复"。单列唯一键与逻辑删除自洽,不要改成 (code, deleted) 复合唯一。
4. MyBatis-Plus updateById 的 NOT_NULL 策略会忽略 null 字段
坑:想通过 updateById 清空某字段(置 null),实际 SQL 根本不带该字段,清不掉。
正确做法:需要显式覆盖(含清空)的字段,用 Wrappers.lambdaUpdate(X.class).set(X::getField, value)...eq(...) 逐个 set;批量改字段前想清楚哪些值可能为 null。
5. 数量单位:采购计划=吨,过磅码单=公斤
坑:从计划/计划明细带出数量直接入库或返回,单位错了 1000 倍。
正确做法:跨模块取数统一走 convertTonToKilogram(BigDecimal.movePointRight(3),无精度损失,null 安全),入口(保存子表)和出口(查询返回)都要换算;新代码涉及数量先问单位。
6. Warm-Flow 集成易漏项
-
BPM_FLAG常量值必须与流程设计器里的流程编号完全一致,否则startInstance失败 - 流程结束回调必须在
BusinessDataHandlerServiceImpl的 switch 注册case,忘了注册 = 单据永远停在 AUDIT -
REVOKE(撤销)/TERMINATION(终止)也要映射到 REFUSE,别只处理 REFUSE - 接入流程后:审核按钮
showExamine必须"当前用户有待办 && AUDIT",不能再按状态硬判;本地 examine 接口应删除 - 列表和详情两条返回路径都要调用
fillOperateFlags
7. 编辑锚点不唯一导致改错位置
坑:文件里存在多个相同代码块(如多处 return PageResultUtil.convert(new PageInfo<>(datas));),用短锚点做替换会命中第一个,方法插错位置甚至误删其他方法。
正确做法:替换锚点必须带上下文保证唯一(方法签名/相邻独有行);插入后 Read 回读确认位置;对含重复片段的大文件尤其小心。
8. 改字段名/删字段前必须全局查引用
坑:Vo 字段改名(如 supplierId→supplierName)后,其他地方仍调用旧 getter,编译失败或静默丢参。
正确做法:先 Grep 字段名|Getter名 全仓确认引用点;XML 里的 #{vo.xxx} / test="vo.xxx" 也要同步搜(Java 诊断查不出 XML 引用)。
9. XML 公共 SQL 片段的改动影响所有引用方
坑:为某个查询在 <sql id> 里加 JOIN/列,导致复用该片段的其他查询行为改变或列名冲突(别名重复)。
正确做法:改公共片段前 Grep <include refid="该片段"> 列出所有使用方逐一核对;加 JOIN 用主键关联(一对一)避免行数膨胀;别名避免与既有别名冲突。
10. 数据库字符集/排序规则兼容
坑:新表用错字符集(utf8mb4_bin vs utf8mb4_general_ci vs utf8mb3),关联查询隐式转换或比较不一致。 正确做法:新表/加列跟随同业务老表的字符集与排序规则(过磅码单系 utf8mb4_general_ci,部分老表 utf8mb3);写 SQL 前先看目标表 DDL。
11. 新增字段的完整同步链
坑:只改了 entity,XML resultMap/SELECT、Vo、Bo 漏改,导致查询列缺失或保存丢字段。
正确做法:按 skill/.trae/skills/新增字段 清单走:base.sql(ALTER 追加)→ entity → XML(resultMap+SELECT) → QueryVo/CreateVo/UpdateVo → GetBo;BeanUtil.copyProperties / BaseBo 构造按同名字段自动映射,字段名必须对齐。
12. 非持久化展示字段用 @TableField(exist = false)
坑:把列表聚合值(GROUP_CONCAT 的 plan_codes)、关联名称(workshop_code)、按钮标记(showExamine)当持久字段建列或漏注解,MP 生成 SQL 报"列不存在"。
正确做法:库中没有的字段一律 @TableField(exist = false);由 XML JOIN/子查询填充,或 Service 层回填并给默认值(如 = false 防止序列化出 null)。
13. 单据状态变更不要"顺带"重置审核状态
坑:修改单据时强制 set(approvalStatus, DRAFT),导致驳回单(REFUSE)修改后状态错乱。
正确做法:修改只改业务字段;状态机流转只发生在明确的状态动作里(submit→AUDIT、流程回调→PASS/REFUSE)。驳回单修改后保持 REFUSE,可直接重新提交。
14. 时间语义字段要写清记录时机
坑:firstGrossWeightTime(首次毛重时间)曾在错误的地方(上传签字凭证)赋值;与"完成时间"混用。
正确做法:每个时间字段的注释写明"以什么为准、何时记录、能否覆盖";多入口赋值前先判断"已记录则不再覆盖"。
15. 模糊筛选注意 NULL 与多值字段
坑:LIKE '%补%' 不会命中 NULL(正常计划 plan_type 为 NULL),"精确查正常"和"不传查全部"语义不同;多值字段(如 "变 补")用 LIKE 才能同时命中组合值。
正确做法:筛选语义与用户确认(不传=全部?要不要"正常"选项?);多值枚举字段沿用项目既有 LIKE 方式(参考 ProcurementPlanMapper 的 plan_type)。
16. POI CellStyle 水平对齐方法名是 setAlignment 而非 setHorizontalAlignment
坑:POI 的 CellStyle 接口设置对齐的方法命名不对称:水平对齐是 setAlignment(HorizontalAlignment),垂直对齐才是 setVerticalAlignment(VerticalAlignment);按直觉写 setHorizontalAlignment 会编译报"找不到符号"。
后果:编译失败(IDE 诊断即可发现)。
正确做法:照抄 ExcelUtil.buildPdfVerticalTitleStyle(ExcelUtil.java 约 408 行):style.setAlignment(HorizontalAlignment.CENTER) + style.setVerticalAlignment(VerticalAlignment.CENTER);克隆样式用 cloneStyleFrom 后再改对齐,避免破坏模板边框。
17. BaseBo 子类必须显式声明两个构造器,否则实体转 Bo 属性全空
坑:项目惯例 GetXxxBo extends BaseBo<Xxx> 必须显式写两个构造器:无参(Jackson/MyBatis 反序列化用)和 GetXxxBo(Xxx dto) { super(dto); }(负责把实体属性拷贝进 Bo)。Controller 里 list.stream().map(GetXxxBo::new) 依赖带参构造器完成转换,漏写则编译报错或运行时拿到全空壳数据。
后果:列表/详情接口返回的字段全为 null(或编译报"构造器无法应用"),前端拿到空数据。
正确做法:新建 Bo 时照抄既有 Bo 的构造器写法,例如:
public GetXxxBo() {
super();
}
public GetXxxBo(Xxx dto) {
super(dto);
}
18. 同一业务概念的字段全链路命名必须与源表/已有实现保持一致
坑:新模块引用已有表的字段时自创命名——如过磅明细的"过磅品种"在源表叫 product_id/product_name(关联 base_data_breed_relationship),新化验送样表却写成 breed_relationship_id/breed_name;同类先例:申请明细的品种代号是 category、采购计划明细也是 product_id。
后果:DB 列 → 实体 → VO/Bo → XML → 前端字段各层对不上,联调时前端要额外记忆映射关系,后续维护者搜字段名搜不全,返工改名牵扯全链路(SQL/实体/VO/Bo/XML/前端传参全要动)。
正确做法:动手前先 Grep 源表字段在项目里的既有命名,新表字段、实体属性、VO/Bo 字段、XML 列名、前端传参全部沿用同一名字;仅在语义确实不同(如"品种代号 category"与"品种ID product_id"是两个东西)时才用不同字段名。
19. XML 里主表别名统一用 tb,禁止自创缩写别名
坑:写新查询时自创主表缩写别名(如 pwt/paa),甚至 FROM 定义的别名与 SELECT/WHERE 用的不一致——FROM procurement_weighing_ticket AS tb 但各处引用 pwt.xxx,运行时报"Unknown column 'pwt.id'"。项目全库(30+ 个 Mapper XML)惯例是主表别名一律 tb。
后果:SQL 运行时才报错(Java 诊断查不出);别名不一致的 SQL 拷贝拼接时极易引入此类错误。
正确做法:任何 XML 的主表(业务单据自身表)统一写 FROM 表名 AS tb,SELECT/WHERE/JOIN ON/ORDER BY 全部用 tb. 前缀;只有 JOIN 进来的关联表才用有区分度的别名(如 ws、bdcs、子表 pwtp、明细 pwtl)。新写 SQL 前先看同目录既有 XML 的别名写法,保持一致。
20. MP getById 查不出 exist=false 字段;分厂审核单据传实体给流程引擎前必须联表带出 workshopCode
坑:分厂相关单据的审核节点编码 = 流程前缀 + 分厂前缀(base_data_workshop.code,如 yfc/efc/sfc/ztfc)+ 环节缩写(如 material_settle_yfcckzg)。单据实体只有 workshop_id/workshop_name(冗余列),workshopCode 是 @TableField(exist = false) 联表字段;this.getById(id) 是 MP 单表查询,查出的实体 workshopCode 永远为 null,startInstance(BPM_FLAG, id, BPM_FLAG, entity) 传给流程引擎的实体就缺分厂前缀。
后果:流程引擎按分厂前缀路由审核节点/角色(material_settle_yfcckzg 等)时匹配不上,审核流向错误或全部落到无分厂节点。
正确做法:涉及分厂审核的单据(原料结算详情单等)Mapper XML 提供 findById(公共片段 LEFT JOIN base_data_workshop ws ON ws.id = tb.workshop_id 带出 ws.code AS workshop_code);提交审核、传实体给流程引擎、以及后续涉及分厂审核路由的取数统一用 mapper.findById(id),不用 getById(参考 ProcurementMaterialSettleDetailServiceImpl.submit)。列表查询若要展示编号,同理在列表公共片段里 JOIN 带出。
回写模板(新增踩坑时复制)
## N. 标题
**坑**:
**后果**:
**正确做法**: