Backend Code Walkthrough — เจาะลึก Lego Engine (Sprint)

เอกสารนี้พาคุณเดินจาก “ไม่รู้เลย” → “เข้าใจว่า engine นี้ทำงานอย่างไร เขียนขึ้นมาทำไม และ code จริงเดินอย่างไร” — ก่อนลงรายละเอียด code ต้องเข้าใจ ทำไม ก่อน

1. ทำไมถึงเรียกว่า “Lego”? — แนวคิดพื้นฐาน

ปัญหาแบบดั้งเดิม: Hardcode Flow

ลองนึกถึงระบบ onboarding แบบเก่า — ถ้าต้องเพิ่ม “ขั้นตอนยืนยันที่อยู่” เข้าไปในกระบวนการสมัคร:

• แก้ Controller ของ flow นั้น
• เพิ่ม if step == 3 ใน logic
• deploy ระบบใหม่
• พอ Business บอกให้สลับลำดับ → refactor ใหม่ทั้งหมด

ทุก flow มี logic การ navigate กระจายอยู่ใน code — ซ้ำซ้อน ทดสอบยาก ขยายยาก

แนวคิด Lego: Data-Driven Engine

นึกถึงตัวต่อ Lego จริงๆ:

3 กฎหลักของ Engine

ผลที่ได้:

• ทุก flow (STANDARD_CUSTOMER, CUSTOMER_FIXED, NEW_REQUESTOR, …) วิ่งผ่าน engine เดียวกัน
• Handler unit test ง่าย — ทดสอบแค่ “input นี้ → output นี้”
• Business ขอเพิ่ม/เปลี่ยน step sequence ได้โดยไม่ต้องรอ engineer

2. สถาปัตยกรรม — Clean Architecture ใน 1 นาที

UserService แบ่งเป็น 4 โปรเจกต์ — ชั้นในไม่รู้จักชั้นนอก:

04 · Domain (Entities + Interfaces) = แกนใน ทุกชั้นอ้างเข้าหา ไม่ออกนอก

หลักการ Controller ใน Lego Engine:

// ✅ ทำอย่างนี้เท่านั้น
var result = await mediator.Send(new ExecuteStepActionCommand(...));
return ApiMatch(result);  // ไม่มี business logic ใน Controller

3. แผนที่ส่วนประกอบหลัก — แต่ละตัวมีไว้ทำอะไร

ก่อนดู code ให้รู้จัก “ตัวละคร” ทุกตัวก่อน:

4. Endpoints ทั้งหมด (OnboardingV2Controller)

ทุก endpoint รับ request → mediator.Send(...) → return ApiMatch(result) — Controller ไม่มี business logic

5. Code Walkthrough — กด “ถัดไป” 1 ครั้ง

POST /api/user-service/v1/onboarding/instances/{id}/steps/PersonalInfoStep/actions/Next

sequenceDiagram
  autonumber
  participant FE as Frontend
  participant C as OnboardingV2Controller
  participant P as MediatR pipeline
  participant H as ExecuteStepActionHandler
  participant E as FlowEngine
  participant SH as PersonalInfoStepHandler
  participant R as Repository (EF)
  participant DB as PostgreSQL
  FE->>C: POST .../actions/Next { stepData }
  C->>P: Send(ExecuteStepActionCommand)
  P->>H: behaviors (Performance/Audit/Validation/Tx…)
  H->>H: FlowAccessGuard (JWT owner หรือ EditSession cookie)
  H->>E: ExecuteActionAsync(instance, "PersonalInfoStep", Next, json)
  E->>SH: handler.ExecuteAsync(ctx)
  SH-->>E: FlowStepExecutionResult.Ok(output)
  E->>R: UpsertAsync(FlowInstanceStepData)
  R->>DB: INSERT/UPDATE DataJson (jsonb)
  E->>E: AdvanceTo(next interactive) + AdvanceAutomaticAsync
  E->>R: UpdateAsync(instance) — Status/CurrentStepIndex
  E-->>H: StepNavigationV2Dto (step ถัดไป)
  H-->>C: Result.Success(nav)
  C-->>FE: 200 ApiOk(nav)

