Domain Events Specification

🧠 DOMAIN_EVENTS.md - Domain Events Specification (รายการเหตุการณ์ทางโดเมน)

This document outlines the event schema, source, consumers, and expected outcomes for SplitDee’s event-driven architecture.
เอกสารฉบับนี้สรุปรายการเหตุการณ์ แหล่งกำเนิด โมดูลคอยรับผลลัพธ์ และสถานะการประมวลผลสำหรับโครงสร้างที่ขับเคลื่อนด้วยอีเวนต์ (Event-Driven Architecture) ของ SplitDee

---

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

1. เหตุการณ์ลงทะเบียนและการระบุตัวตน (Authentication & User Events)

• เหตุการณ์ UserRegistered (ลงทะเบียนผู้ใช้งานใหม่):
  • เงื่อนไขเริ่ม: ผู้ใช้ลงทะเบียนสมัครบัญชีสำเร็จผ่านหน้าจอหลัก
  • แหล่งกำเนิดข้อมูล: RegisterUserUseCase (กระบวนการลงทะเบียนหลังบ้าน)
  • โมดูลคอยรับข้อมูล: NotificationService (ส่งคำต้อนรับในหน้าจอแอป), AnalyticsService (บันทึกสถิติภาพรวม)
  • ผลลัพธ์ระบบ: ข้อมูลผู้ใช้บันทึกลงฐานข้อมูล, ตั้งค่าโปรไฟล์สากล และยิงอีเมลยินดีต้อนรับเข้าคิวงานส่ง

2. เหตุการณ์กลุ่มและสมาชิกกลุ่ม (Group & Membership Events)

• เหตุการณ์ GroupCreated (จัดตั้งกลุ่มแชร์ยอดเงินสำเร็จ):
  • เงื่อนไขเริ่ม: ผู้ใช้กดปุ่มสร้างกลุ่มในแผงควบคุมแอป
  • แหล่งกำเนิดข้อมูล: CreateGroupUseCase (กระบวนการสร้างห้องกลุ่ม)
  • โมดูลคอยรับข้อมูล: PetService (ทำการฟักไข่สัตว์เลี้ยงโมจิเลเวล 1 ร่วมกันสำหรับกลุ่มใหม่นี้)
  • ผลลัพธ์ระบบ: บันทึกข้อมูลคีย์กลุ่ม, ออกรหัสเข้าร่วม 10 หลัก และผูกตัวแปรกราฟิกสัตว์เลี้ยงประจำกลุ่ม
• เหตุการณ์ MemberJoined (เพื่อนร่วมห้องกรอกรหัสเข้ากลุ่ม):
  • เงื่อนไขเริ่ม: เพื่อนในห้องป้อนรหัสคีย์เพื่อเข้าร่วมกลุ่มแชร์ค่าใช้จ่าย
  • แหล่งกำเนิดข้อมูล: JoinGroupUseCase (กระบวนการสืบค้นและดึงชื่อเข้าห้อง)
  • โมดูลคอยรับข้อมูล: ChatService (ส่งกล่องแชทข้อความระบบว่าเพื่อนร่วมเข้าห้องสนทนาแล้ว), PetService (บวกแต้มความรักฟื้นอารมณ์ให้น้องโมจิ +5 แต้ม)
  • ผลลัพธ์ระบบ: บันทึกแถวประวัติสมาชิกกลุ่ม และยิงแชทการ์ดรายงานในกลุ่มให้ทุกคนทราบสถานะทันที

3. เหตุการณ์บันทึกบิลค่าใช้จ่าย (Billing & Expense Events)

• เหตุการณ์ BillCreated (บันทึกบิลใหม่):
  • เงื่อนไขเริ่ม: เจ้าหนี้กดยืนยันป้อนยอดเงินและสัดส่วนส่วนแบ่งชำระเงินของเพื่อน
  • แหล่งกำเนิดข้อมูล: CreateBillUseCase
  • โมดูลคอยรับข้อมูล: ChatService (วาดการ์ดบิลสีเขียวสำหรับกดจ่ายเงินค้างชำระในห้องแชทของทุกคน), NotificationService (ยิงแจ้งเตือนด่วนหน้าจอลูกหนี้ทุกคนที่ถูกหาร)
  • ผลลัพธ์ระบบ: บันทึกยอดค้างและประวัติตารางส่วนแบ่งเงินของลูกหนี้แต่ละคนลงระบบ
