System Sequence Diagrams

🏛️ SEQUENCE_DIAGRAMS.md - System Sequence Diagrams (แผนภาพแสดงลำดับขั้นตอนการทำงานระบบ)

This document contains detailed execution sequence diagrams for key user interactions in SplitDee.
เอกสารฉบับนี้สรุปผังลำดับขั้นตอนการทำงาน การไหลเวียนของข้อสงสัย และกิจกรรมประสานกันของโมดูลระบบย่อยหลัก

---

🇹🇭 ภาษาไทย (สำหรับผู้ใช้งาน)

1. ลำดับขั้นตอนการลงสมัครสมาชิกใหม่และการสร้าง Token (User Registration & Token Generation)

1. ผู้ใช้กรอกฟอร์ม: ลูกหนี้หรือเจ้าหนี้กดป้อนข้อมูลอีเมล รหัสผ่าน ชื่อ และเบอร์โทรสมัครสมาชิกส่งผ่าน POST /auth/signup
2. วิเคราะห์สเปกหลังบ้าน: FastAPI API Router เช็กตัวแปร JSON Schema ป้อนต่อให้กระบวนการหลัก RegisterUserUseCase
3. ตรวจสอบความไม่ซ้ำ: ยูสเคสเรียกใช้ User Repository ค้นหาตารางในฐานข้อมูล PostgreSQL ตรวจสอบว่ามีอีเมลนี้อยู่แล้วหรือไม่
4. แฮชรหัสผ่านความปลอดภัย: หากเป็นผู้ใช้ใหม่ สั่งคลาส Hasher แฮชเข้ารหัส (Hash Password) ความปลอดภัย ก่อนยื่นเขียนระเบียนใหม่ลง PostgreSQL
5. สร้างสิทธิ์ล็อกอินสำเร็จ: ส่งข้อมูลยืนยันกลับมาที่ Router จัดสร้างตั๋วสิทธิ์ JWT Access Token (จำกัดหมดอายุ 15 นาที) และตั๋ว Refresh Token ยิงตอบกลับไปยังไคลเอนต์และแสดงหน้ารายงานตัวสำเร็จ

2. ลำดับขั้นตอนการตั้งหารบิลค่าใช้จ่ายประจำกลุ่ม (Bill Creation & Split Allocation)

1. เจ้าหนี้สร้างบิล: เจ้าหนี้คีย์รายละเอียดบิลหารเงิน ยอดรวม และการแบ่งสัดส่วนส่วนหนี้ ยิงคำขอไปที่หลังบ้าน
2. คำนวณสเปกหนี้: ยูสเคสตรวจเช็กยอดบิลรวมตรงกับยอดส่วนหนี้รายคนเฉลี่ยบวกกันพอดี ➔ ยื่นเขียนประวัติตารางบิลและรายตัวลงตาราง PostgreSQL
3. ยิงแจ้งข่าวเพื่อนร่วมห้อง: เมื่อเบสยืนยันสำเร็จ สั่ง Firebase Notification (FCM) จัดส่ง Push ข้อความทริกเกอร์แจ้งข่าวทุกคน และโพสต์การ์ดบิลสีเขียวลงในช่องแชทกลุ่ม

3. ลำดับขั้นตอนการแสกนตรวจสอบสลิปผ่าน AI และปิดหนี้ (AI Slip Verification & Settlement)

1. ลูกหนี้ส่งสลิป: ลูกหนี้แชะแนบรูปภาพใบสลิปส่ง API ตรวจสอบ
2. AI OCR สแกน Mini-QR: ยูสเคสส่งรูปให้ตัวประมวลผล OCR สกัดแสกนหารหัสคิวอาร์ (Transaction ID)
3. ตรวจสอบการโกงโอนซ้ำ: ตรวจใน PostgreSQL ว่าเลขอ้างอิงนี้เคยโอนผ่านไปแล้วหรือไม่ หากเจอซ้ำ ปฏิเสธและเด้งเตือนลูกหนี้ทันที
4. เช็ก Statement ธนาคารจริง: ยิงรหัสขอ Statement จากธนาคารจริงผ่านพอร์ตเกตเวย์ภายนอก ตรวจสอบยอดเงินโอน และปลายทางผู้รับเงิน
5. อัปเดตและปิดบิล: หากตรงกัน เปลี่ยนยอดหนี้เป็นจ่ายสำเร็จ อัปเดตเลเวลเลเวล XP สัตว์เลี้ยงโมจิ และส่ง Push ข้อความฉลองแจ้งแชทกลุ่ม