ชั้นที่ 1 — Controller (รับ + ส่งต่อ)

[HttpPost("onboarding/instances/{id:guid}/steps/{stepType}/actions/{actionCode}")]
public async Task<IActionResult> Action(Guid id, string stepType, string actionCode, ExecuteActionRequest? body)
{
    if (!Enum.TryParse<StepActionCode>(actionCode, true, out var parsed))
        return BadRequest(new { errorCode = "Session.InvalidAction" });

    var inputJson = body?.StepData?.GetRawText();        // เก็บเป็น raw JSON ส่งต่อ
    var editSessionId = ReadSessionCookie();             // __Host-onboarding
    var result = await mediator.Send(new ExecuteStepActionCommand(id, stepType, parsed, inputJson, editSessionId));
    if (result.IsFailure) return ApiMatch(result);
    // sliding refresh cookie...
    return ApiOk(result.Value.Nav);
}

ชั้นที่ 2 — Application Handler (guard + เรียก engine + map error)

public async Task<Result<ExecuteStepActionResult>> Handle(ExecuteStepActionCommand cmd, CancellationToken ct)
{
    var instance = await repo.GetByIdAsync(cmd.InstanceId, ct);
    if (instance is null) return Result.Failure(Error.NotFound("Application.NotFound", "ไม่พบใบสมัคร"));

    // สิทธิ์ 2 ทาง: JWT owner-match หรือ EditSession cookie ที่ผูก instance นี้ (กัน IDOR)
    var auth = await FlowAccessGuard.AuthorizeAsync(instance, currentUser, cmd.EditSessionId, editSessionRepo, ct);
    if (auth.IsFailure) return Result.Failure(auth.Error);

    try
    {
        var nav = await engine.ExecuteActionAsync(instance, cmd.StepType, cmd.ActionCode, cmd.InputJson, auth.Value, ct);
        // sliding refresh: เลื่อน ExpiresAt ของ EditSession ทุก action
        return Result.Success(new ExecuteStepActionResult(nav, cookieSessionId, ttlSeconds));
    }
    catch (FlowEngineException ex)
    {
        return Result.Failure(Error.Validation(ex.ErrorCode, ex.Message));   // → 400 + ข้อความที่สื่อความหมาย
    }
}

ชั้นที่ 3 — FlowEngine (หัวใจ runtime)

public async Task<StepNavigationV2Dto> ExecuteActionAsync(
    FlowInstance instance, string stepType, StepActionCode action, string? inputJson, string actor, CancellationToken ct)
{
    var snapshot = FlowSnapshotBuilder.Deserialize(instance.FlowSnapshotJson);   // อ่าน flow ที่แช่แข็งไว้
    var curStep  = FlowSnapshotNavigator.StepAt(snapshot, instance.CurrentStepIndex);

    if (curStep.StepType != stepType)                                            // กันยิงผิด step
        throw new FlowEngineException("Session.InvalidStep", "stepType ไม่ตรงกับ currentStep");

    var handler = handlerRegistry.Resolve(stepType);                             // หา IFlowStepHandler ตาม stepType
    var result  = await handler.ExecuteAsync(new FlowStepExecutionContext {
        Instance = instance, StepType = stepType, InputJson = inputJson, StepData = existing, ActionCode = action }, ct);

    if (!result.Success)                                                         // validate ไม่ผ่าน
        throw new FlowEngineException(result.ErrorCode ?? "Step.Failed", result.ErrorMessage);

    await stepDataRepo.UpsertAsync(                                              // เก็บ output ของ step ลง DB
        FlowInstanceStepData.CreateExecuted(instance.Id, stepType, result.OutputJson ?? inputJson, actor), ct);

    // Next → เลื่อนไป interactive ถัดไป แล้วรัน Automatic chain ที่คั่น
    var next = FlowSnapshotNavigator.NextInteractiveIndex(snapshot, instance.CurrentStepIndex);
    instance.AdvanceTo(next >= 0 ? next : instance.CurrentStepIndex + 1, actor);
    await AdvanceAutomaticAsync(instance, snapshot, actor, ct);
    await instanceRepo.UpdateAsync(instance, ct);
    return await BuildNavigationAsync(instance, snapshot, ct);
}

