TicketManagement.Sdk 1.0.17

TicketManagement.Sdk

TicketManagement.Sdk là client .NET chính thức giúp các hệ thống con (source systems) tích hợp với Ticket Management API. Thư viện này phản ánh đầy đủ nghiệp vụ quy trình xử lý ticket (workflow) và các nguyên tắc miền (domain invariants) được định nghĩa trong aggregate root Ticket.

Tổng quan nghiệp vụ (Business Domain Overview)

Ticket là gì?

Ticket là một yêu cầu nghiệp vụ (request) được gửi từ hệ thống con lên hệ thống Ticket Management để xử lý theo một quy trình luồng (workflow). Mỗi ticket có:

• Thông tin nguồn: SourceSystemId (hệ thống con), SourceTicketId (ID gốc), DeepLinkUrl (URL quay lại hệ thống con).
• Phân loại: TicketTypeId, TicketTypeName, Title, Summary, Priority (Low, Medium, High, Critical).
• Người tạo yêu cầu (requester): RequesterHdCode, RequesterName, RequesterEmail, RequesterBranchId.
• Trạng thái nghiệp vụ: BusinessStatus — xem chi tiết bên dưới.
• Các bước xử lý (steps): Một hoặc nhiều bước, mỗi bước có thể có nhiều người xử lý (multi-assignee).
• Lịch sử thay đổi (histories): Ghi lại toàn bộ hành động kèm snapshot trước/sau.
• Reminder: Cấu hình nhắc nhở xử lý ticket.
• Detail Properties: Thông tin mở rộng dạng key-value.

Trạng thái nghiệp vụ (BusinessStatus)

⚠️ Quy tắc chuyển trạng thái:

• Không thể chuyển từ trạng thái kết thúc (Completed / Cancelled / Rejected) sang trạng thái khác.
• Không thể chuyển lùi sang trạng thái có thứ tự thấp hơn (ngoại lệ: Revoke từ PendingReview → Open).
• Thứ tự: Open (0) → PendingReview (1) → Forwarded (2) → Completed (3).

Trạng thái bước xử lý (StepStatus)

Hành động trên bước (StepAction)

Vòng đời ticket (Ticket Lifecycle)

          ┌──────────────────────────────────────────────┐
          │              Tạo ticket (Create)              │
          │  CreateDraft → Open ─── CreateAndSend ──┐     │
          │                      │                   │     │
          └──────────────────────┼───────────────────┘     │
                                 │                         │
                    ┌────────────┴────────────┐             │
                    │  Open (Draft)           │             │
                    │  - Chỉ requester thấy    │             │
                    │  - Chưa có assignee      │             │
                    └────────────┬────────────┘             │
                                 │                          │
                                 │ Send (do requester)      │
                                 │                          │
                    ┌────────────┴────────────┐             │
                    │  PendingReview           │◄────────────┘
                    │  - Assignee xem xét      │
                    │  - Có thể:               │
                    │    • Approve → Completed  │
                    │    • ApproveAndMoveNext   │
                    │      → Forwarded          │
                    │    • Reject → Rejected    │
                    │    • SendBack → step cũ   │
                    │    • Cancel → Cancelled   │
                    │    • Revoke → Open        │
                    └────────────┬────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │  Forwarded               │
                    │  - Bước mới, assignee mới│
                    │  - Các hành động tương tự│
                    └────────────┬────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │  Completed / Cancelled /│
                    │  Rejected               │
                    │  (Terminal)             │
                    └─────────────────────────┘

Quy tắc nghiệp vụ (Business Rules)

Ai được làm gì?

Các ràng buộc khác

1. Mỗi step có thể có nhiều assignees — hỗ trợ multi-approval, parallel assignment.
2. Draft ticket chỉ có 1 step — không thể Send nếu đã có nhiều hơn 1 step.
3. Không thể Revoke nếu step đã được xử lý (thời gian ActedAt đã được ghi nhận).
4. Khi ticket vào trạng thái kết thúc (Completed / Cancelled / Rejected), reminder tự động tắt.
5. Mỗi hành động workflow đều ghi snapshot trước/sau — phục vụ audit và trace.
6. Business status không thể chuyển lùi (trừ Revoke là ngoại lệ có chủ đích).