---

🇬🇧 English (For AI Agents)

🔑 1. User Registration & Token Generation

sequenceDiagram
    autonumber
    actor User as User Client
    participant Router as API Router (FastAPI)
    participant UC as RegisterUser UseCase
    participant Repo as User Repository
    participant Hasher as Security Hasher
    participant DB as PostgreSQL DB

    User->>Router: POST /auth/signup {email, password, name, phone}
    Note over Router: Validates request payload schemas
    Router->>UC: execute(email, password, name, phone)
    UC->>Repo: get_by_email(email)
    Repo->>DB: query User table
    DB-->>Repo: return user/null
    
    alt User Already Exists
        Repo-->>UC: return UserEntity
        UC-->>Router: raise EmailAlreadyExistsException
        Router-->>User: return 400 Bad Request
    else New User
        Repo-->>UC: return null
        UC->>Hasher: hash_password(password)
        Hasher-->>UC: return password_hash
        UC->>Repo: create(UserEntity)
        Repo->>DB: INSERT INTO users
        DB-->>Repo: return inserted record
        Repo-->>UC: return UserEntity
        UC-->>Router: return UserEntity
        Note over Router: Generate JWT access token
        Router-->>User: return 201 Created {access_token, user_details}
    end

💵 2. Bill Creation & Split Allocation

sequenceDiagram
    autonumber
    actor Creator as Bill Creator
    participant Router as API Router (FastAPI)
    participant UC as CreateBill UseCase
    participant DB as PostgreSQL DB
    participant FCM as Firebase Notification

    Creator->>Router: POST /api/v1/groups/{id}/bills {title, amount, shares}
    Router->>UC: execute(group_id, creator_id, title, amount, shares)
    Note over UC: Validate sum(shares) == total_amount
    UC->>DB: INSERT INTO bills (id, group_id, creator_id, total_amount, title, category)
    UC->>DB: INSERT INTO expense_shares (multiple rows user_id, share_amount, status='unpaid')
    DB-->>UC: return success
    UC->>FCM: send_notification_to_members(group_id, payload)
    FCM-->>UC: return status
    UC-->>Router: return bill_details
    Router-->>Creator: return 201 Created {bill_details}

🤖 3. AI Slip Verification & Settlement

sequenceDiagram
    autonumber
    actor Debtor as Bill Debtor
    participant Router as API Router (FastAPI)
    participant UC as VerifySlip UseCase
    participant OCR as OCR Service
    participant Bank as Bank Partner API
    participant DB as PostgreSQL DB
    participant Redis as Redis Cache
    participant Pet as Pet Update UseCase
    participant FCM as Firebase Notification

    Debtor->>Router: POST /api/v1/bills/{id}/payments {slip_image}
    Router->>UC: execute(bill_id, debtor_id, slip_image)
    UC->>OCR: extract_mini_qr(slip_image)
    OCR-->>UC: return transaction_ref_id
    
    UC->>DB: SELECT payment WHERE slip_trans_id == ref_id
    alt Slip Already Used (Double-Spend)
        DB-->>UC: return existing payment
        UC-->>Router: raise DuplicateSlipException
        Router-->>Debtor: return 400 Bad Request
    else Unique Slip
        DB-->>UC: return null
        UC->>Bank: GET /verify/{transaction_ref_id}
        Bank-->>UC: return transfer_details {amount, receiver_name, timestamp}
        Note over UC: Check amount matches share_amount & receiver matches creator
        UC->>DB: UPDATE expense_shares SET status='paid', paid_at=now
        UC->>DB: INSERT INTO payments (bill_id, payer_id, amount, slip_trans_id, status='verified')
        UC->>Pet: reward_group_pet_xp(group_id, speed_bonus)
        Pet->>DB: UPDATE group_pets SET xp = xp + bonus
        UC->>FCM: dispatch_notification(group_id, "Paid!")
        UC-->>Router: return 200 OK {"status": "verified"}
        Router-->>Debtor: return 200 OK {"status": "verified"}
    end