:::details Automatic chain — AdvanceAutomaticAsync (engine รัน step เองจนเจอ Interactive หรือจบ)

while (true)
{
    var step = FlowSnapshotNavigator.StepAt(snapshot, instance.CurrentStepIndex);
    if (step is null) { instance.TransitionToFinalized(actor); return; }   // จบ flow
    if (step.ExecutionMode != StepExecutionMode.Automatic) return;         // หยุดที่ Interactive

    var result = await handlerRegistry.Resolve(step.StepType)
        .ExecuteAsync(new FlowStepExecutionContext { Instance = instance, StepType = step.StepType, InputJson = null, ... }, ct);

    if (!result.Success) { instance.MarkStuck(step.StepType, actor); return; }   // ค้าง → admin retry
    await stepDataRepo.UpsertAsync(FlowInstanceStepData.CreateExecuted(...), ct);
    instance.AdvanceTo(instance.CurrentStepIndex + 1, actor);
}

:::

ชั้นที่ 4 — Handler (โค้ดที่รัน 1 step)

PersonalInfoStepHandler — parse JSON → validate → คืน output:

public Task<FlowStepExecutionResult> ExecuteAsync(FlowStepExecutionContext ctx, CancellationToken ct = default)
{
    if (string.IsNullOrWhiteSpace(ctx.InputJson))
        return Fail("Step.NoInput", "กรุณากรอกข้อมูลส่วนตัว");

    using var doc = JsonDocument.Parse(ctx.InputJson);
    // root = view ที่ชี้เข้า doc — ต้องอ่านค่าทั้งหมด "ก่อน" doc ถูก dispose
    var root = doc.RootElement.TryGetProperty("stepData", out var sd) ? sd : doc.RootElement;
    var firstNameTH = GetStr(root, "firstNameTH");
    // ... validate required ...
    var output = JsonSerializer.Serialize(new { firstNameTH, lastNameTH, phone, ... });
    return Ok(output);
}

6. Handler เจาะลึก: OtpVerificationStep (identity boundary)

Step นี้คือจุดเปลี่ยน anonymous → authenticated — 1 step มี 2 action:

sequenceDiagram
  autonumber
  participant FE as Frontend
  participant H as OtpVerificationStepHandler
  participant OTP as OtpStateClient
  participant EN as Entra (CIAM)
  participant U as CreateUserInternalService
  participant DB as PostgreSQL
  FE->>H: Next (verify) { otp, refCode }
  H->>OTP: VerifyOtpAsync(otp)
  H->>EN: SignUpContinueWithOtp → id_token (oid)
  H->>EN: DeactivateIdentity(oid)  %% กัน orphan จน ActivateEntraUser
  H->>U: CreateAsync(minimal User: email+oid)
  U->>DB: INSERT Users (+ UserRestrictedProfile ค่าว่าง)
  H->>H: instance.BindOwner(userId)  %% anonymous → owner
  H->>DB: rotate EditSession (UserId set + sessionId ใหม่)
  H-->>FE: Ok(status=VERIFIED)

var verify = await otpState.VerifyOtpAsync(OtpModule.Onboarding, email, otp, continuationToken, ct);
if (verify.IsFailure) return Fail(verify.Error.Code, verify.Error.Description);

var auth = await entraSignUp.SignUpContinueWithOtpAsync(_tenantKey, continuationToken, otp, ...);
var oid  = ExtractOidFromIdToken(auth.IdToken);              // CIAM v2: ใช้ oid ไม่ใช่ sub
await graphIdentity.DeactivateIdentityAsync(_tenantKey, oid, ct);

var create = await createUser.CreateAsync(new CreateUserCommand(oid, email, ...), ct);
ctx.Instance.BindOwner(create.Value.Id, "otp-identity");    // engine persist instance หลัง handler
// rotate EditSession: deactivate เก่า + สร้างใหม่ (stamp UserId, anti session-fixation)

7. Attribute ของ Step — มีอะไรให้กำหนดได้บ้าง

