README

💸 SplitDee

AI-Powered Smart Expense Management Platform
แพลตฟอร์มจัดการและแชร์ค่าใช้จ่ายอัจฉริยะด้วยขุมพลัง AI

---

🇹🇭 ภาษาไทย (For User)

📖 ภาพรวม (Overview)

SplitDee คือระบบบริหารจัดการและหารค่าใช้จ่ายส่วนกลางของกลุ่มเพื่อน รูมเมท นักศึกษา และทีมงานขนาดเล็ก ที่ช่วยขจัดปัญหาความกระอักกระอ่วนใจและความยุ่งยากเมื่อต้องทวงหนี้สิน
ตัวระบบผสมผสานฟีเจอร์การลงบันทึกบิล การหารค่าใช้จ่ายที่ยืดหยุ่น การยืนยันสลิปผ่าน AI อัตโนมัติ ระบบห้องแชทสื่อสารในตัว และการสร้างความร่วมมือด้วยสัตว์เลี้ยงเสมือนประจำกลุ่ม (Gamification)

🎯 ภารกิจ (Mission)

ช่วยให้ทุกคนสามารถจัดการแชร์เงินร่วมกันได้อย่างเรียบง่าย โปร่งใส เป็นระบบ และยังคงรักษามิตรภาพที่ดีไว้ได้

🌎 วิสัยทัศน์ (Vision)

ก้าวขึ้นเป็นแพลตฟอร์มบริหารเงินกลุ่มที่ชาญฉลาดที่สุด โดยนำ AI เข้ามาร่วมลดบรรยากาศอึดอัด เพิ่มความโปร่งใส และช่วยกระชับความสัมพันธ์ของผู้ใช้งาน

👥 ผู้ใช้งานเป้าหมาย (Target Users)

• กลุ่มหลัก: นักศึกษา, รูมเมท, กลุ่มเพื่อนสนิท
• กลุ่มรอง: ครอบครัว, กลุ่มนักท่องเที่ยวเดินทาง, ทีมงานขนาดเล็ก

🚨 ปัญหาหลักที่เราต้องการแก้ไข (Problems We Solve)

• สมาชิกลืมชำระเงิน หรือลืมว่าตนเองค้างจ่ายค่าอะไรบ้าง
• ความรู้สึกกระอักกระอ่วนเมื่อต้องเอ่ยปากทวงเงินเพื่อนโดยตรง
• ความเสี่ยงจากการได้รับรูปสลิปปลอม หรือสลิปเก่าส่งซ้ำ
• ความยุ่งยากซับซ้อนในการหารบิลที่มีเงื่อนไขรายบุคคล (เช่น คนนี้กินเหล้า คนนี้ไม่กินไก่)
• การสลับแอปไปมาระหว่างไลน์, โน้ตบิล และแอปโอนเงินธนาคาร

✨ ฟีเจอร์หลัก (Core Features)

• การจัดการบิล (Expense Management): บันทึกค่าใช้จ่าย หารเงินได้หลายแบบ (หารเท่ากัน, ระบุจำนวนเงิน, ตามร้อยละ) และแดชบอร์ดสรุปยอดหนี้
• การชำระเงินและการตรวจสอบ (Payment & Verification): แปลงหนี้เป็น PromptPay QR และใช้ AI สแกนสลิปโอนเงินตรวจสอบรายการจริงทันที
• ระบบช่วยเหลือ AI (AI Assistant): AI ช่วยส่งข้อความแจ้งเตือนตามระดับโทนเสียงที่เลือกได้ (เช่น ทวงเงินแบบกวนๆ ด้วยมีมขำขัน) และสรุปวิเคราะห์ค่าใช้จ่ายประจำเดือน
• ระบบแชทในแอป (Group Chat): สนทนา ส่งบิล และยืนยันการชำระเงินรวมไว้ที่แชทกลุ่มช่องทางเดียว
• ระบบสัตว์เลี้ยงกลุ่ม (Gamification): เลี้ยงน้อง “Mochi” ร่วมกันในกลุ่ม หากมีผู้จ่ายเงินตรงเวลาสัตว์เลี้ยงจะมีค่าประสบการณ์และสถิติสะสม (Streak) เพิ่มขึ้น หากดึงเช็งสัตว์เลี้ยงจะป่วย

🏗️ สถาปัตยกรรมที่ตัดสินใจเลือก (Architecture)

• ระบบเบื้องหน้า (Frontend): Flutter (ครอสแพลตฟอร์ม iOS & Android)
• ระบบหลังบ้าน (Backend): FastAPI (เร็ว แรง รองรับ Asynchronous)
• ฐานข้อมูล (Database): PostgreSQL
• โครงสร้างโค้ด: Clean Architecture
• ระบบการรับรองสิทธิ์ (Auth): JWT (JSON Web Tokens)

---

🇬🇧 English (For AI Agents)

📖 Overview

