🏗️ KIẾN TRÚC BACKEND MODULAR TOÀN TẬP: TIÊU CHUẨN PHÂN TÁCH 5 TẦNG VÀ NGUYÊN TẮC NO RANDOM PATTERNS¶

========================================================================================================
                      HẬU QUẢ TAI HẠI CỦA SPAGHETTI / MONOLITHIC SCRIPTS
========================================================================================================
1. LỖI DÂY CHUYỀN (RIPPLE EFFECT):
   • Sửa logic thanh toán của Module A lại vô tình làm gãy tính năng xuất báo cáo của Module B.
2. KHÔNG THỂ VIẾT UNIT TEST:
   • Logic nghiệp vụ dính chặt với HTTP Request và Session của trình duyệt, không thể mock dữ liệu.
3. DEADLOCK CƠ SỞ DỮ LIỆU:
   • Các câu truy vấn rải rác không nằm trong Database Transaction chuẩn chỉnh, gây khóa bảng hàng loạt.
4. NỢ KỸ THUẬT (TECHNICAL DEBT) KHỦNG KHIẾP:
   • Khi một lập trình viên mới vào dự án, mất hàng tuần để đọc hiểu và không ai dám đụng vào code cũ.
========================================================================================================

========================================================================================================
                               SƠ ĐỒ PHÂN TÁCH 5 TẦNG TRONG MỘT MODULE
========================================================================================================

    [HTTP REQUEST TỪ CLIENT]
                │
                ▼
  ┌───────────────────────────┐
  │ TẦNG 1: ROUTE & ENDPOINT  │ -> Định tuyến URL, middleware xác thực (Auth, CSRF, Role)
  └─────────────┬─────────────┘
                ▼
  ┌───────────────────────────┐
  │ TẦNG 2: REQUEST / SCHEMA  │ -> Validate dữ liệu đầu vào (Type, Exists, Min, Max, Regex)
  └─────────────┬─────────────┘    Dừng ngay lập tức nếu dữ liệu rác, không cho lọt vào Controller!
                ▼
  ┌───────────────────────────┐
  │ TẦNG 3: CONTROLLER        │ -> Tầng điều phối mỏng (Thin Controller).
  └─────────────┬─────────────┘    Chỉ nhận Input hợp lệ -> Gọi Service -> Trả về JSON hoặc View.
                ▼
  ┌───────────────────────────┐
  │ TẦNG 4: SERVICE           │ -> TẦNG TRÍ TUỆ CỐT LÕI (Business Logic).
  └─────────────┬─────────────┘    Tính toán số buổi, cấn trừ, snapshot, gửi thông báo, kiểm tra trùng ca.
                ▼                  Bao bọc trong DB::transaction để bảo toàn dữ liệu.
  ┌───────────────────────────┐
  │ TẦNG 5: MODEL / REPOSITORY│ -> Tầng tương tác CSDL (Data Access).
  └───────────────────────────┘    Định nghĩa quan hệ (Relationships), Scopes, Casts, Query Builder.
========================================================================================================

