Business Rules Specification

🧠 BUSINESS_RULES.md - Business Rules Specification (ข้อกำหนดกฎธุรกิจ)

This document details the business logic, formulas, limits, and edge-case behaviors governing SplitDee.
เอกสารฉบับนี้แสดงตรรกะธุรกิจ สูตรคำนวณ ขีดจำกัด และกรณีพิเศษต่างๆ ที่ควบคุมแพลตฟอร์ม SplitDee

---

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

1. ข้อจำกัดกลุ่มและการเป็นสมาชิก (Group Constraints & Memberships)

• รหัสเกณฑ์ BR-GRP-001 (จำนวนสมาชิกสูงสุดต่อกลุ่ม):
  • กฎ: สมาชิกกลุ่มแต่ละกลุ่มสามารถรองรับสูงสุดไม่เกิน 50 คน
  • เหตุผล: เพื่อให้การสื่อสารในห้องแชทและการสืบค้นประมวลผลการหารเงินทำได้รวดเร็ว ไม่หน่วงช้า
  • ตัวอย่าง: กลุ่มเพื่อนร่วมบ้านมี 4 สมาชิก หรือกลุ่มเพื่อนเดินทางท่องเที่ยวมี 25 สมาชิก
  • ข้อยกเว้น: กลุ่มระดับองค์กรหรือกลุ่มกิจกรรมพิเศษในอนาคต (ซึ่งยังไม่รองรับใน MVP)
  • กรณีพิเศษ: หากกดป้อนรหัสเข้าร่วมกลุ่มที่จำนวนสมาชิกแตะ 50 คนแล้ว ระบบจะรายงานข้อผิดพลาดกลุ่มเต็มและระงับสิทธิ์การเข้าใช้งาน

2. วงจรแก้ไขบิล การลบ และการล็อกประวัติ (Bill Editing, Deletion & Locking Lifecycle)

• รหัสเกณฑ์ BR-BIL-001 (กฎเกณฑ์การแก้ไขบิลค่าใช้จ่าย):
  • กฎ: บิลจะได้รับการแก้ไขจากผู้สร้างบิล (เจ้าหนี้) ได้เฉพาะกรณีที่ยอดส่วนแบ่งของสมาชิกทุกคนอยู่ในสถานะยังไม่จ่าย (‘unpaid’) เท่านั้น หากมีคนแรกเริ่มชำระหรืออยู่ระหว่างตรวจสลิป บิลจะเปลี่ยนเป็นสถานะล็อกห้ามแก้ไขทันที
  • เหตุผล: ป้องกันการแก้ไขตัวเลขบิลข้ามยอดขณะเพื่อนกำลังโอนเงิน ซึ่งทำลายประวัติบัญชี
  • ตัวอย่าง: ดีดี้เปิดบิลแชร์เงิน 1000 บาท มิ้นต์อัปโหลดสลิปขอสแกน บิลจะล็อกแก้ไขทันที ดีดี้ไม่สามารถแก้บิลเพิ่มเป็น 1200 บาทได้
  • กรณีพิเศษ: หากต้องการแก้ไขด่วน เจ้าหนี้ต้องแจ้งให้เพื่อนผู้โอนเงินกดยกเลิกสลิปชั่วคราวเพื่อคืนค่าเป็นยังไม่จ่ายเสียก่อน
• รหัสเกณฑ์ BR-BIL-002 (กฎเกณฑ์การลบบิลค่าใช้จ่าย):
  • กฎ: เจ้าหนี้ลบบิลที่สร้างขึ้นได้เฉพาะตอนที่ยอดของทุกคนเป็นยังไม่ชำระ หากมีผู้โอนจ่ายประวัติเข้ามาแล้วจะระงับการลบถาวร
  • เหตุผล: ป้องกันปัญหาการลบประวัติการเงินที่ส่งผลเสียต่อการเรียกร้องยอดเงินของสมาชิก
  • กรณีพิเศษ: แทนการลบแบบเคลียร์ทิ้ง ระบบสนับสนุนปุ่มกด ‘ยกเลิกบิล’ ซึ่งซ่อนบิลจากแดชบอร์ดหลักแต่เก็บบันทึกประวัติในฐานข้อมูลหลังบ้าน

3. การชำระเงิน สลิป และการอนุมัติ (Payments, Slips & Approvals)

• รหัสเกณฑ์ BR-PAY-001 (ช่วงเวลาอัปโหลดรูปและตรวจสอบสลิป):
  • กฎ: ลูกหนี้สามารถส่งสลิปเพื่อขอตรวจสอบสัดส่วนหนี้ได้ตลอดเวลา เมื่ออัปโหลดแล้วสถานะของสมาชิกจะเปลี่ยนเป็นกำลังตรวจสอบ (‘processing’) ทันที และห้ามส่งรูปหลักฐานซ้อนทับกัน
  • เหตุผล: ป้องกันการนำสลิปใบเดิมมายื่นยืนยันสิทธิ์สองครั้ง หรือแย่งกันยื่น
  • กรณีพิเศษ: หากระบบแสกนสลิปล่าช้าจนหมดเวลาคิวงาน (5 นาที) ยอดจะเด้งกลับเป็นยังไม่ชำระเพื่อให้ป้อนใหม่
