Domain Model Specification

🧠 DOMAIN_MODEL.md - Domain Model Specification (ข้อมูลจำลองโดเมน)

This document defines the core business entities, their responsibilities, attributes, business constraints, lifecycles, and validation rules for the SplitDee platform.
เอกสารฉบับนี้กำหนดเอนทิตีทางธุรกิจแกนหลัก หน้าที่ความรับผิดชอบ คุณลักษณะ ข้อจำกัดทางธุรกิจ วงจรชีวิต และกฎการตรวจสอบความถูกต้องสำหรับแพลตฟอร์ม SplitDee

---

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

1. เอนทิตี: User (ผู้ใช้งาน)

• วัตถุประสงค์: แสดงถึงบัญชีผู้ใช้แต่ละบุคคลที่ลงทะเบียนในระบบ
• ความรับผิดชอบ: จัดเก็บข้อมูลโปรไฟล์ บัญชียืนยันตัวตน รายละเอียดช่องทางพร้อมเพย์สำหรับสร้าง QR โค้ด และบันทึกยอดเงินรวมส่วนบุคคล
• คุณลักษณะ (Attributes):
  • id (UUID): ตัวระบุเฉพาะของแต่ละผู้ใช้งาน
  • email (string): ที่อยู่อีเมลประจำบัญชี
  • password_hash (string): รหัสผ่านที่แฮชด้วย Bcrypt
  • display_name (string): ชื่อแสดงผลโปรไฟล์สาธารณะ
  • phone_number (string, optional): หมายเลขโทรศัพท์ที่ผูกกับพร้อมเพย์
  • avatar_url (string, optional): ลิงก์รูปภาพโปรไฟล์ผู้ใช้
  • is_active (boolean): สถานะความเคลื่อนไหวการใช้งานบัญชี
• ความสัมพันธ์ (Relationships):
  • เชื่อมโยงหนึ่งต่อหลายกับ GroupMember (กลุ่มสมาชิกที่เข้าร่วม)
  • เชื่อมโยงหนึ่งต่อหลายกับ Bill (บิลที่สร้างขึ้น)
  • เชื่อมโยงหนึ่งต่อหลายกับ ExpenseShare (ยอดส่วนแบ่งหนี้ที่ค้างจ่าย)
  • เชื่อมโยงหนึ่งต่อหลายกับ Payment (หลักฐานการโอนเงินที่ยื่นเข้ามา)
• ข้อจำกัดทางธุรกิจ: อีเมลต้องไม่ซ้ำกัน เบอร์โทรศัพท์เป็นข้อมูลเลือกใส่ แต่จำเป็นต้องระบุก่อนสร้างคิวอาร์พร้อมเพย์เมื่อผู้ใช้งานทำหน้าที่เป็นเจ้าหนี้
• วงจรชีวิต (Lifecycle): ลงทะเบียน (Created) ➔ ใช้งานอยู่ (Active) ➔ ระงับชั่วคราว (Suspended) ➔ ยกเลิกใช้งาน/ปกปิดตัวตน (Deactivated)
• กฎการตรวจสอบข้อมูล: อีเมลต้องตรงตามรูปแบบ Regex ชื่อแสดงผลยาว 2 ถึง 100 อักขระ เบอร์โทรศัพท์ไทยมี 10 หลัก (เช่น 08XXXXXXXX)
• การขยายตัวในอนาคต: บัญชี Social Login, รายละเอียดเลขที่บัญชีธนาคาร, ปุ่มปรับแต่งการแจ้งเตือน

2. เอนทิตี: Group (กลุ่มกิจกรรม)

• วัตถุประสงค์: แสดงถึงพื้นที่แบ่งปันค่าใช้จ่ายของรูมเมท เพื่อนสนิท หรือคณะเดินทาง
• ความรับผิดชอบ: จัดการข้อมูลสมาชิก ควบคุมขอบเขตบิล ดูแลสัตว์เลี้ยงของกลุ่ม และควบคุมกล่องแชทข้อความ
• คุณลักษณะ (Attributes):
  • id (UUID): ตัวระบุเฉพาะของกลุ่ม
  • name (string): ชื่อกลุ่ม
  • description (text, optional): คำอธิบายวัตถุประสงค์ของกลุ่ม
  • invite_code (string): รหัสเชิญชวนเข้ากลุ่มความยาว 10 หลัก
