O24Platform 2.5.2

O24Platform

Nền tảng thư viện dùng chung cho các dự án O24 — hỗ trợ Open API, workflow, queue (RabbitMQ), migration đa database, logging và tích hợp microservice.

Cài đặt

dotnet add package O24Platform

Cấu hình nhanh

Thêm section O24OpenAPIConfiguration vào App_Data/appsettings.json (hoặc secret store tương ứng):

"O24OpenAPIConfiguration": {
  "YourServiceID": "MS1",
  "IsMicroservice": true,
  "ConnectToWFO": true,
  "WFOGrpcURL": "https://wfo.example.com",
  "YourGrpcURL": "https://your-service.example.com"
}

• IsMicroservice = false: tắt queue, RabbitMQ event bus consumer và đăng ký WFO — phù hợp service standalone/API thuần.
• DataWarehouseEntities: Danh sách tên các entity cần đồng bộ sang Data Warehouse (DWH) theo cơ chế Transactional Outbox. Ví dụ: ["UserAccount", "Order", "Transaction"].

Release Notes

2.5.0 — 2026-09-06

Data Warehouse Synchronization Foundation (Transactional Outbox Pattern)

• Kiến trúc đồng bộ Transactional Outbox:
  • Bổ sung TableSyncEvent, entity OutboxMessage, OutboxMessageBuilder và cấu hình DataWarehouseEntities (HashSet) trong O24OpenAPIConfiguration.
  • Tự động ghi OutboxMessage trong cùng Database Transaction với entity nghiệp vụ cho cả thao tác đơn lẻ và hàng loạt (InsertAsync, Update, Delete, BulkInsert, BulkDelete, InsertWithoutAuditAsync). Đảm bảo tính toàn vẹn ACID, không bao giờ sinh event ma khi transaction rollback.
• Khóa hàng đa tiến trình tự nhiên (Multi-Instance Concurrency Protection):
  • OutboxPublisherJob hỗ trợ scale nhiều replica/pod chạy song song mà không tranh chấp hay trùng lặp tin nhắn, không phụ thuộc Redis lock.
  • Sử dụng khóa hàng bản địa của RDBMS: WITH (ROWLOCK, UPDLOCK, READPAST) (SQL Server) và FOR UPDATE SKIP LOCKED (PostgreSQL, MySQL 8.0+, Oracle).
  • Tích hợp cơ chế tự phục hồi Lease Timeout (5 phút) và tự động dọn dẹp log outbox đã gửi thành công sau 7 ngày (1 lần/ngày).
• Điều hướng sự kiện riêng biệt (Selective Service Routing):
  • Bổ sung attribute [ServiceRouted] và interface ITargetServiceRouted để RabbitMQ định tuyến routing key {ServiceId}.{EventName} chính xác đến từng microservice mục tiêu, loại bỏ hoàn toàn broadcast thừa thãi.
• Tự chữa lành & Đối soát dữ liệu (Event-Driven Reconciliation & Self-Healing):
  • Tích hợp sẵn DwhTableAuditRequestHandler để phục vụ job đối soát ban đêm từ DWH.
  • Tích hợp sẵn DwhDataBackfillRequestHandler sử dụng kỹ thuật Keyset Pagination (WHERE [Id] > @lastId ORDER BY [Id] LIMIT {batchSize}) để stream dữ liệu bù đắp hoặc khởi tạo bảng lịch sử lần đầu mà không làm khóa bảng hay tràn bộ nhớ RAM.

2.4.0 — 2026-09-04

gRPC Communication Foundation

• Tích hợp và chuẩn hoá toàn bộ hạ tầng gRPC dùng chung vào platform:
  • Protobuf Envelope (common.proto): GrpcRequest, GrpcResponse, GrpcResponseCode (SUCCESS=0, FAIL=-1) chuẩn hoá payload envelope trong namespace O24OpenAPI.Grpc.Common.
  • Interceptors chuẩn hoá:
    • GrpcClientOutboundInterceptor: Tự động đính kèm work_context metadata, đo latency, Serilog structured logging (LogType.Grpc, Direction: Out), phòng vệ null unary response.
    • GrpcServerInboundInterceptor: Tự động bóc tách work_context nạp vào WorkContext / EngineContext, mở AsyncServiceScope, chuẩn hoá exception thành GrpcResponse fail envelope, ghi log Inbound.
    • Hỗ trợ đầy đủ Unary và ServerStreaming calls.
  • Client Factory & Channel Pooling:
    • IGrpcClientFactory & GrpcClientFactory: Pooling GrpcChannel, auto-reconnect khi transient failure, sinh client động qua Expression Tree CallInvoker, tích hợp service discovery độc lập qua IWFOGrpcClientBaseService.
    • IGrpcClient<T> & ClientGrpc<T> generic wrapper cho DI container.
  • Base Client & Server Executor:
    • BaseGrpcClientService: Template method InvokeAsync<TResult> bọc header, parse JSON sang strongly-typed model và log lỗi Serilog.
    • GrpcExecutor: Helper ExecuteAsync cho gRPC server methods.
  • Extensions, Logging & Lifecycle:
    • GrpcExtensions: CallAsync<TResult>, GetGrpcResponseAsync, ToFailResponse, NullResponseFailure.
    • GrpcCallLogger: Ghi log có cấu trúc Serilog cho gRPC.
    • WfoServiceRegistryLifetimeService: Tự động unregister service endpoint khi host shutdown.
    • AddO24GrpcPlatform: Extension đăng ký toàn bộ DI hạ tầng gRPC cho ASP.NET Core service.