• รหัสเกณฑ์ BR-PAY-002 (สิทธิ์ในการกดยกเลิกสลิปของเจ้าหนี้):
  • กฎ: หากการประมวลคำ OCR ล้มเหลว ระบบจะเด้งการ์ดภารกิจให้เจ้าหนี้เป็นคนเช็กยอดด้วยตาเปล่าในแอป และเลือกยอมรับหรือกดปฏิเสธสลิปนั้นได้เอง
  • เหตุผล: ใช้มนุษย์เป็นเกณฑ์สูงสุดตรวจสอบตัวสติกเกอร์เมื่อภาพเบลอ ป้องกันบิลค้างคา
  • ข้อยกเว้น: เจ้าหนี้ห้ามปฏิเสธสลิปที่ได้การกดยืนยันผ่าน API ธนาคารสำเร็จถูกต้องแล้ว
• รหัสเกณฑ์ BR-PAY-003 (การผ่อนหรือทยอยชำระยอด):
  • กฎ: รุ่น MVP ไม่รองรับการแบ่งชำระเป็นงวดหรือทยอยจ่าย สมาชิกต้องสแกนจ่ายโอนยอดตรงเต็มจำนวนของสัดส่วนหนี้สินเท่านั้น
  • เหตุผล: ความเรียบง่ายในการสร้างคิวอาร์พร้อมเพย์และระบบหลังบ้าน
• รหัสเกณฑ์ BR-PAY-004 (การกดยกเลิกธุรกรรม):
  • กฎ: ผู้โอนไม่สามารถขอยกเลิกสลิปได้หากผ่านการตรวจสอบ Verified แล้ว

4. การคำนวณแบ่งยอดและยอดเงินเคลียร์หนี้ (Debt & Balance Calculations)

• รหัสเกณฑ์ BR-DBT-001 (ยอดรวมคงเหลือสุทธิ):
  • กฎ: สัดส่วนยอดหนี้สุทธิของเพื่อนร่วมกลุ่มคำนวณตามสูตรผลรวมบิลสำรองหักลบด้วยหนี้ค้างจ่าย และผลรวมของเน็ตเงินทุกคนในกลุ่มต้องเป็น 0 เสมอ
• รหัสเกณฑ์ BR-DBT-002 (การลดขั้นตอนโอนเงิน):
  • กฎ: ระบบจะหารเฉลี่ยให้การโอนคืนกันประหยัดขั้นตอนการทำธุรกรรมลง (เช่น แป้งติดปอนด์ ปอนด์ติดบีม ยุบเป็น แป้งโอนหาบีมตรง)

5. สัตว์เลี้ยงเสมือน Mochi และระบบเกมจำลอง (Gamification Pet Rules)

• รหัสเกณฑ์ BR-GAM-001 (เกณฑ์รับค่าประสบการณ์ XP):
  • กฎ: สัตว์เลี้ยงประจำกลุ่มได้รับ XP จากพฤติกรรมชำระเร็ว: จ่ายใน 12 ชม. (+25 XP), จ่ายใน 24 ชม. (+15 XP), จ่ายเลย 24 ชม. (+5 XP)
• รหัสเกณฑ์ BR-GAM-002 (เกณฑ์หักพลังชีวิต HP รายวัน):
  • กฎ: ตรวจความค้างชำระเวลาเที่ยงคืน หากเลยดิวบิล หักพลังชีวิตสัตว์เลี้ยง -10 HP ต่อยอดค้าง หากพลังชีวิตถึง 0 สัตว์เลี้ยงจะป่วยและงดสะสม XP จนกว่าจะกู้พลังชีวิตเกิน 50
• รหัสเกณฑ์ BR-GAM-003 (การฟื้นฟู HP):
  • กฎ: โมจิฟื้นพลังทันที +15 HP เมื่อเพื่อนชำระหนี้สำเร็จ หรือใช้พอยท์กลุ่มแลกฟีดอาหาร (+10 HP ต่อครั้ง)

6. การทวงหนี้อัจฉริยะ (AI Reminder Engine)

• รหัสเกณฑ์ BR-AI-001 (ระดับน้ำเสียงการทวง):
  • กฎ: ส่งเตือนตามความสนิท: สุภาพ, เป็นกันเอง (ภาษาพูด), และสร้างภาพมีมตลกๆ ทวงอัตโนมัติ ห้ามป้อนคำหยาบคายและก้าวร้าว

---

🇬🇧 English (For AI Agents)

1. Group Constraints & Memberships

• BR-GRP-001: Group Membership Limit
  • Rule: A group can contain a maximum of 50 members.
  • Reason: Keeps group communication and expense calculation performance clean and fast.
  • Example: Roommate group has 4 members. Trip group has 25 members.
  • Exceptions: Enterprise/event groups (future extension, not allowed in MVP).
  • Edge Cases: If a user attempts to join a group with 50 active members via invite code, show error GROUP_FULL and deny entry.

