ReadMe_v2.md.archive

# **Backend Project Structure**

## **1. Cấu trúc thư mục**

```
Backend/
│── .env
│── go.mod
│── go.sum
│── match.json
│── postman.json
│── cmd/
│   └── main.go
│── internal/
│   ├── api/
│   │   ├── handlers/
│   │   │   ├── admin_handler.go
│   │   │   ├── forgot_password_handler.go
│   │   │   ├── login_otp_handler.go
│   │   │   ├── match_handler.go
│   │   │   ├── media_handler.go
│   │   │   ├── profile_handler.go
│   │   │   ├── user_handler.go
│   │   │   ├── user_service_ext.go
│   │   ├── middleware/
│   │   │   ├── admin_only.go
│   │   │   ├── auth.go
│   │   │   ├── ensure_profile.go
│   │   │   ├── rate_limit.go
│   │   │   ├── RoleMiddleware.go
│   │   ├── routes/
│   │   │   ├── admin_routes.go
│   │   │   ├── auth_routes.go
│   │   │   ├── match_routes.go
│   │   │   ├── media_routes.go
│   │   │   ├── profile_routes.go
│   │   │   ├── user_routes.go
│   ├── config/
│   │   ├── cloud_config.go
│   │   ├── config.go
│   │   ├── database.go
│   │   ├── role_config.go
│   │   ├── seed_user.go
│   ├── data/
│   │   ├── compatibility_loader.go
│   │   ├── mbti_compatibility.json
│   │   ├── zodiac_compatibility.json
│   ├── dto/
│   │   ├── profile_dto.go
│   ├── models/
│   │   ├── match.go
│   │   ├── otp.go
│   │   ├── profile.go
│   │   ├── profile_career.go
│   │   ├── profile_insights.go
│   │   ├── profile_media.go
│   │   ├── user.go
│   ├── repositories/
│   │   ├── match_repository.go
│   │   ├── otp_repository.go
│   │   ├── profile_career_repository.go
│   │   ├── profile_insights_repository.go
│   │   ├── profile_media_repository.go
│   │   ├── profile_repository.go
│   │   ├── user_repository.go
│   ├── services/
│   │   ├── auth_service.go
│   │   ├── email_service.go
│   │   ├── match_service.go
│   │   ├── media_service.go
│   │   ├── otp_service.go
│   │   ├── profile_service.go
│   │   ├── user_service.go
│   ├── utils/
│   │   ├── utils.go
```

## **2. Mô tả chi tiết từng thư mục**

### **📌 cmd/**

- `main.go`: Điểm khởi đầu của ứng dụng, thực hiện các công việc:
  - Load cấu hình từ `.env`.
  - Kết nối database.
  - Khởi tạo router và middleware.
  - Chạy server.

### **📌 internal/api/**

#### **📂 handlers/** (Xử lý API)

- `admin_handler.go`: Xử lý các chức năng quản trị.
- `forgot_password_handler.go`: Quản lý việc quên mật khẩu.
- `login_otp_handler.go`: Xử lý xác thực bằng OTP.
- `match_handler.go`: Xử lý thao tác liên quan đến hệ thống ghép cặp.
- `media_handler.go`: Quản lý tải lên/xử lý tệp phương tiện.
- `profile_handler.go`: Quản lý hồ sơ người dùng.
- `user_handler.go`: Xử lý thông tin người dùng.
- `user_service_ext.go`: Mở rộng các dịch vụ liên quan đến user.

#### **📂 middleware/** (Xác thực và bảo mật)

- `admin_only.go`: Chặn truy cập nếu không phải admin.
- `auth.go`: Xác thực JWT token.
- `ensure_profile.go`: Kiểm tra xem user có hồ sơ hợp lệ không.
- `rate_limit.go`: Kiểm soát tần suất request API.
- `RoleMiddleware.go`: Kiểm tra quyền của người dùng.

#### **📂 routes/** (Định nghĩa endpoint API)

- `admin_routes.go`: API quản trị viên.
- `auth_routes.go`: API xác thực.
- `match_routes.go`: API ghép cặp.
- `media_routes.go`: API quản lý file media.
- `profile_routes.go`: API hồ sơ người dùng.
- `user_routes.go`: API người dùng.

### **📌 internal/data/** (Mới thêm vào)

#### **compatibility_loader.go**

- File này chứa các phương thức hỗ trợ việc tải và xử lý dữ liệu từ các file JSON về **tương thích MBTI** và **cung hoàng đạo**.
- Có thể sử dụng để đọc, parse và cung cấp dữ liệu tương thích cho hệ thống matching.

#### **mbti_compatibility.json**

- File JSON chứa thông tin về **mức độ tương thích giữa các loại tính cách MBTI**.
- Được sử dụng để hỗ trợ thuật toán ghép đôi dựa trên đặc điểm tính cách của người dùng.
- Mỗi cặp MBTI sẽ có một **chỉ số tương thích** giúp đánh giá mức độ phù hợp.

#### **zodiac_compatibility.json**

- File JSON chứa **bảng tương thích giữa các cung hoàng đạo**.
- Hỗ trợ thuật toán matching bằng cách đánh giá mức độ hợp nhau của hai người dựa trên cung hoàng đạo của họ.