SplitDee is an AI-powered expense management platform designed to help students, roommates, friends, and small groups manage shared expenses without damaging relationships. The platform combines expense tracking, bill splitting, payment verification, AI-assisted reminders, group communication, and gamification.

🎯 Mission

Help people manage shared expenses in a simple, transparent, and friendly way.

🌎 Vision

Become the smartest expense management platform for groups by using AI to reduce awkwardness, improve transparency, and strengthen friendships.

👥 Target Users

• Primary: Students, Roommates, Friends
• Secondary: Families, Travelers, Small Teams

🚨 Problems We Solve

• Forgetting who owes whom
• Awkward debt collection
• Fake payment slips or duplicated transfer slips
• Manual complex bill calculations
• App fragmentation (switching between chat, notes, and banking apps)

✨ Core Features

• Expense Management: Bill creation, flexible splits (equal, exact, percentage), partial payments, and debt dashboards.
• Payment & Verification: Automated PromptPay QR generator and AI-powered transfer slip verification.
• AI Assistant: AI-powered reminder with tone options (including meme generation) and monthly spending summaries.
• Group Communication: In-app group chat and automated system notification messages.
• Gamification: Shared group pet (“Mochi”), XP progression, streak counters, and achievements.

🏗️ Architecture

• Frontend: Flutter
• Backend: FastAPI
• Database: PostgreSQL
• Architecture Pattern: Clean Architecture
• Authentication: JWT

---

📂 Project Structure (โครงสร้างโฟลเดอร์ของโปรเจกต์)

backend/       - FastAPI Application Code (FastAPI Backend)
frontend/      - Flutter Mobile App Code (Flutter Mobile App)
docker/        - Container Configuration files (การตั้งค่า Docker)
docs/          - Project Documentation (เอกสารอ้างอิงโครงการ)
scripts/       - Maintenance & Automation scripts (สคริปต์อัตโนมัติ)
obsidian/      - Link to Obsidian Vault (คลังข้อมูล Obsidian)

---

🚀 Current Phase & Roadmap (เฟสปัจจุบันและโรดแมป)

🚩 เฟสปัจจุบัน (Current Phase)

• Sprint 1 — Product Design & System Architecture (การออกแบบผลิตภัณฑ์และโครงสร้างสถาปัตยกรรมระบบ)

🛣️ แผนภาพ Roadmap (Roadmap)

• ออกแบบรายละเอียดฟังก์ชันผลิตภัณฑ์ (Product Design & Requirements)
• ออกแบบแผนภาพความสัมพันธ์ข้อมูล (Database ERD Design)
• ออกแบบและกำหนดสเปก APIs (API Design & Specification)
• ออกแบบรายละเอียดสถาปัตยกรรมโค้ด (Clean Architecture Mapping)
• พัฒนาระบบหลังบ้าน (Backend FastAPI Setup & DB Migration)
• พัฒนาระบบหน้าบ้าน (Frontend Flutter Setup & UI Pages)
• พัฒนาระบบตรวจสอบภาพสลิปผ่าน AI (AI Slip Verification Module)
• จัดทำระบบเกมสัตว์เลี้ยงกลุ่มและแชท (Chat & Gamification Integration)
• การทดสอบระบบและการใช้งานจริง (Testing & Production Deployment)

---

🧠 AI Workflow & Principles (กระบวนการทำงานของ AI)

🔄 ลำดับขั้นตอนการทำงาน (AI Workflow)

ทุกครั้งที่ AI ผู้ช่วยเข้ามาพัฒนาโครงการ จะต้องอ่านเอกสารพื้นฐานก่อนเสมอ:

1. README.md
2. CONTEXT.md
3. DECISIONS.md
4. 04_AI/AI_RULES.md / 04_AI/AI_BRAIN.md
5. CTO_PLAYBOOK/

📌 หลักยึดในการพัฒนา (Development Principles)

• Clean Architecture & SOLID: ยึดมั่นในการเขียนโค้ดที่สะอาดแยกความเกี่ยวข้องชัดเจน
• DRY (Don’t Repeat Yourself): หลีกเลี่ยงความซ้ำซ้อนของโค้ด
• KISS (Keep It Simple, Stupid): ออกแบบระบบที่เข้าใจง่าย ไม่ซับซ้อนเกินจำเป็น
• Documentation First: จัดทำรายละเอียดระบบในเอกสารก่อนลงมือพัฒนาจริงเสมอ เพื่อให้อัปเดตตรงกันตลอดเวลา

---

📖 Status (สถานะล่าสุดของระบบ)

• สถานะ: 🟡 กำลังวางแผนและออกแบบโครงสร้าง (Planning & Designing)
• ความคืบหน้า: ดำเนินการออกแบบระบบ ฐานข้อมูล และ APIs เสร็จสิ้นแล้ว อยู่ในขั้นตอนเตรียมการทำ Mockup/UI Flow และวาง Skeleton โครงสร้างโค้ด