ก่อนดูว่าระบบมี step อะไรบ้าง ต้องเข้าใจก่อนว่า step 1 ตัวมี “ลักษณะ” อะไรที่ตั้งได้บ้าง — ทั้งหมดนี้เก็บอยู่ใน StepCatalog (ทะเบียน step type) และ FlowStep (การผูก step เข้ากับ flow)

ExecutionMode — ใครขับ step นี้?

ExecutionMode กำหนดที่ StepCatalog ต่อ step type — Interactive step ทุกตัวจะมี component บน FE ส่วน Automatic จะไม่อยู่ใน STEP_REGISTRY เลย

CanGoBack — ย้อนกลับได้ไหม?

กำหนดที่ FlowStep (ต่อ step ต่อ flow — ไม่ใช่ต่อ step type) เพราะ step เดียวกันอาจ canGoBack ต่างกันในแต่ละ flow

canGoBack = true  → user กด Back กลับมา step นี้ได้
canGoBack = false → step นี้ผ่านแล้วย้อนไม่ได้ (เช่น OTP ที่ bind identity แล้ว)

MaxRetries + RetryBackoffSeconds — Automatic step ล้มเหลวจัดยังไง?

เฉพาะ Automatic step เท่านั้น — ถ้า handler คืน Fail():

ปัจจุบัน: engine ไม่ retry inline — Fail() ครั้งเดียวก็ MarkStuck ทันที แล้วปล่อยให้ Worker จัดการ

DependenciesJson — step นี้ต้องการ step อื่นก่อนไหม?

เก็บเป็น JSON array บอกว่า step type ไหนต้องทำก่อน และ mode ว่าบังคับหรือแนะนำ:

[
  { "StepTypeCode": "JuristicBindingStep", "Mode": "Required" },
  { "StepTypeCode": "UserModeStep",        "Mode": "Optional" }
]

SkipScope — ข้ามซ้ำได้ไหม?

กำหนดว่า user ที่เคยทำ step นี้ไปแล้วในอดีตจะ “ข้าม” step ได้ไหม (copy-on-skip pattern):

LockedAfterFirstExecution — ทำซ้ำไม่ได้

true  → step นี้ execute ได้ครั้งเดียว เช่น OTP, NDID (กัน replay attack)
false → ทำซ้ำได้ (เช่น กรอกข้อมูลส่วนตัวแก้ได้หลายครั้ง)

ctx.StepData — handler อ่านข้อมูลจาก step อื่น

ทุก handler รับ FlowStepExecutionContext ซึ่งมี StepData เป็น dictionary ของ output ทุก step ที่ผ่านมาแล้ว:

// อ่านข้อมูลจาก step อื่นผ่าน StepType — ไม่ใช่ index
var juristicData = ctx.StepData.GetValueOrDefault("JuristicBindingStep");

ทำให้ handler สามารถ cross-reference ข้อมูลจาก step อื่น โดยไม่ต้องรู้ตำแหน่งของ step นั้นในลำดับ

การ Parse InputJson — Pattern และข้อควรระวัง

ctx.InputJson คือ raw JSON string จาก client — codebase ทั้งหมดอ่านผ่าน JsonDocument + TryGetProperty แบบ manual ไม่ใช้ Deserialize<T> โดยตรง

Pattern มาตรฐาน (ทุก handler ใช้แบบนี้):

using var doc = JsonDocument.Parse(ctx.InputJson ?? "{}");
// รองรับทั้ง { "stepData": { ... } } และ flat { ... }
var root = doc.RootElement.TryGetProperty("stepData", out var sd) ? sd : doc.RootElement;

// อ่านทีละ field ภายใน using scope
var firstName = root.TryGetProperty("firstNameTH", out var v1) ? v1.GetString() ?? "" : "";
var phone     = root.TryGetProperty("phone",       out var v2) ? v2.GetString() ?? "" : "";

ทำไมไม่ Deserialize<T> ตรงๆ? เพราะ JsonElement ยังผูกกับ doc — ถ้าอยาก map ใส่ model มี 2 ทางที่ปลอดภัย:

