AMLO Screening — Phase 2 Design (Backend)

หน้านี้เป็นงานของทีมเรา — ต่างจาก Phase 1 ที่ส่งต่อให้ dev คนอื่น จึงไม่ต้อง self-contained · อ่านคู่กับ Architecture และ Implementation Plan แตะ 4 repo: Backend_Package · Backend_Centralized · Backend_UserService · Backend_FileManagementService

1. ลำดับข้าม repo — ทำผิดลำดับแล้วติด

flowchart TB
    P0["ขั้น 0 — Backend_Package<br/>เพิ่ม field AMLO ใน UserInfoForRedis<br/>แล้ว publish version ใหม่"]
    P1["ขั้น 1 — consumer ที่อ่าน blob<br/>bump package version"]
    P2["ขั้น 2 — Centralized<br/>API อ่าน screened list แบบ bulk"]
    P3["ขั้น 3 — UserService<br/>schema + reconcile + unblock + audit"]
    P4["ขั้น 4 — FileManagementService<br/>เปิด upload/download + category หลักฐาน"]
    P5["ขั้น 5 — UserService<br/>ต่อ FMS เข้ากับ flow ปลดล็อก"]

    P0 --> P1 --> P3
    P2 --> P3
    P4 --> P5
    P3 --> P5

2. Backend_Package — contract กลาง

2.1 สิ่งที่เพิ่ม

เพิ่ม field ลง UserCompanyInfo (record ย่อยใน UserInfoForRedis.cs) ที่วันนี้มี CompanyId, CompanyName, IsDefault, Status, Role, CustCode:

AmloStatus    string?   "amloStatus"     Flagged | Clear | NotScreenable | Unknown
AmloAsOfUtc   DateTime? "amloAsOfUtc"

ทั้งสองตัว optional (?) และมี [JsonPropertyName] ตาม pattern ของ field ที่เพิ่มทีหลังในไฟล์นี้ (CardId, PassportNo, CustCode, RoleType ล้วนเป็น additive แบบเดียวกัน)

AmloStatus เป็น string? ไม่ใช่ enum เพราะ blob เก่าที่ไม่มี field จะ deserialize เป็น null ได้ตรงไปตรงมา และ null ต้องอ่านว่า Unknown ไม่ใช่ Clear

2.2 เงื่อนไขรับงานขั้น 0

• blob เก่าที่ไม่มี field ใหม่ deserialize ได้ ไม่ throw และได้ null
• CurrentSchemaVersion ยังเป็น 1
• service ที่ยังใช้ package เวอร์ชันเก่าอ่าน blob ที่มี field ใหม่ได้ตามปกติ (ignore field ที่ไม่รู้จัก)
• publish ผ่าน checklist ของ skill publish-backend-package แล้ว verify ว่า DLL ใน package ตรงกับ source จริง

3. Backend_Centralized — เส้นอ่าน screened list

3.1 ทำไมต้องมีเส้นใหม่ ไม่ใช้ของเดิม

ของเดิม GET /v1/amlo-screening/{custCode} มีปัญหา 3 ข้อกับงานนี้:

เส้นใหม่ต้องคืน generation identity มาพร้อมข้อมูลในครั้งเดียว เพื่อให้ audit เขียนค่าแช่แข็งได้เลย ไม่ต้องถามซ้ำ

3.2 Contract

// GET /api/centralized-service/v1/amlo-screening/current-generation
{
  "snapshotHeaderId": "…",
  "generationNo": 42,
  "gateResult": "Passed",          // Passed | Held | Failed
  "asOfUtc": "2026-08-20T05:00:00Z",
  "companies": [
    { "custCode": "0079195", "matchCount": 3, "evidenceFingerprint": "…" }
  ]
}

ห้ามใส่ชื่อ/นามสกุล/Similarity/SearchMethod ลง response นี้เด็ดขาด — §7 ของ architecture ห้ามให้ข้อมูลการคัดกรองหลุดออกจาก Centralized · UserService ไม่จำเป็นต้องรู้ว่าใครคือคนที่ match มันต้องการแค่ “custCode ไหนติด และหลักฐานเปลี่ยนหรือยัง”

ต้องมี [RequireApiKey] — ต่างจากเส้นเดิมที่ไม่มี auth เลย (ซึ่งเป็นช่องที่ต้องปิดแยกต่างหาก ดู Plan §4.1 ข้อ 10)

ถ้า companies ยาวมาก ต้องมี paging — แต่ข้อมูลจริงตอนนี้คือ 84 custCode จึงยังไม่จำเป็น ให้เขียน guard ไว้ว่าถ้าเกินจำนวนที่กำหนดให้ตอบ error แทนที่จะส่งก้อนยักษ์เงียบๆ

3.3 วางที่ไหน

controller ใหม่ หรือ action ใหม่ใน AmloScreeningController ก็ได้ · service impl วางที่ Centralized03.Application/Features/AmloScreening/ ตาม pattern AmloScreeningQueryService · port ที่ Centralized04.Domain/Ports/Amlo/ · repository ที่ Centralized02.Infrastructure/Persistence/Repositories/Amlo/

⚠️ ตารางที่อ่าน (amlo_screened_company, amlo_screening_snapshot_header) เป็นของ Phase 1 — schema เป็น contract ที่ freeze แล้ว ถ้าจะขอเปลี่ยนต้องคุยกับคนที่ทำ Phase 1 ก่อน

4. Backend_UserService — งานหลักของเฟสนี้

