LINE Connectivity — Architecture ปัจจุบัน

อ้างอิงจากโค้ดจริงที่ merge เข้า development และรันอยู่บน dev แล้ว (PR #1977 / #1978, 06/08/2569) ฝั่ง FE = Frontend_LINE_Connectivity branch feature/line-connectivity-register (d16b347, ยังไม่เปิด PR ตามที่ Owner สั่ง) ยืนยันด้วยการเดินหน้าจอจริงทั้งชุด 07/08/2569 — ดู “ของที่ยังไม่มี / ยังไม่ได้ทำ” ท้ายหน้า

เอกสารคู่กัน: ทุก Scenario + Sequence Diagram

1. LINE Connectivity คืออะไร

ลูกค้านิติบุคคลผูกบัญชี LINE ของตัวเองเข้ากับบัญชี SuperApp เพื่อรับข่าวสารผ่าน LINE แทน/เพิ่มเติมจากอีเมล

เปิดจากใน LINE เท่านั้น (LIFF) — ทั้ง /register และ /unsubscribe มี lineClientGuard ครอบ ถ้าเปิดจาก browser ปกติจะเด้งไปหน้า /open-in-line

ไม่มี login — ทั้ง flow เป็น anonymous ไม่มี Entra / JWT / cookie ตัวที่ทำหน้าที่ “ใบสั่งงาน” คือ instanceId (GUID) ที่ backend ออกให้ตอนเริ่ม flow

2. แกนความคิดหลัก — บัญชีมี 2 แกน

นี่คือหัวใจของการเปลี่ยนรอบนี้ ถ้าเข้าใจข้อนี้ข้อเดียว ที่เหลือตามได้หมด

เดิม ระบบมองว่า 1 อีเมล = 1 บัญชี ตอนนี้ บัญชี = คู่ (Email, Company)

somchai@abc.com + บริษัท A   ← นี่คือ 1 บัญชี
somchai@abc.com + บริษัท B   ← นี่คืออีก 1 บัญชี คนละใบกัน

จากนิยามนี้ได้กฎ 2 ข้อที่เป็นภาพกลับด้านกัน:

flowchart LR
  subgraph R1["กฎ 1 — คู่หนึ่ง ผูกได้บัญชี LINE เดียว"]
    P1["somchai@abc.com<br/>+ บริษัท A"] -->|ผูกอยู่| L1["LINE: qa1111"]
    P1 -.->|"❌ ผูกซ้ำไม่ได้<br/>ต้องยกเลิกก่อน"| L2["LINE: qa2222"]
  end

flowchart LR
  subgraph R2["กฎ 2 — บัญชี LINE เดียว ผูกได้หลายคู่"]
    LN["LINE: qa1111"] --> A["somchai@abc.com + บริษัท A"]
    LN --> B["somchai@abc.com + บริษัท B"]
    LN --> C["somsri@xyz.com + บริษัท C"]
    LN --> D["...สูงสุด 20 คู่"]
  end

พูดเป็นภาษาคน: พนักงานคนหนึ่งที่ดูแลหลายบริษัท ใช้ LINE ส่วนตัวเบอร์เดียวรับข่าวของทุกบริษัทที่ตัวเองดูแลได้ แต่บริษัทหนึ่ง+อีเมลหนึ่ง จะมี LINE ที่รับข่าวได้แค่เครื่องเดียว ไม่ใช่ใครก็มาผูกทับได้

3. Component — ใครคุยกับใคร

flowchart TB
  subgraph LINE["LINE Platform"]
    LIFF["LIFF SDK<br/>getProfile / getIDToken"]
    VERIFY["api.line.me<br/>/oauth2/v2.1/verify"]
  end

  FE["Frontend_LINE_Connectivity<br/>(Angular 21 standalone, ใน LIFF)"]

  subgraph US["Backend_UserService"]
    CTRL["LineConnectivityController<br/>(AllowAnonymous)"]
    DRV["LineFlowDriver<br/>ขับเฉพาะ LINE_CONNECT / LINE_UNSUBSCRIBE"]
    H["Step Handlers ×6"]
    VER["HttpLineIdTokenVerifier"]
    DB[("AuthDb<br/>LineConnectivitySubscriptions<br/>LineConnectivityConsents<br/>FlowInstance / FlowInstanceStepData")]
  end

  TP["Backend_ThirdPartyService<br/>fx-registration-profile/{juristicId}"]
  CEN["Backend_Centralized<br/>terms/current"]
  NS["Backend_NotificationService<br/>OTP internal-generate"]

  FE -->|"ขอ idToken"| LIFF
  FE -->|"ค้นชื่อบริษัท"| TP
  FE -->|"โหลดข้อกำหนด"| CEN
  FE -->|"start / execute step / get state"| CTRL
  CTRL --> DRV --> H
  H --> VER -->|"verify id_token + client_id"| VERIFY
  H -->|"ส่ง/ตรวจ OTP"| NS
  H -->|"ดึง terms มา verify + hash"| CEN
  H --> DB

:::details ทำไม FE ถึงเรียก Centralized เองด้วย ทั้งที่ backend ก็เรียก

FE เรียกเพื่อเอาเนื้อหามาแสดง (ต้องให้ผู้ใช้อ่านได้) ส่วน backend เรียกเพื่อพิสูจน์ ว่าเวอร์ชันที่ผู้ใช้กดยอมรับ ตรงกับฉบับที่ published อยู่จริง แล้วเก็บ SHA-256 ของเนื้อหาที่ server ดึงเอง ลงเป็นหลักฐาน

ถ้าเชื่อค่าที่ FE ส่งมาอย่างเดียว หลักฐานจะเป็นแค่ “คำกล่าวอ้างของ client” ไม่ใช่หลักฐาน :::

⚠️ ข้อควรรู้: LINE Connectivity ไม่ได้ ใช้ Backend_ConsentService (OneTrust) เลย — integration ตัวนั้นใน UserService เป็น dead code, path constant ผิด, config ว่างทุก env ที่ใช้จริงคือ Backend_Centralized terms/current ซึ่งมีข้อดีกว่าคือ แก้ทับเวอร์ชันที่ publish แล้วไม่ได้ (ต้องออกเวอร์ชันใหม่) — คุณสมบัติที่จำเป็นสำหรับหลักฐาน

4. Data model

erDiagram
  LineConnectivitySubscriptions ||--o{ LineConnectivityConsents : "มีหลักฐาน"

  LineConnectivitySubscriptions {
    uuid Id PK
    varchar Email "normalized: trim + lowercase"
    varchar JuristicId "13 หลัก"
    varchar LineUserId "จาก ID token ที่ verify แล้ว, null ได้"
    uuid CompanyId "null ได้"
    varchar CompanyNameTh "snapshot ตอนสมัคร"
    varchar CompanyNameEn
    varchar Status "Active | Inactive"
    varchar TermsVersion "เพื่อแสดงผล"
    uuid FlowInstanceId
    timestamptz DeactivatedAt
  }

  LineConnectivityConsents {
    uuid Id PK
    uuid SubscriptionId FK
    uuid FlowInstanceId "กัน retry ซ้ำ"
    varchar Email
    uuid UserId "SuperApp user ณ ตอนนั้น"
    varchar LineUserId
    varchar AssertedJuristicId "ยอมรับ*ในนาม*นิติบุคคลใด"
    uuid CompanyId
    uuid UserCompanyMappingId "membership ที่ให้อำนาจ"
    varchar MembershipStatusAtConsent "สถานะ ณ วันนั้น"
    varchar ActingCapacity "JuristicRepresentative"
    varchar AssertionConsentCode "LINE-JURISTIC-CAPACITY"
    text AssertionText "ข้อความที่ผู้ใช้เห็นจริง"
    varchar LanguageCode
    varchar TermsDocumentId "server-verified เท่านั้น"
    varchar TermsVersion "server-verified เท่านั้น"
    char TermsBodySha256 "server-verified เท่านั้น"
    jsonb ConsentDocumentsJson
    varchar ConsentAction "Granted | Withdrawn"
    varchar OtpRefCode "หลักฐานว่าคุมอีเมลบริษัทได้"
    timestamptz OtpVerifiedAt
    timestamptz ConsentedAt "นาฬิกาของ server"
  }

Index ที่เป็น “กฎ” จริง ๆ

:::details ทำไม consent ต้องเป็นตารางแยก ไม่เก็บใน subscription

เพราะ Reactivate() เขียนทับ ค่าเดิมทุกครั้งที่สมัครใหม่ ถ้าเก็บ TermsVersion ไว้ที่แถว subscription อย่างเดียว ประวัติการยอมรับครั้งก่อน ๆ จะหายไปทันทีที่มีการสมัครรอบใหม่ — ใช้เป็นหลักฐานย้อนหลังไม่ได้

ตาราง consent จึงเป็น append-only: entity ไม่มี setter สาธารณะ ไม่มี method แก้ค่า repository ไม่มี Update/Delete และ “การยกเลิก” คือ แถวใหม่ ที่ ConsentAction = Withdrawn ไม่ใช่การไปแก้แถวเดิม :::

ทำไมต้องเก็บถึงขนาดนี้ — ปัญหาที่ Owner ตั้งไว้

โจทย์คือ “แยกไม่ออกว่า LINE ที่ subscribe ไว้เป็นบุคคลธรรมดาหรือนิติบุคคล” — งานนี้เป็นงานนิติบุคคล

ความจริงที่ต้องยอมรับก่อน: บัญชี LINE เป็นของส่วนตัวโดยธรรมชาติ ไม่มีทาง “บังคับ” ให้เป็นบัญชีบริษัทได้ ต่อให้ติ๊ก checkbox ก็ไม่เปลี่ยนความจริงข้อนั้น

สิ่งที่ระบบทำได้จริงคือ เก็บหลักฐานว่าคนที่กดยอมรับ ทำในฐานะตัวแทนนิติบุคคล ซึ่งพิสูจน์ด้วย 3 ชั้นรวมกัน:

1. OTP — พิสูจน์ว่าคนกดคุมกล่องอีเมลของบริษัทได้จริง (OtpRefCode + OtpVerifiedAt)
2. Membership — พิสูจน์ว่า ณ วินาทีนั้นเขาเป็นสมาชิก active ของบริษัทนั้น (UserCompanyMappingId + MembershipStatusAtConsent) — ค่านี้เปลี่ยนได้ทีหลัง จึง re-derive ย้อนหลังไม่ได้ ต้องเก็บ ณ ตอนนั้น
3. คำรับรองที่แสดงชัด — ActingCapacity + ข้อความที่ผู้ใช้เห็นจริง (AssertionText) + เวอร์ชัน/แฮชของข้อกำหนดที่ server ดึงเอง

📌 ข้อความคำรับรอง ไม่ได้ hardcode ในโค้ด — มาจาก consent entry รหัส LINE-JURISTIC-CAPACITY ที่ทีมกฎหมายเขียนเองใน Centralized admin terms ตราบใดที่ยังไม่ได้เขียน หน้าจอจะไม่แสดง checkbox นี้และทำงานเหมือนเดิมทุกอย่าง (ตั้งใจให้ degrade เงียบ)

5. Flow engine — 2 flow, 6 step

Step ทั้งหมด seed เป็น แถวใน DB (seed/line-connectivity-seed.sql → StepCatalog + FlowDefinition + FlowStep) ไม่ใช่ EF HasData — เพิ่ม step ใหม่ = งาน DB ที่ต้องรันมือทุก env

flowchart LR
  subgraph CONNECT["LINE_CONNECT (สมัคร)"]
    direction LR
    C1["1. LineConnectivityInfoStep<br/>Interactive"] --> C2["2. LineOtpVerificationStep<br/>Interactive"] --> C3["3. LineTcConsentStep<br/>Interactive"] --> C4["4. PersistLineSubscriptionStep<br/>⚙️ Automatic"]
  end

flowchart LR
  subgraph UNSUB["LINE_UNSUBSCRIBE (ยกเลิก)"]
    direction LR
    U1["1. LineUnsubInfoStep<br/>Interactive"] --> U2["2. LineDeactivateSubscriptionStep<br/>Interactive"]
  end

ผลลัพธ์ของแต่ละ step เก็บใน FlowInstanceStepData (PK = FlowInstanceId + StepType, คอลัมน์ DataJson เป็น jsonb) — step หลังอ่านของ step หน้าได้จากตรงนี้

🔑 หน้า AccountInfo ไม่ได้เป็น step ใหม่ — มันคือหน้าจอ FE ที่ render จาก output ของ LineUnsubInfoStep ซึ่งตอนนี้คืน รายการ เหตุผล: step definition อยู่ใน DB seed ที่ต้องรันมือทุก env ส่วน routing ของ FE เป็น per-URL อยู่แล้ว การเพิ่ม step จึงเป็นงาน ops ที่ไม่จำเป็น

6. Endpoint contract

สิ่งที่แต่ละ step รับ/คืน (contract ที่ FE ต้องรู้)

⚠️ Breaking จากของเดิม — ต้อง deploy BE + FE พร้อมกัน:

• lineUserId ที่ client ส่ง ถูกเมิน เปลี่ยนเป็น lineIdToken
• LineUnsubInfoStep คืน รายการ ไม่ใช่ binding เดียว
• LineDeactivateSubscriptionStep เดิมไม่ส่ง step data เลย ตอนนี้ต้องส่งคู่ที่เลือก
• /line-subscriptions/me เปลี่ยนรูปเป็น { isConnected, bindings[] }

7. กฎแข็ง 6 ข้อ (ห้ามฝ่าฝืน)

:::details ทำไมกฎ 1 ต้องเช็ค 2 ที่

flow instance ค้างได้ — ผู้ใช้ผ่าน step 1 แล้วปิดจอทิ้งไว้ ระหว่างนั้นคนอื่นสมัครคู่เดียวกันจนสำเร็จ พอผู้ใช้คนแรกกลับมาเดินต่อจนถึง step 4 Reactivate() จะเขียนทับ LineUserId ของคนที่สมัครทีหลังแบบเงียบ ๆ และ binding ของคนนั้นหายไป

เกณฑ์ที่ step 4 ใช้คือ เทียบ FlowInstanceId ไม่ใช่เทียบ LineUserId เพราะการสมัครนอก LINE ทั้งสองฝั่งจะมี lineUserId = null เหมือนกัน การเทียบ LineUserId จึงไม่ทำงาน (null == null) :::

8. Error code ทั้งหมด

ของใหม่จากงานนี้

ของเดิมที่ยังใช้อยู่

NotEligible ตั้งใจรวม 3 กรณี (ไม่พบ user / user ไม่ active / ไม่ได้เป็นสมาชิกบริษัท) เป็นข้อความเดียว เพื่อไม่ให้ใช้ endpoint นี้ไล่เดาว่าอีเมลไหนมีในระบบ

9. Config ที่ต้องมี

🔴 CI overlay ทับ appsettings.{ENV}.json ทั้งไฟล์จาก IaC ตอน build — ใส่แค่ใน service repo ไม่มีผลบน cluster ต้องใส่ที่ IaC ด้วยเสมอ ถ้า ChannelId ว่าง ตัว verifier จะ fail closed = เส้นทาง LIFF ใช้ไม่ได้ทั้งเส้น (แต่เส้นทางค้นด้วยอีเมลยังใช้ได้)

10. ของที่ยังไม่มี / ยังไม่ได้ทำ

อัปเดต 07/08/2569 หลังรัน E2E ชุดเต็มบน dev