2.3.0 — 2026-08-17

Log Download API & Service

• Thêm các endpoint quản lý và tải file log: GET /api/logs/list, GET /api/logs/files, GET /api/logs/download, GET /api/logs/download-zip.
• Hỗ trợ quét tìm kiếm file log theo khoảng thời gian/LogType/SearchPattern, đọc non-blocking (FileShare.ReadWrite), và nén ZIP trực tiếp stream không tạo file tạm trên đĩa.

Swagger Session Validation Middleware

• Bổ sung SwaggerWorkContextMiddleware tự động bắt request gọi từ Swagger UI (X-From-Swagger header hoặc Referer URL), xác thực Session Token qua gRPC ISessionValidationService (CTH) và nạp WorkContext.
• Trả về JSON 401 Unauthorized chứa execution_id chuẩn hoá nếu token thiếu hoặc hết hạn.
• Phân lập hoàn toàn, không can thiệp hay ảnh hưởng tới luồng gọi inter-service giữa các microservices.

Serilog Diagnostics & Swagger UI

• Bật Serilog.Debugging.SelfLog.Enable ghi lỗi ra Console nếu xảy ra sự cố tạo/ghi file log.
• Tự động trích xuất Token trên Swagger UI bằng JavaScript Request Interceptor để đính kèm Authorization: Bearer <token> vào mọi HTTP request từ Swagger UI.

2.2.20 — 2026-08-06

Entity builders & schema

• Bổ sung EntityFieldBuilder, TransactionDetailsBuilder; O24OpenAPIServiceBuilder thêm MediatorKey.
• Gom builder theo entity/file: Language, Log, Setting, StoredCommand (class theo provider: SqlServer/MySQL/PostgreSQL vs Oracle qua [DatabaseType]).
• EntityBuilderStringColumnCatalog + EntityBuilderSchemaAligner: trên DB đã có, probe length + nullability; chỉ AlterColumn khi lệch builder (SqlServer, PostgreSQL, MySQL, Oracle).
• Migrations Update: EntityBuilderSchemaAlignmentMigration, EntityBuilderSchemaNullableAlignmentMigration (và aligner idempotent cho migration length cũ).

Index

• PlatformEntityIndexesMigration: tạo index không unique cho bảng platform; lỗi từng index → log (BusinessLogHelper) và bỏ qua, không throw fail cả migration.

O24OpenAPIService (CQRS fw)

• POST api/o24openapi-services/advance-search — lọc theo field builder.
• POST api/o24openapi-services/export-json — export JSON migration theo cùng điều kiện advance search.
• POST api/o24openapi-services/import-json — import JSON (upsert theo StepCode).
• Seed step WFO: DataO24OpenAPIServiceSearchExportMigration.

2.2.19 — 2026-08-06

• CodeList filter theo CodeId

• Bổ sung field CodeId vào GetCodeListByGroupAndNameQuery và CodeListGroupAndNameRequestModel.

• GET_CODE_LIST_BY_GROUP_AND_NAME hỗ trợ lọc danh sách theo tiền tố CodeId.

• CodeListService.GetByGroupAndName hỗ trợ cùng cơ chế lọc theo CodeId.

• Việc lọc không phân biệt chữ hoa/chữ thường.

• CodeId là tham số tùy chọn:

• Không truyền, truyền null, chuỗi rỗng hoặc khoảng trắng → bỏ qua điều kiện lọc.

• Truyền giá trị, ví dụ HPH → trả về các mã bắt đầu bằng HPH, như HPH07059, HPH07062, HPH07068, HPH08003.

• Bổ sung kiểm tra CodeId khác null trước khi thực hiện StartsWith, tránh lỗi với dữ liệu không có mã.

Ví dụ request:

{
  "code_id": "HPH",
  "page_index": 0,
  "page_size": 20
}

2.2.18 — 2026-08-05

