Msm.Module.DynamicRecords.Application 1.0.15

Msm.Module.Workflow

Một thư viện Workflow Engine mạnh mẽ được xây dựng theo Clean Architecture, hỗ trợ multi-tenancy và cung cấp đầy đủ các tính năng để quản lý quy trình phê duyệt và workflow phức tạp.

📋 Mục lục

• Tính năng
• Kiến trúc
• Cài đặt
• Bắt đầu nhanh
• Tài liệu
• Ví dụ
• Đóng góp
• License

✨ Tính năng

Core Features

• ✅ Workflow Process Management: Tạo và quản lý các quy trình workflow phức tạp
• ✅ Multi-Step Approval: Hỗ trợ nhiều bước phê duyệt với logic phức tạp
• ✅ Validation / Flow Builder: Hỗ trợ các workflow không cần phê duyệt, dùng cho validation dữ liệu (ví dụ: khi tạo Order sẽ chạy workflow để kiểm tra dữ liệu, tồn kho, hạn mức, v.v.) và trả về kết quả/ thông điệp cho hệ thống gọi
• ✅ Multi-Tenancy: Schema-based multi-tenancy với PostgreSQL
• ✅ Dynamic Approvers: Resolve approvers động dựa trên criteria
• ✅ Workflow Actions: Hệ thống action handler mở rộng (email, notification, task, etc.)
• ✅ External API Actions: Mỗi bước có thể cấu hình action gọi API bên ngoài với mapping payload linh hoạt từ ContextData sang payload của hệ thống khác, mapping ngược response về kết quả workflow, và lưu trong ResultData
• ✅ Dynamic Validation Logic: Hỗ trợ viết logic kiểm tra động (ví dụ JavaScript/expressions ở UI Designer) để validate response từ API và quyết định nhánh workflow/ trạng thái cuối cùng
• ✅ Delegation & Reassignment: Ủy quyền và chuyển giao workflow items
• ✅ Timeout Management: Quản lý timeout và behavior khi quá hạn
• ✅ Workflow History: Audit trail đầy đủ cho mọi thao tác
• ✅ Ad-hoc Steps: Thêm bước phê duyệt động trong runtime
• ✅ Criteria Evaluation: Đánh giá điều kiện động để quyết định workflow path

Technical Features

• 🏗️ Clean Architecture: Tách domain (Msm.Module.Workflow), triển khai (Msm.Module.Workflow.Infrastructure), và HTTP (Msm.Module.Workflow.AspNetCore)
• 🔌 Dependency Injection: Hỗ trợ đầy đủ DI với Microsoft.Extensions.DependencyInjection
• 📦 NuGet Packages: Có thể đóng gói thành các NuGet packages độc lập
• 🗄️ Entity Framework Core: Sử dụng EF Core với PostgreSQL
• 🎨 RESTful API: Controllers sẵn có để tích hợp nhanh
• 🖥️ UI Designer: React-based workflow designer với drag & drop

🏗️ Kiến trúc

Project được xây dựng theo Clean Architecture với 4 layers chính:

framework/module/Workflow/
├── Msm.Module.Workflow/                 # Domain: entities, enums, exceptions (NuGet: Msm.Module.Workflow)
├── Msm.Module.Workflow.Infrastructure/ # MediatR, services, DTOs, EF Core (NuGet: …Infrastructure)
└── Msm.Module.Workflow.AspNetCore/     # REST controllers (NuGet: …AspNetCore)

Dependency Flow

AspNetCore → Infrastructure → Domain (Msm.Module.Workflow)

Nguyên tắc:

• Domain không phụ thuộc module khác
• Infrastructure phụ thuộc Domain (và Msm.Core.Abstractions)
• AspNetCore phụ thuộc Infrastructure

Persistence Layers (Core)

• Msm.Core.Persistence: contracts chuẩn cho IRepository<T> và IUnitOfWork.
• Msm.Core.EntityFrameworkCore.PostgreSql: implementation EF Core/Npgsql cho contracts ở trên.
• Msm.Core.EFCore: legacy API để tương thích ngược cho các service cũ; ưu tiên code mới theo 2 package phía trên để dễ maintain lâu dài.