SDK API & Domain Mapping

Mỗi method trong SDK tương ứng với một domain method trên entity Ticket:

Quick Start — Luồng nghiệp vụ điển hình

1. Khởi tạo client

using TicketManagement.Sdk.Builder;
using TicketManagement.Sdk.Implementation;
using TicketManagement.Sdk.Models.Common;
using TicketManagement.Sdk.Models.Enums;
using TicketManagement.Sdk.Models.Requests;

var client = TicketManagementClient
    .CreateBuilder()
    .WithBaseUrl("https://your-ticket-management-host/")
    .WithSourceSystemId("YOUR_SOURCE_SYSTEM")
    .WithSecret("YOUR_SHARED_SECRET")
    .Build();

2. Tạo ticket và gửi xử lý (luồng 2 bước)

// Requester tạo step đầu tiên
var stepBuilder = TicketStep
    .CreateBuilder()
    .WithStepCode("SUBMIT")
    .WithStepName("Trình ký")
    .WithStepOrder(1)
    .WithAssignees(new List<TicketAssignee>
    {
        new() { HdCode = "HD0002", Name = "Trưởng bộ phận", Email = "truongbp@bank.com", BranchId = "BR001" }
    });

var requestBuilder = CreateTicketRequest
    .CreateBuilder()
    .WithTicketTypeId("LOAN")
    .WithTicketTypeName("Giải ngân vay")
    .WithSourceTicketId("EXT-001")
    .WithTitle("Giải ngân cho khách hàng XYZ")
    .WithPriority(TicketPriority.High)
    .WithRequesterHdCode("HD0001")
    .WithRequesterName("Nguyễn Văn A")
    .WithRequesterEmail("a.nguyen@bank.com")
    .WithRequesterBranchId("BR001")
    .WithStep(stepBuilder);

// Tạo và tự động Send — ticket vào PendingReview ngay
var result = await client.CreateAndSendAsync(requestBuilder);

3. Xử lý ticket — phê duyệt và kết thúc

// Assignee (HD0002) phê duyệt — ticket kết thúc
var approveResult = await client.ApproveAsync(
    result.TicketId,
    TicketApproveRequest.CreateBuilder()
        .WithApproverHdCode("HD0002")
        .WithApproverName("Trưởng bộ phận")
        .WithComments("Đã kiểm tra và phê duyệt")
);
// BusinessStatus → Completed

4. Xử lý ticket — phê duyệt và chuyển tiếp

// Assignee phê duyệt và tạo step mới cho cấp trên
var nextStep = TicketStep
    .CreateBuilder()
    .WithStepCode("DIRECTOR_APPROVE")
    .WithStepName("Giám đốc duyệt")
    .WithStepOrder(2)
    .WithAssignees(new List<TicketAssignee>
    {
        new() { HdCode = "HD0003", Name = "Giám đốc", Email = "gd@bank.com", BranchId = "BR001" }
    });

var nextResult = await client.ApproveAndMoveNextAsync(
    result.TicketId,
    TicketApproveAndMoveNextRequest.CreateBuilder()
        .WithApproverHdCode("HD0002")
        .WithApproverName("Trưởng bộ phận")
        .WithComments("Trình giám đốc duyệt")
        .WithNextStep(nextStep)
);
// BusinessStatus → Forwarded, step DIRECTOR_APPROVE được tạo

5. Các hành động khác

// Từ chối — chỉ assignee hiện tại mới được reject
await client.RejectAsync(
    ticketId,
    TicketRejectRequest.CreateBuilder()
        .WithRejecterHdcode("HD0002")
        .WithRejectionReason("Hồ sơ chưa đầy đủ")
);
// BusinessStatus → Rejected

