开发流程.md
7.17 KB
开发流程 — 星云 ERP
开发任何功能前先通读本文档。搭配
AGENTS.md(入口)与skill/避坑清单.md使用。
1. 角色定位
- 身份:星云 ERP 资深 Java 后端开发
- 行为准则:先搜后写——任何新功能先找项目内同类实现(如过磅码单参考采购计划模块),复用其分层结构、命名、分页、响应包装方式;禁止引入项目里没有的框架用法
- 汇报准则:改完必报「改动清单 + 前端同步点 + 存量库 SQL」,让用户能直接转给前端/DBA
2. 技术栈与基础设施
- Java 8 / Spring Boot / Maven 多模块(
javax.*,勿用 jakarta、勿用 Java 8 以上语法) - MyBatis-Plus:
BaseMpServiceImpl<Mapper, Entity>、Wrappers.lambdaQuery/lambdaUpdate - 分页:
PageHelperUtil.startPage(pageIndex, pageSize)→ 紧跟第一条查询 →PageResultUtil.convert(new PageInfo<>(datas))→ Controller 用getPageIndex(vo)/getPageSize(vo)(Vo 继承SortPageVo) - Swagger 注解:实体/VO/BO 字段都带
@ApiModelProperty("中文说明") - 审核流:Warm-Flow(详见第 5 节)
- 消息:站内信走
MqProducerService.createSysSiteMessage(SysSiteMessageDto) - 角色找人:
sysUserRoleService.listUserIdByRoleCodes(roleCodes)/TransactorHandler.listTransactorsByRoleCode
3. 分层与命名规范(以 xingyun-sc 为准)
controller/ XxxController extends DefaultBaseController
@Api(tags) + @Validated + @RestController + @RequestMapping("/模块/资源")
service/ XxxService extends BaseMpService<Xxx>
impl/ XxxServiceImpl extends BaseMpServiceImpl<XxxMapper, Xxx> implements XxxService
entity/ @TableName("表名"),BaseEntity,createBy/createTime 等用 @TableField(fill = ...)
vo/ QueryXxxVo(查询,继承 SortPageVo 可分页)/ CreateXxxVo / UpdateXxxVo
bo/ GetXxxBo extends BaseBo<Xxx>(详情返回);XxxSelectorBo / 分页列表 Bo
mappers/ XxxMapper extends BaseMapper<Xxx>,XML 放 resources/mappers/<业务>/XxxMapper.xml
handlers/ BusinessDataHandlerServiceImpl(流程结束回调,见第 5 节)
- 响应统一
InvokeResultBuilder.success(data);分页返回InvokeResult<PageResult<Bo>> - 校验:入参
Assert.notBlank/greaterThanZero,业务错误throw new DefaultClientException("中文提示!") - 操作日志:写操作加
@OpLog(type = OtherOpLogType.class, name = "...,ID:{}", params = {...})+OpLogUtil.setVariable/setExtra
4. 新功能/新单据开发清单
-
SQL:
xingyun-api/src/main/resources/db/chujiang/base.sql文件尾部追加(新表CREATE TABLE IF NOT EXISTS;已有表加列用ALTER TABLE ... ADD COLUMN,不改原 CREATE)。字符集/排序规则与同业务老表一致(utf8mb4_general_ci 或 utf8mb3) -
Entity:字段注释中文;非库字段用
@TableField(exist = false) -
Mapper + XML:列表查询统一写
<sql id="Xxx_sql">公共片段 + resultMap;条件用<if test="vo.xxx != null and vo.xxx != ''">;IN 用<foreach> -
Service/Impl:业务校验、事务
@Transactional(rollbackFor = Exception.class) -
Controller:查询 GET / 新增 POST / 修改 PUT / 删除 DELETE(
.trae/rules/方法类型.md);权限@HasPermission({"模块:资源:动作"}) - VO/BO:查询入参 Vo 与列表出参 Bo 字段对齐前端需求
- 自查:GetDiagnostics 全部改动文件;XML 列名/resultMap/别名三处一致
5. Warm-Flow 审核流接入(完整步骤)
适用:任何需要审批的单据(参考:采购计划 PROCUREMENT_PLAN、过磅码单 WEIGHING_RECORD)
5.1 提交侧(XxxServiceImpl)
private static final String BPM_FLAG = "业务标识"; // 如 WEIGHING_RECORD,需与流程设计器中的流程编号一致
@Resource
private FlowInstanceWrapperService flowInstanceWrapperService;
// submit() 内:单据状态先置 AUDIT,再发起流程
this.update(Wrappers.lambdaUpdate(Xxx.class)
.set(Xxx::getApprovalStatus, STATUS_AUDIT)
.eq(Xxx::getId, id));
flowInstanceWrapperService.startInstance(BPM_FLAG, entity.getId(), BPM_FLAG, entity);
5.2 流程结束回调(handlers/BusinessDataHandlerServiceImpl)
- 注入该单据 Service
-
businessStatusHandler的 switch 中注册case "BPM_FLAG": - 新增私有方法处理结果(项目统一口径):
private void handleXxxData(String flowStatus, String businessId) {
if (FlowInstanceStatus.APPROVE_PASS.getCode().equals(flowStatus)
|| FlowInstanceStatus.FINISH.getCode().equals(flowStatus)) {
xxxService.updateApprovalStatus(businessId, "PASS"); // 通过
} else if (FlowInstanceStatus.REVOKE.getCode().equals(flowStatus)
|| FlowInstanceStatus.REFUSE.getCode().equals(flowStatus)
|| FlowInstanceStatus.TERMINATION.getCode().equals(flowStatus)) {
xxxService.updateApprovalStatus(businessId, "REFUSE"); // 驳回/撤销/终止
}
// UNDO(撤回)按业务定:多数模块归为 REFUSE,少数(如正式合同)为 CANCEL
}
- Service 侧提供
updateApprovalStatus(String id, String approvalStatus):校验存在 → 更新approval_status;有附加联动(如通过后写时间/状态机流转)也在此方法内做
5.3 审核按钮标记(列表/详情)
private void fillOperateFlags(List<Xxx> datas) {
// 1) 是否发起过流程 → showExamineDetail(有审核状态即可看审批轨迹)
List<FlowInstanceWrapper> flowList = flowInstanceWrapperService.getFlowByBusinessIdList(businessIds);
// 2) 当前用户待办 → showExamine(且单据为 AUDIT 才显示审核按钮)
List<FlowTaskDto> todoList = flowTaskWrapperMapper.queryTodoList(new QueryTodoTaskListVo(), SecurityUtil.getCurrentUser().getId());
}
- 两个标记是实体上的
@TableField(exist = false)字段,默认 false;分页列表与详情两条返回路径都要调用填充 -
不要再按
approvalStatus硬编码判断审核按钮(接入流程后以待办为准) - 审核动作本身走统一流程待办接口,本地不写 examine 接口
5.4 状态机约定
| approvalStatus | 含义 | 可修改 | 可提交 | 可作废 |
|---|---|---|---|---|
| DRAFT | 草稿 | ✅ | ✅ | 视业务 |
| AUDIT | 审核中 | ❌(流程中) | ❌ | ❌ |
| PASS | 通过 | ❌ | ❌ | ✅ |
| REFUSE | 已驳回 | ✅(改完保持 REFUSE 可直接重新提交) | ✅ | ❌ |
5.5 接入检查清单
-
流程设计器已建
BPM_FLAG同名流程定义 - submit 置 AUDIT + startInstance
- BusinessDataHandlerServiceImpl 注册 case + handleXxxData
- Service 有 updateApprovalStatus
- fillOperateFlags 改为待办驱动(列表 + 详情都调用)
- 删除本地 examine 接口(如有)
6. 修改既有代码的流程
- Read 目标文件相关段落(含上下文引用方),Grep 全局确认该方法/字段的所有调用点
- 评估影响面(尤其是改签名、改字段名、改筛选口径)
- 自底向上修改,保持对外行为兼容或明确列出破坏性变更
- GetDiagnostics 验证 + 全局 Grep 确认无残留引用
- 汇报:改了什么、为什么、前端/SQL 需同步什么