System Use Cases

📋 USE_CASES.md - System Use Cases (กรณีการใช้งานของระบบ)

This document details the primary use cases and user interaction flows for the SplitDee platform.
เอกสารฉบับนี้สรุปโครงสร้างกรณีการเข้าใช้งานหลัก (Use Cases) และเส้นทางการไหลเวียนข้อมูลธุรกรรมสากลของ SplitDee

---

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

📊 สรุปประเด็นกรณียูสเคสเข้าใช้งานระบบ (Use Case Specifications)

1. UC-001: สร้างโปรไฟล์และผูกเบอร์พร้อมเพย์ (Create Profile & Setup PromptPay):
   • ผู้กระทำ: ผู้ใช้งานทั่วไป
   • เงื่อนไขก่อนหน้า: ผู้ใช้เปิดใช้หรือติดตั้งแอปพลิเคชันSplitDee
   • ขั้นตอน: ผู้ใช้ป้อนอีเมล รหัสผ่าน และชื่อโปรไฟล์ ➔ ผู้ใช้ลงทะเบียนเบอร์โทรศัพท์ (ซึ่งผูกบัญชีพร้อมเพย์รับโอนเงินของตน) ➔ หลังบ้านยืนยันและออก Access Token ป้องกันสิทธิ์
   • ผลลัพธ์: บัญชีได้รับการยืนยันตัวตนสำเร็จ สามารถสร้างบิลหรือกดเข้าร่วมกลุ่มเพื่อนได้
2. UC-002: ตั้งหารบิลส่วนแบ่งค่าใช้จ่าย (Create Bill & Split Shares):
   • ผู้กระทำ: เจ้าหนี้/ผู้สำรองจ่ายเงินคนแรก
   • เงื่อนไขก่อนหน้า: สมาชิกถูกดึงเข้าร่วมกลุ่มเดียวกันเรียบร้อยแล้ว
   • ขั้นตอน: เจ้าหนี้คีย์รายละเอียดบิล ยอดเงินรวม และเลือกวิธีเฉลี่ยหนี้ (หารเท่ากัน, ระบุยอดคนละตัว, หรือเปอร์เซ็นต์) ➔ เลือกเพื่อนร่วมแชร์ ➔ ระบบตรวจประมวลผลผลรวมเศษทศนิยมหนี้ ➔ บันทึกตารางบิลและจัดหารส่วนแบ่งรายคน
   • ผลลัพธ์: การ์ดบิลหารเงินสีเขียวถูกยิงแสดงผลบนห้องแชทและแจ้งเตือนจอมือถือลูกหนี้ทุกคน
3. UC-003: สแกนสลิปโอนชำระเงิน (Generate PromptPay QR & Upload Slip):
   • ผู้กระทำ: ลูกหนี้ผู้ค้างชำระ
   • เงื่อนไขก่อนหน้า: ลูกหนี้มียอดค้างชำระในหน้าจอบิลของกลุ่ม
   • ขั้นตอน: ลูกหนี้เปิดบิลเพื่อดึงภาพคิวอาร์พร้อมเพย์ที่ฝังยอดและเบอร์เจ้าหนี้ออโต้ ➔ บันทึกภาพคิวอาร์ สลับเข้าแอปธนาคารสแกนโอนเงินสำเร็จ ➔ กลับเข้าแอปและกดแนบภาพหลักฐานสลิปโอนเงิน
   • ผลลัพธ์: ระบบเริ่มทริกเกอร์เรียกการทำงานของคิวงานแสกนและตรวจสอบสลิปอัตโนมัติ