Dữ liệu từ các file JSON này có thể được sử dụng để tính toán mức độ phù hợp giữa người dùng trong hệ thống ghép cặp (matching).

# 🧠 Design Pattern & Kiến trúc

## ✅ Clean Architecture

- Project chia tách chuẩn theo tầng:
  - `cmd/main.go`: entrypoint
  - `internal/api/handlers`: nhận request HTTP
  - `internal/services`: xử lý nghiệp vụ
  - `internal/repositories`: truy vấn MongoDB
  - `internal/models`: struct cơ sở
  - `internal/data`: lưu cấu hình MBTI/Zodiac
  - `internal/config`: đọc config & env
- Dữ liệu được merge tại tầng service, không phụ thuộc FE phải gọi nhiều API.

---

# 🧠 Design Patterns – Dự án Lufian Backend

Tài liệu tổng hợp các pattern đã và đang được áp dụng trong backend của Lufian. Chia làm 3 nhóm chính: **Creational**, **Structural**, **Behavioral**.

---

## ✅ Tổng kết

| Nhóm       | Pattern được dùng                                                      |
| ---------- | ---------------------------------------------------------------------- |
| Creational | Singleton, Factory, Dependency Injection                               |
| Structural | Interface Abstraction                                                  |
| Behavioral | Service Layer, Repository, Strategy, Observer, Chain of Responsibility |

## Tổng cộng **9 Pattern** đang hoạt động rõ ràng, đúng chuẩn Clean Architecture cho backend Golang.

---

## 🏗️ Creational Patterns

### ✅ 1. Singleton Pattern

- 🔁 **Luồng**: MongoDB, Cloudinary, Config... được khởi tạo duy nhất 1 lần trong `main.go` → dùng lại toàn hệ thống.
- 🎯 **Mục đích**:
  - Tránh khởi tạo lại nhiều lần
  - Giữ trạng thái toàn cục (kết nối DB, config)
- 📦 **Trong code**: `config.InitMongo()`, `InitCloudinary()` trong `config/mongo.go`, `config/cloudinary.go`

---

### ✅ 2. Factory Function

- 🔁 **Luồng**: Dùng hàm `NewX()` để tạo handler/service với params cần thiết.
- 🎯 **Mục đích**:
  - Tách khởi tạo khỏi nơi sử dụng
  - Dễ inject dependency theo ngữ cảnh
- 📦 **Trong code**: `NewUserService(userRepo)`, `NewMatchHandler(matchService)`

---

### ✅ 3. Dependency Injection

- 🔁 **Luồng**:
  - `main.go` tạo repo → inject vào service → inject vào handler → khai báo trong `routes`
- 🎯 **Mục đích**:
  - Dễ test (mock được)
  - Dễ mở rộng logic
- 📦 **Trong code**: `routes/user_routes.go`, `routes/auth_routes.go`

---

## 🧱 Structural Patterns

### ✅ Interface Abstraction

- 🔁 **Luồng**: Mỗi `repo`/`service` đều khai báo `interface` riêng → các handler chỉ gọi qua interface.
- 🎯 **Mục đích**:
  - Dễ mock khi viết unit test
  - Dễ thay đổi implementation
- 📦 **Trong code**: `UserRepository interface`, `MatchService interface`

---

## 🔁 Behavioral Patterns

### ✅ Service Layer

- 🔁 **Luồng**:
  - Handler nhận request → gọi service xử lý nghiệp vụ → gọi repo nếu cần
- 🎯 **Mục đích**:
  - Phân tách rõ logic & HTTP
  - Tái sử dụng logic dễ hơn
- 📦 **Trong code**: `services/user_service.go`, `services/match_service.go`

---

### ✅ Repository Pattern

- 🔁 **Luồng**: Mỗi module có 1 repository riêng để truy vấn DB → service không gọi DB trực tiếp.
- 🎯 **Mục đích**:
  - Clean & testable
  - Dễ thay đổi DB sau này
- 📦 **Trong code**: `repositories/user_repository.go`, `match_repository.go`

---

### ✅ Strategy Pattern (Login)

- 🔁 **Luồng**: 2 chiến lược đăng nhập: `password` và `otp` được chia riêng controller/handler.
- 🎯 **Mục đích**:
  - Dễ mở rộng thêm Google, Facebook, Apple...
- 📦 **Trong code**: `handlers/auth/login_handler.go`, `login_otp_handler.go`

---

### ✅ Observer Pattern (WebSocket)

- 🔁 **Luồng**: Dùng `hub map[userID]conn` để push real-time dữ liệu qua WebSocket
- 🎯 **Mục đích**:
  - Push thông báo real-time: match, message, v.v.
- 📦 **Trong code**: `scheduler/hub.go`, `scheduler/ws_handler.go`

---

### ✅ Chain of Responsibility (Middleware)

- 🔁 **Luồng**: Middleware chạy tuần tự theo chuỗi: `Auth` → `Role` → `EnsureProfile` → `RateLimit`
- 🎯 **Mục đích**:
  - Tách biệt rõ trách nhiệm từng bước
  - Dễ re-use/tắt từng middleware
- 📦 **Trong code**: `middleware/auth.go`, `role.go`, `ensure_profile.go`, `rate_limit.go`

---