Commit 81e0d31b68032184994c9ca8da79434747551bce

Authored by 房远帅
1 parent 91f1bd11

楚江-开发skill

  1 +# AGENTS.md — 星云 ERP 项目 Agent 工作指引
  2 +
  3 +> **每次会话开始前,必须先完整阅读本文件,并按第 5 节索引加载相关 skill 文档后再开始任何开发任务。**
  4 +> 本文件是 Agent 在本项目工作的唯一入口规范,所有开发、修改、排查行为都必须遵守。
  5 +
  6 +---
  7 +
  8 +## 1. 角色定位
  9 +
  10 +你是本项目的**资深 Java 后端开发工程师**,负责星云 ERP(供应链采购/仓储/结算方向)的业务开发与维护:
  11 +
  12 +- 严格遵循项目既有代码风格与分层约定,**先读懂再动手**,禁止凭空臆造项目里不存在的模式
  13 +- 所有改动必须**最小化、聚焦**:只改任务要求的部分,不顺手重构、不加无关注释、不引入新依赖
  14 +- 改动完成后必须自查(编译诊断/引用检查),并主动向用户说明影响范围与需要同步的前端/SQL 事项
  15 +
  16 +## 2. 技术栈(本项目实际使用)
  17 +
  18 +| 类别 | 技术 | 备注 |
  19 +|---|---|---|
  20 +| 语言/运行时 | Java 8、Maven 多模块 | `javax.*` 体系(非 jakarta) |
  21 +| 框架 | Spring Boot + Spring MVC | RESTful Controller |
  22 +| ORM | MyBatis-Plus + MyBatis XML | `BaseMapper`、`Wrappers`、`@TableName` |
  23 +| 分页 | PageHelper | `PageHelperUtil.startPage` + `PageResultUtil.convert(new PageInfo<>())` |
  24 +| 数据库 | MySQL | 脚本在 `xingyun-api/src/main/resources/db/`,字符集 utf8mb4/utf8mb3 混用 |
  25 +| 审核流 | **Warm-Flow**(org.dromara.warm.flow)+ BPM starter | 见 `skill/开发流程.md` 第 5 节 |
  26 +| API 文档 | Swagger(springfox `io.swagger.annotations`) | `@Api/@ApiOperation/@ApiModelProperty` |
  27 +| 其他 | Lombok、Redis(RedisHandler)、MQ(MqProducerService)、POI(Excel 导入导出) | |
  28 +
  29 +## 3. 项目结构(多模块)
  30 +
  31 +```
  32 +xingyun-erp/
  33 +├── xingyun-api/ 启动模块 + 全部数据库脚本(db/chujiang/base.sql 为主)
  34 +├── xingyun-sc/ 核心业务模块(采购/销售/仓储/合同/结算单据,本次主要工作区)
  35 +│ └── src/main/java/com/lframework/xingyun/sc/
  36 +│ ├── controller/ 接口层
  37 +│ ├── service/ 服务接口
  38 +│ ├── impl/ 服务实现
  39 +│ ├── entity/ 数据库实体
  40 +│ ├── vo/ 请求参数(Query/Create/Update 前缀)
  41 +│ ├── bo/ 返回对象(Get 前缀 / 查询 Bo)
  42 +│ ├── mappers/ Mapper 接口(XML 在 resources/mappers/ 同名目录)
  43 +│ └── handlers/ BPM 流程处理器(BusinessDataHandlerServiceImpl 等)
  44 +├── xingyun-basedata/ 基础数据(品种/分厂/公司简称/客户等)
  45 +├── xingyun-settle/ 结算模块
  46 +├── xingyun-comp/ 组件(文件箱/在线 Excel)
  47 +└── .trae/skills/ 可调用技能库(见第 5 节)
  48 +```
  49 +
  50 +分层命名约定:`XxxController → XxxService → XxxServiceImpl → XxxMapper(+XML) → entity`;
  51 +入参 `QueryXxxVo/CreateXxxVo/UpdateXxxVo`,出参 `GetXxxBo` 或实体,统一用 `InvokeResultBuilder.success()` 包装。
  52 +
  53 +## 4. 核心开发流程(概要,详见 skill/开发流程.md)
  54 +
  55 +1. **读代码**:先搜同类功能的现有实现(Controller/ServiceImpl/Mapper.xml 各层),照抄项目模式
  56 +2. **动手**:按 自底向上(XML/Mapper → Service → Controller)顺序改,遵循 HTTP 方法规范(查询 GET / 新增 POST / 修改 PUT / 删除 DELETE,见 `.trae/rules/方法类型.md`)
  57 +3. **带审核流的单据**:BPM_FLAG → startInstance → BusinessDataHandlerServiceImpl 注册 case → updateApprovalStatus 回调 → fillOperateFlags 待办按钮
  58 +4. **验证**:每轮改动后用 IDE 诊断检查所有被改文件;涉及 XML 的检查 resultMap/列名/别名一致性
  59 +5. **收尾汇报**:列改动清单 + 前端需同步点(字段改名/响应结构变化/传参变化)+ 存量库需执行的 SQL
  60 +
  61 +## 5. Skill 索引(按需加载)
  62 +
  63 +### 5.1 项目 skill 文件夹(`skill/`,本次会话必读的标 ⭐)
  64 +
  65 +| 文档 | 内容 | 何时读 |
  66 +|---|---|---|
  67 +| ⭐ `skill/开发流程.md` | 角色定位、技术栈细节、分层规范、**Warm-Flow 审核流完整接入步骤**、单据开发清单 | 任何开发任务开始前 |
  68 +| ⭐ `skill/避坑清单.md` | 踩坑记录(持续补充):口径一致性、PageHelper、逻辑删除+唯一键、单位换算、MyBatis-Plus 更新策略等 | 任何开发任务开始前;解决问题后回写新坑 |
  69 +
  70 +### 5.2 可调用技能(`.trae/skills/`,触发对应场景时调用 Skill 工具)
  71 +
  72 +| 技能 | 触发场景 |
  73 +|---|---|
  74 +| `warm-flow审核流程` | 涉及审核流/流程接入 |
  75 +| `列表查询接口` | 新建/修改列表查询接口(统一分页风格) |
  76 +| `新增字段` | 实体加字段(各层同步清单) |
  77 +| `数据库sql` | 生成 SQL(字符集兼容等注意事项) |
  78 +| `明细列表数据导出` | 列表数据导出 Excel |
  79 +| `系统导入` | 导入功能 |
  80 +| `打印/导出pdf` | 打印/导出 PDF |
  81 +
  82 +### 5.3 工作区规则(`.trae/rules/`)
  83 +
  84 +- `方法类型.md`:新增用 POST、修改用 PUT、删除用 DELETE、查询用 GET
  85 +
  86 +## 6. 单据导出(打印)模板填充规范
  87 +
  88 +单据打印 = 用 Excel 模板(`xingyun-sc/src/main/resources/templates/*.xlsx`)按占位符填充后输出。参考实现:
  89 +- `ProcurementPlanController.export`(纯占位符填充)
  90 +- `CoordinationSummaryApprovalController.print`(动态行插入)
  91 +- `ProcurementWeighingTicketController.export`(动态行 + 占位符混合,过磅码单)
  92 +
  93 +固定套路(Controller 内完成,不起 Service 层):
  94 +
  95 +1. 接口:`@GetMapping("/export")`,参数 id,方法返回 `void`,入参加 `HttpServletResponse response`;权限 `@HasPermission({"xxx:print"})`(:print 后缀)
  96 + - 需要多种输出时参考 `PurchaseOrderInfoController.printPurchaseOrder`:加 `exportType`("PDF" 走 LibreOffice 转 PDF,默认 Excel)与 `templateType`(字符串区分多套模板)两个 query 参数;PDF 分支 = `ResponseUtil.setPDFResponseHead` → 临时 xlsx(`File.createTempFile` + `workbook.write`)→ `ExcelUtil.convertExcelToPdf(tempExcel, "/usr/bin/libreoffice --headless --convert-to pdf --outdir %s %s")` → 流式输出 → finally 删临时文件;Excel 分支 = `ResponseUtil.setExcelResponseHead` + `workbook.write`(响应头须在分支内设置,不能提前定死 Excel 头)
  97 +2. 响应头:`ExcelUtil.setupResponse(response, 编号 + "-单据名.xlsx")`(`com.lframework.xingyun.sc.utils.ExcelUtil`)
  98 +3. 开模板:`new ClassPathResource("templates/xxx.xlsx").getStream()`(hutool)→ `new XSSFWorkbook(inputStream)`,try-with-resources
  99 +4. 动态行(明细条数不固定):先 `sheet.shiftRows(起始行+1, sheet.getLastRowNum(), 插入行数, true, true)` 整体下移,再循环复制模板行样式(`newRow.setHeight` + 逐格 `nc.setCellStyle(tc.getCellStyle())`),最后 `ExcelUtil.setCellValue(sheet, 行, 列, 值)` 逐格填充
  100 +5. 静态占位符:模板单元格写 `${字段名}`(支持 `#{}`),Java 组装 `Map<String, Object>` 后调用 `processTemplateSheet(sheet, dataMap)` 遍历 STRING 单元格 replace(私有方法,各 Controller 持有副本,照抄即可)
  101 +6. 输出:`workbook.write(response.getOutputStream())` + `flush()`;异常包装为 `RuntimeException("模板文件不存在/无法读取模板文件: templates/xxx.xlsx")`
  102 +
  103 +注意事项:
  104 +- 动态行行索引用 0-based 常量定义(如 `APPLY_START_ROW = 4` = Excel 第 5 行),以模板实际行为准;确认模板可解压看 `xl/worksheets/sheet1.xml`(合并单元格/占位符/行列位置)
  105 +- 占位符可能嵌在长文本中间(如“单位:公斤 … ${firstGrossWeightTime}”),字符串 replace 天然支持
  106 +- 数字大写直接用 hutool:`NumberChineseFormatter.format(value.doubleValue(), true)` 输出“壹万贰仟叁佰肆拾伍点陆”(位名万仟佰拾、小数读点),再拼单位后缀如“公斤”
  107 +- BigDecimal 填充:展示列用 `formatDecimal`(stripTrailingZeros 去尾零转字符串),数值列可 `ExcelUtil.setCellValue` 直写 BigDecimal(内部转 double 保留样式)
  108 +
  109 +## 7. 硬性纪律
  110 +
  111 +- **不创建不必要的文件**;能改现有文件就不新建
  112 +- **不使用 emoji**;注释、报错文案用中文,与现有代码一致
  113 +- **改前必读**:任何文件编辑前先 Read 该文件相关段落,禁止盲改
  114 +- **不擅自 git commit/push**,除非用户明确要求
  115 +- 数量单位敏感:采购计划=**吨**,过磅码单=**公斤**,跨模块取数必须换算(见避坑清单 #5)
... ...
  1 +# 开发流程 — 星云 ERP
  2 +
  3 +> 开发任何功能前先通读本文档。搭配 `AGENTS.md`(入口)与 `skill/避坑清单.md` 使用。
  4 +
  5 +---
  6 +
  7 +## 1. 角色定位
  8 +
  9 +- 身份:星云 ERP 资深 Java 后端开发
  10 +- 行为准则:**先搜后写**——任何新功能先找项目内同类实现(如过磅码单参考采购计划模块),复用其分层结构、命名、分页、响应包装方式;禁止引入项目里没有的框架用法
  11 +- 汇报准则:改完必报「改动清单 + 前端同步点 + 存量库 SQL」,让用户能直接转给前端/DBA
  12 +
  13 +## 2. 技术栈与基础设施
  14 +
  15 +- Java 8 / Spring Boot / Maven 多模块(`javax.*`,勿用 jakarta、勿用 Java 8 以上语法)
  16 +- MyBatis-Plus:`BaseMpServiceImpl<Mapper, Entity>`、`Wrappers.lambdaQuery/lambdaUpdate`
  17 +- 分页:`PageHelperUtil.startPage(pageIndex, pageSize)` → 紧跟第一条查询 → `PageResultUtil.convert(new PageInfo<>(datas))` → Controller 用 `getPageIndex(vo)/getPageSize(vo)`(Vo 继承 `SortPageVo`)
  18 +- Swagger 注解:实体/VO/BO 字段都带 `@ApiModelProperty("中文说明")`
  19 +- 审核流:**Warm-Flow**(详见第 5 节)
  20 +- 消息:站内信走 `MqProducerService.createSysSiteMessage(SysSiteMessageDto)`
  21 +- 角色找人:`sysUserRoleService.listUserIdByRoleCodes(roleCodes)` / `TransactorHandler.listTransactorsByRoleCode`
  22 +
  23 +## 3. 分层与命名规范(以 xingyun-sc 为准)
  24 +
  25 +```
  26 +controller/ XxxController extends DefaultBaseController
  27 + @Api(tags) + @Validated + @RestController + @RequestMapping("/模块/资源")
  28 +service/ XxxService extends BaseMpService<Xxx>
  29 +impl/ XxxServiceImpl extends BaseMpServiceImpl<XxxMapper, Xxx> implements XxxService
  30 +entity/ @TableName("表名"),BaseEntity,createBy/createTime 等用 @TableField(fill = ...)
  31 +vo/ QueryXxxVo(查询,继承 SortPageVo 可分页)/ CreateXxxVo / UpdateXxxVo
  32 +bo/ GetXxxBo extends BaseBo<Xxx>(详情返回);XxxSelectorBo / 分页列表 Bo
  33 +mappers/ XxxMapper extends BaseMapper<Xxx>,XML 放 resources/mappers/<业务>/XxxMapper.xml
  34 +handlers/ BusinessDataHandlerServiceImpl(流程结束回调,见第 5 节)
  35 +```
  36 +
  37 +- 响应统一 `InvokeResultBuilder.success(data)`;分页返回 `InvokeResult<PageResult<Bo>>`
  38 +- 校验:入参 `Assert.notBlank/greaterThanZero`,业务错误 `throw new DefaultClientException("中文提示!")`
  39 +- 操作日志:写操作加 `@OpLog(type = OtherOpLogType.class, name = "...,ID:{}", params = {...})` + `OpLogUtil.setVariable/setExtra`
  40 +
  41 +## 4. 新功能/新单据开发清单
  42 +
  43 +1. **SQL**:`xingyun-api/src/main/resources/db/chujiang/base.sql` 文件尾部追加(新表 `CREATE TABLE IF NOT EXISTS`;已有表加列用 `ALTER TABLE ... ADD COLUMN`,不改原 CREATE)。字符集/排序规则与同业务老表一致(utf8mb4_general_ci 或 utf8mb3)
  44 +2. **Entity**:字段注释中文;非库字段用 `@TableField(exist = false)`
  45 +3. **Mapper + XML**:列表查询统一写 `<sql id="Xxx_sql">` 公共片段 + resultMap;条件用 `<if test="vo.xxx != null and vo.xxx != ''">`;IN 用 `<foreach>`
  46 +4. **Service/Impl**:业务校验、事务 `@Transactional(rollbackFor = Exception.class)`
  47 +5. **Controller**:查询 GET / 新增 POST / 修改 PUT / 删除 DELETE(`.trae/rules/方法类型.md`);权限 `@HasPermission({"模块:资源:动作"})`
  48 +6. **VO/BO**:查询入参 Vo 与列表出参 Bo 字段对齐前端需求
  49 +7. **自查**:GetDiagnostics 全部改动文件;XML 列名/resultMap/别名三处一致
  50 +
  51 +## 5. Warm-Flow 审核流接入(完整步骤)
  52 +
  53 +> 适用:任何需要审批的单据(参考:采购计划 PROCUREMENT_PLAN、过磅码单 WEIGHING_RECORD)
  54 +
  55 +### 5.1 提交侧(XxxServiceImpl)
  56 +
  57 +```java
  58 +private static final String BPM_FLAG = "业务标识"; // 如 WEIGHING_RECORD,需与流程设计器中的流程编号一致
  59 +
  60 +@Resource
  61 +private FlowInstanceWrapperService flowInstanceWrapperService;
  62 +
  63 +// submit() 内:单据状态先置 AUDIT,再发起流程
  64 +this.update(Wrappers.lambdaUpdate(Xxx.class)
  65 + .set(Xxx::getApprovalStatus, STATUS_AUDIT)
  66 + .eq(Xxx::getId, id));
  67 +flowInstanceWrapperService.startInstance(BPM_FLAG, entity.getId(), BPM_FLAG, entity);
  68 +```
  69 +
  70 +### 5.2 流程结束回调(handlers/BusinessDataHandlerServiceImpl)
  71 +
  72 +1. 注入该单据 Service
  73 +2. `businessStatusHandler` 的 switch 中注册 `case "BPM_FLAG":`
  74 +3. 新增私有方法处理结果(项目统一口径):
  75 +
  76 +```java
  77 +private void handleXxxData(String flowStatus, String businessId) {
  78 + if (FlowInstanceStatus.APPROVE_PASS.getCode().equals(flowStatus)
  79 + || FlowInstanceStatus.FINISH.getCode().equals(flowStatus)) {
  80 + xxxService.updateApprovalStatus(businessId, "PASS"); // 通过
  81 + } else if (FlowInstanceStatus.REVOKE.getCode().equals(flowStatus)
  82 + || FlowInstanceStatus.REFUSE.getCode().equals(flowStatus)
  83 + || FlowInstanceStatus.TERMINATION.getCode().equals(flowStatus)) {
  84 + xxxService.updateApprovalStatus(businessId, "REFUSE"); // 驳回/撤销/终止
  85 + }
  86 + // UNDO(撤回)按业务定:多数模块归为 REFUSE,少数(如正式合同)为 CANCEL
  87 +}
  88 +```
  89 +
  90 +4. Service 侧提供 `updateApprovalStatus(String id, String approvalStatus)`:校验存在 → 更新 `approval_status`;有附加联动(如通过后写时间/状态机流转)也在此方法内做
  91 +
  92 +### 5.3 审核按钮标记(列表/详情)
  93 +
  94 +```java
  95 +private void fillOperateFlags(List<Xxx> datas) {
  96 + // 1) 是否发起过流程 → showExamineDetail(有审核状态即可看审批轨迹)
  97 + List<FlowInstanceWrapper> flowList = flowInstanceWrapperService.getFlowByBusinessIdList(businessIds);
  98 + // 2) 当前用户待办 → showExamine(且单据为 AUDIT 才显示审核按钮)
  99 + List<FlowTaskDto> todoList = flowTaskWrapperMapper.queryTodoList(new QueryTodoTaskListVo(), SecurityUtil.getCurrentUser().getId());
  100 +}
  101 +```
  102 +
  103 +- 两个标记是实体上的 `@TableField(exist = false)` 字段,默认 false;分页列表与详情两条返回路径都要调用填充
  104 +- **不要**再按 `approvalStatus` 硬编码判断审核按钮(接入流程后以待办为准)
  105 +- 审核动作本身走统一流程待办接口,**本地不写 examine 接口**
  106 +
  107 +### 5.4 状态机约定
  108 +
  109 +| approvalStatus | 含义 | 可修改 | 可提交 | 可作废 |
  110 +|---|---|---|---|---|
  111 +| DRAFT | 草稿 | ✅ | ✅ | 视业务 |
  112 +| AUDIT | 审核中 | ❌(流程中) | ❌ | ❌ |
  113 +| PASS | 通过 | ❌ | ❌ | ✅ |
  114 +| REFUSE | 已驳回 | ✅(改完保持 REFUSE 可直接重新提交) | ✅ | ❌ |
  115 +
  116 +### 5.5 接入检查清单
  117 +
  118 +- [ ] 流程设计器已建 `BPM_FLAG` 同名流程定义
  119 +- [ ] submit 置 AUDIT + startInstance
  120 +- [ ] BusinessDataHandlerServiceImpl 注册 case + handleXxxData
  121 +- [ ] Service 有 updateApprovalStatus
  122 +- [ ] fillOperateFlags 改为待办驱动(列表 + 详情都调用)
  123 +- [ ] 删除本地 examine 接口(如有)
  124 +
  125 +## 6. 修改既有代码的流程
  126 +
  127 +1. Read 目标文件相关段落(含上下文引用方),Grep 全局确认该方法/字段的**所有调用点**
  128 +2. 评估影响面(尤其是改签名、改字段名、改筛选口径)
  129 +3. 自底向上修改,保持对外行为兼容或明确列出破坏性变更
  130 +4. GetDiagnostics 验证 + 全局 Grep 确认无残留引用
  131 +5. 汇报:改了什么、为什么、前端/SQL 需同步什么
... ...
  1 +# 避坑清单 — 星云 ERP
  2 +
  3 +> **持续补充**:每次解决一个新坑,追加一条(编号递增),写清「坑 → 后果 → 正确做法」。
  4 +> 开发前通读,开发中怀疑踩坑时回来对照。
  5 +
  6 +---
  7 +
  8 +## 1. 同一功能的多个查询接口口径必须一致
  9 +
  10 +**坑**:弹窗查询用 `process_status = 'COMPLETED'` + `frozen = 0`,而提交校验用 `approval_status = 'PASS'`,且校验不查 frozen。
  11 +**后果**:前端能选出来的计划,提交时被后端拒绝;或被冻结的计划能通过校验。
  12 +**正确做法**:同一业务对象的所有查询/校验路径统一同一筛选口径(过磅码单已统一为:未删除 + 未冻结 + `process_status='COMPLETED'` + 不在变更/补单中);新增接口时先 Grep 该表已有查询条件。
  13 +
  14 +## 2. PageHelper 分页只拦截 startPage 后的第一条 SQL
  15 +
  16 +**坑**:`PageHelperUtil.startPage` 与目标查询之间插入了其他查询(如校验用的 count),分页作用到错误的 SQL 上。
  17 +**正确做法**:startPage 紧贴目标查询;需要预校验的逻辑放在 startPage 之前。返回统一 `PageResultUtil.convert(new PageInfo<>(datas))`。改完接口响应结构会从数组变 `{datas, total, ...}`,必须提醒前端。
  18 +
  19 +## 3. 逻辑删除 + 唯一键(如 `uk_pwt_code`)
  20 +
  21 +**坑**:作废是 `deleted=1` 逻辑删除,行不物理删除;若取号/查重过滤了 deleted,作废单编号会被复用,撞数据库唯一键。
  22 +**正确做法**:编号类查询(`findMaxCodeByPrefix`、唯一性 count)**不过滤 deleted**,并写注释说明"避免与作废单据编号重复"。单列唯一键与逻辑删除自洽,不要改成 `(code, deleted)` 复合唯一。
  23 +
  24 +## 4. MyBatis-Plus updateById 的 NOT_NULL 策略会忽略 null 字段
  25 +
  26 +**坑**:想通过 updateById 清空某字段(置 null),实际 SQL 根本不带该字段,清不掉。
  27 +**正确做法**:需要显式覆盖(含清空)的字段,用 `Wrappers.lambdaUpdate(X.class).set(X::getField, value)...eq(...)` 逐个 set;批量改字段前想清楚哪些值可能为 null。
  28 +
  29 +## 5. 数量单位:采购计划=吨,过磅码单=公斤
  30 +
  31 +**坑**:从计划/计划明细带出数量直接入库或返回,单位错了 1000 倍。
  32 +**正确做法**:跨模块取数统一走 `convertTonToKilogram`(`BigDecimal.movePointRight(3)`,无精度损失,null 安全),入口(保存子表)和出口(查询返回)都要换算;新代码涉及数量先问单位。
  33 +
  34 +## 6. Warm-Flow 集成易漏项
  35 +
  36 +- `BPM_FLAG` 常量值必须与流程设计器里的流程编号完全一致,否则 `startInstance` 失败
  37 +- 流程结束回调必须在 `BusinessDataHandlerServiceImpl` 的 switch 注册 `case`,**忘了注册 = 单据永远停在 AUDIT**
  38 +- `REVOKE`(撤销)/`TERMINATION`(终止)也要映射到 REFUSE,别只处理 REFUSE
  39 +- 接入流程后:审核按钮 `showExamine` 必须"当前用户有待办 && AUDIT",不能再按状态硬判;本地 examine 接口应删除
  40 +- 列表和**详情**两条返回路径都要调用 `fillOperateFlags`
  41 +
  42 +## 7. 编辑锚点不唯一导致改错位置
  43 +
  44 +**坑**:文件里存在多个相同代码块(如多处 `return PageResultUtil.convert(new PageInfo<>(datas));`),用短锚点做替换会命中第一个,方法插错位置甚至误删其他方法。
  45 +**正确做法**:替换锚点必须带上下文保证唯一(方法签名/相邻独有行);插入后 Read 回读确认位置;对含重复片段的大文件尤其小心。
  46 +
  47 +## 8. 改字段名/删字段前必须全局查引用
  48 +
  49 +**坑**:Vo 字段改名(如 supplierId→supplierName)后,其他地方仍调用旧 getter,编译失败或静默丢参。
  50 +**正确做法**:先 Grep `字段名|Getter名` 全仓确认引用点;XML 里的 `#{vo.xxx}` / `test="vo.xxx"` 也要同步搜(Java 诊断查不出 XML 引用)。
  51 +
  52 +## 9. XML 公共 SQL 片段的改动影响所有引用方
  53 +
  54 +**坑**:为某个查询在 `<sql id>` 里加 JOIN/列,导致复用该片段的其他查询行为改变或列名冲突(别名重复)。
  55 +**正确做法**:改公共片段前 Grep `<include refid="该片段">` 列出所有使用方逐一核对;加 JOIN 用主键关联(一对一)避免行数膨胀;别名避免与既有别名冲突。
  56 +
  57 +## 10. 数据库字符集/排序规则兼容
  58 +
  59 +**坑**:新表用错字符集(utf8mb4_bin vs utf8mb4_general_ci vs utf8mb3),关联查询隐式转换或比较不一致。
  60 +**正确做法**:新表/加列跟随同业务老表的字符集与排序规则(过磅码单系 utf8mb4_general_ci,部分老表 utf8mb3);写 SQL 前先看目标表 DDL。
  61 +
  62 +## 11. 新增字段的完整同步链
  63 +
  64 +**坑**:只改了 entity,XML resultMap/SELECT、Vo、Bo 漏改,导致查询列缺失或保存丢字段。
  65 +**正确做法**:按 `skill/.trae/skills/新增字段` 清单走:base.sql(ALTER 追加)→ entity → XML(resultMap+SELECT) → QueryVo/CreateVo/UpdateVo → GetBo;BeanUtil.copyProperties / BaseBo 构造按同名字段自动映射,**字段名必须对齐**。
  66 +
  67 +## 12. 非持久化展示字段用 @TableField(exist = false)
  68 +
  69 +**坑**:把列表聚合值(GROUP_CONCAT 的 plan_codes)、关联名称(workshop_code)、按钮标记(showExamine)当持久字段建列或漏注解,MP 生成 SQL 报"列不存在"。
  70 +**正确做法**:库中没有的字段一律 `@TableField(exist = false)`;由 XML JOIN/子查询填充,或 Service 层回填并给默认值(如 `= false` 防止序列化出 null)。
  71 +
  72 +## 13. 单据状态变更不要"顺带"重置审核状态
  73 +
  74 +**坑**:修改单据时强制 `set(approvalStatus, DRAFT)`,导致驳回单(REFUSE)修改后状态错乱。
  75 +**正确做法**:修改只改业务字段;状态机流转只发生在明确的状态动作里(submit→AUDIT、流程回调→PASS/REFUSE)。驳回单修改后保持 REFUSE,可直接重新提交。
  76 +
  77 +## 14. 时间语义字段要写清记录时机
  78 +
  79 +**坑**:`firstGrossWeightTime`(首次毛重时间)曾在错误的地方(上传签字凭证)赋值;与"完成时间"混用。
  80 +**正确做法**:每个时间字段的注释写明"以什么为准、何时记录、能否覆盖";多入口赋值前先判断"已记录则不再覆盖"。
  81 +
  82 +## 15. 模糊筛选注意 NULL 与多值字段
  83 +
  84 +**坑**:`LIKE '%补%'` 不会命中 NULL(正常计划 plan_type 为 NULL),"精确查正常"和"不传查全部"语义不同;多值字段(如 "变 补")用 LIKE 才能同时命中组合值。
  85 +**正确做法**:筛选语义与用户确认(不传=全部?要不要"正常"选项?);多值枚举字段沿用项目既有 LIKE 方式(参考 ProcurementPlanMapper 的 plan_type)。
  86 +
  87 +## 16. POI CellStyle 水平对齐方法名是 setAlignment 而非 setHorizontalAlignment
  88 +
  89 +**坑**:POI 的 CellStyle 接口设置对齐的方法命名不对称:水平对齐是 `setAlignment(HorizontalAlignment)`,垂直对齐才是 `setVerticalAlignment(VerticalAlignment)`;按直觉写 `setHorizontalAlignment` 会编译报"找不到符号"。
  90 +**后果**:编译失败(IDE 诊断即可发现)。
  91 +**正确做法**:照抄 `ExcelUtil.buildPdfVerticalTitleStyle`(ExcelUtil.java 约 408 行):`style.setAlignment(HorizontalAlignment.CENTER)` + `style.setVerticalAlignment(VerticalAlignment.CENTER)`;克隆样式用 `cloneStyleFrom` 后再改对齐,避免破坏模板边框。
  92 +
  93 +## 17. BaseBo 子类必须显式声明两个构造器,否则实体转 Bo 属性全空
  94 +
  95 +**坑**:项目惯例 `GetXxxBo extends BaseBo<Xxx>` 必须显式写两个构造器:无参(Jackson/MyBatis 反序列化用)和 `GetXxxBo(Xxx dto) { super(dto); }`(负责把实体属性拷贝进 Bo)。Controller 里 `list.stream().map(GetXxxBo::new)` 依赖带参构造器完成转换,漏写则编译报错或运行时拿到全空壳数据。
  96 +**后果**:列表/详情接口返回的字段全为 null(或编译报"构造器无法应用"),前端拿到空数据。
  97 +**正确做法**:新建 Bo 时照抄既有 Bo 的构造器写法,例如:
  98 +
  99 +```java
  100 +public GetXxxBo() {
  101 + super();
  102 +}
  103 +
  104 +public GetXxxBo(Xxx dto) {
  105 + super(dto);
  106 +}
  107 +```
  108 +
  109 +## 18. 同一业务概念的字段全链路命名必须与源表/已有实现保持一致
  110 +
  111 +**坑**:新模块引用已有表的字段时自创命名——如过磅明细的"过磅品种"在源表叫 `product_id`/`product_name`(关联 base_data_breed_relationship),新化验送样表却写成 `breed_relationship_id`/`breed_name`;同类先例:申请明细的品种代号是 `category`、采购计划明细也是 `product_id`。
  112 +**后果**:DB 列 → 实体 → VO/Bo → XML → 前端字段各层对不上,联调时前端要额外记忆映射关系,后续维护者搜字段名搜不全,返工改名牵扯全链路(SQL/实体/VO/Bo/XML/前端传参全要动)。
  113 +**正确做法**:动手前先 Grep 源表字段在项目里的既有命名,新表字段、实体属性、VO/Bo 字段、XML 列名、前端传参**全部沿用同一名字**;仅在语义确实不同(如"品种代号 category"与"品种ID product_id"是两个东西)时才用不同字段名。
  114 +
  115 +---
  116 +
  117 +## 回写模板(新增踩坑时复制)
  118 +
  119 +```
  120 +## N. 标题
  121 +**坑**:
  122 +**后果**:
  123 +**正确做法**:
  124 +```
... ...