Source code

1. Tổng quan

Hệ thống Admin Banner gồm 2 thành phần chính:

Backend (Laravel): cung cấp API, xử lý nghiệp vụ, quản lý dữ liệu, phân quyền, xử lý banner/domain/campaign.

Frontend (Vue 3 + Vite): giao diện quản trị cho admin thao tác với hệ thống thông qua API backend.

Luồng tổng thể:

Frontend (Vue) → gọi API → Backend (Laravel) → xử lý → Database / Service ngoài → trả JSON → render UI

2. Quy ước branch

Hệ thống hiện sử dụng quy ước branch chính như sau:

dev: sử dụng branch develop

production: sử dụng branch production

Mục đích sử dụng

Branch develop dùng cho quá trình phát triển, kiểm thử nội bộ và xác nhận tính năng trước khi phát hành.

Branch production dùng cho mã nguồn triển khai chính thức ở môi trường production.

Lưu ý

Các thay đổi tính năng mới, fix bug hoặc refactor nên được thực hiện từ branch làm việc riêng, sau đó merge vào develop.

Chỉ các phiên bản đã được kiểm thử và xác nhận ổn định mới được merge từ develop lên production.

3. Backend source structure (Laravel)

thscore-api-admin/
├── app/                                       # Core business logic của hệ thống
│   ├── Http/
│   │   ├── Controllers/                       # Xử lý request/response API
│   │   ├── Middleware/                        # Auth, permission, logging
│   │   ├── Requests/                          # Validate input
│   │   └── Resources/                         # Format response API
│   ├── Models/                                # Entity mapping với database
│   │   ├── Domain.php                         # Domain/project
│   │   ├── DomainBanner.php                   # Banner theo domain
│   │   ├── BannerTemplate.php                 # Template banner
│   │   ├── BannerImage.php                    # Ảnh banner
│   │   ├── Company.php                        # Company quảng cáo
│   │   ├── User.php                           # Người dùng
│   │   ├── Role.php / RoleGroup.php           # Phân quyền
│   │   ├── SeoContent.php                     # Nội dung SEO
│   │   ├── LicenseKey.php                     # License/domain
│   │   ├── WhitelistRequest.php               # Whitelist domain
│   │   └── Zone.php                           # Zone hiển thị banner
│   ├── Services/                              # Business logic chính
│   │   ├── DomainService.php                  # Xử lý domain/project
│   │   ├── DomainBannerService.php            # Publish banner
│   │   ├── BannerTemplateService.php          # Template banner
│   │   ├── AuthService.php                    # Xác thực
│   │   ├── UserService.php                    # Người dùng
│   │   ├── UploadService.php                  # Upload file/banner
│   │   ├── S3UploadService.php                # Upload lên S3
│   │   ├── DBApiService.php                   # Kết nối API DB ngoài
│   │   ├── LiveSitesRemoteService.php         # Sync site ngoài
│   │   ├── TelegramNotifier.php               # Gửi thông báo Telegram
│   │   └── ...                                # Các service nghiệp vụ khác
│   ├── Repositories/                          # Tầng truy xuất dữ liệu (DB)
│   │   ├── DomainRepo.php
│   │   ├── DomainBannerRepo.php
│   │   ├── UserRepo.php
│   │   └── ...
│   ├── Jobs/                                  # Queue job bất đồng bộ
│   │   ├── PublishDomainBannerJob.php         # Publish banner async
│   │   ├── ProcessMassUpload.php              # Upload hàng loạt
│   │   └── CheckWhitelistDomainJob.php        # Check whitelist
│   ├── Events/                                # Event hệ thống
│   │   ├── LicenseApprovedEvent.php
│   │   └── LicenseRejectedEvent.php
│   ├── Listeners/                             # Lắng nghe event
│   │   ├── SendLicenseApprovedEmail.php
│   │   ├── SendLicenseApprovedTelegram.php
│   │   └── ...
│   ├── Mail/                                  # Template email
│   ├── Helpers/                               # Helper function
│   └── Providers/                             # Service provider Laravel
├── routes/
│   ├── api.php                                # API chính cho frontend
│   └── web.php                                # Route web nếu có
├── database/
│   ├── migrations/                            # Cấu trúc DB
│   ├── seeders/                               # Seed dữ liệu
│   └── factories/                             # Factory test
├── config/                                    # Cấu hình hệ thống
│   ├── database.php
│   ├── jwt.php
│   ├── queue.php
│   ├── services.php
│   └── ...
├── public/                                    # Entry public
│   └── index.php
├── resources/                                 # View/email/template
├── docker/                                    # Docker config
├── composer.json                              # Dependency PHP
├── artisan                                    # CLI Laravel
└── vite.config.js                             # Build frontend (nếu dùng chung)