Xem chi tiết tại ARCHITECTURE.md

📦 Cài đặt

Yêu cầu

• .NET 8.0 SDK hoặc cao hơn (khuyến nghị .NET 10.0 nếu có)
• PostgreSQL 12+ (cho multi-tenancy)
• Node.js 18+ (cho UI Designer - tùy chọn)

Cài đặt từ Source

git clone <repository-url>
cd msm-workflow-lib
dotnet restore
dotnet build

Cài đặt từ NuGet (Khi đã publish)

<PackageReference Include="Msm.Module.Workflow" Version="1.0.0" />
<PackageReference Include="Msm.Module.Workflow.Infrastructure" Version="1.0.0" />
<PackageReference Include="Msm.Module.Workflow.AspNetCore" Version="1.0.0" />

Build NuGet packages bằng command line

Sử dụng script build-packages.sh để build + pack theo từng nhóm:

cd msm-workflow-lib

# all groups: core + dynamic + workflow
./build-packages.sh 1.0.0 ./nupkg all

# chỉ build/pack Core packages
./build-packages.sh 1.0.0 ./nupkg core

# chỉ build/pack DynamicRecords packages
./build-packages.sh 1.0.0 ./nupkg dynamic

# chỉ build/pack Workflow packages
./build-packages.sh 1.0.0 ./nupkg workflow

Nếu không truyền group, mặc định là all. Sau khi chạy xong, bạn sẽ thấy các file .nupkg và .snupkg trong thư mục nupkg/.

Push package lên NuGet server