DI, EngineContext và AsyncScope

• IEngine.CreateScope(WorkContextTemplate?) và CaptureWorkContextSnapshot() — snapshot WorkContext từ AsyncScope → HTTP → ambient scope (xử lý scope đã dispose).
• AsyncScope: TryGetServiceProvider(), Reset() (chỉ xóa pointer) vs Clear() (dispose + reset); bỏ property ServiceProvider dễ NRE.
• TaskUtils / TransactionDispatcher: capture snapshot trên thread gọi, CreateScope, restore ambient trong finally.
• QueueClient (command/event): CreateScope(template); dispose scope message + restore/Reset ambient (không Clear() kèm using).
• StartEngine: khôi phục AsyncScope sau migration/queue init (tránh trỏ scope đã dispose).
• Ghi chú trên EngineContext.Current: ưu tiên constructor DI; locator chỉ khi bắt buộc.

Health & runtime

• MapO24HealthEndpoints: GET /api/health/ping, GET /api/health/info (version, uptime, … qua IAppRuntimeInfoProvider).
• Startup banner dùng runtime info khi có.

Logging HTTP

• RestApiLoggingMiddleware: giới hạn kích thước body log, redact header, LogSanitizer; inject WorkContext.
• CorrelationIdMiddleware: tôn trọng header X-Correlation-ID.
• Cấu hình qua section Logging (LoggingConfig).

Event bus & queue

• IEventBus.PublishAsync(eventName, payload) — publish theo tên + object, không bắt buộc deserialize IntegrationEvent.
• RabbitMQEventBus / NoOpEventBus cập nhật tương ứng.

Data & cache

• Migration PlatformEntityIndexesMigration: index hiệu năng (không unique) cho entity platform (ví dụ LocaleStringResource, audit, CDC config, …).
• DistributedCacheManager.ClearAll(): xóa theo key đã track, không dùng Redis KEYS *.

Startup

• CreateDatabaseAsync() gọi trong StartEngine (async), bỏ .Wait() trên request pipeline.

Gợi ý dùng EngineContext (khi không inject được DI)

1. Request API: EngineContext.Current.Resolve<T>() thường ổn (ưu tiên HttpContext.RequestServices).
2. Background: CaptureWorkContextSnapshot() trên caller → using var scope = EngineContext.Current.CreateScope(snapshot) → restore ambient; hoặc TaskUtils.RunAsync / RunInNewScope.
3. Không gọi AsyncScope.Clear() trong finally nếu scope đã Dispose() bằng using/biến local.

2.2.17 — 2026-07-31

JSON static files (sandbox theo thư mục cấu hình)

• IJsonStaticFileService: search / get / update file .json trong RootPath; chặn path traversal và path ngoài root.
• Extension DI: AddJsonStaticFileService — root từ O24OpenAPIConfiguration.JsonStaticFileRootPath (mặc định ./StaticConfig).
• CQRS (MediatorKey = "fw"):
  • POST api/json-static-files/search
  • POST api/json-static-files/get
  • POST api/json-static-files/update

O24Resource / localization

• Bổ sung mã lỗi dùng chung (vi/en): NotFound, NotExists, InvalidInput, path/file/JSON validation, unique/conflict, … — cùng format class phẳng như các hằng validation hiện có.
• Migration O24ResourceMigration seed resource mới qua BaseResourceMigration.

Ví dụ đăng ký host (RootPath lấy từ O24OpenAPIConfiguration.JsonStaticFileRootPath):

"O24OpenAPIConfiguration": {
  "JsonStaticFileRootPath": "./StaticConfig"
}

builder.AddJsonStaticFileService();

2.2.16 — 2026-07-24

Connection string password decrypt / escape theo DataProvider

• DataConfig.DecryptConnectionString escape password theo từng DataProvider (Oracle / SqlServer / MySql / PostgreSQL).
• Oracle: không bọc single-quote (tránh ORA-01017 với Oracle.ManagedDataAccess.Core 23.x); chỉ double-quote khi password có delimiter.
• SqlServer: single-quote khi cần; MySQL / PostgreSQL: double-quote khi cần.
• Đổi DataProvider sẽ invalidate cache decrypted connection string.

2.2.15 — 2026-07-23

Stored procedure workflow V2

• Thêm ProcessNumber.StoredProcedureV2 (6).
• O24OpenAPIServiceManager hỗ trợ luồng HandleStoredProcedureWorkflowV2 khi processing_version = StoredProcedureV2.
• BaseQueue bổ sung CallStoredProcedureV2 và chuẩn hóa response data (snake_case) cho stored procedure V2.

2.2.14 — 2026-07-22

WorkContext scope