• เหตุการณ์ BillClosed (ปิดบิลชำระเงินสำเร็จครบ):
  • เงื่อนไขเริ่ม: สมาชิกกลุ่มทุกคนทำการแสกนสลิปโอนคืนเงินสำเร็จครบถ้วนในบิล
  • แหล่งกำเนิดข้อมูล: PaymentVerificationUseCase
  • โมดูลคอยรับข้อมูล: ChatService (โพสต์ส่งการ์ดสำเร็จปิดบิลถาวรลงแชทกลุ่ม), PetService (วิเคราะห์เวลาชำระเงินเพื่อมอบ XP โบนัสให้เลเวลสัตว์เลี้ยงกลุ่ม)
  • ผลลัพธ์ระบบ: สเตตัสบิลหลักเปลี่ยนเป็น ‘settled’ เคลียร์บัญชีหนี้สิ้นและสัตว์เลี้ยงกลุ่มเลเวลอัป

4. เหตุการณ์ตรวจชำระและอนุมัติสลิป (Payment & Verification Events)

• เหตุการณ์ SlipUploaded (ลูกหนี้ยื่นหลักฐานสลิปโอนเงิน):
  • เงื่อนไขเริ่ม: ลูกหนี้สแกนคิวอาร์พร้อมเพย์แล้วถ่ายรูปหรือเลือกไฟล์สลิปส่งเข้ามา
  • แหล่งกำเนิดข้อมูล: PaymentSubmitUseCase
  • โมดูลคอยรับข้อมูล: AI_JobQueue (โยนภาพเข้าคิวงานประมวลผล OCR ตรวจแกบรหัสคิวอาร์อัตโนมัติ)
  • ผลลัพธ์ระบบ: สัดส่วนของลูกหนี้ถูกล็อกเป็น ‘processing’ และคีย์ตรวจสอบสถานะตั้งค่าเป็น ‘รอตรวจสอบ’
• เหตุการณ์ SlipVerified (สลิปผ่านการอนุมัติออโต้สำเร็จ):
  • เงื่อนไขเริ่ม: ผลสืบค้นธุรกรรมธนาคารตอบกลับตรงความจริง
  • แหล่งกำเนิดข้อมูล: VerifySlipUseCase
  • โมดูลคอยรับข้อมูล: PaymentService (กดยอมรับประวัติผ่าน), BillService (เคลียร์สเตตัสยอดของลูกหนี้เป็น ‘paid’), ChatService (ยิงการ์ดติ๊กถูกแชทสีเขียวแจ้งเตือนทุกคน)
  • ผลลัพธ์ระบบ: เคลียร์ยอดหนี้สินออกจากบัญชีกลาง บันทึกแชท และสืบเงื่อนไขความพร้อมปิดบิลบิลต่อไป
• เหตุการณ์ PaymentRejected (หลักฐานโอนเงินไม่ผ่าน):
  • เงื่อนไขเริ่ม: ธนาคารระบุสลิปปลอม/สลิปโอนซ้ำ หรือเจ้าหนี้ปฏิเสธประวัติ
  • โมดูลคอยรับข้อมูล: NotificationService (แจ้งเตือนมือถือลูกหนี้บอกสลิปไม่ผ่านกรุณาส่งใหม่), ChatService (เพิ่มบันทึกความล้มเหลวลงแชทกลุ่ม)
  • ผลลัพธ์ระบบ: ปรับปรุงยอดกลับมาเป็นยังไม่ได้จ่ายและเครื่องหมายกากบาทสีแดง

5. เหตุการณ์สัตว์เลี้ยงโมจิแสนรัก (Gamification & Pet Events)

• เหตุการณ์ PetFed (ให้อาหารน้องสัตว์เลี้ยงกลุ่ม):
  • เงื่อนไขเริ่ม: สมาชิกกดใช้พอยท์ป้อนอาหารโมจิ ➔ เพิ่ม HP สัตว์เลี้ยง +10 แต้ม
• เหตุการณ์ PetHungry (โมจิประท้วงหิวเนื่องจากบิลดึงเช็ง):
  • เงื่อนไขเริ่ม: บิลค้างชำระเลยกำหนดเวลากำหนด ➔ หัก HP สัตว์เลี้ยง -10 HP ต่อยอดหนี้ และส่งแชทกวนเตือนกลุ่ม
