Skip to content

单据公共组件 ​

新写单据时直接使用下面的组件,不要在业务 Service 中重复实现:

场景组件说明
接入审批framework/workflow/ApprovalFlow、ApprovalSupport声明 ApprovalFlow 常量(流程标识 + 业务标识前缀,上线后不能修改),提交用 approvalSupport.submit(flow, id, 变量, 直接生效, 改为审批中, 记录实例 ID)(流程未发布时直接生效);撤回用 cancelIfRunning;结果在 @EventListener 中 FLOW.onFinished(e, (id, approved) -> ...)
状态流转framework/data/StatusTransitions按原状态条件更新:change(失败提示刷新)、tryChange、changeFromAny
按数据权限读取framework/security/datascope/DataScopesload(rule, loader)、require(...),看不到的数据视为不存在;电商数据按店铺用 EcomStoreScope.require
明细行整体替换framework/data/DetailLines先删后用 XML 多值 INSERT 插入
只取前几条framework/data/Queriesfirst、limit,不在 Java 中写 .last("LIMIT 1")
金额、数量common/util/Decimals金额 2 位、数量和单价 4 位,HALF_UP
制单人CreateByInnerInterceptor插入时自动填当前用户
单据编号DocNoService.next(规则标识)在本模块 XxxDocNos 中声明 DocNoCatalog,「编码规则」页面据此列出

接入审批示例 ​

以头程货件为例:

java
// 1. 声明业务流程及其变量(EcomFlowBusinesses),名称写消息键
@Bean
public FlowBusiness inboundFlow() {
    return FlowBusiness.of("ecom_inbound", "ecom.label.inboundApproval",
            number("amount", "ecom.label.inboundCost"),
            number("totalQty", "ecom.label.totalQty"),
            text("storeName", "ecom.label.store"));
}

// 2. Service 中提交(EcomInboundService)
static final ApprovalFlow FLOW = new ApprovalFlow("ecom_inbound", "ecom_inbound:");

public boolean submit(Long id) {
    EcomInbound i = require(id);
    Map<String, Object> vars = Map.of("amount", totalCost(i), "totalQty", i.getTotalQty(), "storeName", storeName);
    return approvalSupport.submit(FLOW, id, vars,
            () -> ship(i),                                            // 流程未发布:直接发运
            () -> StatusTransitions.change(inboundMapper, EcomInbound::getId, id, EcomInbound::getStatus,
                    InboundStatus.DRAFT, InboundStatus.APPROVING, "ecom.error.inboundStatusChanged"),
            instanceId -> saveInstanceId(id, instanceId));            // 记录流程实例
}

// 3. 监听结果(与审批操作在同一事务中,抛异常会回滚审批)
@EventListener
@Transactional
public void onFlowFinished(FlowFinishedEvent e) {
    FLOW.onFinished(e, (id, approved) -> {
        if (approved) ship(inboundMapper.selectById(id)); else backToDraft(id);
    });
}

流程变量要与 flowApi.start 实际传入的一致:设计器的条件分支、流程详情的「业务信息」都依赖它。

数据访问规范 ​

  • SQL 只写在 mapper XML 里,Java 中不写 SQL 字符串(包括 .apply、.inSql、.setSql、.last);单表简单条件可用 Wrappers。
  • 统计在数据库中 GROUP BY / COUNT;批量写入用单条多值 INSERT;关联查询用 JOIN 避免 N+1;不对索引列套函数。
  • 列表接口不返回大字段(平台原始报文、描述)和敏感字段(授权)。
  • 分页单页上限 500,无 WHERE 的 UPDATE / DELETE 会被拦截。
  • 跨模块只允许只读 JOIN,写操作经过所属模块的 Service。
  • 新增业务表引用物料、仓库、客户、供应商、用户时,在本模块 XxxRefMapper.xml 中登记引用检查;引用客户 / 供应商时还要在 XxxMergeMapper.xml 中登记合并迁移。
  • 缓存通过 CacheService,新增缓存前缀登记到 CacheMonitorService.CACHES。

事务 ​

  • 有两次及以上写操作的 public 方法加 @Transactional,加在被外部调用的入口上。
  • 事务内不做平台接口、海外仓、物流商、大模型等外部调用,改用 @TransactionalEventListener(AFTER_COMMIT) 或在事务之外调用后再开事务写结果(如刊登:领取 → 调用连接器 → 在事务中写结果)。
  • 定时任务、批量操作逐条处理时每条一个事务(TransactionTemplate),一条失败不影响其他。

面向跨境电商卖家的开源 ERP · 基于 GPL-3.0 协议
联系我们:电话 17701123202 · 微信 BG7LIF · 邮箱 zmissu@163.com