// Trả về bước trước
await client.SendBackAsync(
    ticketId,
    TicketSendBackRequest.CreateBuilder()
        .WithApprovalManagerHdcode("HD0002")
        .WithComments("Vui lòng chỉnh sửa thông tin")
);
// BusinessStatus → PendingReview, current step trở về step trước

// Hủy — chỉ requester mới được cancel
await client.CancelAsync(
    ticketId,
    TicketCancelRequest.CreateBuilder()
        .WithCancellerHdcode("HD0001")
        .WithCancellationReason("Không còn nhu cầu")
);
// BusinessStatus → Cancelled

// Đóng — step hiện tại phải đang Approved
await client.CloseAsync(
    ticketId,
    TicketCloseRequest.CreateBuilder()
        .WithCloserHdcode("HD0002")
        .WithCloseReason("Hoàn thành")
);
// BusinessStatus → Completed

// Rút lại — chỉ requester, step chưa xử lý
await client.RevokeAsync(
    ticketId,
    TicketRevokeRequest.CreateBuilder()
        .WithRevokerHdcode("HD0001")
        .WithRevocationReason("Tạo nhầm, cần chỉnh sửa")
);
// BusinessStatus → Open

Request Models & Builders

Mỗi request model có private constructor — không thể dùng new. Phải dùng fluent builder (truy cập qua CreateBuilder()), builder sẽ validate các field bắt buộc khi Build() được gọi nội bộ.

Mỗi SDK method nhận builder interface (không phải request đã build) và gọi Build() nội bộ trước khi gửi.

Response Models

Models

Xử lý lỗi (Error Handling)

Tất cả exception kế thừa từ TicketClientException với thuộc tính ErrorCode.

Các exception không phải HTTP:

Cấu hình client

var client = TicketManagementClient
    .CreateBuilder()
    .WithBaseUrl("https://api.example.com/")            // Required
    .WithSourceSystemId("MY_SYSTEM")                     // Required
    .WithSecret("shared-secret")                         // Required
    .WithSchemaVersion("1.0")                            // Optional, default "1.0"
    .WithTimeout(TimeSpan.FromSeconds(60))               // Optional, default 30s
    .WithRetryPolicy(maxRetries: 5, initialDelayMs: 200) // Optional, default 3/100ms
    .WithLogger(msg => Console.WriteLine(msg))           // Optional
    .WithMessageId(Guid.NewGuid())                       // Optional
    .Build();

Authentication Headers

Idempotency

Mỗi request có thể gửi kèm header X-Message-Id (GUID) để đảm bảo xử lý một lần. Nếu message trùng, API trả về kết quả của lần xử lý trước — không tạo ticket mới.

// Gán mặc định cho tất cả request
client = clientBuilder.WithMessageId(Guid.NewGuid()).Build();

// Hoặc gán riêng cho từng request
var result = await client.CreateAndSendAsync(requestBuilder, messageId: Guid.NewGuid());

Retry Policy

SDK tự động retry trên transient failures với exponential backoff:

• Transient status codes: 408 (RequestTimeout), 429 (TooManyRequests), 500, 502, 503, 504
• Transport errors: HttpRequestException
• Mặc định: 3 retries, 100ms initial delay (nhân đôi mỗi lần)
• Custom: WithRetryPolicy(maxRetries, initialDelayMs)

Cấu trúc thư mục

TicketManagement.Sdk/
├── Builder/                         # Fluent builders
├── Contracts/
│   └── ITicketClient.cs             # Public SDK contract
├── Exceptions/                      # Exception hierarchy
├── Implementation/
│   ├── TicketManagementClient.cs    # Core SDK implementation
│   └── SdkClientOptions.cs
├── Models/
│   ├── Common/                      # TicketStep, TicketAssignee, TicketReminder
│   ├── Enums/                       # Business/step enums
│   ├── Requests/                    # Request models (builder pattern)
│   └── Responses/                   # Response models
└── README.md