• ความสัมพันธ์ (Relationships):
  • หนึ่งต่อหลายกับ GroupMember (สมาชิกกลุ่ม)
  • หนึ่งต่อหลายกับ Bill (บิลค่าใช้จ่าย)
  • หนึ่งต่อหลายกับ ChatMessage (แชทสนทนากลุ่ม)
  • หนึ่งต่อหนึ่งกับ Pet (สัตว์เลี้ยงประจำกลุ่ม)
• ข้อจำกัดทางธุรกิจ: ชื่อกลุ่มห้ามว่าง รหัสเชิญชวนต้องไม่ซ้ำและประกอบด้วยตัวอักษรผสมตัวเลข
• วงจรชีวิต (Lifecycle): สร้างกลุ่ม ➔ ใช้งานอยู่ ➔ จัดเก็บถาวร (Archived)
• กฎการตรวจสอบข้อมูล: ชื่อกลุ่มต้องมีความยาวระหว่าง 1 ถึง 100 อักขระ

3. เอนทิตี: GroupMember (สมาชิกกลุ่ม)

• วัตถุประสงค์: แสดงความสัมพันธ์และความเชื่อมโยงระหว่างผู้ใช้งานและกลุ่ม
• ความรับผิดชอบ: ควบคุมบทบาทสิทธิ์การทำรายการและเข้าถึงข้อมูลภายในกลุ่ม
• คุณลักษณะ (Attributes):
  • id (UUID): ตัวระบุสถานะสมาชิก
  • group_id (UUID): ตัวอ้างอิงกลุ่มหลัก
  • user_id (UUID): ตัวอ้างอิงผู้ใช้งาน
  • role (string): บทบาทหน้าที่สิทธิ์ (owner หรือ member)
• ข้อจำกัดทางธุรกิจ: ค่าไอดีคู่กัน (group_id, user_id) ต้องไม่ซ้ำกัน ผู้ใช้งานไม่สามารถเข้าร่วมกลุ่มเดิมซ้ำซ้อนได้

4. เอนทิตี: Bill (บิลค่าใช้จ่าย)

• วัตถุประสงค์: รายการบันทึกค่าใช้จ่ายหนึ่งรายการที่เกิดขึ้นในกลุ่ม
• ความรับผิดชอบ: บันทึกผู้สำรองจ่าย ยอดเงินรวม วิธีการหารเงิน และสถานะชำระหนี้
• คุณลักษณะ (Attributes):
  • id (UUID): ตัวระบุบิล
  • group_id (UUID): อ้างอิงกลุ่ม
  • creator_id (UUID): เจ้าหนี้ผู้สำรองออกเงินก่อน
  • title (string): ชื่อบิลค่าใช้จ่าย
  • total_amount (numeric): ยอดเงินรวมของบิล
  • category (string): หมวดหมู่บิล
  • status (string): สถานะบิล (active, settled, locked)
• ข้อจำกัดทางธุรกิจ: ยอดเงินต้องมากกว่า 0 ผลรวมส่วนแบ่งต้องเท่ากับยอดรวมบิลพอดี
• วงจรชีวิต (Lifecycle): ร่างจด ➔ เปิดใช้งานรอชำระ ➔ ชำระครบถ้วน ➔ ล็อกบิลถาวร (Locked)

5. เอนทิตี: ExpenseShare (ส่วนแบ่งยอดหนี้)

• วัตถุประสงค์: ยอดเงินค้างจ่ายที่ลูกหนี้แต่ละคนต้องโอนคืนให้เจ้าหนี้
• คุณลักษณะ (Attributes):
  • id (UUID): ตัวระบุยอดค้างชำระ
  • bill_id (UUID): อ้างอิงบิลหลัก
  • user_id (UUID): ตัวระบุลูกหนี้
  • share_amount (numeric): ยอดเงินที่ต้องจ่าย
  • status (string): สถานะชำระหนี้ (unpaid, processing, paid)

