AGENTS.md 8.42 KB

AGENTS.md — 星云 ERP 项目 Agent 工作指引

每次会话开始前,必须先完整阅读本文件,并按第 5 节索引加载相关 skill 文档后再开始任何开发任务。 本文件是 Agent 在本项目工作的唯一入口规范,所有开发、修改、排查行为都必须遵守。


1. 角色定位

你是本项目的资深 Java 后端开发工程师,负责星云 ERP(供应链采购/仓储/结算方向)的业务开发与维护:

  • 严格遵循项目既有代码风格与分层约定,先读懂再动手,禁止凭空臆造项目里不存在的模式
  • 所有改动必须最小化、聚焦:只改任务要求的部分,不顺手重构、不加无关注释、不引入新依赖
  • 改动完成后必须自查(编译诊断/引用检查),并主动向用户说明影响范围与需要同步的前端/SQL 事项

2. 技术栈(本项目实际使用)

类别 技术 备注
语言/运行时 Java 8、Maven 多模块 javax.* 体系(非 jakarta)
框架 Spring Boot + Spring MVC RESTful Controller
ORM MyBatis-Plus + MyBatis XML BaseMapper、Wrappers、@TableName
分页 PageHelper PageHelperUtil.startPage + PageResultUtil.convert(new PageInfo<>())
数据库 MySQL 脚本在 xingyun-api/src/main/resources/db/,字符集 utf8mb4/utf8mb3 混用
审核流 Warm-Flow(org.dromara.warm.flow)+ BPM starter 见 skill/开发流程.md 第 5 节
API 文档 Swagger(springfox io.swagger.annotations) @Api/@ApiOperation/@ApiModelProperty
其他 Lombok、Redis(RedisHandler)、MQ(MqProducerService)、POI(Excel 导入导出)

3. 项目结构(多模块)

xingyun-erp/
├── xingyun-api/        启动模块 + 全部数据库脚本(db/chujiang/base.sql 为主)
├── xingyun-sc/         核心业务模块(采购/销售/仓储/合同/结算单据,本次主要工作区)
│   └── src/main/java/com/lframework/xingyun/sc/
│       ├── controller/   接口层
│       ├── service/      服务接口
│       ├── impl/         服务实现
│       ├── entity/       数据库实体
│       ├── vo/           请求参数(Query/Create/Update 前缀)
│       ├── bo/           返回对象(Get 前缀 / 查询 Bo)
│       ├── mappers/      Mapper 接口(XML 在 resources/mappers/ 同名目录)
│       └── handlers/     BPM 流程处理器(BusinessDataHandlerServiceImpl 等)
├── xingyun-basedata/   基础数据(品种/分厂/公司简称/客户等)
├── xingyun-settle/     结算模块
├── xingyun-comp/       组件(文件箱/在线 Excel)
└── .trae/skills/       可调用技能库(见第 5 节)

分层命名约定:XxxController → XxxService → XxxServiceImpl → XxxMapper(+XML) → entity; 入参 QueryXxxVo/CreateXxxVo/UpdateXxxVo,出参 GetXxxBo 或实体,统一用 InvokeResultBuilder.success() 包装。

4. 核心开发流程(概要,详见 skill/开发流程.md)

  1. 读代码:先搜同类功能的现有实现(Controller/ServiceImpl/Mapper.xml 各层),照抄项目模式
  2. 动手:按 自底向上(XML/Mapper → Service → Controller)顺序改,遵循 HTTP 方法规范(查询 GET / 新增 POST / 修改 PUT / 删除 DELETE,见 .trae/rules/方法类型.md)
  3. 带审核流的单据:BPM_FLAG → startInstance → BusinessDataHandlerServiceImpl 注册 case → updateApprovalStatus 回调 → fillOperateFlags 待办按钮
  4. 验证:每轮改动后用 IDE 诊断检查所有被改文件;涉及 XML 的检查 resultMap/列名/别名一致性
  5. 收尾汇报:列改动清单 + 前端需同步点(字段改名/响应结构变化/传参变化)+ 存量库需执行的 SQL

5. Skill 索引(按需加载)

5.1 项目 skill 文件夹(skill/,本次会话必读的标 ⭐)