+---+-------------------------------------------+-------------------------------------------------------------+
| # | HÀNH VI CẤM KỴ (ANTI-PATTERNS)            | TẠI SAO BỊ CẤM & QUY CHUẨN THAY THẾ                         |
+---+-------------------------------------------+-------------------------------------------------------------+
| 1 | Fat Controller (Controller nghìn dòng)    | Controller chỉ được phép đóng vai trò "người gác cổng".     |
|   |                                           | Mọi logic từ 5 dòng code nghiệp vụ trở lên PHẢI vào Service.|
+---+-------------------------------------------+-------------------------------------------------------------+
| 2 | Truy vấn DB trong View/Blade Template     | CẤM gọi `App\Models\User::all()` hoặc chạy query trong view.|
|   |                                           | Toàn bộ dữ liệu hiển thị phải do Controller/Service nạp sẵn.|
+---+-------------------------------------------+-------------------------------------------------------------+
| 3 | Raw Query tùy tiện bỏ qua Transaction     | Khi ghi nhiều bảng liên quan (Session + Students + Lessons) |
|   |                                           | BẮT BUỘC dùng `DB::transaction(function() { ... })`.        |
+---+-------------------------------------------+-------------------------------------------------------------+
| 4 | Validate thủ công bằng if-else lung tung  | Validate phải nằm ở FormRequest (Laravel) hoặc Pydantic     |
|   |                                           | Schema (Python) để tái sử dụng và chuẩn hóa thông báo lỗi.  |
+---+-------------------------------------------+-------------------------------------------------------------+
| 5 | Cross-Module Database Hijack              | Module A KHÔNG ĐƯỢC tự ý cập nhật ngầm bảng của Module B    |
|   | (Tùy tiện chọc vào bảng phân hệ khác)     | mà phải thông qua Service/Method công khai của Module B.    |
+---+-------------------------------------------+-------------------------------------------------------------+
| 6 | Trộn lẫn Response HTML và JSON bừa bãi    | Phân tách rõ ràng route Web (trả View Blade) và route API   |
|   |                                           | (trả chuẩn JSON { success: true, data: ... }).              |
+---+-------------------------------------------+-------------------------------------------------------------+

app/
├── Core/                               # Các thành phần dùng chung toàn hệ thống
│   ├── Exceptions/                     # Exception nghiệp vụ (TeachingSessionDuplicateException...)
│   ├── Support/                        # Helper utils, formatters, date handlers
│   └── Traits/                         # Reusable traits
│
└── Modules/                            # TẤT CẢ CÁC PHÂN HỆ NẰM ĐỘC LẬP TẠI ĐÂY
    │
    ├── TeachingSession/                # MODULE 1: QUẢN LÝ BUỔI DẠY
    │   ├── Controllers/                # Controller chuyên trách cho phân hệ
    │   │   ├── TeachingSessionController.php
    │   │   └── TeachingSessionReportController.php
    │   ├── Requests/                   # Tầng Request Validation
    │   │   ├── StoreTeachingSessionRequest.php
    │   │   └── UpdateTeachingSessionRequest.php
    │   ├── Services/                   # Tầng Trí tuệ Nghiệp vụ (Business Logic)
    │   │   ├── TeachingSessionService.php
    │   │   └── TeachingSessionReportService.php
    │   └── Models/ (hoặc dùng App\Models)
    │
    ├── StudentEnrollment/              # MODULE 2: GÓI HỌC & CẤN TRỪ BUỔI
    │   ├── Controllers/
    │   │   └── StudentEnrollmentController.php
    │   ├── Requests/
    │   │   ├── StoreEnrollmentRequest.php
    │   │   └── TransferSessionRequest.php
    │   └── Services/
    │       ├── StudentEnrollmentService.php
    │       └── SessionTransferService.php
    │
    └── TeacherPayroll/                 # MODULE 3: TÍNH LƯƠNG GIÁO VIÊN
        ├── Controllers/
        ├── Requests/
        └── Services/
            └── PayrollCalculatorService.php

namespace App\Modules\TeachingSession\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreTeachingSessionRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            "teacher_id" => ["required", "integer", "exists:teachers,id"],
            "subject_id" => ["required", "integer", "exists:subjects,id"],
            "student_ids" => ["required", "array", "min:1"],
            "student_ids.*" => ["integer", "distinct", "exists:students,id"],
            "started_at" => ["nullable", "date"],
        ];
    }
}

namespace App\Http\Controllers\Admin;

use App\Http\Controllers\Controller;
use App\Modules\TeachingSession\Requests\StoreTeachingSessionRequest;
use App\Modules\TeachingSession\Services\TeachingSessionService;
use Illuminate\Http\RedirectResponse;