6. เอนทิตี: Payment (รายการชำระเงิน)

• วัตถุประสงค์: รายการชำระเงินและตรวจสอบหลักฐานของลูกหนี้
• คุณลักษณะ (Attributes):
  • id (UUID): ตัวระบุ
  • bill_id (UUID): อ้างอิงบิล
  • payer_id (UUID): ลูกหนี้ผู้โอนเงิน
  • amount (numeric): ยอดเงินโอนจริง
  • slip_image_url (string): ลิงก์ที่เก็บไฟล์รูปภาพสลิป
  • slip_trans_id (string): เลขอ้างอิงรหัสธุรกรรมของธนาคาร
  • verification_status (string): สถานะตรวจสลิป (pending, verified, failed)

7. เอนทิตี: Receipt (ภาพใบเสร็จร้านค้า)

• วัตถุประสงค์: ข้อมูลสแกนใบเสร็จต้นทางเพื่ออำนวยความสะดวกในการจัดสรรค่าใช้จ่ายสร้างบิล

8. เอนทิตี: Notification (การแจ้งเตือน)

• วัตถุประสงค์: บันทึกและจัดส่งข้อความแจ้งข่าวสารในระบบไปยังมือถือของผู้ใช้งาน

9. เอนทิตี: ChatMessage (ข้อความสนทนา)

• วัตถุประสงค์: ข้อความ กิจกรรมระบบ หรือการ์ดบิลที่แสดงผลบนห้องแชทของห้อง

10. เอนทิตี: Pet & PetStatus (สัตว์เลี้ยงเสมือนโมจิ)

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

11. เอนทิตี: Reminder (รายการส่งทวง)

• วัตถุประสงค์: บันทึกข้อมูลประวัติการกดเตือนเงินและระดับน้ำเสียงทวงเพื่อน

12. เอนทิตี: AIJob (คิวงาน AI)

• วัตถุประสงค์: งานประมวลผลระบบ AI หลังบ้าน เช่น การสแกนภาพสลิปธนาคาร

13. เอนทิตี: MemeTemplate (แม่แบบมีม)

• วัตถุประสงค์: รูปพื้นหลังมีมและข้อมูลพิกัดวางข้อความทับ สำหรับยิงทวงหนี้อัตโนมัติ

---

🇬🇧 English (For AI Agents)

1. Entity: User

• Purpose: Represents an individual account registered in the system.
• Responsibilities: Holds identity profiles, security credentials, contact details for PromptPay QR generation, and tracks individual financial balance aggregates.
• Attributes:
  • id (UUID): Unique user identifier.
  • email (string): Account email address.
  • password_hash (string): Bcrypt hash of user password.
  • display_name (string): Public profile display name.
  • phone_number (string, optional): Phone number linked to PromptPay.
  • avatar_url (string, optional): Link to profile avatar.
  • is_active (boolean): Active status flags.
• Relationships:
  • One-to-Many with GroupMember (groups joined).
  • One-to-Many with Bill (bills created).
  • One-to-Many with ExpenseShare (debts owed).
  • One-to-Many with Payment (slips submitted).
• Business Constraints: Email must be unique. Phone number is optional, but required prior to generating PromptPay codes where the user is the creditor.
• Lifecycle: Created (Registered) -> Active -> Suspended (optional) -> Deactivated/Anonymized.
• Validation Rules: Email must match valid email regex. Display name must be between 2 and 100 characters. Phone number must match standard Thai mobile formats (e.g., 08XXXXXXXX or 09XXXXXXXX, total 10 digits).
• Future Extensions: Social Login credentials, banking account details, notification preference toggles.

2. Entity: Group

• Purpose: Represents a shared space containing roommates, friends, or travelers who share expenses.
• Responsibilities: Manages memberships, scopes bills, contains a group pet, and scopes chat messages.
• Attributes:
  • id (UUID): Unique group identifier.
  • name (string): Group name.
  • description (text, optional): Description of the group’s purpose.
  • invite_code (string): Unique 10-character code to join the group.