• Thêm WorkContext.Scope / WorkContextTemplate.Scope và SetScope.
• Thêm abstraction IScopeHandler để service tự implement xử lý scope.
• O24OpenAPIServiceManager gọi IScopeHandler.HandleScope() trước khi execute workflow khi Scope có giá trị.

2.2.13 — 2026-07-22

CodeList CQRS / WorkflowStep

• Thêm feature cho domain C_CODELIST (LinKit CQRS + [WorkflowStep]):
  • GET_CODE_LIST_BY_GROUP_AND_NAME
  • GET_CODE_LIST_BY_ID
  • CREATE_CODE_LIST
  • UPDATE_CODE_LIST
  • DELETE_CODE_LIST
• Response dùng CodeListResponseModel; caption resolve theo Language qua CodeListUtils.

Platform WorkflowStepInvoker

• Thêm O24Analyzer để gen WorkflowStepInvoker trong assembly O24Platform.
• Đăng ký IWorkflowStepInvoker keyed "fw" cùng AddLinKitCqrs("fw") — service dùng platform có thể invoke step CodeList qua mediator key fw.

2.2.12 — 2026-07-21

Read/write database split (read replica)

• Thêm cấu hình opt-in trên ConnectionStrings (DataConfig):
  • UseReadReplica: bật dùng read replica.
  • ReadConnectionString: connection string replica (decrypt giống ConnectionString).
  • Khi tắt hoặc thiếu read string → toàn bộ traffic vẫn đi primary (backward compatible).
• IDataConnectionFactory hỗ trợ DbAccessMode (Write | Read):
  • Query dùng read khi replica được bật.
  • Trong transaction (command / TransactionBehavior) luôn force Write để đảm bảo read-your-writes.
• BaseRepository tách connection theo thao tác:
  • Đọc (Table, Get*, Count, Search*) → Read.
  • Ghi (Insert / Update / Delete / bulk / audit) và mutate-by-query (WriteTable, WriteTableFilter) → Write.

Ví dụ cấu hình:

"ConnectionStrings": {
  "ConnectionString": "...",
  "ReadConnectionString": "...",
  "UseReadReplica": true
}

2.2.11 — 2026-07-20

Event Dispatching

• Hỗ trợ tham số mediatorKey trong IEventDispatcher.DispatchAsync và LinKitEventDispatcher để resolve IMediator instance theo tên (hỗ trợ sử dụng multi-mediator).

2.2.10 — 2026-07-19

Multi-database execution trên ServiceDBContext

• Bật đầy đủ EF Core provider cho SQL Server, PostgreSQL, MySQL/MariaDB và Oracle trong OnConfiguring (theo DataConfig.DataProvider / RDBMSType).
• Thống nhất execute SQL, query, DML, paged query và stored procedure qua dialect helpers (SqlServer | PostgreSQL | MySql | Oracle):
  • Parameter prefix (@ / :), identifier quoting ([] / "" / `), LIKE concat.
  • Schema switch: USE / SET search_path / ALTER SESSION SET CURRENT_SCHEMA.
  • Workflow SP: EXEC / CALL / BEGIN … END với output parameter chung.
• Thêm package Npgsql.EntityFrameworkCore.PostgreSQL, Pomelo.EntityFrameworkCore.MySql; cập nhật EF Core 9.0.1, MySqlConnector 2.4.0.

2.2.9 — 2026-07-19

Microservice opt-out

• Thêm O24OpenAPIConfiguration.IsMicroservice (mặc định true) để xác định service có tham gia hệ thống microservice hay không.
• Khi IsMicroservice = false:
  • Không khởi tạo QueueClient, không gọi WFO QueryServiceInfo, không chạy reconnect scheduler.
  • Không đăng ký RabbitMQEventBus consumer; dùng NoOpEventBus cho IEventBus.
  • Bỏ qua SyncProjectCodeAsync và InitializeMessageQueue.
  • Startup banner hiển thị Queue Status: DISABLED.

Bug fix

• CodeListService.GetByGroupAndName: trả về thêm field MCaption trong kết quả phân trang.

2.2.8 — 2026-07-17

• Bổ sung interface và implementation xử lý event.
• Refactor quản lý domain events.

2.2.6 — 2026-07-16

• Thêm ProjectCode vào O24OpenAPIConfiguration.
• Đồng bộ project code từ WFO qua SyncProjectCodeAsync.

2.2.x (trước 2.2.6)

• Chuẩn hóa pagination (PageIndex, offset) trên PagedList và ServiceDBContext.
• RabbitMQ event bus với partition-based dispatch.
• Data provider abstraction (SQL Server, Oracle, MySQL, PostgreSQL) và migration infrastructure.
• Workflow step source generator, O24OpenAPIServiceManager, logging Serilog, schedule tasks.