单据公共组件
新写单据时直接使用下面的组件,不要在业务 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/DataScopes | load(rule, loader)、require(...),看不到的数据视为不存在;电商数据按店铺用 EcomStoreScope.require |
| 明细行整体替换 | framework/data/DetailLines | 先删后用 XML 多值 INSERT 插入 |
| 只取前几条 | framework/data/Queries | first、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),一条失败不影响其他。