4.1 กับดัก 3 ข้อของ pipeline ที่มีอยู่ — อ่านก่อนเขียน handler

4.2 Schema ที่เพิ่ม

คอลัมน์ใหม่บน Companies — allow NULL ทุกตัว · NULL แปลว่า “ยังไม่เคยตรวจ” ไม่ใช่ “ผ่าน”

AmloStatus              varchar(20)  NULL
AmloAsOfUtc             timestamptz  NULL
AmloGenerationId        uuid         NULL
AmloEvidenceFingerprint varchar(64)  NULL

ตารางใหม่ 2 ตัว — โครงเต็มอยู่ที่ Architecture §4.2

• AmloUserUnblock — การปลดราย user · unique partial index บน (CompanyId, UserId) WHERE Status = 'Active'
• AmloAuditLog — append-only · เก็บ snapshot identity เป็นค่าแช่แข็ง ไม่ใช่ FK (คนละ DB กับ Centralized)

branch MIGRATION ของ UserService มีอยู่แล้ว แต่ตามหลัง development อยู่ 75 commit (แยกออกไปตั้งแต่ 07/08 มี 3 commit ของตัวเอง)

⚠️ ห้ามแก้ด้วยการ merge development → MIGRATION ตามกติกาของทีม — วิธีที่ถูกคือ port เฉพาะ source ของ data tier ที่ต้องใช้ (entity / enum / EF config) เข้าไปใน MIGRATION เอง แล้วค่อย dotnet ef migrations add บนนั้น · จบแล้ว merge MIGRATION กลับเข้า feature branch

4.3 งานย่อยและจุดเสียบจริง

4.4 เงื่อนไขรับงาน Phase 2 (UserService)

• คอลัมน์ใหม่ NULL ได้ทุกตัว และรันแอปเวอร์ชันก่อนหน้าชี้ DB ใหม่แล้วไม่พัง
• NULL ถูกอ่านเป็น Unknown ไม่ใช่ Clear ทุกจุด
• enforcement ยังปิดอยู่ — เปิด flag = ปิด แล้วทุก flow เดิมผ่านเหมือนเดิม
• AmloAuditLog เขียนใน transaction เดียวกับการเปลี่ยนสถานะจริง — มี test ที่ทำให้ audit เขียนไม่ได้ แล้วพิสูจน์ว่าสถานะ rollback ตาม
• AmloAuditLog.ActorEmail เป็นอีเมลคนกดจริง ไม่ใช่ system@exim.go.th — มี test ครอบ
• มี test ของ Redis refresh ล้มเหลว แล้วพิสูจน์ว่าไม่ถูกรายงานว่า propagation สำเร็จ
• guard เดิม 4 call site ยังทำงานถูก + test 5 ไฟล์ยังผ่าน
• has-pending-model-changes = none หลัง merge MIGRATION เข้า feature และ migration รันผ่านกับ Postgres จริงใน dev
• key ใหม่ทุกตัวเพิ่มที่ Backend_Iac/config/user-service/{env}/ ครบทุก env
• dotnet build -c Release ผ่าน (analyzer เป็น error)

5. Backend_FileManagementService — ไฟล์หลักฐาน

5.1 สถานะจริงของ endpoint ที่ต้องใช้

endpoint ที่ Phase 2 ต้องใช้ (POST /files/upload, GET /files/{id}/download, /metadata, DELETE /files/{id}) ถูก comment ออกทั้งบล็อกใน controller เหลือ live แค่ 4 เส้นของ profile-photo

✅ ข่าวดี: handler เบื้องหลังยังอยู่ครบทุกตัวบน origin/development — UploadFileHandler, DownloadFileQueryHandler, GetFileMetadataQueryHandler, PreviewFileQueryHandler, DeleteFileCommandHandler และ UploadFileValidator · งานนี้จึงเป็น “เปิดและ hardening” จริง ไม่ใช่เขียนใหม่ทั้งชุด

⚠️ แต่โค้ดใน controller ที่ comment ไว้ไม่เคยถูก compile ตั้งแต่วันที่ comment — ต้องเผื่อว่า signature ของ DTO/ctor drift ไปแล้ว งานแรกคือ uncomment แล้ว build ดูว่าพังตรงไหนบ้าง ก่อนจะไปคิดเรื่อง authorization

5.2 สิ่งที่ต้องเพิ่มนอกจากการ uncomment

6. Test plan

6.1 pattern ที่ต้องลอก

UserService05.Tests — xUnit + Moq + EF SQLite/InMemory · โครง test สะท้อนโครง feature (Application/Features/<Feature>/{Commands,Queries,...}/<Name>Test.cs)

pattern ของ handler test: field เป็น Mock<T> ต่อ dependency · wiring ทั้งหมดใน constructor ที่ไม่มีพารามิเตอร์ แล้วสร้าง handler เก็บไว้ · private static BuildCommand() อ่านจาก InitialData.ValidData ของ feature นั้น · ชื่อ test เป็น Handle_Should_<Behavior>_When_<Condition> · comment // Arrange / // Act / // Assert · assert result.IsSuccess + .Verify(..., Times.Once)

repository test ที่ต้องใช้ DB จริงอยู่แยกที่ Infrastructure/Persistence/Repositories/*PostgresTest.cs

6.2 ของเดิมที่จะพัง

6.3 ของใหม่ที่ต้องเขียน

7. ของที่ยังไม่ตัดสิน