4. Frontend source structure (Vue 3 + Vite)

thscore-client-admin/
├── src/                                       # Source chính của frontend
│   ├── App.vue                                # Root component
│   ├── main.ts                                # Entry point
│   ├── assets/                                # Ảnh, CSS
│   ├── components/                            # Component dùng chung
│   │   ├── common/
│   │   ├── header/
│   │   ├── block/
│   │   └── icon/
│   ├── composables/                           # Logic tái sử dụng (Composition API)
│   │   ├── auth.ts
│   │   ├── i18n.ts
│   │   ├── router.ts
│   │   └── utils.ts
│   ├── configs/                               # Cấu hình hệ thống
│   │   ├── axios.ts                           # Base API config
│   │   ├── axios-db-api.ts                    # API DB
│   │   ├── axios-sport.ts                     # API sport
│   │   ├── axios-traffic.ts                   # API traffic
│   │   └── theme.ts
│   ├── layouts/                               # Layout UI
│   │   └── LayoutDefault.vue
│   ├── router/                                # Vue Router
│   │   ├── index.ts
│   │   └── modules/                           # Route theo module
│   ├── services/
│   │   └── api/                               # Hàm gọi API backend
│   ├── stores/                                # State (Pinia)
│   │   ├── authStore.ts
│   │   ├── appStore.ts
│   │   └── ...
│   ├── types/                                 # TypeScript type
│   ├── utils/                                 # Helper function
│   └── views/                                 # Màn hình nghiệp vụ
│       ├── banner/                            # Quản lý banner
│       ├── project/                           # Quản lý domain/project
│       ├── users/                             # Quản lý user
│       ├── white-list/                        # Whitelist domain
│       ├── traffic-report/                    # Báo cáo traffic
│       ├── tool/                              # Tools
│       ├── theme-plugin/                      # Theme/plugin
│       ├── tip/                               # Tip system
│       └── ...
├── public/                                    # Static file
│   ├── csv/                                   # File mẫu import
│   └── runtime.config.js                      # Config runtime
├── locales/                                   # i18n
│   ├── en-US.json
│   └── vi-VN.json
├── package.json                               # Dependency FE
├── vite.config.ts                             # Config build
├── tailwind.config.ts                         # TailwindCSS
├── Dockerfile                                 # Build container
└── nginx.conf                                 # Serve frontend

5. Mapping Frontend ↔ Backend

Frontend (views)	Backend (Model/Service)	Mô tả
banner	DomainBanner, BannerTemplate	Quản lý banner
project	Domain	Quản lý domain
users	User, Role	Quản lý user
white-list	WhitelistRequest	Domain whitelist
traffic-report	UserTrafficDomain	Tracking traffic
theme-plugin	WpSite, WpComponent	Plugin/theme
tip	ContentCreatorService	Nội dung tip
tool	Various services	Công cụ nội bộ

6. File cấu hình quan trọng

Backend

.env: DB, JWT, queue, service ngoài

config/*.php: cấu hình hệ thống

routes/api.php: entry API chính

composer.json: dependency

Frontend

.env: base API URL

configs/axios*.ts: cấu hình nhiều nguồn API

router/modules: phân quyền + route

stores/authStore.ts: trạng thái login

public/runtime.config.js: runtime config

7. Lưu ý kỹ thuật

Backend sử dụng:

Laravel 11

JWT auth

Queue (job async)

S3 upload

Telegram notification

Frontend sử dụng:

Vue 3 + Composition API

Pinia (state)

Vue Router (module-based)

Vite (build tool)

TailwindCSS

8. Nhận xét kiến trúc

Backend tách rõ:

Controller → Service → Repository → Model

Có sử dụng:

Event + Listener

Queue job

Frontend tổ chức theo:

module (views)

service API

store state

=> Kiến trúc phù hợp cho hệ thống admin quy mô lớn, dễ mở rộng.

Source Code

Source code#

1. Tổng quan#

2. Quy ước branch#

Mục đích sử dụng#

Lưu ý#

3. Backend source structure (Laravel)#

4. Frontend source structure (Vue 3 + Vite)#

5. Mapping Frontend ↔ Backend#

6. File cấu hình quan trọng#

Backend#

Frontend#

7. Lưu ý kỹ thuật#

8. Nhận xét kiến trúc#