// ทาง 1: Deserialize จาก GetRawText() ภายใน using (doc) — ยังอยู่ใน scope
using var doc = JsonDocument.Parse(ctx.InputJson ?? "{}");
var root  = doc.RootElement.TryGetProperty("stepData", out var sd) ? sd : doc.RootElement;
var model = JsonSerializer.Deserialize<MyInputModel>(root.GetRawText()); // ✅

// ทาง 2: ข้าม JsonDocument ทั้งหมด — Deserialize จาก InputJson ตรงๆ
var wrapper = JsonSerializer.Deserialize<StepDataWrapper>(ctx.InputJson ?? "{}");
var model   = wrapper?.StepData ?? wrapper;                               // ✅

บาง handler สร้าง private sealed record เพื่อรับค่า แต่ก็ยัง map ด้วยมือ ผ่าน TryGetProperty:

// PersonalInfoStepHandler — มี record แต่ map เอง ไม่มี auto-deserialize
private sealed record PersonalInfoRecord(string FirstNameTH, string LastNameTH, string Phone, ...);

var pi = new PersonalInfoRecord(
    FirstNameTH: root.TryGetProperty("firstNameTH", out var v1) ? v1.GetString() ?? "" : "",
    LastNameTH:  root.TryGetProperty("lastNameTH",  out var v2) ? v2.GetString() ?? "" : "",
    Phone:       root.TryGetProperty("phone",       out var v5) ? v5.GetString() ?? "" : ""
);

8. ประเภท Step และ Handler ทั้งหมด

Lego Engine มี handler 20 ตัว แบ่งเป็น Interactive (รอ user) และ Automatic (engine run เอง) เข้าใจแต่ละตัวก่อนจะทำให้เห็นภาพว่า “เลโก้” แต่ละชิ้นมี spec อะไร

ตารางสรุป StepCatalog ทั้งหมด

Interactive Steps — เจาะลึกทีละตัว

OtpVerificationStep — Identity Boundary (2-action)

Step นี้พิเศษกว่าตัวอื่น: 1 step มี 2 action แตกต่างกันโดยสิ้นเชิง

SaveDraft (ส่ง OTP) flow:

1. อ่าน email จาก EditSession (server-side — ไม่รับจาก client เพื่อป้องกัน account takeover)
2. ค้นหา orphan identity ใน Entra (email เดิม) → deactivate ทิ้ง
3. สร้าง OTP refCode ผ่าน OtpStateClient
4. เรียก Entra SignUpStart → บันทึก continuation token

Next (verify OTP) flow:

1. Verify OTP ผ่าน OtpStateClient
2. เรียก Entra SignUpContinueWithOtp → ได้ id_token → แยก oid
3. Deactivate Entra identity ชั่วคราว (ป้องกัน orphan ก่อน ActivateEntraUser)
4. สร้าง User minimal (email + oid) → CreatePlatformUser จะ fill profile ทีหลัง
5. ctx.Instance.BindOwner(userId) — instance เปลี่ยนจาก anonymous → owner-bound
6. Rotate EditSession (สร้างใหม่ + invalidate เก่า — anti session-fixation per ADR-0023)

JuristicBindingStep — CRM + DBD + Company Uniqueness

Step ที่ซับซ้อนที่สุดใน Requestor flow — มี 3 external calls + 3 uniqueness checks:

juristicId → DBD lookup → company info
           → CRM eligibility check → block ถ้าไม่ eligible
           → find-or-create Company (sync from DBD)
           → uniqueness check 1: same-requestor duplicate?
           → uniqueness check 2: cross-requestor in-progress?
           → uniqueness check 3: requestor already bound to company?
           → ctx.Instance.SetCompanyId(companyId)

OutputJson: {juristicId, companyId, nameTH, nameEN, juristicType, juristicStatus, address, creditLineCap}

DesignateCustomersStep — Validation หนักที่สุด

Validate ทุก customer ที่ Requestor ระบุมา:

Reads from ctx.StepData: JuristicBindingStep (creditLineCap), UserModeStep (mode)

OutputJson: Array ของ {idType, idNo, nameTH, nameEN, position, email, companyRole, transactionLimit}

SubmitApplicationStep — Dependency Gate (Requestor)