• Relationships:
  • One-to-Many with GroupMember (members).
  • One-to-Many with Bill (bills).
  • One-to-Many with ChatMessage (chat activity feed).
  • One-to-One with Pet (shared pet).
• Business Constraints: Name must not be blank. Invite code must be unique and alphanumeric.
• Lifecycle: Created -> Active -> Archived.
• Validation Rules: Group name must be between 1 and 100 characters.
• Future Extensions: Group category, group avatars, group specific thresholds for expenses.

3. Entity: GroupMember

• Purpose: Represents the association between a User and a Group.
• Responsibilities: Governs role permissions inside a group.
• Attributes:
  • id (UUID): Unique membership identifier.
  • group_id (UUID): Reference to parent Group.
  • user_id (UUID): Reference to associated User.
  • role (string): Member privileges (owner, member).
• Relationships: Many-to-One with Group, Many-to-One with User.
• Business Constraints: Composite uniqueness on (group_id, user_id): a user cannot join a group twice.
• Lifecycle: Joined -> Active -> Removed/Left.
• Validation Rules: Role must match either 'owner' or 'member'.

4. Entity: Bill

• Purpose: Represents a single recorded expense.
• Responsibilities: Tracks who paid, total cost, split logic, and settlement status.
• Attributes:
  • id (UUID): Unique bill identifier.
  • group_id (UUID): Parent group.
  • creator_id (UUID): The creditor (who paid the initial cost).
  • title (string): Purpose of the bill.
  • total_amount (numeric): Total expense amount.
  • category (string): Expense category.
  • status (string): Status of the bill (active, settled, locked).
• Relationships:
  • Many-to-One with Group.
  • Many-to-One with User (creator).
  • One-to-Many with ExpenseShare (individual splits).
  • One-to-Many with Payment (associated payments).
• Business Constraints: Total amount must be greater than 0. Sum of associated expense shares must exactly equal the total amount.
• Lifecycle: Draft -> Active (Published) -> Settled (all shares paid) -> Locked (archived after verification).
• Validation Rules: Title must be between 1 and 255 characters. Total amount must have up to 2 decimal places.

5. Entity: ExpenseShare

• Purpose: Represents an individual debtor’s share of a specific bill.
• Responsibilities: Tracks debt status and payment details for a single user.
• Attributes:
  • id (UUID): Unique share identifier.
  • bill_id (UUID): Parent bill.
  • user_id (UUID): Debtor.
  • share_amount (numeric): Amount this user owes.
  • status (string): Status of the share (unpaid, processing, paid).
  • paid_at (datetime, optional): Time of verification.
• Relationships: Many-to-One with Bill, Many-to-One with User (debtor).
• Business Constraints: Share amount must be positive. Debtor cannot be the same user as the bill creator unless it’s a multi-debtor custom split adjustment.
• Lifecycle: Created -> Unpaid -> Processing (slip uploaded, pending OCR/manual review) -> Paid.
• Validation Rules: Share status must be in ['unpaid', 'processing', 'paid'].

6. Entity: Payment

• Purpose: Represents a transaction submission by a debtor.
• Responsibilities: Houses reference numbers and links to slip photos to verify debt settlement.
• Attributes:
  • id (UUID): Unique identifier.
  • bill_id (UUID): Associated bill.
  • payer_id (UUID): The debtor who made the payment.
  • amount (numeric): Amount transferred.
  • slip_image_url (string): Path to slip image in secure storage.
  • slip_trans_id (string, optional): Extracted bank transaction ID.
  • verification_status (string): Verification status (pending, verified, failed).
  • verified_at (datetime, optional): Time of verification completion.
• Relationships: Many-to-One with Bill, Many-to-One with User (payer).
• Business Constraints: slip_trans_id must be unique across the entire platform database (prevents double-spending).
• Lifecycle: Initiated -> Pending (awaiting OCR/Bank query) -> Verified / Failed.
• Validation Rules: Status must match ['pending', 'verified', 'failed'].

