Coding Standards & Development Workflow

💻 Coding Standards & Development Workflow (คู่มือมาตรฐานการเขียนโค้ดและขั้นตอนการพัฒนา)

This document defines the coding styles, conventions, repository structure, git branching strategy, commit guidelines, and release procedures for the SplitDee project.
เอกสารฉบับนี้กำหนดมาตรฐานการเขียนโค้ด การจัดแบ่งไฟล์ กติกาการแตกสาขา Git และขั้นตอนการอัปเดตระบบของโครงการ SplitDee

---

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

1. มาตรฐานการเขียนโค้ด (Coding Standards)

• ภาษา Python (หลังบ้าน FastAPI):
  • ยึดเกณฑ์มาตรฐาน PEP 8 ทั่วทั้งไฟล์โค้ด
  • ใช้เครื่องมือจัดรูปแบบโค้ด black (จำกัดความยาวบรรทัดสูงสุด 88 อักขระ)
  • ใช้ ruff หรือ flake8 ร่วมกับ isort ในการจัดเรียงหัวข้อการนำเข้าอิมพอร์ต (Imports)
  • บังคับ ระบุ Type hints เสมอสำหรับการประกาศฟังก์ชัน (Parameters & Returns)
  • การตั้งชื่อ: คลาสใช้ PascalCase (เช่น CreateBillUseCase), ฟังก์ชันและตัวแปรใช้ snake_case (เช่น verify_slip_image), ตัวแปรค่าคงที่ใช้ตัวพิมพ์ใหญ่ทั้งหมด UPPER_SNAKE_CASE
• ภาษา Dart (หน้าบ้าน Flutter):
  • ยึดเกณฑ์คู่มือการเขียน Dart Style Guide อย่างเคร่งครัด
  • ใช้ dart format จัดรูปแบบ และใช้ flutter_lints ตรวจหาข้อบกพร่องตามระดับความเข้มงวด
  • หลีกเลี่ยงการประกาศชนิดตัวแปรประเภท dynamic โดยไม่จำเป็น
  • การตั้งชื่อ: คลาสใช้ PascalCase (เช่น GroupPetController), ฟังก์ชันและตัวแปรใช้ camelCase (เช่น updateMochiHappiness), ชื่อไฟล์ใช้ snake_case (เช่น bill_detail_screen.dart)

2. นโยบายการแตกสาขา Git (Git Branch Strategy)

ใช้โมเดลสลับประสานกิ่งรหัสแบบย่อเพื่อให้คล่องตัวในการจัดส่งระบบ:

• กิ่ง main: กิ่งหลักเก็บบันทึกซอร์สโค้ดรุ่นที่ใช้งานได้จริงบนโปรดักชัน (Production) ทุกการรวมประวัติเข้ากิ่งนี้ต้องมีการระบุรุ่น เช่น v1.0.0
• กิ่งฟีเจอร์ (feature/<name>): แตกออกจาก main เพื่อพัฒนาฟังก์ชันย่อยรายชิ้น หรืองานแก้บั๊กทั่วไป (เช่น feature/fcm-notifications)
• กิ่งร้อนแก้บั๊กโปรดักชัน (hotfix/<name>): แตกตรงจาก main เพื่อแก้ปัญหาฉุกเฉินร้ายแรงทางการเงินทันทีและควบรวมกลับเข้า main ทันทีหลังยืนยันเสร็จ

3. มาตรฐานข้อความคำอธิบายประวัติรวมประวัติ (Commit Message Convention)

บังคับรูปแบบกติกา Conventional Commits เพื่อความเป็นระเบียบเรียบร้อยใน Git History:

• ประเภทหัวเรื่อง (Commit Types):
  • feat: ฟีเจอร์ตัวใหม่ (เช่น feat(auth): add JWT token rotation)
  • fix: แก้ไขบั๊กทางเทคนิค (เช่น fix(slip): prevent duplicate transaction upload)
  • docs: ปรับแต่งเอกสารอย่างเดียว (เช่น docs(security): specify CORS setup)
  • refactor: แก้ไขจัดระเบียบโครงสร้างโค้ดภายในโดยไม่เพิ่มฟังก์ชันย่อยหรือแก้บั๊ก (เช่น การดึงคลาส Interface โดเมน)
  • test: การจัดการเพิ่มหรือแก้ไขโค้ดทดสอบ Unit test/Integration test

---

🇬🇧 English (For AI Agents)

1. Coding Standards

• Python (Backend - FastAPI):
  • Follow PEP 8 style guidelines.
  • Formatter: black with a maximum line length of 88 characters.
  • Linter: ruff or flake8 and isort for import sorting.
  • Type Annotations: Mandatory for all parameters and return types.
  • Naming: Classes (PascalCase), Functions/Variables (snake_case), Modules (snake_case), Constants (UPPER_SNAKE_CASE).
• Dart (Frontend - Flutter):
  • Follow official Dart Style Guide.
  • Formatter: dart format.
  • Linter: flutter_lints with strict rules in analysis_options.yaml.
  • Type Safety: Avoid dynamic type declarations.
  • Naming: Classes (PascalCase), Functions/Variables (camelCase), Files (snake_case).

2. Git Branch Strategy

• main: Production-ready code. Tagged with releases (e.g. v1.0.0).
• Feature Branches (feature/<name>): Short-lived branches for features, bug fixes, or docs.
• Hotfix Branches (hotfix/<name>): Dispatched from main to address critical production issues and merged back to main.

3. Commit Message Convention

• Format: <type>(<scope>): <description>
• Types:
  • feat: A new feature (e.g., feat(auth): add JWT token rotation).
  • fix: A bug fix (e.g., fix(slip): prevent duplicate transaction upload).
  • docs: Documentation changes only.
  • style: Visual formatting changes that do not affect code semantics.
  • refactor: Structural code improvements without behavioral changes.
  • test: Adding or correcting tests.
  • chore: Modifying build scripts, tools, or dependencies.

4. Release Process

1. Feature Merge: Merge PRs into main after passing linters, tests, and coverage gates.
2. Version Bump & Tagging: Update versions in package configs and create a signed git tag.
3. Deployment: CI triggers on tag detection, builds production images, and runs server deploy.sh.
4. Post-Release Verification: Validate health endpoints and monitor errors on Sentry.