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)
- 读代码:先搜同类功能的现有实现(Controller/ServiceImpl/Mapper.xml 各层),照抄项目模式
-
动手:按 自底向上(XML/Mapper → Service → Controller)顺序改,遵循 HTTP 方法规范(查询 GET / 新增 POST / 修改 PUT / 删除 DELETE,见
.trae/rules/方法类型.md) - 带审核流的单据:BPM_FLAG → startInstance → BusinessDataHandlerServiceImpl 注册 case → updateApprovalStatus 回调 → fillOperateFlags 待办按钮
- 验证:每轮改动后用 IDE 诊断检查所有被改文件;涉及 XML 的检查 resultMap/列名/别名一致性
- 收尾汇报:列改动清单 + 前端需同步点(字段改名/响应结构变化/传参变化)+ 存量库需执行的 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 层):
- 接口:
@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 头)
- 需要多种输出时参考
- 响应头:
ExcelUtil.setupResponse(response, 编号 + "-单据名.xlsx")(com.lframework.xingyun.sc.utils.ExcelUtil) - 开模板:
new ClassPathResource("templates/xxx.xlsx").getStream()(hutool)→new XSSFWorkbook(inputStream),try-with-resources - 动态行(明细条数不固定):先
sheet.shiftRows(起始行+1, sheet.getLastRowNum(), 插入行数, true, true)整体下移,再循环复制模板行样式(newRow.setHeight+ 逐格nc.setCellStyle(tc.getCellStyle())),最后ExcelUtil.setCellValue(sheet, 行, 列, 值)逐格填充 - 静态占位符:模板单元格写
${字段名}(支持#{}),Java 组装Map<String, Object>后调用processTemplateSheet(sheet, dataMap)遍历 STRING 单元格 replace(私有方法,各 Controller 持有副本,照抄即可) - 输出:
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)