class TeachingSessionController extends Controller
{
    public function store(
        StoreTeachingSessionRequest $request,
        TeachingSessionService $service
    ): RedirectResponse {
        // Controller KHÔNG chứa bất kỳ logic tính toán hay câu lệnh SQL nào!
        $result = $service->create(
            $request->validated(),
            auth("admin")->id(),
            auth("manager")->id()
        );

        return redirect()
            ->back()
            ->with("status", "Đã lưu thành công buổi dạy của: " . $result["teacher"]->name);
    }
}

namespace App\Modules\TeachingSession\Services;

use App\Models\TeachingSession;
use App\Models\TeachingSessionStudent;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Carbon;

class TeachingSessionService
{
    public function create(array $data, ?int $adminId = null, ?int $managerId = null): array
    {
        // Toàn bộ logic phức tạp được bảo vệ trong Database Transaction
        return DB::transaction(function () use ($data, $adminId, $managerId) {
            $session = TeachingSession::create([
                "teacher_id" => $data["teacher_id"],
                "subject_id" => $data["subject_id"],
                "started_at" => Carbon::parse($data["started_at"] ?? now()),
                "created_by_admin_id" => $adminId,
                "created_by_manager_id" => $managerId,
            ]);

            foreach ($data["student_ids"] as $studentId) {
                TeachingSessionStudent::create([
                    "teaching_session_id" => $session->id,
                    "student_id" => $studentId,
                    "subject_id" => $data["subject_id"],
                ]);
            }

            return ["session" => $session, "teacher" => $session->teacher];
        });
    }
}

api/
├── main.py                             # Khởi tạo App & Mount Routers
└── modules/
    └── session_transfer/
        ├── schemas.py                  # Pydantic Schemas (Request/Response)
        ├── router.py                   # API Routes (Endpoints)
        ├── service.py                  # Business Logic Service
        └── repository.py               # Database Query / Storage Engine

from pydantic import BaseModel, Field
from datetime import date

class SessionTransferRequest(BaseModel):
    from_student_id: int = Field(..., gt=0)
    to_student_id: int = Field(..., gt=0)
    sessions_count: int = Field(..., gt=0, le=100)
    transfer_date: date
    reason: str = Field(..., min_length=5, max_length=500)

class SessionTransferService:
    def __init__(self, db_session):
        self.db = db_session

    def execute_transfer(self, req: SessionTransferRequest, actor_id: int):
        with self.db.begin():
            # 1. Kiểm tra số buổi khả dụng của học viên nguồn
            source_balance = self._get_balance(req.from_student_id)
            if source_balance < req.sessions_count:
                raise ValueError("Số buổi khả dụng không đủ để cấn trừ!")

            # 2. Tạo bản ghi giao dịch cấn trừ
            transfer_record = self._create_audit_record(req, actor_id)

            # 3. Điều chỉnh số buổi gói học
            self._apply_balance_changes(req)

            return {"success": True, "transfer_id": transfer_record.id}

# 1. Controller này có dài quá 200 dòng không?
#    -> Nếu có, lập tức bóc tách bớt logic sang Service Layer.

# 2. Có bất kỳ câu lệnh SQL raw hoặc truy vấn bảng khác trong View/Template không?
#    -> Nếu có, bắt buộc chuyển về Controller/Service.

# 3. Tất cả các thao tác ghi từ 2 bảng trở lên có được bọc trong DB::transaction chưa?
#    -> Bắt buộc phải có để chống rách nát dữ liệu khi gặp sự cố mạng hoặc lỗi runtime.

# 4. Đầu vào Request đã có lớp FormRequest / Pydantic Schema kiểm định chưa?
#    -> Tuyệt đối không đọc trực tiếp $request->all() mà không validate rules.

# 5. Các module có tôn trọng ranh giới của nhau không?
#    -> Không module nào được tự tiện viết lệnh INSERT/UPDATE trực tiếp vào bảng của module khác.