Quy trình nghiệp vụ (Flowable)

govex-cloud-workflow cung cấp nền tảng quy trình nghiệp vụ dùng Flowable: quản lý định nghĩa quy trình, publish/deploy CMMN, chạy case/task và đọc runtime/history. Dùng khi service cần quy trình phê duyệt, luồng công việc nhiều bước giữa nhiều người.

Khi nào sử dụng

Quản lý danh mục quy trình và thư viện bước dùng chung giữa các service.
Publish định nghĩa CMMN đã thiết kế và deploy vào Flowable để chạy case.
Chạy case, giao việc cho người dùng (claim/complete/delegate), lưu nháp dữ liệu form của task.
Lấy snapshot quy trình (CMMN XML, plan items, sentries) cho phía client.
Gắn hook kiểm tra nghiệp vụ trước/sau khi hoàn thành task và phát sự kiện workflow ra ngoài.

Cài đặt

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-workflow</artifactId>
</dependency>

Version do BOM quản lý, xem Cài đặt.

Cấu hình

Dependency bật mặc định; chỉ khai báo khi cần đổi hành vi:

govex:
  workflow:
    enabled: true
    bpmn-endpoints-enabled: false

Property	Mô tả	Mặc định
`govex.workflow.enabled`	Bật dependency workflow (repository/entity/component scan, scheduling)	`true`
`govex.workflow.bpmn-endpoints-enabled`	Đăng ký các endpoint BPMN `/api/v1/process-instance/` và `/api/v1/preview/`; mặc định không đăng ký, chỉ bật khi cần	`false`
`govex.workflow.deployment-compensation-retry-ms`	Khoảng nghỉ giữa các lần retry tác vụ bù trừ deployment (ms)	`60000`

Sử dụng

Publish/deploy và chạy quy trình CMMN qua REST:

POST /api/v1/workflow/cmmn/validate
POST /api/v1/workflow/cmmn/deployments
POST /api/v1/workflow/cmmn/cases
GET  /api/v1/workflow/cmmn/snapshots/{workflowCode}?tenantCode=TA_HN
POST /api/v1/workflow/cmmn/tasks/{flowableTaskId}:complete
POST /api/v1/workflow/cmmn/cases/{caseInstanceId}/plan-items/{planItemDefinitionKey}:trigger

Quản lý công việc của người dùng:

GET  /api/v1/tasks?status=PENDING
GET  /api/v1/tasks/by-entity/HO_SO/{entityId}/active
POST /api/v1/tasks/{taskId}/claim
POST /api/v1/tasks/{taskId}/complete
POST /api/v1/tasks/{taskId}/save-draft
POST /api/v1/tasks/{taskId}/delegate

Gắn hook nghiệp vụ quanh thao tác hoàn thành task:

@Component
public class HoSoTaskCompletionInterceptor implements TaskCompletionInterceptor {

    @Override
    public void beforeComplete(WorkflowTaskContext context, TaskCompleteRequest request) {
        // Validate dữ liệu nghiệp vụ; ném exception để chặn hoàn thành task.
    }

    @Override
    public void afterComplete(WorkflowTaskContext context, TaskCompleteRequest request) {
        // Merge formData vào hồ sơ nghiệp vụ hoặc ghi audit.
    }
}

Khai báo SPI ánh xạ candidate group khi dùng nhóm người nhận việc:

@Bean
WorkflowTaskCandidateGroupResolver workflowTaskCandidateGroupResolver(DonViService donViService) {
    return (userId, candidateGroups, authentication) -> donViService.thuocNhom(userId, candidateGroups);
}

Trong service có thể inject WorkflowRuntimeService để chạy case/task trực tiếp: deployCmmn, startCase, completeTask, triggerPlanItem, assignTask, setCaseVariables, listActiveTasks. Sự kiện workflow (workflow.step.completed, workflow.process.completed, workflow.task.created, ...) phát qua govex-cloud-mq.

Luồng hoạt động

Sơ đồ dưới đây mô tả vòng đời một case CMMN: publish definition → start case → giao việc (claim/complete) → trigger plan item → kết thúc case.

Lưu ý

Cần datasource/JPA; changelog classpath db/changelog/workflow/changelog-master.yaml phải include trong changelog master của ứng dụng; bảng runtime ACT_RU_*/ACT_HI_* do Flowable engine tạo và quản lý theo cấu hình của host.
Các thao tác task được kiểm tra quyền fail-closed theo policy host (WorkflowTaskAuthorizationService); nên triển khai WorkflowTaskCandidateGroupResolver nếu candidate group không trùng hệ định danh.
Endpoint /api/v1/workflow/**, /api/v1/tasks/**, /api/v1/process-instance/**, /api/v1/preview/** đi qua policy host của govex-cloud-security.
Endpoint /api/v1/workflow/cmmn chỉ hoạt động khi runtime CMMN (Flowable CMMN engine) sẵn sàng.
Các endpoint BPMN (/api/v1/process-instance/**, /api/v1/preview/**) mặc định không đăng ký; bật govex.workflow.bpmn-endpoints-enabled khi cần.

Khi nào sử dụng​

Cài đặt​

Cấu hình​

Sử dụng​

Luồng hoạt động​

Lưu ý​