2. Bill Editing, Deletion & Locking Lifecycle

• BR-BIL-001: Bill Editing Rules
  • Rule: A bill can only be edited by its creator (creditor) if all associated expense shares are 'unpaid'. Once any member transitions their share status to 'processing' or 'paid', the bill becomes locked and cannot be edited.
  • Reason: Modifying a bill after shares are already settled creates financial inconsistencies and destroys audit trails.
  • Example: Didi creates a bill for 1000 THB. Mint uploads a slip to pay. The bill is locked; Didi cannot change the bill to 1200 THB.
  • Exceptions: None.
  • Edge Cases: If the creator wants to edit, they must first request the payer to cancel their payment/processing share back to 'unpaid'.
• BR-BIL-002: Bill Deletion Rules
  • Rule: A bill can be deleted by its creator only if all shares are 'unpaid'. Once a payment is registered, the bill cannot be deleted.
  • Reason: Prevents accidental or fraudulent deletion of payment history.
  • Exceptions: None.
  • Edge Cases: Instead of deletion, creators can mark active bills as “Cancelled” which hides them from active lists but retains the audit log in the database.

3. Payments, Slips, & Approvals

• BR-PAY-001: Slip Upload & Processing Windows
  • Rule: Debtors can upload slips for their share at any time. When a slip is uploaded, the corresponding expense_shares.status moves to 'processing', blocking other payment uploads for the same share.
  • Reason: Prevents multiple users from uploading the same slip or duplicate attempts on the same share.
  • Example: Mint uploads a slip. Her share status is 'processing'. She cannot upload another slip until the system verifies or rejects the current one.
  • Edge Cases: If AI verification times out, status reverts to 'unpaid' after 5 minutes, freeing the slot for retry or manual confirmation.
• BR-PAY-002: Creditor Rejection Rights
  • Rule: If automated AI slip verification fails, the bill creator (creditor) receives a manual approval task in their feed. The creator can approve or reject the slip.
  • Reason: Establishes the human user as the ultimate source of truth, preventing system blockages due to low-quality slip photos.
  • Exceptions: Creditors cannot manually reject a transaction that has been marked as 'verified' by the official bank database query.
• BR-PAY-003: Partial Payments
  • Rule: MVP does not support partial payments of individual shares. A user must settle their exact calculated share amount in full.
  • Reason: Keeps EMV Co PromptPay QR generation simple and matches the payment status flags exactly.
  • Exceptions: Custom splits can adjust initial share divisions before publishing.
• BR-PAY-004: Payment Cancellation
  • Rule: Payers cannot cancel a payment once the status has transitioned to 'verified'. They can only request cancellation during the 'processing' state (before AI/manual check completes).

4. Debt & Balance Calculations

• BR-DBT-001: Net Balance Aggregates (Zero-sum Debt)
  • Rule: The system calculates individual user net balances using a standard clearing algorithm:
    $\text{Net Balance}=\sum (\text{Bills Created by User}-\text{User’s Own Share})-\sum (\text{User’s Debt Shares to Others})$
    The sum of all net balances across a group must always equal exactly 0.
  • Reason: Prevents phantom money generation and ensures accounting balance.
• BR-DBT-002: Debt Simplification (Clearing)
  • Rule: Debt calculations are simplified across a group using a transaction minimization algorithm (e.g. standard net balance clearing).
  • Example: If A owes B 100 THB, and B owes C 100 THB, the system simplifies the ledger so A pays C 100 THB directly.

5. Gamification (Mochi Pet Rules)

• BR-GAM-001: XP Gains
  • Rule: The group pet (“Mochi”) gains XP when members settle debts:
    • Early Settlement (Within 12 hours): $+25\text{ XP}$
    • Standard Settlement (Within 24 hours): $+15\text{ XP}$
    • Late Settlement (After 24 hours but before deadline): $+5\text{ XP}$
• BR-GAM-002: HP Losses (Cron Schedule)
  • Rule: A cron job executes daily at 00:00. For each bill in the group that has passed its due date, Mochi loses health:
    $\text{HP Loss}=\text{Number of Overdue Shares}\times 10\text{ HP}$
    If Mochi’s HP reaches 0, Mochi becomes “Sick” and XP gain is frozen until HP is restored to at least 50.
• BR-GAM-003: HP Recovery
  • Rule: Mochi recovers 15 HP immediately when any overdue share is settled. Group members can also spend group XP to “feed” Mochi, restoring 10 HP per feed action.

6. AI Reminder Engine

• BR-AI-001: Tone-of-Voice Selection
  • Rule: Reminders are dispatched based on the creditor’s selected tone:
    • Polite: Standard professional notification.
    • Casual: Friendly chat message layout.
    • Humorous/Meme: AI generates a meme matching the group’s spending context and displays it in chat.
  • Safety Policy: Memes must not contain offensive language or hostile references.