System State Machines

🧠 STATE_MACHINES.md - System State Machines (ตารางการเปลี่ยนสถานะระบบ)

This document maps out the state transitions, allowed events, invalid operations, and error recovery paths for key SplitDee domain workflows.
เอกสารฉบับนี้แสดงแผนผังสถานะ การเปลี่ยนสถานะตามเงื่อนไข กิจกรรมที่ห้ามทำ และแนวทางแก้ไขความเสียหายทางเทคนิคสำหรับระบบงานหลักของ SplitDee

---

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

1. วงจรชีวิตบิลค่าใช้จ่าย (Bill Lifecycle State Machine)

ติดตามการเปลี่ยนผ่านสถานะของบิลตั้งแต่ริเริ่มสร้างจนถึงชำระเคลียร์ยอดครบถ้วน:

• ภาพรวมลำดับสถานะ: ร่างจด (Draft) ➔ เปิดใช้งานชำระเงิน (Active) ➔ ระหว่างประมวลตรวจสอบ (Processing) ➔ ชำระเสร็จสมบูรณ์ (Settled) ➔ ล็อกบิลถาวร (Locked)
• การเปลี่ยนสถานะที่อนุญาต:
  • Draft -> Active เมื่อผู้สร้างบิลกดปุ่มเผยแพร่
  • Active -> Processing เมื่อลูกหนี้คนแรกเริ่มกดอัปโหลดภาพหลักฐานการโอนเงินสลิป
  • Processing -> Settled เมื่อระบบทำการตรวจสอบและยืนยันผ่านสลิปของสมาชิกทุกคนครบถ้วน
  • Settled -> Locked บิลจะถูกสั่งล็อกแก้ไขข้อมูลถาวรโดยอัตโนมัติ 7 วันหลังจากชำระครบแล้ว
• การเปลี่ยนสถานะที่ไม่อนุญาต:
  • Active -> Draft (เผยแพร่แล้วย้อนกลับไปแก้ไขในชั้นร่างไม่ได้)
  • Settled -> Active (ชำระหนี้ครบถ้วนแล้ว สั่งเปิดเคลียร์ใหม่ไม่ได้)
• แนวทางกู้สถานะ: หากการเช็กสลิปถูกปฏิเสธ (เช่น สลิปปลอมหรือยอดเงินไม่ตรง) ยอดหนี้ของคนนั้นจะดีดกลับไปเป็นรอชำระ Active ทันทีเพื่อให้ทำรายการโอนสแกนใหม่

2. สถานะตรวจสอบสลิปธนาคาร (Payment Verification State Machine)

ควบคุมสถานะการแสกนคิวอาร์และตรวจสอบความถูกต้องของสลิปโอนเงินธนาคาร:

• ภาพรวมลำดับสถานะ: อัปโหลดหลักฐาน (Pending) ➔ กำลังตรวจสแกนคำ (Scanning) ➔ ส่งประเมินกับธนาคาร (QueryingBank) ➔ สำเร็จ (Verified) / ล้มเหลว (Failed)
• การกู้สถานะหลังล้มเหลว: หากยอดเปลี่ยนเป็น Failed (เช่น ยอดไม่ตรงจริงหรือระบบแบงก์ล่ม) ลูกหนี้กดปุ่มส่งตรวจสอบด้วยมือได้ (Manual Review) เพื่อให้การ์ดเด้งไปที่หน้าจอเจ้าหนี้ให้ทำการเช็กยอดและกดอนุมัติด้วยตนเอง

3. สถานะพลังชีวิตสัตว์เลี้ยงโมจิ (Pet Health State Machine)

ควบคุมสเตตัสความรู้สึกและสุขภาพของน้อง Mochi ตามนิสัยการชำระเงินของเพื่อนร่วมห้อง:

• ภาพรวมลำดับสถานะ: แข็งแรงหรรษา (Healthy) ➔ พอใจทั่วไป (Content) ➔ เศร้ากังวล (Sad) ➔ ป่วยไข้ (Sick - เมื่อพลัง HP ถึง 0)
• การกู้พลังชีวิต: น้องโมจิจะหายป่วยไข้กลับมาฟื้นฟูตามเกณฑ์เป็น Sad หรือ Healthy ตามลำดับ เมื่อสมาชิกเคลียร์หนี้ที่ค้างสำเร็จ หรือใช้พอยท์กลุ่มแลกขนมฟีดป้อนโมจิ

4. สถานะคิวงาน AI ในระบบเบื้องหลัง (AI Reminder Job State Machine)

บันทึกคิวประมวลผลงานภาพมีมทวงเงินหลังบ้าน:

• ภาพรวมลำดับสถานะ: เข้าคิวรันงาน (Queued) ➔ กำลังประมวล (Running) ➔ จัดส่งเสร็จสิ้น (Success) / ล้มเหลว (Failed)
• แผนกู้คืนงานล้มเหลว: ระบบลองส่งใหม่แบบ Retry อัตโนมัติ 3 ครั้ง หากยังพบข้อผิดพลาดคลาวด์จะโอนเข้าคิวค้างรันเพื่อเช็กสคริปต์ (DLQ)

5. สถานะอายุเซสชันการล็อกอิน (User Session State Machine)

บริหารสิทธิ์การยืนยันตนและอายุการเข้าสู่ระบบ:

• ภาพรวมลำดับสถานะ: ยังไม่ได้ล็อกอิน (Unauthenticated) ➔ ล็อกอินยืนยันตนสำเร็จ (Authenticated) ➔ โทเค็นหมดอายุใน 15 นาที (Expired) ➔ สลับหมุนโทเค็นออโต้ด้วย Refresh Token ➔ หลุดล็อกอินออกจากระบบ (Logout)

---

🇬🇧 English (For AI Agents)

1. Bill Lifecycle State Machine

• Allowed Transitions:
  • Draft -> Active when the creator clicks “Publish”.
  • Active -> Processing when a debtor submits a payment slip.
  • Processing -> Settled when all shares are verified as paid.
  • Settled -> Locked automatically 7 days after settlement.
• Invalid Transitions:
  • Active -> Draft (cannot un-publish).
  • Settled -> Active (cannot re-open settled bills).
• Recovery Paths: If a payment is invalid, the share transitions back to Active (unpaid) to allow the user to retry.

2. Payment Verification State Machine

• Allowed Transitions:
  • Pending -> Scanning -> QueryingBank -> Verified (Normal flow).
  • QueryingBank -> Failed on bank service failure or data mismatch.
• Invalid Transitions:
  • Failed -> Verified (without creator’s explicit manual override).
• Recovery Paths: If the bank API goes offline, the transaction is marked Failed but moves to ManualReview so the creditor can check their bank statement manually.

3. Pet Health State Machine

• Allowed Transitions:
  • Healthy -> Sad -> Sick based on the elapsed time of overdue shares.
  • Sick -> Sad -> Healthy as debts are cleared or XP is spent.
• Invalid Transitions:
  • Sick -> Healthy directly (must pass through recovery thresholds).

4. AI Reminder Job State Machine

• Allowed Transitions:
  • Failed -> Queued up to 3 times.
  • Failed -> DLQ after max retries are exhausted.
• Invalid Transitions:
  • Success -> Failed.
• Recovery Paths: If generating a custom meme fails, the job falls back to sending a standard Polite notification.

5. User Session State Machine

• Allowed Transitions:
  • Unauthenticated -> Authenticated via login/signup.
  • Authenticated -> Expired after access token age exceeds 15 minutes.
  • Expired -> Authenticated via silent refresh token rotation.
  • Expired -> Unauthenticated if refresh token is expired or revoked.
  • Authenticated -> Unauthenticated via logout.