7. Entity: Receipt

• Purpose: Represents the initial invoice or merchant receipt of a bill.
• Responsibilities: Holds details extracted by AI/OCR to auto-populate Bill creation fields.
• Attributes:
  • id (UUID): Unique identifier.
  • image_url (string): Path to receipt image.
  • extracted_total (numeric, optional): Extracted total cost.
  • extracted_merchant (string, optional): Extracted merchant name.
• Relationships: Associated with Bill (optional).
• Lifecycle: Uploaded -> Extracted -> Linked to Bill / Discarded.

8. Entity: Notification

• Purpose: Represents a system notification to a user.
• Responsibilities: Holds message payload and dispatch status.
• Attributes:
  • id (UUID): Unique identifier.
  • user_id (UUID): Recipient.
  • title (string): Title of notification.
  • body (text): Content.
  • is_read (boolean): Read status.
  • channel (string): Delivery method (in-app, push).
• Relationships: Many-to-One with User.
• Lifecycle: Created -> Sent -> Read / Expired.

9. Entity: ChatMessage

• Purpose: Represents a message inside a group chat feed.
• Responsibilities: Holds text details, system events, and references to bills/payments.
• Attributes:
  • id (UUID): Unique identifier.
  • group_id (UUID): Parent group.
  • sender_id (UUID, optional): Sender. If null, represents a system message.
  • message_type (string): Message type (text, system_event, bill_card).
  • message (text): Main message content.
  • metadata_json (JSON, optional): Auxiliary ID references.
• Relationships: Many-to-One with Group, Many-to-One with User.
• Lifecycle: Sent -> Delivered. No editing allowed.

10. Entity: Pet

• Purpose: Represents the shared virtual pet (“Mochi”) belonging to a group.
• Responsibilities: Motivates timely debt repayment through gamified health status.
• Attributes:
  • id (UUID): Unique identifier.
  • group_id (UUID): Associated group.
  • pet_name (string): Name chosen by the group.
• Relationships: One-to-One with Group, One-to-Many with PetStatus.
• Lifecycle: Hatched -> Active -> Inactive (group archived).

11. Entity: PetStatus

• Purpose: Represents the dynamic health state of a Pet.
• Responsibilities: Manages level, HP, and Happiness levels.
• Attributes:
  • id (UUID): Unique identifier.
  • pet_id (UUID): Parent pet.
  • level (integer): Current level.
  • xp (integer): Experience points.
  • hp (integer): Health points (0-100).
  • happiness (integer): Happiness level (0-100).
• Relationships: Many-to-One with Pet.
• Business Constraints: HP and Happiness must be clamped between 0 and 100.
• Lifecycle: Updated daily via cron schedules and whenever payment events trigger updates.

12. Entity: Reminder

• Purpose: Represents a debt-collection notification task.
• Responsibilities: Tracks when, how, and in what tone a debtor was reminded.
• Attributes:
  • id (UUID): Unique identifier.
  • bill_id (UUID): Reference bill.
  • debtor_id (UUID): Debtor.
  • tone (string): Reminder tone (polite, casual, meme).
  • sent_at (datetime): Time of dispatch.
• Relationships: Many-to-One with Bill, Many-to-One with User.

13. Entity: AIJob

• Purpose: Represents an asynchronous background task processed by the AI system (OCR or meme generation).
• Responsibilities: Tracks job status, worker ID, and outputs.
• Attributes:
  • id (UUID): Unique identifier.
  • job_type (string): Task type (slip_ocr, receipt_ocr, meme_generation).
  • status (string): Status (queued, processing, completed, failed).
  • result (JSON, optional): Output payload.
• Lifecycle: Queued -> Processing -> Completed / Failed.

14. Entity: MemeTemplate

• Purpose: Represents a predefined image layout used to generate AI reminder memes.
• Responsibilities: Holds base paths and coordinates for text placement.
• Attributes:
  • id (UUID): Unique identifier.
  • name (string): Name of the meme format.
  • image_url (string): Base layout image.
  • text_coordinates (JSON): Pixel boundaries for text overlays.