TCIS.Pluggable.Engine 1.0.0-rc.12

TCIS.Pluggable.Engine

The core engine library for the TCIS Pluggable Pipeline architecture. It provides a unified discovery mechanism (Modules + Steps + Rules + Services), Pipeline Analyzer, and Pipeline Engine.

📦 Installation

dotnet add package TCIS.Pluggable.Engine

🚀 Registration / Setup (Program.cs)

Register the Pluggable Engine and Discovery:

using TCIS.Pluggable.Engine.Modules;

var builder = WebApplication.CreateBuilder(args);

// Platform: nghiệp vụ chuẩn, dùng chung mọi Site.
builder.Services.AddPluggablePipeline(
    builder.Configuration,
    typeof(GatePlatformModule).Assembly
);

// Plugin đặc thù theo Site — tham chiếu TƯỜNG MINH, không quét thư mục.
builder.Services.AddSitePlugins(
    builder.Configuration,
    typeof(CatLaiModule).Assembly
);

Plugin được nạp bằng tham chiếu tĩnh, không phải nạp động

Mỗi bản triển khai có Host riêng, và các Host khác nhau đúng ở danh sách assembly truyền vào AddSitePlugins:

// Cảng lớn triển khai riêng — build từ Platform + plugin của cảng đó
.AddSitePlugins(configuration, typeof(CatLaiModule).Assembly);

// Nhiều cảng nhỏ dùng chung một bản triển khai
.AddSitePlugins(configuration,
    typeof(SiteAModule).Assembly,
    typeof(SiteBModule).Assembly);

⚙️ Configuration

Cấu hình hậu tố cho việc tự động đăng ký DI trong appsettings.json:

{
  "TLogSettings": {
    "AopSettings": {
      "DiRegistrationSuffixes": [
        "Service",
        "Provider",
        "Mapper",
        "Factory",
        "Manager",
        "Repository",
        "Policy"
      ]
    }
  }
}

Resilience — Engine KHÔNG áp policy lên Step

Không có timeout, retry hay circuit breaker ở tầng Step. Đây là quyết định có chủ đích, không phải thiếu sót — xem md/28.

Chính sách chịu lỗi thuộc về nơi lời gọi vượt qua ranh giới hạ tầng, không thuộc về logic nghiệp vụ chạy in-process:

Cấu hình chốt chặn cuối:

builder.Services.AddRequestTimeouts(o =>
    o.DefaultPolicy = new RequestTimeoutPolicy { Timeout = TimeSpan.FromSeconds(60) });

app.UseTCISCore();       // TExceptionMiddleware phải BỌC NGOÀI để phân loại được sự cố
app.UseRequestTimeouts();

📈 Số đo — cơ chế phát hiện sự cố duy nhất

Circuit breaker từng đảm nhiệm việc phát hiện một Step hỏng lặp lại. Nó đã bị gỡ bỏ vì bảo vệ sai mối đe doạ, nhưng tín hiệu thì vẫn cần. Từ nay cảnh báo là cơ chế cắt mạch duy nhất.

builder.Services.AddOpenTelemetry()
    .WithMetrics(m => m.AddMeter(PipelineMetrics.MeterName));   // "TCIS.Platform.Pipelines"

Cả ba đều mang nhãn tcis.site_code, tcis.step_key, tcis.context.

Quy tắc cảnh báo gợi ý (PromQL):

# Một Step của một cảng hỏng liên tục — thay cho vai trò của circuit breaker
sum by (tcis_site_code, tcis_step_key) (rate(tcis_pipeline_step_errors_total[5m])) > 0.2

# Một Step chậm bất thường — dấu hiệu sớm của DB treo
histogram_quantile(0.95,
  sum by (le, tcis_site_code, tcis_step_key) (rate(tcis_pipeline_step_duration_bucket[5m]))) > 5000

Hành vi lỗi của Engine

Chỉ còn ba tình huống, và không tình huống nào bỏ qua một Step. Mỗi Step hoặc chạy, hoặc làm dừng pipeline — nên lớp lỗi "pipeline báo thành công dù Step nghiệp vụ chưa chạy" (phát hiện P1-8) nay không còn tồn tại về mặt cấu trúc.

💡 Usage

Automatically register services by suffix (Auto-MultiTenantService) or utilize Attributes:

using TCIS.Pluggable.Abstractions.Pipelines.Attributes;
using TCIS.Pluggable.Abstractions.Pipelines.Abstractions;

[PipelineStep(StepKey = "ValidateOrder", Priority = 1, ExecutionOrder = 10)]
public class ValidateOrderStep : IPipelineStep<OrderContext>
{
    public Task ExecuteAsync(OrderContext context, CancellationToken cancellationToken)
    {
        // ... logic
        return Task.CompletedTask;
    }
}