开发流程.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. 新功能/新单据开发清单

  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)
  2. Entity:字段注释中文;非库字段用 @TableField(exist = false)
  3. Mapper + XML:列表查询统一写 <sql id="Xxx_sql"> 公共片段 + resultMap;条件用 <if test="vo.xxx != null and vo.xxx != ''">;IN 用 <foreach>
  4. Service/Impl:业务校验、事务 @Transactional(rollbackFor = Exception.class)
  5. Controller:查询 GET / 新增 POST / 修改 PUT / 删除 DELETE(.trae/rules/方法类型.md);权限 @HasPermission({"模块:资源:动作"})
  6. VO/BO:查询入参 Vo 与列表出参 Bo 字段对齐前端需求
  7. 自查: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)

  1. 注入该单据 Service
  2. businessStatusHandler 的 switch 中注册 case "BPM_FLAG":
  3. 新增私有方法处理结果(项目统一口径):
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
}
  1. 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. 修改既有代码的流程

  1. Read 目标文件相关段落(含上下文引用方),Grep 全局确认该方法/字段的所有调用点
  2. 评估影响面(尤其是改签名、改字段名、改筛选口径)
  3. 自底向上修改,保持对外行为兼容或明确列出破坏性变更
  4. GetDiagnostics 验证 + 全局 Grep 确认无残留引用
  5. 汇报:改了什么、为什么、前端/SQL 需同步什么