Showing
3 changed files
with
370 additions
and
0 deletions
AGENTS.md
0 → 100644
| 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) |
skill/开发流程.md
0 → 100644
| 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 需同步什么 |
skill/避坑清单.md
0 → 100644
| 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 | +``` |