4. UC-004: การสแกนเช็กสลิปอัตโนมัติ (Validate Slip):
   • ผู้กระทำ: ระบบหลังบ้านอัตโนมัติ, เกตเวย์คู่ค้าธนาคารภายนอก
   • ขั้นตอน: ระบบใช้ OCR สกัดเลขอ้างอิงรหัสธุรกรรมจาก Mini-QR ของสลิป ➔ ค้นหาประวัติว่าถูกสแกนโอนซ้ำในบิลอื่นเพื่อโกงเงินหรือไม่ ➔ ยิงถาม Statement ยืนยันเงินจากธนาคารจริง ➔ ยอดเงินและวันเวลาโอนต้องตรงหลักฐาน ➔ เปลี่ยนสเตตัสเป็น ’ paid’ จ่ายสำเร็จ
5. UC-005: การบวกแต้มสัตว์เลี้ยงโมจิกลุ่ม (Update Group Pet Mochi):
   • ผู้กระทำ: ระบบหลังบ้านอัตโนมัติ
   • ขั้นตอน: ยอดชำระหนี้ผ่านการตรวจสำเร็จ ➔ คำนวณความเร็ว (หากโอนไวใน 12 ชม.) ➔ มอบ XP อัปเลเวล หรือฟื้น HP น้องโมจิประจำห้อง ➔ ยิงแชทแจ้งความเคลื่อนไหว: “ยินดีด้วย มิ้นต์จ่ายค่าไฟแล้ว น้องโมจิได้รับแต้ม +15 XP! 🎉”

---

🇬🇧 English (For AI Agents)

📊 Use Case Diagram

graph TD
    User([User / Roommate])
    Creator([Bill Creator])
    Debtor([Bill Debtor])
    BankAPI[(Bank verification API)]
    FCM[(Firebase Notification Service)]

    User --> UC1(UC-001: Create Profile & Join Group)
    Creator --> UC2(UC-002: Create Bill & Split Shares)
    Debtor --> UC3(UC-003: Generate QR & Upload Slip)
    UC3 --> UC4(UC-004: Validate Slip)
    UC4 --> BankAPI
    UC4 --> UC5(UC-005: Update Group Pet Mochi)
    UC5 --> FCM

📝 Use Case Specifications

• UC-001: Create Profile & Setup PromptPay
  • Actors: User
  • Preconditions: User has installed the SplitDee mobile application.
  • Basic Flow: User enters email, password, display name, and registers their phone number (linked to PromptPay). System encrypts and stores the PII data, issuing a JWT access token.
  • Postconditions: User is authenticated and can create or join expense groups.
• UC-002: Create Bill & Split Shares
  • Actors: Bill Creator
  • Preconditions: Group has been established with at least 2 members.
  • Basic Flow: Creator inputs total bill amount, title, category, select splitting method (equally, exact amount, percentage), and selects involved members. System validates sum of shares equals total amount and persists records in bills and expense_shares.
  • Postconditions: A new bill status card is posted in the group chat and dashboard.
• UC-003: Generate PromptPay QR & Upload Slip
  • Actors: Bill Debtor
  • Preconditions: Debtor owes a balance on an active bill.
  • Basic Flow: Debtor navigates to bill detail, system generates EMV Co PromptPay QR containing exact amount. Debtor saves QR, transfers money externally, and uploads the transfer slip image back to the app.
  • Postconditions: System triggers slip verification use case.
• UC-004: Validate Slip (AI & Bank Integration)
  • Actors: System, Bank Verification API
  • Preconditions: Slip image has been uploaded by the debtor.
  • Basic Flow: System extracts transaction reference ID from slip Mini-QR. Queries DB to prevent double-spending. Sends reference to bank API. Validates response amount matches expense_shares.share_amount and recipient matches bill creator. Updates share status to 'paid'.
  • Postconditions: Bill status transitions to settled, triggering pet updates.
• UC-005: Update Group Pet (Mochi)
  • Actors: System, Push Notification Service
  • Preconditions: A share has been marked as settled.
  • Basic Flow: System retrieves the group_pets record. Awards XP to Mochi based on settlement speed. Updates level and happiness. Dispatches FCM push alert: “Mint paid! Mochi gained +15 XP! 🎉”
  • Postconditions: Mochi’s stats are updated and rendered on group dashboards.