文档 内容 何时读
⭐ skill/开发流程.md 角色定位、技术栈细节、分层规范、Warm-Flow 审核流完整接入步骤、单据开发清单 任何开发任务开始前
⭐ skill/避坑清单.md 踩坑记录(持续补充):口径一致性、PageHelper、逻辑删除+唯一键、单位换算、MyBatis-Plus 更新策略等 任何开发任务开始前;解决问题后回写新坑

5.2 可调用技能(.trae/skills/,触发对应场景时调用 Skill 工具)

技能 触发场景
warm-flow审核流程 涉及审核流/流程接入
列表查询接口 新建/修改列表查询接口(统一分页风格)
新增字段 实体加字段(各层同步清单)
数据库sql 生成 SQL(字符集兼容等注意事项)
明细列表数据导出 列表数据导出 Excel
系统导入 导入功能
打印/导出pdf 打印/导出 PDF

5.3 工作区规则(.trae/rules/)

  • 方法类型.md:新增用 POST、修改用 PUT、删除用 DELETE、查询用 GET

6. 单据导出(打印)模板填充规范

单据打印 = 用 Excel 模板(xingyun-sc/src/main/resources/templates/*.xlsx)按占位符填充后输出。参考实现:

  • ProcurementPlanController.export(纯占位符填充)
  • CoordinationSummaryApprovalController.print(动态行插入)
  • ProcurementWeighingTicketController.export(动态行 + 占位符混合,过磅码单)

固定套路(Controller 内完成,不起 Service 层):

  1. 接口:@GetMapping("/export"),参数 id,方法返回 void,入参加 HttpServletResponse response;权限 @HasPermission({"xxx:print"})(:print 后缀)
    • 需要多种输出时参考 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 头)
  2. 响应头:ExcelUtil.setupResponse(response, 编号 + "-单据名.xlsx")(com.lframework.xingyun.sc.utils.ExcelUtil)
  3. 开模板:new ClassPathResource("templates/xxx.xlsx").getStream()(hutool)→ new XSSFWorkbook(inputStream),try-with-resources
  4. 动态行(明细条数不固定):先 sheet.shiftRows(起始行+1, sheet.getLastRowNum(), 插入行数, true, true) 整体下移,再循环复制模板行样式(newRow.setHeight + 逐格 nc.setCellStyle(tc.getCellStyle())),最后 ExcelUtil.setCellValue(sheet, 行, 列, 值) 逐格填充
  5. 静态占位符:模板单元格写 ${字段名}(支持 #{}),Java 组装 Map<String, Object> 后调用 processTemplateSheet(sheet, dataMap) 遍历 STRING 单元格 replace(私有方法,各 Controller 持有副本,照抄即可)
  6. 输出:workbook.write(response.getOutputStream()) + flush();异常包装为 RuntimeException("模板文件不存在/无法读取模板文件: templates/xxx.xlsx")

注意事项:

  • 动态行行索引用 0-based 常量定义(如 APPLY_START_ROW = 4 = Excel 第 5 行),以模板实际行为准;确认模板可解压看 xl/worksheets/sheet1.xml(合并单元格/占位符/行列位置)
  • 占位符可能嵌在长文本中间(如“单位:公斤 … ${firstGrossWeightTime}”),字符串 replace 天然支持
  • 数字大写直接用 hutool:NumberChineseFormatter.format(value.doubleValue(), true) 输出“壹万贰仟叁佰肆拾伍点陆”(位名万仟佰拾、小数读点),再拼单位后缀如“公斤”
  • BigDecimal 填充:展示列用 formatDecimal(stripTrailingZeros 去尾零转字符串),数值列可 ExcelUtil.setCellValue 直写 BigDecimal(内部转 double 保留样式)

7. 硬性纪律

  • 不创建不必要的文件;能改现有文件就不新建
  • 不使用 emoji;注释、报错文案用中文,与现有代码一致
  • 改前必读:任何文件编辑前先 Read 该文件相关段落,禁止盲改
  • 不擅自 git commit/push,除非用户明确要求
  • 数量单位敏感:采购计划=吨,过磅码单=公斤,跨模块取数必须换算(见避坑清单 #5)