ตรวจว่า 6 step ครบทุกตัว ก่อน Submit:

required = ["JuristicBindingStep", "CompanyInfoStep", "UserModeStep",
            "DesignateCustomersStep", "ServiceTcConsentStep", "SignatoryFormStep"]

ถ้าขาด step ใด → Fail("Step.DependencyMissing", "กรุณาทำ ... ให้ครบก่อน")

SubmitRegistrationStep — Dependency Gate (Customer)

required = ["ConsentStep", "PersonalInfoStep"]

PersonalInfoStep — ข้อมูลส่วนตัว (Customer)

Required: firstNameTH, lastNameTH, phone Optional: firstNameEN, lastNameEN, nameTitleTH, nameTitleEN

NdidStep — Stub (ยังไม่ integrate จริง)

ปัจจุบัน stub: always return {status:"verified", verifiedAt:"<timestamp>"} ไม่ว่า input จะเป็นอะไร — จะ replace ด้วย NDID service จริงในอนาคต

Automatic Steps — เจาะลึกทีละตัว

Automatic step รับ InputJson = null (ไม่มี user input) — อ่านข้อมูลจาก ctx.StepData ของ step ก่อนหน้าแทน

CreatePlatformUser — Fill User Profile

ctx.StepData["PersonalInfoStep"] → firstName, lastName, phone, nameTitle
User minimal (สร้างตอน OTP) → update profile

Idempotent: ถ้า User ถูก create แล้วก็แค่ update profile — ไม่ duplicate

ActivateEntraUser — Stub

ปัจจุบัน stub: return {entraActivated:false, stub:true} — จะ replace ด้วย Microsoft Graph call เพื่อ activate identity ที่ถูก deactivate ตอน OTP

CreateUserCompanyMapping — ผูก Customer กับ Company (CUSTOMER_FIXED)

InvitationToken.CompanyId → สร้าง UserCompanyMapping (isDefault=true)

ผูก Customer user เข้ากับบริษัทที่ Requestor เชิญมา

CreateCompanyApplication — สร้าง CompanyApplication (Requestor)

instance.CompanyId + instance.ServiceId → สร้าง CompanyApplication
→ Lock Requestor ผ่าน CompanyRequestor junction table
→ Auto-reject competing in-progress application สำหรับ company+service เดิม (ถ้ามี)

Idempotent: ถ้ามี CompanyApplication อยู่แล้ว → skip ไม่ error

GenerateCustomerInvitations — สร้าง InvitationToken

ctx.StepData["DesignateCustomersStep"] → array of customers (email, role, limit)
FlowDefinition.SpawnsCustomerFlowCode → flow code สำหรับ customer
FlowDefinition.InvitationTtlDays → TTL ของ token (default 7 วัน)
→ สร้าง InvitationToken per customer (CompanyId + OriginatingFlowInstanceId)

OutputJson: {invitations:[{email, tokenId}]}

SendInvitationEmails — ส่งอีเมล

ctx.StepData["GenerateCustomerInvitations"] → list of {email, tokenId}
FlowDefinition.TemplateKey → email template
FlowDefinition.FrontendBaseUrl → base URL สำหรับ link
→ publish invitation event per email → NotificationService
Link format: {FrontendBaseUrl}/onboarding?code={tokenId}

ProvisionCustomerAccess — Set Role + Limit (CUSTOMER_FIXED)

Step สุดท้ายที่ซับซ้อนที่สุดใน Customer Fixed flow — ต้อง cross-reference ไป Requestor flow:

InvitationToken.OriginatingFlowInstanceId → Requestor's FlowInstance
→ อ่าน DesignateCustomersStep ของ Requestor
→ match customer by email
→ resolve companyRole enum
→ update UserCompanyMapping (role + transactionLimit)

8. การตั้งค่า FlowDefinition — ทุก Field มีผลอะไรที่ Runtime

Admin ตั้งค่าเหล่านี้ใน FlowStudio (หรือ DB โดยตรง) และ engine จะ อ่านค่าเหล่านี้ตอน runtime เพื่อปรับพฤติกรรม:

9. Database — ทุก Table ทุก Field