export NUGET_API_KEY=<YOUR_NUGET_API_KEY>
dotnet nuget push ./nupkg/*.nupkg \
  --api-key "$NUGET_API_KEY" \
  --source https://api.nuget.org/v3/index.json

🚀 Bắt đầu nhanh

1. Cấu hình Database

Tạo file appsettings.json trong Infrastructure project:

{
  "Database": {
    "Host": "localhost",
    "Port": "5432",
    "Name": "msm_workflow",
    "Username": "postgres",
    "Password": "your_password"
  }
}

2. Tạo Migration

cd framework/module/Workflow/Msm.Module.Workflow.Infrastructure
dotnet ef migrations add InitialCreate --startup-project .
dotnet ef database update --startup-project .

3. Đăng ký Services

using Msm.Module.Workflow.Infrastructure;
using Msm.Module.Workflow.AspNetCore;

// Trong Program.cs hoặc Startup.cs
services.AddApplication();
services.AddInfrastructure(configuration);
services.AddWorkflowApiControllers();

4. Sử dụng trong Controller

[ApiController]
[Route("api/[controller]")]
public class MyController : ControllerBase
{
    private readonly IWorkflowProcessService _processService;
    private readonly IWorkflowInstanceService _instanceService;

    public MyController(
        IWorkflowProcessService processService,
        IWorkflowInstanceService instanceService)
    {
        _processService = processService;
        _instanceService = instanceService;
    }

    [HttpPost("create-process")]
    public async Task<IActionResult> CreateProcess(CreateWorkflowProcessDto dto)
    {
        var process = await _processService.CreateProcessAsync(dto);
        return Ok(process);
    }
}

Xem chi tiết tại GETTING_STARTED.md

📚 Tài liệu

• ARCHITECTURE.md - Kiến trúc và design patterns
• CORE_PERSISTENCE_MIGRATION_GUIDE.md - Lo trinh migration Core Persistence cho CatalogService va SaleProcess
• GETTING_STARTED.md - Hướng dẫn bắt đầu chi tiết
• MODULE_CREATION_GUIDE.md - Huong dan tao module moi va script scaffold
• NEW_PROJECT_DYNAMIC_RECORDS_GUIDE.md - Huong dan khoi tao project moi co DynamicRecords
• LOGGING_GUIDELINES.md - Chuẩn logging thống nhất cho toàn repo
• Example/Msm.Workflow.Api/Services/README.md - Template Method Pattern examples

💡 Ví dụ

Tạo Workflow Process

var processDto = new CreateWorkflowProcessDto
{
    Name = "Purchase Order Approval",
    Code = "PO_APPROVAL",
    ObjectType = "PURCHASE_ORDER",
    Description = "Workflow for approving purchase orders",
    EntryCriteria = "amount > 10000",
    AllowSubmitterToRecall = true
};

var process = await _processService.CreateWorkflowProcessFromDtoAsync(processDto);

Tạo Workflow Step

var stepDto = new CreateWorkflowStepDto
{
    ProcessId = process.Id,
    Name = "Manager Approval",
    StepType = WorkflowStepType.Approval,
    StepOrder = 1,
    WorkflowBehavior = WorkflowBehavior.AllMustApprove,
    ApprovalTimeoutDays = 1, // 1 day
    TimeoutBehavior = TimeoutBehavior.Escalate
};

var step = await _processService.AddStepFromDtoAsync(process.Id, stepDto);

Trigger Workflow Instance

// Lấy process theo code trước
var process = await _processService.GetWorkflowProcessesAsync()
    .FirstOrDefaultAsync(p => p.Code == "PO_APPROVAL");

var contextData = JsonDocument.Parse(JsonSerializer.Serialize(new
{
    amount = 15000,
    department = "IT"
}));

var instance = await _instanceService.SubmitWorkflowInstanceAsync(
    workflowProcessId: process.Id,
    targetRecordId: purchaseOrderId,
    targetObjectType: "PURCHASE_ORDER",
    submittedBy: currentUserId,
    contextData: contextData
);

// instance.Status và instance.History cho biết trạng thái phê duyệt

Xem thêm ví dụ tại Example/

Validation Workflow (Flow Builder) với External API

Ví dụ một workflow dùng để validation Order trước khi lưu:

• WorkflowProcess có Code = "ORDER_VALIDATION" và ObjectType = "ORDER", loại process là Validation.
• Bước workflow cấu hình action ExternalApiCall với ActionConfig:
  • URL/HTTP method của API hệ thống khác (OMS, WMS, Pricing, v.v.)
  • Mapping payload từ WorkflowInstance.ContextData sang payload của API (qua UI Designer).
  • Mapping response về WorkflowInstance.ResultData để trả lại cho caller.

Khi tạo Order, hệ thống chỉ cần trigger workflow:

var contextData = JsonDocument.Parse(JsonSerializer.Serialize(new
{
    orderId = orderId,
    totalAmount = 1500000,
    customerCode = "C001"
}));

var instance = await _instanceService.SubmitWorkflowInstanceAsync(
    workflowProcessId: validationProcess.Id,   // ORDER_VALIDATION
    targetRecordId: orderId.ToString(),
    targetObjectType: "ORDER",
    submittedBy: currentUserId,
    contextData: contextData
);

// Sau khi workflow chạy xong (các step validation tự động, không cần approver):
// - instance.Status: thành công/failed tùy theo logic validation
// - instance.Metadata / ResultData (tùy implement) chứa chi tiết lỗi/cảnh báo để hiển thị trên UI

Trong UI Designer, bạn có thể:

• Cấu hình mapping payload/response cho action ExternalApiCall.
• Viết code/expressions động để validate response (ví dụ: if tồn kho < requestedQty thì trả về lỗi).
• Chia nhánh workflow cho các trường hợp pass/fail khác nhau.

🎨 Workflow Designer UI

Project bao gồm một React-based UI designer để thiết kế workflow trực quan:

cd Example/workflow-designer-ui
npm install
npm run dev

Truy cập tại http://localhost:5173

🧪 Testing

# Chạy tests (khi có)
dotnet test

# Build solution
dotnet build

# Restore packages
dotnet restore

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp! Vui lòng đọc CONTRIBUTING.md để biết cách đóng góp.

📝 License

[Specify your license here]

👥 Authors

• MSM Software Team

🙏 Acknowledgments

• Clean Architecture principles by Robert C. Martin
• Entity Framework Core team
• React Flow for workflow visualization

Lưu ý: Đây là version 1.0.0. API có thể thay đổi trong các phiên bản tương lai.