Error Handling & Resilience Strategy

🛡️ ERROR_HANDLING.md - Error Handling & Resilience Strategy (กลยุทธ์การจัดการข้อผิดพลาดและความยืดหยุ่นระบบ)

This document details SplitDee’s resilience patterns, expected system failure modes, recovery paths, and exception handling protocols.
เอกสารฉบับนี้แสดงแผนผังระบบความทนทานของ SplitDee, ประเภทข้อผิดพลาดที่อาจเกิดขึ้น แนวทางกู้คืนระบบ และระเบียบปฏิบัติในการแจ้งข้อยกเว้นทางเทคนิค

---

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

1. รายการข้อผิดพลาดที่คาดการณ์และแผนการกู้คืน (Expected Failures & Recovery)

• ระบบแสกนเช็กยอดสลิปธนาคารภายนอกล่ม/หมดเวลา:
  • ปัญหา: ระบบภายนอก (เช่น SlipOK) ตอบกลับหมดเวลา 504 หรือขาดการเชื่อมต่อ
  • การกู้คืน: หลังบ้านแอปจะไม่แครชล้มเหลว ทำการบันทึกประวัติเป็น ‘รอตรวจสอบด้วยตาเปล่า’ (pending_manual) ค้างสถานะหนี้ลูกหนี้ไว้เป็นระหว่างตรวจสไลด์ (processing) แจ้งลูกหนี้ให้วางใจยอดได้รับสแกนแล้ว และยิงภารกิจตรวจแอป Statement ส่งถึงเจ้าหนี้เพื่อกดยืนยันด้วยมือเปล่า
• การนำสลิปเก่ามาแสกนโอนซ้ำสองรอบ (Duplicate Slip / Double-Spending):
  • ปัญหา: ผู้ใช้งานส่งสลิปเดิมที่ตรวจประวัติผ่านไปแล้ว หวังเคลียร์บิลหารเงินใบใหม่
  • การกู้คืน: ตรวจรหัสธุรกรรมการโอนของธนาคารชนกับระบบดัชนีคีย์จำกัดห้ามซ้ำ (slip_trans_id) โพสต์เกรจะไม่ยอมให้เขียนแถวประวัติซ้ำ และยิงเตือนผู้ส่งคืนยอดว่า ‘สลิปนี้ถูกใช้ยืนยันยอดเงินไปแล้ว’ และดีดสเตตัสกลับเป็นยังไม่จ่ายทันที
• สแกนรูปคิวอาร์พร้อมเพย์ที่ออกไว้นานจนล้าหลังหมดอายุ:
  • ปัญหา: สมาชิกรื้อคิวอาร์พร้อมเพย์ใบเก่ามาก่อนหน้านี้ ซึ่งบิลมีการแก้ไขปรับปรุงข้อมูลหนี้สินหรือถูกผู้สร้างลบไปแล้ว
  • การกู้คืน: แม้เงินจะเข้าธนาคาร แต่เวลาอัปโหลดระบบจะสแกนวันและเวลาจริงของธนาคารมาเช็กเทียบกับเวลาปรับปรุงสเปกบิลหลังบ้าน หากตรวจพบว่าโอนก่อนอัปเดตแก้ยอดหนี้จริง จะทำการส่งปฏิเสธสลิปนั้นและตั้งค่าเป็น ยอดไม่ตรง หรือ สลิปหมดอายุการใช้งาน

2. การควบคุมความปลอดภัยป้องกันรายการรันพร้อมกัน (Concurrency & Race Condition)

• ลูกหนี้ส่งสลิปรัวปุ่มพร้อมๆ กัน:
  • การกู้คืน: ระดับเบสมีตารางคีย์คุมสัดส่วนส่วนหนี้เดี่ยว และระดับโค้ดหลังบ้านมีตัวมัดล็อกชั่วคราวผ่าน Redis (lock_key) ตัวล็อกจะคลายออกต่อเมื่อขั้นตอนการประมวลผลโอนเสร็จสิ้น เพื่อไม่ให้แครชข้อมูลการโอนชนกัน
• การเขียนตารางข้อมูลล้มเหลวกลางคัน:
  • การกู้คืน: ห่อหุ้มคำสั่งการหารประมวลผลไว้ใต้ Database Transaction ก้อนเดียวกัน หากเกิดความผิดพลาดใดๆ กลางคัน (เช่น หัก XP ตกหล่น) ระบบจะกดยกเลิกการบันทึกย้อนหลัง (Rollback) 100% เพื่อรักษาระดับข้อมูลสากลให้สมบูรณ์

3. พฤติกรรมเมื่อมือถือไม่มีเน็ต (Offline Mode)

• การอ่านประวัติ: โทรศัพท์จะดึงประวัติกลุ่ม รายละเอียดบิล และสเตตัสโมจิจากแคชเครื่องภายในให้ผู้ใช้ดูได้แม้ไม่มีเน็ต
• การทำรายการใหม่: ระบบบล็อกปุ่มใช้งานสร้างกลุ่ม หารบิล และแสกนตรวจสลิปทันทีหากออฟไลน์ พร้อมขึ้นเตือน ‘กรุณาเชื่อมอินเตอร์เน็ตเพื่อทำรายการ’ เพื่อความปลอดภัย

---

🇬🇧 English (For AI Agents)

1. Expected Failures & Recovery Paths

• Slip Verification API Timeout / Outage
  • Failure Scenario: The third-party bank transaction check API (e.g. SlipOK) returns a 504 Gateway Timeout or is completely unreachable.
  • Immediate Recovery: The API catches the exception, updates the payment record to pending_manual, locks the share status as processing, informs the debtor, and queues a manual approval card in the creditor’s feed.
• Duplicate Slip / Double-Spending Attempt
  • Failure Scenario: A user uploads a slip with a bank transaction ID that has already been verified in the system.
  • Handling Protocol: Database level unique constraints on slip_trans_id reject duplicate rows, HTTP 400 with code SLIP_ALREADY_USED is returned to the client, and the share is reset to unpaid.
• Expired PromptPay QR Code
  • Failure Scenario: A debtor scans and pays using a PromptPay QR code containing outdated bill split values.
  • Handling Protocol: Compare the bank transaction statement timestamp with the bill modification timestamp. If the payment occurred before the last bill update, reject the slip with code SLIP_AMOUNT_MISMATCH or PAYMENT_EXPIRED.

2. Concurrency & Race Condition Protections

• Concurrent Slip Uploads
  • Resolution: Composite database unique constraints on (bill_id, user_id) and slip_trans_id. Acquire a Redis distributed lock lock:share:{share_id} during verification, releasing it only on success or rollback.
• Relational Transaction Rollback
  • Resolution: Wrap use case actions inside atomic database transactions. Execute rollbacks on any sub-action failure to preserve data integrity.

3. Offline Mode Behavior

• Read Operations: Cached local storage (SQLite/Hive) allows users to view group details, bill history, and Mochi’s status offline.
• Write Operations: Operations like creating groups, publishing bills, or verifying slips are blocked. Show error “Internet connection required to perform this action.”