FlowInstance เป็นศูนย์กลาง ผูกกับทุกตารางอื่น section นี้อธิบายทุก field ว่าเก็บอะไร เพื่ออะไร และ null ได้ไหม

FlowDefinitions — template ของ flow (admin config)

StepCatalogs — ทะเบียน step type ทั้งหมด

FlowSteps — ลำดับ step ใน flow

FlowInstances — 1 execution จริงของ flow

ตารางนี้สำคัญที่สุด — ทุก action ของ user อ่านและเขียนที่นี่:

FlowInstanceStepData — output ของแต่ละ step

EditSessions — anonymous session ก่อน bind owner

InvitationTokens — one-time token สำหรับ invite customer

CorrectionRequests — ประวัติคำขอแก้ไข (append-only)

8. Use Cases / Scenarios

A · Happy path (STANDARD_CUSTOMER_ONBOARDING) — เดินครบจน Finalized

B · Validation fail → field ว่าง → handler Fail("Step.RequiredField", "...") → engine throw FlowEngineException → catch → 400 + ข้อความไทย (ผู้ใช้เข้าใจ ไม่ใช่ SYS001)

C · Unhandled exception → ObjectDisposedException (เคสที่แก้ใน sprint) → หลุดถึง GlobalExceptionHandler → 500 SYS001 generic — แต่ stack trace ถูก log ฝั่ง server (มี traceId ใน problem+json)

D · Resume จาก cookie → เปิด /onboarding ใหม่ → GET /onboarding/session:

// resume เฉพาะ flow ที่ยัง in-progress; instance ที่จบ/ส่งแล้ว = "ไม่มี session" → 404 → FE เริ่มใหม่
if (instance.Status is not (FlowInstanceStatus.Draft or FlowInstanceStatus.CorrectionRequested))
    return NoSession();

9. วิธีเพิ่ม Step ใหม่ — สรุปย่อ

การเพิ่ม step ใหม่แตะ 4 จุด backend + 2 จุด frontend และทั้งหมดผูกกันด้วย string เดียวคือ stepType:

// Template handler — StepType ต้องตรงกับ StepCatalog.StepTypeCode และ FE STEP_REGISTRY key เป๊ะ
public sealed class MyNewStepHandler : IFlowStepHandler
{
    public string StepType => "MyNewStep";   // ← string นี้คือ contract ทั้งหมด

    public Task<FlowStepExecutionResult> ExecuteAsync(FlowStepExecutionContext ctx, CancellationToken ct = default)
    {
        using var doc = JsonDocument.Parse(ctx.InputJson ?? "{}");
        var root = doc.RootElement.TryGetProperty("stepData", out var sd) ? sd : doc.RootElement;
        // validate ที่นี่ — อ่านค่าให้เสร็จก่อน doc ถูก dispose
        var val = GetStr(root, "requiredField");
        if (string.IsNullOrWhiteSpace(val))
            return Task.FromResult(FlowStepExecutionResult.Fail("Step.RequiredField", "กรุณากรอกข้อมูล"));

        // อ่าน output ของ step อื่นผ่าน StepType (ไม่ใช่ index)
        var prev = ctx.StepData.GetValueOrDefault("JuristicBindingStep");

        var output = JsonSerializer.Serialize(new { val });
        return Task.FromResult(FlowStepExecutionResult.Ok(output));
    }
}

10. สรุปสิ่งที่ทำใน Sprint นี้

• engine generic (FlowEngine) — Start / ExecuteAction / AdvanceAutomatic + state machine (Draft→Submitted→Approved→Finalized/…)
• endpoint เดียวขับทุก step (POST .../steps/{stepType}/actions/{action}) + guard 2 ทาง (owner / EditSession)
• handler ต่อ step (Consent / NDID / PersonalInfo / Otp identity / Automatic chain)
• error model — Fail()→FlowEngineException→400 ไทย · unhandled→500 SYS001 (+log)
• resume guard — instance ที่จบแล้วไม่ resume (404)
• บั๊กที่แก้ — PersonalInfoStep ObjectDisposedException (JsonElement หลุด using scope) → 500 หาย