• เหตุการณ์ FriendshipIncreased (ความรักเพื่อนเบ่งบาน):
  • เงื่อนไขเริ่ม: ทุกคนแสกนโอนเคลียร์เงินครบถ้วนด่วนใน 12 ชม. ➔ บันทึกสถิติความรักเพื่อนสะสมเพิ่มอย่างต่อเนื่อง

6. เหตุการณ์ระบบทำงานอัตโนมัติ AI (AI & Reminder Events)

• เหตุการณ์ ReminderTriggered (สั่งยิงแชทเตือนเงิน):
  • เงื่อนไขเริ่ม: เกินดิวครบชำระหรือเจ้าหนี้กดทวงเพื่อน ➔ ส่งทวงตามเสียงที่เลือก หากเป็นมีมตลก AI จะเข้าคิว
• เหตุการณ์ AIJobFinished (AI ประมวลภาพมีมเสร็จสิ้น):
  • เงื่อนไขเริ่ม: งานตรวจ OCR หรือเขียนมีมทวงเงินเสร็จ ➔ จัดส่งมีมสำเร็จลงห้องแชทและมือถือเพื่อน

---

🇬🇧 English (For AI Agents)

1. Authentication & User Events

• UserRegistered
  • Trigger: A new user completes signup.
  • Source: RegisterUserUseCase
  • Consumers: NotificationService, AnalyticsService
  • Expected Result: Database record persists, profile initialized, welcome email scheduled.

2. Group & Membership Events

• GroupCreated
  • Trigger: A user clicks “Create Group” on the dashboard.
  • Source: CreateGroupUseCase
  • Consumers: PetService
  • Expected Result: Database record created, invite code generated, pet instance associated.
• MemberJoined
  • Trigger: A user enters a valid group invite code.
  • Source: JoinGroupUseCase
  • Consumers: ChatService, PetService
  • Expected Result: User added to group_members table, group chat notified.

3. Billing & Expense Events

• BillCreated
  • Trigger: A creator submits a new bill split.
  • Source: CreateBillUseCase
  • Consumers: ChatService, NotificationService
  • Expected Result: Bill and associated expense shares persist.
• BillClosed
  • Trigger: All individual expense shares associated with a bill are marked as 'paid'.
  • Source: PaymentVerificationUseCase
  • Consumers: ChatService, PetService
  • Expected Result: Bill status transitions to settled, Mochi gains levels/XP.

4. Payment & Verification Events

• SlipUploaded
  • Trigger: Debtor uploads a transfer slip.
  • Source: PaymentSubmitUseCase
  • Consumers: AI_JobQueue
  • Expected Result: Share status changes to 'processing', payment record created as 'pending'.
• SlipVerified
  • Trigger: Bank API query confirms transfer validity.
  • Source: VerifySlipUseCase
  • Consumers: PaymentService, BillService, ChatService
  • Expected Result: Balance cleared, chat logs receipt, triggers BillClosed checks.
• PaymentRejected
  • Trigger: AI validation fails and creditor manually rejects the slip.
  • Source: ManualReviewUseCase
  • Consumers: NotificationService, ChatService
  • Expected Result: Share status resets to 'unpaid', payment marked 'failed'.

5. Gamification & Pet Events

• PetFed
  • Trigger: Group member spends XP points to feed Mochi.
  • Source: PetInteractUseCase
  • Consumers: PetService
  • Expected Result: Group XP decremented, pet HP status updated.
• PetHungry
  • Trigger: Nightly cron finds bills that are past their due date.
  • Source: CronJobEngine
  • Consumers: PetService, ChatService
  • Expected Result: Pet HP decremented, alerts dispatched.
• FriendshipIncreased
  • Trigger: All roommates pay their bills within 12 hours of publishing.
  • Source: VerifySlipUseCase
  • Consumers: AnalyticsService
  • Expected Result: Streak counter increments.

6. AI & Reminder Events

• ReminderTriggered
  • Trigger: Deadline approach or manual trigger by creditor.
  • Source: ReminderService
  • Consumers: AI_MemeJobQueue
  • Expected Result: Generates custom meme text and schedules message.
• AIJobFinished
  • Trigger: Image generation or OCR engine completes processing.
  • Source: AIWorkerEngine
  • Consumers: ChatService
  • Expected Result: Output JSON processed, notification dispatched.