Tài liệu Frontend - NewsLooks Theme

1. Tổng quan

Theme NewsLooks cung cấp các chức năng frontend cho website tin tức/blog, bao gồm hiển thị trang chủ, chi tiết bài viết, danh mục, tìm kiếm, bình luận, đăng ký newsletter, và nhiều tính năng khác.

2. Yêu cầu từ Thethaoso.online

Website tổng hợp tin tức thể thao trực tuyến với các chức năng:

Tin tức bóng đá trong nước và quốc tế

Tin chuyển nhượng, nhận định trận đấu

Lịch thi đấu, kết quả, bảng xếp hạng

Dữ liệu đội bóng, cầu thủ, HLV, giải đấu

Hệ thống cào dữ liệu và AI viết bài tự động

Tổng hợp nhận định và tips chuyên gia

Analytics và tracking user

Page builder kéo thả

Quản lý nội dung, người dùng, phân quyền

LƯU Ý PRODUCTION

Các data section, block của các page trên production sẽ được lưu data của chức năng page builder

Các chức năng sẽ có các trường quản lý nội dung

FIGMA: https://www.figma.com/design/rhAvJ0Thj70CNsHSsaShth/DEV---Trang-Tin-Tu%CC%9B%CC%81c-The%CC%82%CC%89-Thao?node-id=496-10026&m=dev

CÀI ĐẶT:

Import file database đã cung cấp

Clone source vào httdocs của xampp hoặc các server web

Install các module của laravel với composer install

Thay đổi đúng env

db dev: https://drive.google.com/file/d/1xldck1PKyUXQAELiaBqhW5FY2b8_8Ye4/view?usp=drive_link
db local: https://drive.google.com/file/d/1e48nd6l6WPHmnOv9dvXxSLJTEsYrvBiw/view?usp=sharing

ENV
`
APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:QpKADkaSFTP60qtQaOr6V0BWuEC/c+pTbPCXX+Nnbgo=
APP_DEBUG=true
APP_URL=http://localhost/newslooks

LOG_CHANNEL=stack
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=newslook
DB_USERNAME=root
DB_PASSWORD=root

BROADCAST_DRIVER=log
CACHE_DRIVER=file
FILESYSTEM_DISK=local
QUEUE_CONNECTION=database
SESSION_DRIVER=file
SESSION_LIFETIME=120

MEMCACHED_HOST=127.0.0.1

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=

MAILGUN_DOMAIN=
MAILGUN_SECRET=

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=
AWS_USE_PATH_STYLE_ENDPOINT=false

PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=
PUSHER_APP_CLUSTER=mt1

MIX_PUSHER_APP_KEY="

P U S H E R_{A} P P_{K} E Y " M I X_{P} U S H E R_{A} P P_{C} LU STER = "

{PUSHER_APP_CLUSTER}"

JWT_SECRET=

JWT_ALGO=HS256
APP_TIMEZONE=Asia/Dhaka

MAILCHIMP_APIKEY=
MAILCHIMP_LIST_ID=

APP_DEMO=false

IS_USER_REGISTERED=1
LICENSE_CHECKED=1
AWS_URL=
ANYTHING_AI_KEY=Y72P38Y-ZX7MNM4-Q1SCY84-B3SF5DS
ANYTHING_AI_URL=https://ai.nospace.network/api/v1/openai/chat/completions
ANYTHING_AI_MODEL=test-ai
MAIL_TO_ADDRESS=t.rap.dnh@gmail.com
`

3. AI Settings - Chi Tiết

3.1. Tổng quan

Trang quản lý cấu hình AI nằm tại Core/Views/base/blog/settings/ai_setting.blade.php và được điều khiển bởi AIAssistantController::AISetting().

Route: GET /ai-settings → core.blog.ai.setting

Table lưu trữ: open_ai_settings (1 row duy nhất)

3.2. Cấu trúc Fields trong `open_ai_settings`

Field	Type	Mô tả
`id`	bigint	Primary key
`default_model`	varchar(100)	Model OpenAI mặc định (gpt-4, gpt-3.5-turbo-instruct...)
`api_key`	text	OpenAI Secret Key (encrypted)
`enable_blog_ai_assistant`	tinyint	Bật/tắt AI Assistant (0/1)
`ai_job_interval_minutes`	int	Khoảng thời gian giữa các lần chạy AI job (default: 5 phút)
`ai_job_batch_size`	int	Số blog xử lý mỗi lần chạy (default: 1)
`ai_blog_status`	varchar(50)	Status blog sau khi AI xử lý (pending/publish/draft)
`use_custom_model`	tinyint	Bật sử dụng custom AI model thay vì OpenAI mặc định (0/1)
`custom_api_url`	text	URL API của custom AI provider
`custom_api_key`	text	API Key của custom AI provider
`custom_model`	varchar(255)	Tên model custom
`translate_model_name`	varchar(255)	Tên model dùng cho translate operation
`title_model_name`	varchar(255)	Tên model dùng cho title rewrite
`description_model_name`	varchar(255)	Tên model dùng cho description rewrite
`content_model_name`	varchar(255)	Tên model dùng cho content rewrite
`translate_workspace_chain`	varchar(500)	Danh sách model fallback cho translate (comma-separated)
`title_workspace_chain`	varchar(500)	Danh sách model fallback cho title (comma-separated)
`description_workspace_chain`	varchar(500)	Danh sách model fallback cho description (comma-separated)
`content_workspace_chain`	varchar(500)	Danh sách model fallback cho content (comma-separated)
`mattermost_enabled`	tinyint	Bật thông báo Mattermost (0/1)
`mattermost_server_url`	text	URL Mattermost server
`mattermost_bot_token`	text	Bot access token cho thông báo thành công
`mattermost_channel_id`	varchar(255)	Channel ID nhận thông báo thành công
`mattermost_error_server_url`	text	URL Mattermost server cho bot lỗi
`mattermost_error_bot_token`	text	Bot access token cho thông báo lỗi
`mattermost_error_channel_id`	varchar(255)	Channel ID nhận thông báo lỗi
`prompts`	longtext	JSON chứa custom prompts (định dạng mới: `{key: {system, user}}`)

3.3. Cấu hình các nhóm settings trong AI Settings Page

3.3.1. Enable AI Assistant

Toggle bật/tắt toàn bộ chức năng AI

Lưu vào getGeneralSetting('enable_blog_ai_assistant')

3.3.2. Default OpenAI Model

Field: default_model

Options: gpt-4, gpt-3.5-turbo-instruct, text-davinci-003, text-babbage-001, text-curie-001, text-ada-001

Model mặc định được sử dụng khi không cấu hình custom model

3.3.3. OpenAI Secret Key

Field: api_key

Input type: password

Lưu trữ OpenAI API key để gọi Chat Completions API

3.3.4. AI Job Settings (AI Job Configuration)

Cấu hình cách AI job tự động xử lý blog:

Field	DB Field	Default	Mô tả
AI Job Interval (minutes)	`ai_job_interval_minutes`	5	Khoảng thời gian giữa 2 lần chạy job
AI Job Batch Size	`ai_job_batch_size`	1	Số blog xử lý mỗi lần chạy
AI Blog Status After Update	`ai_blog_status`	pending	Status blog sau khi AI update

3.3.5. Custom AI Model Configuration

Khi bật use_custom_model = true, hệ thống ưu tiên dùng custom model thay vì OpenAI mặc định:

Field	DB Field	Mô tả	Ví dụ
Use Custom Model	`use_custom_model`	Toggle bật/tắt	-
Custom API URL	`custom_api_url`	URL API endpoint (OpenAI-compatible)	`https://api.example.com/v1/chat/completions`
Custom API Key	`custom_api_key`	API key của custom provider	-
Custom Model Name	`custom_model`	Tên model	`gpt-4`, `llama-2-7b`, `mistral-7b`

Workspace Model Names (sử dụng chung API URL/Key của custom model):

Field	DB Field	Mô tả
Translate Model Name	`translate_model_name`	Model cho operation dịch
Title Model Name	`title_model_name`	Model cho viết lại title
Description Model Name	`description_model_name`	Model cho viết lại description
Content Model Name	`content_model_name`	Model cho viết lại content

Retry Chain (Workspace Retry Chains - fallback models):

Field	DB Field	Mô tả
Translate Workspace Retry Chain	`translate_workspace_chain`	Model fallback cho translate (comma-separated)
Title Workspace Retry Chain	`title_workspace_chain`	Model fallback cho title
Description Workspace Retry Chain	`description_workspace_chain`	Model fallback cho description
Content Workspace Chain	`content_workspace_chain`	Model fallback cho content

3.3.6. Mattermost Integration

Cấu hình gửi thông báo qua Mattermost khi AI update blog:

Success Bot:

Field	DB Field	Mô tả
Enable Mattermost	`mattermost_enabled`	Toggle bật/tắt
Mattermost Server URL	`mattermost_server_url`	URL Mattermost server
Bot Access Token	`mattermost_bot_token`	Bot token
Channel ID	`mattermost_channel_id`	Channel nhận thông báo

Error Bot (Bot riêng cho lỗi):

Field	DB Field	Mô tả
Error Bot Server URL	`mattermost_error_server_url`	URL Mattermost server lỗi
Error Bot Token	`mattermost_error_bot_token`	Bot token lỗi
Error Channel ID	`mattermost_error_channel_id`	Channel nhận lỗi

3.3.7. AI Prompts Management

Cấu hình custom prompts cho 4 loại operation, lưu trong field prompts (JSON format):

Format:

{
  "title_and_description_rewrite": {
    "system": "System role prompt...",
    "user": "User prompt với placeholders..."
  },
  "content_rewrite": {
    "system": "...",
    "user": "..."
  },
  "title_rewrite": {
    "system": "...",
    "user": "..."
  },
  "description_rewrite": {
    "system": "...",
    "user": "..."
  }
}

Prompt Key	Operation	Placeholders	Mô tả
`title_and_description_rewrite`	Viết lại title + description	`{blog_title}`, `{short_details}`	Rewrite cả title và short description cùng lúc
`content_rewrite`	Viết lại nội dung HTML	`{blog_content}`	Dịch + viết lại nội dung blog
`title_rewrite`	Viết lại title	`{blog_title}`	Chỉ viết lại title
`description_rewrite`	Viết lại description	`{short_details}`	Chỉ viết lại short description

Mỗi prompt có 2 phần:

System Role: Định nghĩa vai trò AI (role + context)

User Prompt: Prompt chính với placeholders được thay thế tự động

3.4. AIAssistantController - Chi tiết Methods

File: Core/Http/Controllers/AIAssistantController.php (3753+ lines)

3.4.1. Constructor

Load open_ai_settings từ database

Khởi tạo api_key, default_model, ai_settings

Áp dụng middleware themelooks + license

3.4.2. AI Settings Management

Method	Route	Mô tả
`AISetting()`	GET `/ai-settings`	Hiển thị trang AI Settings
`updateAISetting(Request)`	POST `/ai-settings-update`	Lưu cấu hình AI settings

3.4.3. AI Content Generation (Frontend)

Method	Route	Mô tả
`generateContent(Request)`	POST `/generate-content-with-ai`	Tạo nội dung mới với AI
`generateUpdateContent(Request)`	PUT `/generate-content-with-ai`	Cập nhật nội dung blog với AI

3.4.4. AI Crawl/Update System (Backend)

Method	Route	Mô tả
`updateContentBlogs(Request, $id)`	GET `/crawl-ai` / `/crawl-ai/{id}`	Xử lý AI update cho blog(s)
`forceRunSingleCrawlJobAI($crawlJobId, Request)`	-	Force chạy AI cho 1 crawl job
`getUpdateContent($request)`	-	Lấy content cần update
`generateUpdateOutput($type, $request, $workspace)`	-	Tạo output từ AI response
`translateEditorialTone($request)`	-	Dịch + chỉnh sửa editorial tone
`generatePromptForShortDescription($request)`	-	Tạo prompt cho short description
`generatePromptForBlogContent($request)`	-	Tạo prompt cho blog content
`generatePromptForBlogTitle($request)`	-	Tạo prompt cho blog title

3.4.5. AI Logs

Method	Route	Mô tả
`viewBlogAILogs($id)`	GET `/blog/{id}/ai-logs`	Xem AI logs của 1 blog
`listAILogs(Request)`	GET `/ai-logs`	Danh sách tất cả AI logs
`showAILogDetail($logId)`	GET `/ai-logs/{logId}`	Chi tiết 1 AI log
`deleteAILog($logId)`	DELETE `/ai-logs/{logId}`	Xóa AI log

3.4.6. Internal Methods (Private/Helpers)

Method	Mô tả
`getPromptKeyMapping()`	Map operation type → prompt key
`getPromptPlaceholders($promptKey)`	Lấy available placeholders cho 1 prompt key
`getPrompt($promptKey, $defaultPrompt, $data, $defaultSystemRole)`	Lấy prompt từ DB hoặc default, tự động replace placeholders
`replacePromptPlaceholders($prompt, $replacements)`	Replace placeholders trong prompt
`cleanPromptWhitespace($prompt)`	Clean extra whitespace trong prompt
`getAIConfig()`	Lấy AI config ưu tiên: custom model → default OpenAI
`logApiRequest(...)`	Log API request vào `ai_api_logs` table
`setCurrentBlogId($id)`	Set blog ID hiện tại cho logging
`setCurrentCrawlJobId($id)`	Set crawl job ID hiện tại cho logging

3.4.7. Workflow của `updateContentBlogs()`

Load AI Settings: Lấy config từ open_ai_settings

Select Blogs: Chọn blogs cần xử lý (pending/draft, có name_crawl)

Get AI Config: Ưu tiên custom model > default OpenAI

Get Workspace: Build workspace config (API URL, key, model name, retry chain)

Process Operations:

title_and_description → translate + rewrite title + description (JSON output)

blog_details → translate + rewrite content (HTML output)

short_details → rewrite description

Workspace Chain: Nếu primary model fail → retry với chain models

Update Blog: Cập nhật name, short_description, content vào database

Mattermost Notification: Gửi thông báo thành công/lỗi

Update Schedule: Cập nhật ai_next_run_time cho crawl job

3.4.8. Mattermost Notification Flow

Thành công: Gửi message qua success bot với thông tin blog đã update

Lỗi: Gửi message qua error bot với error details

Mỗi loại operation có bot/channel riêng

3.5. AI API Logs Table Schema

Table: ai_api_logs

Column	Type	Mô tả
`id`	bigint	Primary key
`blog_id`	bigint	Blog ID liên quan
`crawl_job_id`	bigint	Crawl job ID liên quan
`operation_type`	varchar(100)	Loại operation (title_and_description, content_rewrite...)
`model_name`	varchar(255)	Tên model được sử dụng
`api_url`	text	API URL đã gọi
`request_data`	json	Dữ liệu request
`response_data`	json	Dữ liệu response
`http_code`	int	HTTP status code
`retry_attempt`	int	Số lần retry
`success`	tinyint	Thành công (0/1)
`error_message`	text	Error message nếu fail
`duration_ms`	int	Thời gian xử lý (ms)
`created_at`	timestamp	Thời gian tạo

3.6. Placeholder System

Hệ thống hỗ trợ auto-replace placeholders trong prompts:

Placeholder	Giá trị	Áp dụng cho
`{blog_title}`	Tiêu đề bài viết gốc	title_and_description_rewrite, title_rewrite
`{short_details}`	Mô tả ngắn bài viết gốc	title_and_description_rewrite, description_rewrite
`{blog_content}`	Nội dung HTML bài viết gốc	content_rewrite
`{content}`	Fallback - đại diện cho content duy nhất	Legacy prompts

3.7. AI Config Priority Flow

1. Check "Use Custom Model" toggle
   ├── YES + custom_api_url/key/model configured
   │   └── Use: custom_api_url + custom_api_key + custom_model (hoặc operation-specific model)
   └── NO or incomplete
       └── Use: https://api.openai.com/v1/chat/completions + api_key + default_model

2. Per-Operation Model Override
   ├── translate_model_name → dùng cho translate operation
   ├── title_model_name → dùng cho title rewrite
   ├── description_model_name → dùng cho description rewrite
   └── content_model_name → dùng cho content rewrite

3. Workspace Retry Chain
   ├── Primary model fail → retry với model #2 trong chain
   ├── Model #2 fail → retry với model #3...
   └── Cuối cùng fail → log error + gửi Mattermost notification

4. Phân Tích Tính Năng

4.1. Tính năng đã có ✅

Yêu cầu	Trạng thái	Chi tiết
Tin tức bóng đá	✅ Có	Hệ thống Blog với categories/tags
Chuyển nhượng	✅ Có thể thêm	Blog category riêng
Nhận định trận đấu	✅ Có	Blog system với categories
Thống kê đội bóng	✅ Có widget	`league_ranking_widget`
Lịch thi đấu	✅ Có widget	`match_schedule_widget`
Kết quả trận đấu	✅ Có widget	`match_schedule_widget`
Bảng xếp hạng	✅ Có widget	`league_ranking_widget`, `sports_ranking_widget`
Analytics/Tracking	✅ Có	AnalyticsDashboardController, Heatmap
Page Builder	✅ Có	newslooks-pagebuilder plugin
Quản lý nội dung	✅ Có	Core Blog, Page, Media, Sitemap
Quản lý người dùng	✅ Có	User authentication, roles, permissions
Tips chuyên gia	✅ Có widget	`sports_expert_tips_widget`, `hot_tips_widget`

4.2. Tính năng cần phát triển thêm ❌

Yêu cầu	Trạng thái	Đề xuất
Dữ liệu đội bóng, cầu thủ, HLV	⚠️ Cơ bản	Có SportsDataHelper, Widgets sẵn có
Hệ thống cào dữ liệu	✅ Có đầy đủ	CrawlJobController, CrawlerService, Dashboard
AI viết bài tự động	✅ Có đầy đủ	AIAssistantController, AI Settings, Auto-translate

5. Cấu trúc Controller

5.1. FrontendController (`src/Http/Controllers/Frontend/FrontendController.php`)

Method	Route	Mô tả
`index()`	`/`	Trang chủ - hiển thị homepage với pagebuilder
`pageDetails()`	`/{permalink}`	Hiển thị chi tiết trang (page)
`pageOrBlogDetails()`	`/{permalink?}`	Xử lý cả page và blog - ưu tiên page trước
`getPageContent()`	POST `/page/password/load`	Lấy nội dung trang có password
`changeLanguage()`	POST `/language-change`	Đổi ngôn ngữ frontend
`vote()`	POST `/poll-vote`	Bình chọn (poll/voting)
`privacyPolicy()`	`/chinh-sach-bao-mat`	Trang chính sách bảo mật
`termsOfService()`	`/dieu-khoan-su-dung`	Trang điều khoản sử dụng
`feedback()`	`/gop-y`	Trang góp ý
`submitFeedback()`	POST `/gop-y/submit`	Submit form góp ý
`adContact()`	`/lien-he-quang-cao`	Trang liên hệ quảng cáo
`submitAdContact()`	POST `/lien-he-quang-cao/submit`	Submit form liên hệ quảng cáo
`sendMessage()`	POST `/contact/submit`	Gửi tin nhắn liên hệ

5.2. FrontendBlogController (`src/Http/Controllers/Frontend/FrontendBlogController.php`)

Method	Route	Mô tả
`blogs()`	`/posts`	Danh sách tất cả bài viết
`blogByCategory()`	`/{prefix}/{permalink}`	Lọc bài viết theo danh mục
`blogByVideo()`	`/{prefix}/video`	Lọc bài viết video
`blogByTag()`	`/{tag_prefix}/{permalink}`	Lọc bài viết theo tag
`blogBySearch()`	`/search/{text}`	Tìm kiếm bài viết
`blogByAuthor()`	`/author/{name}`	Lọc bài viết theo tác giả
`blogByDate()`	`/date/{date}`	Lọc bài viết theo ngày
`blogByFilter()`	`/filter/{filter}`	Lọc bài viết theo bộ lọc (featured, popular, recent...)
`details()`	`/{permalink}`	Chi tiết bài viết (v1)
`blogDetailsV2()`	`/v2/{permalink}`	Chi tiết bài viết (v2)
`getBlogContent()`	POST `/post/password/load`	Lấy nội dung bài viết có password
`loadBlogComment()`	POST `/post/comment`	Load bình luận bài viết
`createBlogComment()`	POST `/post/comment/create`	Tạo bình luận mới
`getPaginationData()`	-	Lấy dữ liệu phân trang (internal)
`getBlogsPagination()`	GET `/blogs`	API phân trang bài viết
`findBlogsPagination()`	GET `/blogs-search`	API tìm kiếm bài viết

5.3. NewsletterController (`src/Http/Controllers/Frontend/NewsletterController.php`)

Method	Route	Mô tả
`store()`	POST `/newsletter/store`	Đăng ký nhận newsletter qua Mailchimp

6. Các Route chính

6.1. Route công khai (không cần đăng nhập)

6.2. Route cần đăng nhập (User)

6.3. Route Backend (Admin)

7. Repository Layer

7.1. FrontendBlogRepository (`src/Repositories/FrontendBlogRepository.php`)

Method	Mô tả
`getBlogs($paginate, $type, $value)`	Lấy danh sách bài viết với phân trang và bộ lọc
`blogDetails($permalink)`	Lấy chi tiết bài viết (v1)
`blogDetailsV2($permalink)`	Lấy chi tiết bài viết (v2)
`getBlogContent($request)`	Lấy nội dung bài viết có password

7.2. BlogCommentRepository (`src/Repositories/BlogCommentRepository.php`)

Method	Mô tả
`getBlogComment($request)`	Lấy danh sách bình luận của bài viết
`createComment($request)`	Tạo bình luận mới

8. Middleware

tract.visitor - Theo dõi lượt truy cập

auth - Yêu cầu đăng nhập

user.guard - Guard cho user

admin.guard - Guard cho admin

throttle - Giới hạn request

9. Tên Route (Route Names)

Tên Route	Controller@Method
`home`	FrontendController@index
`theme.newslooks.blog.list`	FrontendBlogController@blogs
`theme.newslooks.blog.blogByCategory`	FrontendBlogController@blogByCategory
`theme.newslooks.blog.blogByTag`	FrontendBlogController@blogByTag
`theme.newslooks.blog.blogBySearch`	FrontendBlogController@blogBySearch
`theme.newslooks.blog.blogByAuthor`	FrontendBlogController@blogByAuthor
`theme.newslooks.blog.blogByDate`	FrontendBlogController@blogByDate
`theme.newslooks.blog.blogByFilter`	FrontendBlogController@blogByFilter
`theme.newslooks.blog.details`	FrontendController@pageOrBlogDetails
`theme.newslooks.blog.details.v2`	FrontendBlogController@blogDetailsV2
`theme.newslooks.newsletter.store`	NewsletterController@store
`theme.newslooks.contact.submit`	FrontendController@sendMessage
`theme.newslooks.vote.give`	FrontendController@vote
`theme.newslooks.language.change`	FrontendController@changeLanguage
`theme.newslooks.user.login`	UserController@login
`theme.newslooks.user.registration`	UserController@registration
`theme.newslooks.user.dashboard`	UserController@dashboard

10. Cấu hình URL Prefix

Các prefix URL được cấu hình động qua helper functions:

getCategoryUrlPrefix() - Prefix cho danh mục (mặc định: danh-muc)

getTagUrlPrefix() - Prefix cho tag (mặc định: tag)

11. View Files

Các view templates nằm trong thư mục resources/views/frontend/:

pages/home.blade.php - Trang chủ

pages/page.blade.php - Chi tiết trang

pages/blogs.blade.php - Danh sách bài viết

pages/category.blade.php - Danh mục/Tag

pages/search.blade.php - Tìm kiếm

pages/blog-details.blade.php - Chi tiết bài viết (v1)

pages/blog-details-v2.blade.php - Chi tiết bài viết (v2)

pages/privacy-policy.blade.php - Chính sách bảo mật

pages/terms-of-service.blade.php - Điều khoản sử dụng

pages/ad-contact.blade.php - Liên hệ quảng cáo

12. Models liên quan

Core\Models\TlBlog - Bài viết

Core\Models\TlBlogCategory - Danh mục

Core\Models\TlBlogTag - Tag

Core\Models\TlPage - Trang (Page)

Core\Models\User - User

Theme\NewsLooks\Models\Vote - Bình chọn

Theme\NewsLooks\Models\VoteCount - Lượt bình chọn

13. Helpers hỗ trợ

getActiveTheme() - Lấy theme hiện tại

getThemeOption($option, $theme_id) - Lấy cấu hình theme

isActivePluging($plugin) - Kiểm tra plugin có active không

getFrontLocale() - Lấy ngôn ngữ frontend

front_translate($text) - Dịch text frontend

toastNotification($type, $message) - Hiển thị thông báo

newlooksTimeAgo($date) - Format thời gian relative

getImageVariation($image, $size) - Lấy image variant

14. Sports Data Integration

14.1. SportsDataHelper (`app/Helpers/SportsDataHelper.php`)

Helper class cung cấp dữ liệu bóng đá tĩnh:

Method	Mô tả
`getArrayLeague()`	Lấy danh sách giải đấu (có image)
`getArrayLeagueSimple()`	Lấy danh sách giải đấu (không image)
`getNationalTeams()`	Lấy danh sách đội tuyển quốc gia
`getLeagueByValue($value)`	Lấy thông tin giải đấu theo ID
`getNationalTeamById($id)`	Lấy thông tin đội tuyển theo ID

Các giải đấu được hỗ trợ:

Ngoại Hạng Anh (36)

VĐQG Tây Ban Nha (31)

VĐQG Ý (34)

VĐQG Đức (8)

VĐQG Pháp (11)

Cúp C1 châu âu (103)

Europa League (113)

Copa Libertadores (89)

MLS Mỹ (21)

AFC Champions League (192)

V-League (766)

VĐQG Bồ Đào Nha (23)

VĐQG Brazil (4)

VĐQG Argentina (2)

VĐQG Thổ Nhĩ Kỳ (30)

VĐQG Hà Lan (16)

Mexico Liga MX (140)

VĐQG Nhật Bản (25)

K-League Hàn Quốc (15)

VĐQG Ả Rập Xê Út (292)

14.2. Sports Widgets (Page Builder)

Widget	File	Mô tả
`match_schedule_widget`	`match_schedule_widget.blade.php`	Lịch thi đấu
`match_analysis_list_widget`	`match_analysis_list_widget.blade.php`	Danh sách nhận định trận đấu
`league_ranking_widget`	`league_ranking_widget.blade.php`	Bảng xếp hạng giải đấu
`sports_ranking_widget`	`sports_ranking_widget.blade.php`	Xếp hạng thể thao
`sports_schedule_board`	`sports_schedule_board.blade.php`	Bảng lịch thi đấu
`sports_team_feature_widget`	`sports_team_feature_widget`	Nổi bật đội bóng
`sport_team_post`	`sport_team_post.blade.php`	Bài viết về đội bóng
`sports_expert_tips_widget`	`sports_expert_tips_widget.blade.php`	Tips chuyên gia
`hot_tips_widget`	`hot_tips_widget.blade.php`	Tips nóng
`video_thethaoso`	`video_thethaoso.blade.php`	Video thể thao
`tips_thethaoso`	`tips_thethaoso.blade.php`	Tips Thethaoso
`odds_slider`	`sports_odds_slider.blade.php`	Tỷ lệ kèo

Widget hiển thị lịch thi đấu bóng đá:

Widget Title: Tiêu đề widget

Max Matches: Số trận tối đa hiển thị (default: 10)

Selected League: Chọn giải đấu (mặc định: 36 - Ngoại Hạng Anh)

Dữ liệu được load từ: API bên thứ 3 hoặc SportsDataHelper

15. Models & Database

15.1. Core Models

Model	Bảng	Mô tả
`TlBlog`	`tl_blogs`	Bài viết
`TlBlogCategory`	`tl_blog_categories`	Danh mục
`TlBlogTag`	`tl_blog_tags`	Tags
`TlBlogComment`	`tl_blog_comments`	Bình luận
`TlPage`	`tl_pages`	Trang
`User`	`users`	Người dùng
`Role`	`roles`	Vai trò
`Permission`	`permissions`	Quyền
`Language`	`tl_languages`	Ngôn ngữ
`Menu`	`tl_menus`	Menu
`UploadedFile`	`uploaded_files`	Media files

15.2. Theme Models

Model	Bảng	Mô tả
`Vote`	`tl_votes`	Bình chọn/Polls
`VoteCount`	`tl_vote_counts`	Lượt bình chọn
`VoteTranslation`	`tl_vote_translations`	Dịch bình chọn
`Visitor`	`tl_visitors`	Khách truy cập
`ReadingList`	`tl_reading_lists`	Danh sách đọc
`ThemeSidebar`	`tl_theme_sidebars`	Sidebar
`Widget`	`tl_widgets`	Widgets

16. API Endpoints

16.1. Public APIs

Endpoint	Method	Mô tả
`/blogs`	GET	Phân trang bài viết
`/blogs-search`	GET	Tìm kiếm bài viết
`/heatmap/click`	POST	Ghi nhận click heatmap
`/heatmap/grid`	GET	Lấy dữ liệu heatmap
`/exchange-rate`	GET	Tỷ giá ngoại hối
`/location-city`	GET	Vị trí và thành phố

16.2. Blog APIs

Endpoint	Method	Mô tả
`/post/password/load`	POST	Lấy nội dung bài viết có password
`/post/comment`	POST	Load bình luận
`/post/comment/create`	POST	Tạo bình luận mới

17. Page Builder Widgets (Toàn bộ)

17.1. Post/Blog Widgets

post_thethaoso - Bài viết Thethaoso

post_thethaoso_match - Bài viết trận đấu

post_list_thethaoso - Danh sách bài viết

post_layout - Layout bài viết

post_filter - Lọc bài viết

post_tab - Tab bài viết

post_advance_layout - Layout nâng cao

gallery_post - Gallery bài viết

video_post - Video bài viết

slider_post - Slider bài viết

hot_tips - Tips nóng

17.2. Category/Tag Widgets

category_thethaoso - Danh mục Thethaoso

category - Danh mục

tag - Tag

tag_thethaoso - Tag Thethaoso

tag_nhandinh - Tag nhận định

17.3. Sports Widgets

match_schedule_widget - Lịch thi đấu

match_analysis_list_widget - Nhận định trận đấu

league_ranking_widget - Bảng xếp hạng

sports_ranking_widget - Xếp hạng thể thao

sports_schedule_board - Bảng lịch thi đấu

sports_team_feature_widget - Đội bóng nổi bật

sport_team_post - Bài viết đội bóng

sports_expert_tips_widget - Tips chuyên gia

odds_slider - Tỷ lệ kèo

video_thethaoso - Video

tips_thethaoso - Tips

17.4. Common Widgets

slider_thethaoso - Slider

header - Header

footer - Footer

breadcrumb_thethaoso - Breadcrumb

search - Tìm kiếm

newsletter - Newsletter

voting - Bình chọn

contact - Liên hệ

contact_info_box - Thông tin liên hệ

contact_ads_form - Form quảng cáo

text_editor - Text editor

text_editor_thethaoso - Text editor Thethaoso

image - Hình ảnh

button - Nút

social - Social links

author - Tác giả

recent_comments - Bình luận gần đây

ads - Quảng cáo

menu_links - Menu links

heading_tag - Heading

address - Địa chỉ

error_page - Trang lỗi

18. Crawl Data System (Hệ thống Cào Dữ liệu)

18.1. CrawlJobController (`app/Http/Controllers/CrawlJobController.php`)

Method	Route	Mô tả
`index()`	`GET /crawl-jobs`	Danh sách tất cả crawl jobs
`add()`	`GET /crawl-jobs/add`	Form tạo crawl job mới
`store()`	`POST /crawl-jobs`	Tạo/cập nhật crawl job
`edit($id)`	`GET /crawl-jobs/edit/{id}`	Form chỉnh sửa crawl job
`preview(Request)`	`POST /crawl-jobs/preview`	Preview kết quả crawl
`show($id)`	`GET /crawl-jobs/{id}`	Xem chi tiết job
`destroy($id)`	`DELETE /crawl-jobs/{id}`	Xóa crawl job
`dashboard()`	`GET /crawl-jobs/dashboard`	Dashboard quản lý crawl với thống kê
`forceRunAI($id)`	`POST /crawl-jobs/{id}/force-run-ai`	Force chạy crawl/AI (bỏ qua timing)
`toggleActive($id)`	`POST /crawl-jobs/{id}/toggle-active`	Bật/tắt trạng thái active
`getStatus($id)`	`GET /crawl-jobs/{id}/status`	Lấy trạng thái job (JSON)

18.2. CrawlJob Model (`app/Models/CrawlJob.php`)

Bảng: crawl_jobs

Thuộc tính	Kiểu	Mô tả
`url`	string	URL nguồn cần crawl
`category`	string	ID danh mục gán vào
`limit_posts`	integer	Số bài viết tối đa cần crawl
`page`	integer	Số trang pagination
`class`	string	CSS selector cho danh sách bài
`title`	string	CSS selector cho tiêu đề bài viết
`detail`	string	CSS selector cho link chi tiết
`content`	string	CSS selector cho nội dung bài
`replace_text`	string	Text cần thay thế trong content
`remove_element`	string	CSS selector các element cần loại bỏ
`tag_selector`	string	CSS selector cho tags
`tag_limit`	integer	Số tag tối đa
`image`	string	CSS selector cho thumbnail
`image_detail`	string	CSS selector cho ảnh trong chi tiết
`pagination`	string	CSS selector cho pagination
`frequency`	string	Tần suất: `once`, `daily`, `hourly`
`frequency_time`	datetime	Thời gian chạy tiếp theo
`active`	boolean	Trạng thái hoạt động
`start_time`	datetime	Thời gian bắt đầu job
`video`	string	CSS selector cho video
`internal_link_limit`	integer	Giới hạn internal links
`ai_enabled`	boolean	Bật AI xử lý sau crawl
`ai_batch_size`	integer	Số bài xử lý mỗi batch
`ai_interval_minutes`	integer	Khoảng cách giữa các batch (phút)
`ai_next_run_time`	datetime	Thời gian chạy AI tiếp theo
`ai_use_translate`	boolean	Dùng AI dịch nội dung

18.3. CrawlerService (`app/Services/Crawler/CrawlerService.php`)

Method	Mô tả
`execute($config)`	Thực thi crawl job theo cấu hình
`testCrawl($config)`	Test crawl không lưu vào DB

18.4. Crawler Strategy & Pagination

File	Mô tả
`TimeStrategy/ITimeStrategy.php`	Interface cho time strategy
`TimeStrategy/DailyStrategy.php`	Chiến lược chạy hàng ngày
`TimeStrategy/HourlyStrategy.php`	Chiến lược chạy hàng giờ
`TimeStrategy/TimeStrategyFactory.php`	Factory tạo strategy
`Pagination/PaginationStrategyInterface.php`	Interface cho pagination
`Pagination/LinkPagination.php`	Pagination qua link trang
`Pagination/ClickPagination.php`	Pagination qua nút "Xem thêm"

18.5. Crawl Routes (Backend)

19. AI Update Content System

19.1. AIAssistantController (`Core/Http/Controllers/AIAssistantController.php`)

Method	Route	Mô tả
`AISetting()`	`GET /ai-settings`	Trang cấu hình AI settings
`updateAISetting(Request)`	`POST /ai-settings-update`	Cập nhật AI settings
`generateContent(Request)`	`POST /generate-content-with-ai`	Tạo nội dung bằng AI
`generateUpdateContent(Request)`	`PUT /generate-content-with-ai`	Cập nhật nội dung bằng AI
`updateContentBlogs(Request, $id)`	`GET /crawl-ai`, `GET /crawl-ai/{id}`	AI xử lý bài viết crawl
`forceRunSingleCrawlJobAI($id, Request)`	`GET /crawl-ai/{id}` (force)	Force chạy AI cho 1 job
`generateUpdateOutput($type, $request, $workspace)`	-	Tạo output AI (internal)
`generatePromptForShortDescription(Request)`	-	Tạo prompt cho mô tả ngắn
`generatePromptForBlogContent(Request)`	-	Tạo prompt cho nội dung blog
`generatePromptForBlogTitle(Request)`	-	Tạo prompt cho tiêu đề blog
`translateEditorialTone(Request)`	-	Dịch/chỉnh sửa giọng văn
`viewBlogAILogs($id)`	`GET /blog/{id}/ai-logs`	Xem AI logs của 1 blog
`listAILogs(Request)`	`GET /ai-logs`	Danh sách tất cả AI logs
`showAILogDetail($logId)`	`GET /ai-logs/{logId}`	Chi tiết 1 AI log
`deleteAILog($logId)`	`DELETE /ai-logs/{logId}`	Xóa AI log

19.2. AI Settings

Bảng: open_ai_settings

Field	Mô tả
`api_key`	OpenAI API Key
`default_model`	Model mặc định (e.g., `gpt-4`, `gpt-4o`, `gpt-3.5-turbo`)
`title_rewrite`	Prompt cho rewrite tiêu đề
`description_rewrite`	Prompt cho rewrite mô tả
`content_rewrite`	Prompt cho rewrite nội dung
`title_and_description_rewrite`	Prompt cho rewrite cả 2
`title_model_name`	Model cho title generation
`description_model_name`	Model cho description generation
`workspace`	Workspace AI settings
`retry_chains`	Retry chain configuration
`custom_model_fields`	Custom model fields
`ai_blog_status`	Trạng thái blog sau khi AI xử lý
`ai_job_settings`	Cấu hình job AI (batch_size, interval)
`mattermost_webhook_url`	Webhook URL cho Mattermost notification

19.3. AI API Logs

Bảng: ai_api_logs (Core/Models/AIApiLog.php)

Lưu trữ chi tiết mỗi lần gọi API AI:

Field	Mô tả
`blog_id`	ID bài viết liên quan
`crawl_job_id`	ID crawl job liên quan
`model`	Model AI được sử dụng
`prompt_type`	Loại prompt (title, description, content)
`input_tokens`	Số tokens đầu vào
`output_tokens`	Số tokens đầu ra
`total_tokens`	Tổng tokens
`cost`	Chi phí API
`response`	Full response từ API
`status`	Trạng thái (success, error)
`created_at`	Thời gian gọi

19.4. AI Routes (Backend - Auth Required)

20. Các Models Quan trọng (Core)

Model	Bảng	Mô tả
`Core\Models\TlBlog`	`tl_blogs`	Bài viết chính
`Core\Models\TlBlogCategory`	`tl_blog_categories`	Danh mục bài viết
`Core\Models\TlBlogTag`	`tl_blog_tags`	Tags bài viết
`Core\Models\TlBlogComment`	`tl_blog_comments`	Bình luận
`Core\Models\TlPage`	`tl_pages`	Trang tĩnh
`Core\Models\User`	`users`	Người dùng
`Core\Models\Role`	`roles`	Vai trò
`Core\Models\Permission`	`permissions`	Quyền hạn
`Core\Models\AIApiLog`	`ai_api_logs`	AI API call logs (id, blog_id, crawl_job_id, operation_type, model_name, api_url, request_data, response_data, http_code, retry_attempt, success, error_message, duration_ms)
`App\Models\CrawlJob`	`crawl_jobs`	Crawl jobs
`App\Models\CrawlConfig`	-	Crawl configuration
`App\Models\CrawlImage`	`crawl_images`	Crawled images cache
`App\Models\HeatmapClick`	`heatmap_clicks`	Heatmap click data

21. Các Helper Functions Quan trọng

Helper	File	Mô tả
`getCategoryUrlPrefix()`	Helper	Lấy prefix URL danh mục (mặc định: `danh-muc`)
`getTagUrlPrefix()`	Helper	Lấy prefix URL tag (mặc định: `tag`)
`getActiveTheme()`	Helper	Lấy theme hiện tại
`getThemeOption($option, $theme_id)`	Helper	Lấy cấu hình theme option
`isActivePluging($plugin)`	Helper	Kiểm tra plugin có active không
`getFrontLocale()`	Helper	Lấy ngôn ngữ frontend
`front_translate($text)`	Helper	Dịch text frontend
`toastNotification($type, $message)`	Helper	Hiển thị toast notification
`newlooksTimeAgo($date)`	Helper	Format thời gian relative
`getImageVariation($image, $size)`	Helper	Lấy image variant
`getAdminPrefix()`	Helper	Lấy admin URL prefix

22. Tên Route Quan trọng (Route Names)

22.1. Core Backend Routes

Tên Route	Controller@Method
`core.login`	AuthenticationController@login
`core.attemptLogin`	AuthenticationController@attemptLogin
`core.logout`	AuthenticationController@logout
`core.dashboard`	DashboardController@dashboard
`core.general.settings`	GeneralSettingsController@generalSettings
`core.email.smtp.configuration`	EmailController@smtpConfiguration
`core.email.templates`	EmailController@emailTemplates
`core.blog`	BlogController@blog
`core.add.blog`	BlogController@addBlog
`core.store.blog`	BlogController@storeBlog
`core.edit.blog`	BlogController@editBlog
`core.update.blog`	BlogController@updateBlog
`core.delete.blog`	BlogController@deleteBlog
`core.bulk.delete.blog`	BlogController@bulkDeleteBlog
`core.blog.category`	BlogCategoryController@blogCategory
`core.store.blog.category`	BlogCategoryController@storeBlogCategory
`core.edit.blog.category`	BlogCategoryController@editBlogCategory
`core.update.blog.category`	BlogCategoryController@updateBlogCategory
`core.delete.blog.category`	BlogCategoryController@deleteBlogCategory
`core.tag`	TagController@tag
`core.store.tag`	TagController@storeTag
`core.edit.tag`	TagController@editTag
`core.update.tag`	TagController@updateTag
`core.delete.tag`	TagController@deleteTag
`core.page`	PageController@page
`core.page.add`	PageController@addPage
`core.page.store`	PageController@storePage
`core.page.edit`	PageController@editPage
`core.page.update`	PageController@updatePage
`core.page.delete`	PageController@deletePage
`core.page.make.homepage`	PageController@makeHomepage
`core.media.page`	MediaController@mediaPage
`core.upload.media.file`	MediaController@uploadMediaFile
`core.blog.comment`	CommentController@comment
`core.blog.comment.bulk.action`	CommentController@bulkAction
`core.blog.comment.delete`	CommentController@commentDelete
`core.blog.comment.reply`	CommentController@replyBlogComment
`core.users`	UserController@users
`core.add.user`	UserController@addUser
`core.edit.user`	UserController@editUser
`core.delete.user`	UserController@deleteUser
`core.blog.share.options`	BlogController@shareOptions
`core.blog.share.options.update.status`	BlogController@shareOptionUpdateStatus
`core.blog.history`	BlogController@blogHistory
`core.blog.history.detail`	BlogController@blogHistoryDetail
`core.blog.history.compare`	BlogController@compareBlogHistory
`core.blog.history.restore`	BlogController@restoreBlogHistory
`core.blog.history.delete`	BlogController@deleteBlogHistory
`core.blog.draft.preview`	BlogController@blogDraftPreview
`core.blog.preview`	BlogController@blogPreview
`core.blog.ai.setting`	AIAssistantController@AISetting
`core.blog.update.ai.setting`	AIAssistantController@updateAISetting
`core.blog.generate.content.with.ai`	AIAssistantController@generateContent
`core.blog.update.content.with.ai`	AIAssistantController@generateUpdateContent
`core.blog.all.content.with.ai`	AIAssistantController@updateContentBlogs
`core.blog.ai.crawl.single`	AIAssistantController@updateContentBlogs
`core.update.crawl.images`	CrawlNewsJob@updateCrawlImages
`core.blog.ai.logs`	AIAssistantController@viewBlogAILogs
`core.ai.logs.list`	AIAssistantController@listAILogs
`core.ai.logs.show`	AIAssistantController@showAILogDetail
`core.ai.logs.delete`	AIAssistantController@deleteAILog
`core.internal.links.index`	InternalLinkController@index
`core.internal.links.create`	InternalLinkController@create
`core.internal.links.store`	InternalLinkController@store
`core.internal.links.edit`	InternalLinkController@edit
`core.internal.links.update`	InternalLinkController@update
`core.internal.links.destroy`	InternalLinkController@destroy
`core.internal.links.settings`	InternalLinkController@settings
`core.internal.links.import.csv`	InternalLinkController@importCsv
`core.roles`	RolePermissionController@roles
`core.permissions`	RolePermissionController@permissions
`core.languages`	LanguageController@allLanguages
`core.plugins.index`	PluginsController@index
`core.themes.index`	ThemesController@index
`core.manage.menus`	MenuController@index
`core.sitemap`	SystemController@serveSitemap
`core.admin.generate.sitemap`	SystemController@generateSitemap
`core.admin.clear.system.cache`	SystemController@clearSystemCache
`core.seo.settings`	SeoController@seoSettings
`core.ads.list`	CustomAdsController@adsList
`core.backup.files.list`	BackupController@filesBackup
`core.backup.database.list`	BackupController@databaseBackup
`core.content-replace.index`	ContentReplaceController@index
`core.content-replace.preview`	ContentReplaceController@preview
`core.content-replace.execute`	ContentReplaceController@execute
`core.blog.csv.import.export`	CSVImportExportController@csvImportExport
`core.blog.csv.import.submit`	CSVImportExportController@submit
`core.blog.csv.export`	CSVImportExportController@export
`core.get.login.activity`	ActivityLogController@getLoginActivity
`core.get.all.login.activity`	ActivityLogController@getAllLoginActivity
`core.license.active`	DashboardController@licenseActive
`core.admin.welcome`	SystemController@welcome

22.2. Crawl Job Routes

Tên Route	Controller@Method
`crawl_jobs.index`	CrawlJobController@index
`crawl_jobs.add`	CrawlJobController@add
`crawl_jobs.store`	CrawlJobController@store
`crawl_jobs.edit`	CrawlJobController@edit
`crawl_jobs.preview`	CrawlJobController@preview
`crawl_jobs.destroy`	CrawlJobController@destroy
`crawl_jobs.dashboard`	CrawlJobController@dashboard
`crawl_jobs.force_run_ai`	CrawlJobController@forceRunAI
`crawl_jobs.status`	CrawlJobController@getStatus
`crawl_jobs.toggle_active`	CrawlJobController@toggleActive

22.3. Theme Backend Routes

Tên Route	Controller@Method
`theme.newslooks.widgets`	WidgetController@widgets
`theme.newslooks.widget.get_input_field`	WidgetController@getWidgetInputFields
`theme.newslooks.widget.addToSidebar`	WidgetController@addWidgetToSidebar
`theme.newslooks.widget.removeFromSidebar`	WidgetController@removeWidgetFromSidebar
`theme.newslooks.widget.widgetSidebarForm`	WidgetController@saveWidgetSidebarInput
`theme.newslooks.widget.saveWidgetOrder`	WidgetController@saveWidgetOrder
`theme.newslooks.options`	ThemeOptionController@themeOptions
`theme.newslooks.get.option.form`	ThemeOptionController@getOptionForm
`theme.newslooks.save.option.form`	ThemeOptionController@saveOptionForm
`theme.newslooks.theme-option.import`	ThemeOptionController@importThemeOption
`theme.newslooks.theme-option.download`	ThemeOptionController@downloadThemeOption
`theme.newslooks.vote.index`	VotingController@index
`theme.newslooks.vote.create`	VotingController@create
`theme.newslooks.vote.store`	VotingController@store
`theme.newslooks.vote.edit`	VotingController@edit
`theme.newslooks.vote.update`	VotingController@update
`theme.newslooks.vote.delete`	VotingController@delete
`theme.newslooks.users`	ManageUserController@allUsers
`theme.newslooks.users.status`	ManageUserController@statusUpdate
`theme.newslooks.users.delete`	ManageUserController@deleteUser
`theme.newslooks.analytics.dashboard`	AnalyticsDashboardController@index
`theme.newslooks.visitor.reports`	ReportController@visitorReports
`theme.newslooks.country.reports`	ReportController@countryReports
`theme.newslooks.browser.reports`	ReportController@browserReports
`theme.newslooks.device.reports`	ReportController@deviceReports

22.4. Heatmap & Analytics Routes

Tên Route	Controller@Method
`admin.heatmap.index`	HeatmapDashboardController@index
`admin.heatmap.track`	HeatmapDashboardController@track
`api.heatmap.click`	HeatmapClickController@store
`api.heatmap.grid`	HeatmapClickController@grid
`pagebuilder.league-ranking`	ProxyController@leagueRank
`pagebuilder.hot-tips`	ProxyController@hotTips

23. Các Service Quan trọng

Service	File	Mô tả
`CrawlerService`	`app/Services/Crawler/CrawlerService.php`	Service chính cho crawl data
`DefaultCrawler`	`app/Services/Crawler/DefaultCrawler.php`	Crawler implementation mặc định
`ContentReplaceService`	`app/Services/ContentReplaceService.php`	Thay thế nội dung hàng loạt
`AnalyticsService`	`app/Services/AnalyticsService.php`	Analytics data processing

24. Các API Endpoints (Public)

Endpoint	Method	Mô tả
`/blogs`	GET	Phân trang bài viết
`/blogs-search`	GET	Tìm kiếm bài viết
`/heatmap/click`	POST	Ghi nhận click heatmap
`/heatmap/grid`	GET	Lấy dữ liệu heatmap grid
`/exchange-rate`	GET	Tỷ giá ngoại hối
`/location-city`	GET	Vị trí và thành phố
`/newsletter/store`	POST	Đăng ký newsletter
`/contact/submit`	POST	Gửi liên hệ
`/poll-vote`	POST	Bình chọn poll
`/language-change`	POST	Đổi ngôn ngữ
`/post/password/load`	POST	Load nội dung bài viết có password
`/post/comment`	POST	Load bình luận
`/post/comment/create`	POST	Tạo bình luận
`/page/password/load`	POST	Load nội dung page có password
`/user/readingList/update`	POST	Cập nhật danh sách đọc
`/user/readingList/remove`	DELETE	Xóa khỏi danh sách đọc
`/ajax/pagebuilder/league-rank`	GET	Proxy - xếp hạng giải đấu
`/ajax/pagebuilder/hot-tips`	GET	Proxy - tips nóng
`sitemap.xml`	GET	Sitemap XML

25. Các Controller Quan trọng (Core)

Controller	File	Mô tả
`AuthenticationController`	`Core/Http/Controllers/Auth/AuthenticationController.php`	Auth login/logout/reset
`BlogController`	`Core/Http/Controllers/BlogController.php`	CRUD blog posts
`BlogCategoryController`	`Core/Http/Controllers/BlogCategoryController.php`	CRUD blog categories
`TagController`	`Core/Http/Controllers/TagController.php`	CRUD tags
`PageController`	`Core/Http/Controllers/PageController.php`	CRUD pages
`CommentController`	`Core/Http/Controllers/CommentController.php`	Quản lý bình luận
`UserController`	`Core/Http/Controllers/UserController.php`	Quản lý users
`RolePermissionController`	`Core/Http/Controllers/RolePermissionController.php`	Roles & Permissions
`LanguageController`	`Core/Http/Controllers/LanguageController.php`	Quản lý ngôn ngữ
`MenuController`	`Core/Http/Controllers/MenuController.php`	Quản lý menus
`MediaController`	`Core/Http/Controllers/MediaController.php`	Quản lý media files
`EmailController`	`Core/Http/Controllers/EmailController.php`	Email settings & templates
`SeoController`	`Core/Http/Controllers/SeoController.php`	SEO settings
`PluginsController`	`Core/Http/Controllers/PluginsController.php`	Plugin management
`ThemesController`	`Core/Http/Controllers/ThemesController.php`	Theme management
`DashboardController`	`Core/Http/Controllers/DashboardController.php`	Admin dashboard
`SystemController`	`Core/Http/Controllers/SystemController.php`	System settings
`BackupController`	`Core/Http/Controllers/BackupController.php`	Backup files & database
`ActivityLogController`	`Core/Http/Controllers/ActivityLogController.php`	Login activity logs
`GeneralSettingsController`	`Core/Http/Controllers/GeneralSettingsController.php`	General settings
`StyleController`	`Core/Http/Controllers/StyleController.php`	Style/mood settings
`CustomAdsController`	`Core/Http/Controllers/CustomAdsController.php`	Quản lý quảng cáo
`CSVImportExportController`	`Core/Http/Controllers/CSVImportExportController.php`	Import/export CSV
`InternalLinkController`	`Core/Http/Controllers/InternalLinkController.php`	Internal link manager
`AIAssistantController`	`Core/Http/Controllers/AIAssistantController.php`	AI content generation
`HeatmapDashboardController`	`app/Http/Controllers/Admin/HeatmapDashboardController.php`	Heatmap analytics
`HeatmapClickController`	`app/Http/Controllers/HeatmapClickController.php`	Heatmap click ingestion
`ExchangeRateController`	`app/Http/Controllers/ExchangeRateController.php`	Tỷ giá ngoại hối
`ProxyController`	`app/Http/Controllers/ProxyController.php`	Proxy cho pagebuilder widgets
`UpdateController`	`app/Http/Controllers/UpdateController.php`	System update
`MigrationController`	`app/Http/Controllers/MigrationController.php`	Database migrations

26. Content Replace System

26.1. ContentReplaceController (`Core/Http/Controllers/ContentReplaceController.php`)

Method	Route	Mô tả
`index()`	`GET /content-replace`	Trang quản lý replace
`preview(Request)`	`POST /content-replace/preview`	Preview thay thế trước khi áp dụng
`execute(Request)`	`POST /content-replace/execute`	Thực thi thay thế hàng loạt

26.2. ContentReplaceService (`app/Services/ContentReplaceService.php`)

Service xử lý thay thế text hàng loạt trong blog content.

27. Internal Link Manager

27.1. InternalLinkController (`Core/Http/Controllers/InternalLinkController.php`)

Method	Route	Mô tả
`index()`	`GET /internal-links`	Danh sách internal links
`create()`	`GET /internal-links/create`	Form tạo mới
`store(Request)`	`POST /internal-links`	Tạo internal link
`edit($id)`	`GET /internal-links/{id}/edit`	Form chỉnh sửa
`update(Request, $id)`	`PUT /internal-links/{id}`	Cập nhật internal link
`destroy($id)`	`DELETE /internal-links/{id}`	Xóa internal link
`toggleStatus($id)`	`POST /internal-links/toggle-status`	Bật/tắt trạng thái
`settings()`	`GET /internal-links/settings`	Cấu hình internal links
`saveSettings(Request)`	`POST /internal-links/settings`	Lưu cấu hình
`testReplace(Request)`	`POST /internal-links/test`	Test replace
`previewBlog(Request)`	`POST /internal-links/preview-blog`	Preview blog với links
`importCsv(Request)`	`POST /internal-links/import-csv`	Import từ CSV

28. System Backup

28.1. BackupController (`Core/Http/Controllers/BackupController.php`)

Method	Route	Mô tả
`filesBackup()`	`GET /backup/files`	Danh sách file backups
`fileBackupGenerate()`	`GET /backup/generate-backup-file`	Tạo file backup
`fileBackupDelete()`	`POST /backup/delete-backup-file`	Xóa file backup
`fileBackupDownload()`	`GET /backup/download-backup-file/{filename}`	Download file backup
`databaseBackup()`	`GET /backup/database`	Danh sách database backups
`databaseBackupGenerate()`	`GET /backup/generate-database-backup`	Tạo database backup
`databaseBackupDownload()`	`GET /backup/download-backup-database/{filename}`	Download DB backup
`databaseBackupDelete()`	`POST /backup/delete-backup-database`	Xóa DB backup

29. Middleware

Middleware	Mô tả
`tract.visitor`	Theo dõi lượt truy cập website
`auth`	Yêu cầu đăng nhập
`admin.guard`	Guard cho admin panel
`user.guard`	Guard cho frontend user
`throttle`	Giới hạn request rate
`demo`	Chặn thao tác thay đổi trên demo mode
`menu.maintain`	Duy trì menu structure
`themelooks` / `thelooks`	License check middleware (obfuscated)
`license` / `license`	License verification (obfuscated)
`can:...`	Kiểm tra permission

30. Cấu hình Quan trọng

30.1. Database Tables

Bảng	Mô tả
`tl_blogs`	Bài viết blog
`tl_blogs_categories`	Danh mục bài viết (pivot)
`tl_blogs_tags`	Tags bài viết (pivot)
`tl_blogs_comments`	Bình luận bài viết
`tl_pages`	Trang tĩnh
`tl_menus`	Menus
`tl_languages`	Ngôn ngữ
`tl_theme_sidebars`	Sidebars
`tl_widgets`	Widgets
`tl_votes`	Bình chọn/Polls
`tl_vote_counts`	Lượt bình chọn
`tl_vote_translations`	Dịch bình chọn
`tl_visitors`	Visitor tracking data
`tl_reading_lists`	User reading lists
`tl_blog_histories`	Blog edit history
`uploaded_files`	Media files
`roles`	User roles
`permissions`	Permissions
`users`	Users
`open_ai_settings`	AI configuration
`ai_api_logs`	AI API call logs
`crawl_jobs`	Crawl job definitions
`crawl_images`	Crawled images cache
`heatmap_clicks`	Heatmap click data
`ai_provider_keys`	AI provider API keys

30.2. Config Files

File	Mô tả
`config/mail.php`	Email/SMTP configuration
`config/settings.php`	Application settings (blog_status, etc.)

31. View Files - Backend Core

Các view templates backend core nằm trong Core/Views/base/:

View	Mô tả
`blog/settings/ai_setting.blade.php`	AI settings page
`blog/settings/ai_compare.blade.php`	AI content comparison
`blog/ai_logs.blade.php`	AI logs listing
`blog/history_detail.blade.php`	Blog history detail
`media/partial/media_details_side_bar.blade.php`	Media details sidebar
`media/partial/media_details_pop_up.blade.php`	Media details popup
`email/email_templates/*.blade.php`	Email templates
`email/smtp/test_mail.blade.php`	Test email template
`errors/theme_required_plugin_failed.blade.php`	Error - missing plugin
`base/sitemap/sitemap.blade.php`	Sitemap view
`base/system/update/system_update.blade.php`	System update page
`base/license/*.blade.php`	License pages
`base/welcome/index.blade.php`	Welcome page

32. TÀI LIỆU BÀN GIAO CHI TIẾT API & ENDPOINTS (API DOCS)

Tài liệu này cung cấp chi tiết toàn bộ danh sách API, Endpoints, logic xử lý (Controllers, Middleware), mô tả Params/Payload cũng như cấu trúc dữ liệu Model liên quan để đội ngũ phát triển mới nắm bắt và vận hành hệ thống NewsLooks.

Tài liệu thích hợp để Import vào Apidog (dạng Article/Document), hoặc dùng làm tài liệu tham chiếu mã nguồn trực tiếp cho Front-end & Back-end Developer.

32.1. FRONTEND & PUBLIC ENDPOINTS

Nhóm API phục vụ hiển thị nội dung giao diện, không yêu cầu đăng nhập. Điểm chung là chịu sự kiểm soát của Middleware tract.visitor để theo dõi visitor tĩnh và throttle để chống spam request.

32.1.1. Core Pages & Utilities (Tiện ích và Dữ liệu chung)

Method	Endpoint	Controller@Action (Route Name)	Payload / Query Params	Mô tả Chi Tiết Cốt Lõi
`GET`	`/`	`FrontendController@index` (home)	-	Render Homepage (Trang chủ) sử dụng hệ thống Widget Page Builder đọc cấu hình từ file JSON Theme Options. Kích hoạt Tracking visitor.
`GET`	`/chinh-sach-bao-mat`	`FrontendController@privacyPolicy`	-	Truy xuất nội dung trang tĩnh (Page): Chính sách bảo mật. Gọi model `TlPage`.
`GET`	`/dieu-khoan-su-dung`	`FrontendController@termsOfService`	-	Truy xuất nội dung trang tĩnh (Page): Điều khoản. Gọi model `TlPage`.
`POST`	`/language-change`	`FrontendController@changeLanguage` (theme.newslooks.language.change)	`{ lang: string }`	Thay đổi ngôn ngữ hiển thị giao diện Frontend. Setup biến Session/Cookie locale rồi return back.
`GET`	`/sitemap.xml`	`SystemController@serveSitemap` (core.sitemap)	-	Đọc file XML nội bộ hoặc sinh tự động Sitemap cho Google/Bing Bots quét bài phục vụ SEO.
`GET`	`/exchange-rate`	`ExchangeRateController`	-	API proxy trả về tỉ giá ngoại hối theo thời gian thực (Dữ liệu cache Redis/DB từ API Bank).
`GET`	`/location-city`	`FrontendController`	`?search=keyword`	Trả về danh sách thành phố/vị trí địa lý theo format mảng JSON phục vụ auto-fill dropdown.
`POST`	`/contact/submit`	`FrontendController@sendMessage` (theme.newslooks.contact.submit)	`name`, `email`, `subject`, `message`	User gửi form liên hệ. Chức năng lưu vào DB contact và gửi E-Mail trực tiếp tới Admin qua SMTP Mailer.
`POST`	`/newsletter/store`	`NewsletterController@store` (theme.newslooks.newsletter.store)	`email`	User đăng ký nhận email bản tin. Lưu danh sách DB nội bộ và tự động gọi API đẩy vào List Mailchimp nếu cấu hình hoạt động.
`POST`	`/poll-vote`	`FrontendController@vote` (theme.newslooks.vote.give)	`poll_id`, `option_id`	Tham gia bình chọn (Poll/Voting). Validate 1 IP / 1 Option, cập nhật bảng Model `VoteCount`.

32.1.2. Module Hệ Thống Bài Viết (Blog & Category)

Nhóm API chuyên xử lý dữ liệu tin tức thể thao. Xử lý tập trung qua FrontendBlogRepository mapping các bảng tl_blogs, tl_blog_categories, tl_blog_tags.

Method	Endpoint	Controller@Action	Params	Mô tả Chi Tiết Cơ Sở Dữ Liệu
`GET`	`/posts`	`FrontendBlogController@blogs`	`page`, `per_page`	Danh sách bài viết tổng hợp hiển thị giao diện phân trang Grid/List hỗn hợp.
`GET`	`/blogs`	`FrontendBlogController@getBlogsPagination`	`page`, `category_id`	API (JSON) trả về phân trang dữ liệu bài viết chuẩn JSON phục vụ tính năng "Load More" (Ajax Scroll) mà không chuyển trang.
`GET`	`/blogs-search`	`FrontendBlogController@findBlogsPagination`	`q` (từ khóa)	API (JSON) truy xuất tìm kiếm LIKE %q% bài viết theo title, sapo hoặc content. Trả về format thẻ bài viết.
`GET`	`/{prefix}/{permalink}`	`FrontendBlogController@blogByCategory`	-	Router động Truy xuất bài viết theo URL Category (VD: `/danh-muc/the-thao`). Query Model cấu trúc Parent-Child.
`GET`	`/{prefix}/video`	`FrontendBlogController@blogByVideo`	-	Lọc và trả cấu trúc các bài viết chỉ chứa format Video.
`GET`	`/{tag_prefix}/{permalink}`	`FrontendBlogController@blogByTag`	-	Truy vấn các bài viết map với Models `TlBlogTag` thông qua khóa ngoại (VD: `/tag/bong-da-anh`).
`GET`	`/search/{text}`	`FrontendBlogController@blogBySearch`	-	UI Trang hiển thị các kết quả truy vấn Full-text search toàn website.
`GET`	`/author/{name}`	`FrontendBlogController@blogByAuthor`	-	Filter các bài viết được xuất bản (Publish) bởi một Account của Author cụ thể (Bảng `users`).
`GET`	`/filter/{filter}`	`FrontendBlogController@blogByFilter`	`filter=popular/recent`	Lọc và sắp xếp nội dung Bài viết Nổi bật (views count lớn), Phổ biến, hoặc Cũ hơn qua Query Builder.
`GET`	`/{permalink}`	`FrontendController@pageOrBlogDetails`	-	Core Router Catch-all: Render chi tiết. Server tiến hành First-check trong DB bảng `tl_pages` (ưu tiên Page tĩnh trước), nếu Fail => truy vấn vào `tl_blogs`.
`GET`	`/v2/{permalink}`	`FrontendBlogController@blogDetailsV2`	-	Render giao diện Detail Bài viết Version 2 (Template Modern/Sport Layout).
`POST`	`/post/password/load`	`FrontendBlogController@getBlogContent`	`id`, `password`	Nhập mật khẩu để mở khóa bài viết có thuộc tính Protected. Server check đúng Pass => Tạo session valid -> return HTML Content qua AJAX.
`POST`	`/page/password/load`	`FrontendController@getPageContent`	`id`, `password`	Mở khóa riêng cho định dạng cấu trúc Page Protected tĩnh (tương tự như trên).
`POST`	`/post/comment`	`FrontendBlogController@loadBlogComment`	`blog_id`, `page`	API load danh sách Comment cho một tin tức. Dữ liệu JOIN bảng `users` + `tl_blog_comments` (Kèm tính năng Nested).
`POST`	`/post/comment/create`	`FrontendBlogController@createBlogComment`	`blog_id`, `comment`, `parent_id`	Nhận Submit bình luận con/cha. Model tạo record mới trạng thái Pending/Publish tùy biến Config của Web.

32.1.3. Module Widgets & API Page Builder Data

Method	Endpoint	Controller Node	Trả về / Mô Tả Logic
`GET`	`/ajax/pagebuilder/league-rank`	`ProxyController@leagueRank`	Gọi ProxyAPI truy xuất / Caching dữ liệu Bảng xếp hạng các giải đấu Thể Thao (Bóng đá) từ Helper `SportsDataHelper`.
`GET`	`/ajax/pagebuilder/hot-tips`	`ProxyController@hotTips`	Trả về chuỗi nhận định, tips nóng hổi của các chuyên gia để nhúng UI vào Widget Page Builder.
`POST`	`/heatmap/click`	`HeatmapClickController@store`	Nhận fetch từ Client log lại sự kiện user Click (Tham số nhận: Tọa độ ngầm X-Y, User-Agent Browser, Window Width). Ghi DB `heatmap_clicks`.
`GET`	`/heatmap/grid`	`HeatmapClickController@grid`	Trả ma trận dữ liệu tọa độ (Array point clusters) theo Filter để Frontend Vẽ lớp Heatmap Overlay.

32.2. MODULE AUTHENTICATION & USER PORTAL

Nhóm API liên quan đến quản lý thành viên đăng ký website, đòi hỏi Middleware Check Authentication (auth, user.guard). Tương tác Models: User, Role.

32.2.1. Tài khoản & Đăng nhập (Auth Controller)

Method	Endpoint	Controller@Action	Chi Tiết Nghiệp Vụ Cốt Lõi
`GET`	`/user/login`	`UserController@login`	Trả UI giao diện đăng nhập dành riêng Frontend User (tách biệt cổng Admin).
`POST`	`/user/login-submit`	`UserController@attemptLogin`	Post credentials (`email`/`password`). Auth Attempt -> Nếu hợp lệ Record nhật ký Event login vào bảng `activity_log` -> Trả về Session cookie.
`GET`	`/user/registration`	`UserController@registration`	Request UI trang đăng ký.
`POST`	`/user/registration-submit`	`UserController@registrationSubmit`	Nhận dữ liệu Create User: Auto sinh mã hóa mật khẩu Hash bcrypt, Check Unique Username/Email, Gán Role Default là `User`.
`GET`	`/user/auth/{provider}`	`SocialAuthController@redirectToProvider`	Khởi tạo OAuth2 thông qua Provider (`google`, `facebook`). Server gọi SDK sinh URL ủy quyền Redirect và gửi về Client.
`GET`	`/user/auth/{provider}/callback`	`SocialAuthController@handleProviderCallback`	Máy chủ nhận Auth Code JWT từ Provider, gọi API truy xuất Email & Profile; Kiểm tra nếu tồn tại Email thì mapping login, chưa có thì tạo mới Auto User.
`GET`	`/user/logout`	`UserController@logout`	Hủy toàn bộ User Session Key, Cookie Token, Redirect về vị trí trang chủ.

32.2.2. Dashboard & Cá nhân người dùng

Method	Endpoint	Payload Request / Mô tả
`GET`	`/user/dashboard`	Cổng chính Admin Portal mini cho user: Aggregate Thống kê số block Comments, số Reading Lists saved.
`GET`	`/user/profile`	API Endpoint nội bộ load form view Thông tin Bio cá nhân, SĐT, Data Contact.
`POST`	`/user/update-profile/{user}`	Multipart Upload formData: Chứa ảnh Avatar (Lưu server/S3), chỉnh sửa các Profile strings.
`POST`	`/user/update-password/{user}`	Request `{ old_pass, new_pass, confirm_pass }`. Backend compare bcrypt password cũ, validate chuỗi mật khẩu mới, update.
`GET`	`/user/comments`	Fetch lịch sử toàn phần của tất cả Comments user đã đăng tải. Tính năng hỗ trợ user quản lý bình luận.
`POST`	`/user/readingList/update`	Nhận param `blog_id`. Chức năng "Lưu bài viết Đọc sau" (Bookmark). Insert/Update DB record vào bảng `tl_reading_lists` liên kết relation ID User.
`DELETE`	`/user/readingList/remove`	Nhận param `blog_id`. Remove mapping Foreign Key (Blog-User) lưu ở bảng `tl_reading_lists`.

32.3. BACKEND API ADMIN CORE (CMS SYSTEM)

Nhóm chức năng chỉ định dành cho Ban Quản Trị Website. Chặn ngặt nghèo bởi Middleware bảo mật: auth, admin.guard, Role/Permission. Tiền tố Prefix chung: /admin/....

32.3.1. Content Management (Blog / Page / Thư viện)

Method	Thực Thể Routing	Luồng thực thi (Nghiệp vụ Controller thao tác)
`GET/POST`	Quản lý Posts (`core.blog`)	Thêm, xem, publish, chỉnh sửa status bài viết. (Sử dụng Model TlBlog). Lưu thông tin Taxonomies, Tags, Meta Seo.
`PUT/DEL`	Cập nhật/Xóa Blog (`core.update.blog`)	Thao tác Modify bài viết. Nếu xóa (Force/Soft Delete) thì tích hợp Bulk Delete Data qua Repository.
`REST`	Quản lý Category (`core.blog.category`)	CRUD cho hệ thống Danh mục. Nested Set Data Hierarchy (Parent - Child levels).
`REST`	Quản lý Page tĩnh (`core.page`)	Tạo Page độc lập (Ex: Giới thiệu chung), render qua JSON config của Newslooks Page Builder plugin.
`GET/POST`	Media Editor (`core.media.page`)	Tool quản lý Media. Upload hình ảnh -> Resize server sinh các variants image size (VD: thumb, lagre). Lưu vào `uploaded_files`.
`POST/DEL`	Duyệt Comment (`core.blog.comment`)	Panel quản lý Comment người dùng: Cho hiển thị/Ẩn, Reply ẩn danh Admin.
`POST`	Track Lịch Sử (`core.blog.history.compare`)	Tra lại lịch sử thay đổi Revisions của bài đăng, diff compare chuỗi text (Cấu trúc Log Changes), Trigger rollback.

32.3.2. Setting & System Configurations

Method	Route Name / Logic Handle	Module Thao tác / Kết quả
`POST`	Cấu hình SMTP (`core.email.smtp.configuration`)	Lưu cấu hình cổng Email gửi đi (Host, Port, User, Password_app, SSL/TLS). Test Mail SMTP trực tiếp (Bắt lỗi Exception Socket).
`POST`	Setting SEO tổng thể (`core.seo.settings`)	Setting Meta Title, Description, Image OpenGraph chung mặc định của toàn trang.
`REST`	Multi-language (`core.languages`)	Quản lý Resource JSON Language pack (`front_translate`). Ghi đè file dịch / Quản trị key.
`GET`	Quản trị Plugin (`core.plugins.index`)	Xem thông tin Plugin system, License verification checking, Status of active features.
`GET/POST`	Menu Builder (`core.manage.menus`)	Công cụ Builder Header/Footer dạng kéo thả Drag/Drop cấp bậc nested-tree (Node cha con) và Sync DB.
`REST`	Quản trị Banner (`core.ads.list`)	CRUD list danh sách Custom Quảng cáo (Header Ad, Sidebar Ad) qua các Slot Banner code injection.

32.4. MODULES NÂNG CAO ĐẶC TRƯNG - NEWSLOOKS ENGINE

Các tiện ích tối thượng tạo nên lợi thế quản lý của hệ thống: Auto Crawler, Auto AI Rewrite, Tự động Internal Link và Tích hợp Proxy.

32.4.1. Crawler - Hệ thống Cào Dữ Liệu Tự Động (CronJobs)

Controller core: CrawlJobController, CrawlNewsJob

Models thao tác: CrawlJob, CrawlImage, các pattern Crawler (DailyStrategy, LinkPagination).

Method	Endpoint Workflow (`/admin/crawl-jobs...`)	Mô tả Data Flow chi tiết
`GET`	`/`	Fetch & Render DataTables JSON các bản ghi cấu hình Job đang chạy (`tl_crawl_jobs`).
`GET/POST`	`/add` & `POST /`	Add/Update Crawler Job config: Map Config Target URL, thiết lập CSS Selectors (Title/Body/Time), set Tần suất (Cron rate), set Pagination (Next url / Load more), Map setting vào AI Content Modifier.
`POST`	`/preview`	Tool Submit Config -> Máy chủ thực thi Guzzle Request 1 bài ngẫu nhiên -> Cào Body -> Render thử UI trả về Browser cho Admin test trước khi Apply.
`GET`	`/dashboard`	Tổng hợp Chart Statistic: Số Queue đã chạy, % Error Catching Logs, Timeline jobs qua JSON feed.
`POST`	`/{id}/force-run-ai`	Triggler bắt máy chủ khởi chạy Worker AI Assistant ép buộc theo Job thủ công mà không cần chờ Timer Cronjob.
`GET`	`/{id}/status`	Endpoint định dạng Ajax Request Pooling: Client sẽ gọi 3s/1 lần để render Job Progress Bar đang cào.
`POST`	`/{id}/toggle-active`	Action bật / tắt trạng thái (Boolean) dừng cào hoặc tiếp tục cào định kỳ.

32.4.2. Lõi Trợ Lý AI (AI Content Generator & Rewriter)

Controller core: AIAssistantController

Tác động Models/Bảng: open_ai_settings, ai_api_logs.

Method	Thực thể Endpoint Data	Xử Lý Máy Chủ Lõi (Behind The Scenes)
`GET/POST`	`/admin/ai-settings` `core.blog.ai.setting`	Load & Config (1 Row) ở database cho API Keys, Model ID Default (VD: `gpt-4o-mini`), Model chuyên trách (Translate Node, Rewrite Node). Quản trị JSON Prompts. Webhook Mattermost setup.
`POST/PUT`	`/admin/generate-content-with-ai`	Manual mode: Trình duyệt bắn chuỗi Content qua Axios -> Server Build prompt theo cấu hình -> Call Model API (VD OpenAI) -> Wait stream -> Generate Result Push back trực tiếp qua Editor UI.
`GET`	`/admin/crawl-ai`	Auto mode: Cronjob trigger -> Server select Batch (VD: 5 bài cần cào Crawler chưa Modify) -> Build Workspace Chain API -> Translate Tone/Rewrite -> Map fallback Models (Nếu model 1 tạch server limit -> dùng model 2) -> Kết thúc gọi CURL Notify chốt Mattermost báo cáo Status. Update blog table.
`GET`	`/admin/crawl-news/{id}`	Lệnh Call API chạy độc quyền 1 Job Scraping chỉ định.
`GET`	`/admin/update-crawl-images`	Background API Worker scan bảng `crawl_images`, call Image URLs -> Storage vật lý -> Sync records map vào Media Manager DB và replace domain nội bộ vào Post Content HTML.
`GET/DEL`	`/admin/ai-logs` / `{logId}`	Module Audit: Ghi Data Tracking Call API request Payload/Response JSON Body, calculate lượng Token Input/Output tiêu hao -> Sinh Report Log hiển thị (Bảng `ai_api_logs`).

32.4.3. Quản Lý Liên Kết Nội Bộ Tự Động (Auto Internal Link)

Controller core: InternalLinkController

Mục tiêu: Tối ưu SEO On-Page bằng cách Cấu hình [Từ khóa] -> [URL liên kết], hệ thống tự Match content và replace Regex HTML thành Tag <a> hiển thị cho Client.

Method	Endpoint	Quy Trình Chức Năng
`GET/POST`	`/admin/internal-links`	Quản trị CRUD Table Mapping: Keyword Target -> Anchortext Link URL. Tùy chọn rule DoFollow/NoFollow.
`POST`	`/admin/internal-links/toggle-status`	API Pause/Resume cắm cờ Disable tạm thời cho 1 Rule từ khóa (Update Boolean `status`).
`GET/POST`	`/admin/internal-links/settings`	API form lưu config Server limits: Giới hạn tối đa số liên kết chèn tự động trên mỗi bài Content (VD: Tối đa 3 Link khác nhau).
`POST`	`/admin/internal-links/test`	Input Sandbox String Text -> Server gọi Service `InternalLinkProcessor` -> Chạy thuật toán Regex tránh thẻ HTML tồn tại `(<a,...>)` -> Trả Output Text chèn Tag `<a>` thử.
`POST`	`/admin/internal-links/preview-blog`	Input Blog ID -> Lấy content thật truy cập -> Pass qua Processor -> Render thử HTML. Cho Admin xem preview trước khi chèn để soi Layout.
`POST`	`/admin/internal-links/import-csv`	Handle file Upload Bulk: Parse dạng file CSV, import insert hàng ngàn Rules Keyword Mapping 1 lúc.

32.4.4. Thống Kê, System Tools & File Tiện Ích Hành Cấp

Trách nhiệm bảo vệ: Root Admin level.

Method	Routing API / System Handle	Hệ Sinh Thái Phân Tích & Bảo Trì
`GET`	`/admin/analytics`	Fetch Dashboard Graph Chart phân tích chỉ số web traffic Real-time (Truy xuất `tl_visitors`).
`POST`	`/admin/website-visitor-reports`	Endpoint lọc Data Export / Table list Logs chi tiết Logs Session vào web.
`POST`	`/admin/country-reports`, `browser...`	Aggregation Query -> Trả JSON Data biểu đồ tròn phân hóa Device (Mobile/PC), Country Map traffic.
`POST`	`core.content-replace.preview`	Tiện ích Update Mass Content: Truy vấn `Tìm (Old String) -> Thay (New String)`. Sử dụng Regex LIKE %. API sẽ Scan Content toàn DB xem có bao Record đang dính Cụm từ Cũ để Preview List.
`POST`	`core.content-replace.execute`	Action thực thi Lệnh REPLACE Database Query (`UPDATE fields SET content = REPLACE(content, 'old', 'new')`) -> Refresh Cache hệ thống.
`GET/POST`	System Backup (`/admin/backup..`)	Server Module gọi Command Line / Shell Command để Zip source code (`generate-backup-file`) hoặc dump Database tables SQL (`generate-database-backup`). Trả Response file .zip, .sql header Stream force Download. Xóa vật lý Backup sau lệnh Delete.

32.4.5. Quản Trị Hệ Thống Visual Theo Component (Theme Options / Widgets)

Cốt lõi của Framework System Page Builder kéo thả. Quản trị phân tách API JSON config Option cho Frontend Indexer.

Method	API Server Hook	Giao Việc Layout Frontend
`GET/POST`	`/admin/manage-widgets`	Component Hub UI. Trả Layout UI kéo thả các Widgets đăng ký từ Backend.
Các view templates backend core nằm trong `Core/Views/base/`:

View	Mô tả
`blog/settings/ai_setting.blade.php`	AI settings page
`blog/settings/ai_compare.blade.php`	AI content comparison
`blog/ai_logs.blade.php`	AI logs listing
`blog/history_detail.blade.php`	Blog history detail
`media/partial/media_details_side_bar.blade.php`	Media details sidebar
`media/partial/media_details_pop_up.blade.php`	Media details popup
`email/email_templates/*.blade.php`	Email templates
`email/smtp/test_mail.blade.php`	Test email template
`errors/theme_required_plugin_failed.blade.php`	Error - missing plugin
`base/sitemap/sitemap.blade.php`	Sitemap view
`base/system/update/system_update.blade.php`	System update page
`base/license/*.blade.php`	License pages
`base/welcome/index.blade.php`	Welcome page

33. TÀI LIỆU BÀN GIAO CHI TIẾT API & ENDPOINTS (API DOCS)

Tài liệu thích hợp để Import vào Apidog (dạng Article/Document), hoặc dùng làm tài liệu tham chiếu mã nguồn trực tiếp cho Front-end & Back-end Developer.

33.1. FRONTEND & PUBLIC ENDPOINTS

33.1.1. Core Pages & Utilities (Tiện ích và Dữ liệu chung)

Method	Endpoint	Controller@Action (Route Name)	Payload / Query Params	Mô tả Chi Tiết Cốt Lõi
`GET`	`/`	`FrontendController@index` (home)	-	Render Homepage (Trang chủ) sử dụng hệ thống Widget Page Builder đọc cấu hình từ file JSON Theme Options. Kích hoạt Tracking visitor.
`GET`	`/chinh-sach-bao-mat`	`FrontendController@privacyPolicy`	-	Truy xuất nội dung trang tĩnh (Page): Chính sách bảo mật. Gọi model `TlPage`.
`GET`	`/dieu-khoan-su-dung`	`FrontendController@termsOfService`	-	Truy xuất nội dung trang tĩnh (Page): Điều khoản. Gọi model `TlPage`.
`POST`	`/language-change`	`FrontendController@changeLanguage` (theme.newslooks.language.change)	`{ lang: string }`	Thay đổi ngôn ngữ hiển thị giao diện Frontend. Setup biến Session/Cookie locale rồi return back.
`GET`	`/sitemap.xml`	`SystemController@serveSitemap` (core.sitemap)	-	Đọc file XML nội bộ hoặc sinh tự động Sitemap cho Google/Bing Bots quét bài phục vụ SEO.
`GET`	`/exchange-rate`	`ExchangeRateController`	-	API proxy trả về tỉ giá ngoại hối theo thời gian thực (Dữ liệu cache Redis/DB từ API Bank).
`GET`	`/location-city`	`FrontendController`	`?search=keyword`	Trả về danh sách thành phố/vị trí địa lý theo format mảng JSON phục vụ auto-fill dropdown.
`POST`	`/contact/submit`	`FrontendController@sendMessage` (theme.newslooks.contact.submit)	`name`, `email`, `subject`, `message`	User gửi form liên hệ. Chức năng lưu vào DB contact và gửi E-Mail trực tiếp tới Admin qua SMTP Mailer.
`POST`	`/newsletter/store`	`NewsletterController@store` (theme.newslooks.newsletter.store)	`email`	User đăng ký nhận email bản tin. Lưu danh sách DB nội bộ và tự động gọi API đẩy vào List Mailchimp nếu cấu hình hoạt động.
`POST`	`/poll-vote`	`FrontendController@vote` (theme.newslooks.vote.give)	`poll_id`, `option_id`	Tham gia bình chọn (Poll/Voting). Validate 1 IP / 1 Option, cập nhật bảng Model `VoteCount`.

33.1.2. Module Hệ Thống Bài Viết (Blog & Category)

Nhóm API chuyên xử lý dữ liệu tin tức thể thao. Xử lý tập trung qua FrontendBlogRepository mapping các bảng tl_blogs, tl_blog_categories, tl_blog_tags.

Method	Endpoint	Controller@Action	Params	Mô tả Chi Tiết Cơ Sở Dữ Liệu
`GET`	`/posts`	`FrontendBlogController@blogs`	`page`, `per_page`	Danh sách bài viết tổng hợp hiển thị giao diện phân trang Grid/List hỗn hợp.
`GET`	`/blogs`	`FrontendBlogController@getBlogsPagination`	`page`, `category_id`	API (JSON) trả về phân trang dữ liệu bài viết chuẩn JSON phục vụ tính năng "Load More" (Ajax Scroll) mà không chuyển trang.
`GET`	`/blogs-search`	`FrontendBlogController@findBlogsPagination`	`q` (từ khóa)	API (JSON) truy xuất tìm kiếm LIKE %q% bài viết theo title, sapo hoặc content. Trả về format thẻ bài viết.
`GET`	`/{prefix}/{permalink}`	`FrontendBlogController@blogByCategory`	-	Router động Truy xuất bài viết theo URL Category (VD: `/danh-muc/the-thao`). Query Model cấu trúc Parent-Child.
`GET`	`/{prefix}/video`	`FrontendBlogController@blogByVideo`	-	Lọc và trả cấu trúc các bài viết chỉ chứa format Video.
`GET`	`/{tag_prefix}/{permalink}`	`FrontendBlogController@blogByTag`	-	Truy vấn các bài viết map với Models `TlBlogTag` thông qua khóa ngoại (VD: `/tag/bong-da-anh`).
`GET`	`/search/{text}`	`FrontendBlogController@blogBySearch`	-	UI Trang hiển thị các kết quả truy vấn Full-text search toàn website.
`GET`	`/author/{name}`	`FrontendBlogController@blogByAuthor`	-	Filter các bài viết được xuất bản (Publish) bởi một Account của Author cụ thể (Bảng `users`).
`GET`	`/filter/{filter}`	`FrontendBlogController@blogByFilter`	`filter=popular/recent`	Lọc và sắp xếp nội dung Bài viết Nổi bật (views count lớn), Phổ biến, hoặc Cũ hơn qua Query Builder.
`GET`	`/{permalink}`	`FrontendController@pageOrBlogDetails`	-	Core Router Catch-all: Render chi tiết. Server tiến hành First-check trong DB bảng `tl_pages` (ưu tiên Page tĩnh trước), nếu Fail => truy vấn vào `tl_blogs`.
`GET`	`/v2/{permalink}`	`FrontendBlogController@blogDetailsV2`	-	Render giao diện Detail Bài viết Version 2 (Template Modern/Sport Layout).
`POST`	`/post/password/load`	`FrontendBlogController@getBlogContent`	`id`, `password`	Nhập mật khẩu để mở khóa bài viết có thuộc tính Protected. Server check đúng Pass => Tạo session valid -> return HTML Content qua AJAX.
`POST`	`/page/password/load`	`FrontendController@getPageContent`	`id`, `password`	Mở khóa riêng cho định dạng cấu trúc Page Protected tĩnh (tương tự như trên).
`POST`	`/post/comment`	`FrontendBlogController@loadBlogComment`	`blog_id`, `page`	API load danh sách Comment cho một tin tức. Dữ liệu JOIN bảng `users` + `tl_blog_comments` (Kèm tính năng Nested).
`POST`	`/post/comment/create`	`FrontendBlogController@createBlogComment`	`blog_id`, `comment`, `parent_id`	Nhận Submit bình luận con/cha. Model tạo record mới trạng thái Pending/Publish tùy biến Config của Web.

33.1.3. Module Widgets & API Page Builder Data

| Method | Endpoint | Controller Node | Trả về / Mô Tả Logic |
|---|---|---|
| GET | /ajax/pagebuilder/league-rank| ProxyController@leagueRank | Gọi ProxyAPI truy xuất / Caching dữ liệu Bảng xếp hạng các giải đấu Thể Thao (Bóng đá) từ Helper SportsDataHelper. |
| GET | /ajax/pagebuilder/hot-tips | ProxyController@hotTips | Trả về chuỗi nhận định, tips nóng hổi của các chuyên gia để nhúng UI vào Widget Page Builder. |
| POST| /heatmap/click | HeatmapClickController@store | Nhận fetch từ Client log lại sự kiện user Click (Tham số nhận: Tọa độ ngầm X-Y, User-Agent Browser, Window Width). Ghi DB heatmap_clicks. |
| GET | /heatmap/grid | HeatmapClickController@grid | Trả ma trận dữ liệu tọa độ (Array point clusters) theo Filter để Frontend Vẽ lớp Heatmap Overlay. |

33.2. MODULE AUTHENTICATION & USER PORTAL

Nhóm API liên quan đến quản lý thành viên đăng ký website, đòi hỏi Middleware Check Authentication (auth, user.guard). Tương tác Models: User, Role.

33.2.1. Tài khoản & Đăng nhập (Auth Controller)

Method	Endpoint	Controller@Action	Chi Tiết Nghiệp Vụ Cốt Lõi
`GET`	`/user/login`	`UserController@login`	Trả UI giao diện đăng nhập dành riêng Frontend User (tách biệt cổng Admin).
`POST`	`/user/login-submit`	`UserController@attemptLogin`	Post credentials (`email`/`password`). Auth Attempt -> Nếu hợp lệ Record nhật ký Event login vào bảng `activity_log` -> Trả về Session cookie.
`GET`	`/user/registration`	`UserController@registration`	Request UI trang đăng ký.
`POST`	`/user/registration-submit`	`UserController@registrationSubmit`	Nhận dữ liệu Create User: Auto sinh mã hóa mật khẩu Hash bcrypt, Check Unique Username/Email, Gán Role Default là `User`.
`GET`	`/user/auth/{provider}`	`SocialAuthController@redirectToProvider`	Khởi tạo OAuth2 thông qua Provider (`google`, `facebook`). Server gọi SDK sinh URL ủy quyền Redirect và gửi về Client.
`GET`	`/user/auth/{provider}/callback`	`SocialAuthController@handleProviderCallback`	Máy chủ nhận Auth Code JWT từ Provider, gọi API truy xuất Email & Profile; Kiểm tra nếu tồn tại Email thì mapping login, chưa có thì tạo mới Auto User.
`GET`	`/user/logout`	`UserController@logout`	Hủy toàn bộ User Session Key, Cookie Token, Redirect về vị trí trang chủ.

33.2.2. Dashboard & Cá nhân người dùng

Method	Endpoint	Payload Request / Mô tả
`GET`	`/user/dashboard`	Cổng chính Admin Portal mini cho user: Aggregate Thống kê số block Comments, số Reading Lists saved.
`GET`	`/user/profile`	API Endpoint nội bộ load form view Thông tin Bio cá nhân, SĐT, Data Contact.
`POST`	`/user/update-profile/{user}`	Multipart Upload formData: Chứa ảnh Avatar (Lưu server/S3), chỉnh sửa các Profile strings.
`POST`	`/user/update-password/{user}`	Request `{ old_pass, new_pass, confirm_pass }`. Backend compare bcrypt password cũ, validate chuỗi mật khẩu mới, update.
`GET`	`/user/comments`	Fetch lịch sử toàn phần của tất cả Comments user đã đăng tải. Tính năng hỗ trợ user quản lý bình luận.
`POST`	`/user/readingList/update`	Nhận param `blog_id`. Chức năng "Lưu bài viết Đọc sau" (Bookmark). Insert/Update DB record vào bảng `tl_reading_lists` liên kết relation ID User.
`DELETE`	`/user/readingList/remove`	Nhận param `blog_id`. Remove mapping Foreign Key (Blog-User) lưu ở bảng `tl_reading_lists`.

33.3. BACKEND API ADMIN CORE (CMS SYSTEM)

Nhóm chức năng chỉ định dành cho Ban Quản Trị Website. Chặn ngặt nghèo bởi Middleware bảo mật: auth, admin.guard, Role/Permission. Tiền tố Prefix chung: /admin/....

33.3.1. Content Management (Blog / Page / Thư viện)

Method	Thực Thể Routing	Luồng thực thi (Nghiệp vụ Controller thao tác)
`GET/POST`	Quản lý Posts (`core.blog`)	Thêm, xem, publish, chỉnh sửa status bài viết. (Sử dụng Model TlBlog). Lưu thông tin Taxonomies, Tags, Meta Seo.
`PUT/DEL`	Cập nhật/Xóa Blog (`core.update.blog`)	Thao tác Modify bài viết. Nếu xóa (Force/Soft Delete) thì tích hợp Bulk Delete Data qua Repository.
`REST`	Quản lý Category (`core.blog.category`)	CRUD cho hệ thống Danh mục. Nested Set Data Hierarchy (Parent - Child levels).
`REST`	Quản lý Page tĩnh (`core.page`)	Tạo Page độc lập (Ex: Giới thiệu chung), render qua JSON config của Newslooks Page Builder plugin.
`GET/POST`	Media Editor (`core.media.page`)	Tool quản lý Media. Upload hình ảnh -> Resize server sinh các variants image size (VD: thumb, lagre). Lưu vào `uploaded_files`.
`POST/DEL`	Duyệt Comment (`core.blog.comment`)	Panel quản lý Comment người dùng: Cho hiển thị/Ẩn, Reply ẩn danh Admin.
`POST`	Track Lịch Sử (`core.blog.history.compare`)	Tra lại lịch sử thay đổi Revisions của bài đăng, diff compare chuỗi text (Cấu trúc Log Changes), Trigger rollback.

33.3.2. Setting & System Configurations

Method	Route Name / Logic Handle	Module Thao tác / Kết quả
`POST`	Cấu hình SMTP (`core.email.smtp.configuration`)	Lưu cấu hình cổng Email gửi đi (Host, Port, User, Password_app, SSL/TLS). Test Mail SMTP trực tiếp (Bắt lỗi Exception Socket).
`POST`	Setting SEO tổng thể (`core.seo.settings`)	Setting Meta Title, Description, Image OpenGraph chung mặc định của toàn trang.
`REST`	Multi-language (`core.languages`)	Quản lý Resource JSON Language pack (`front_translate`). Ghi đè file dịch / Quản trị key.
`GET`	Quản trị Plugin (`core.plugins.index`)	Xem thông tin Plugin system, License verification checking, Status of active features.
`GET/POST`	Menu Builder (`core.manage.menus`)	Công cụ Builder Header/Footer dạng kéo thả Drag/Drop cấp bậc nested-tree (Node cha con) và Sync DB.
`REST`	Quản trị Banner (`core.ads.list`)	CRUD list danh sách Custom Quảng cáo (Header Ad, Sidebar Ad) qua các Slot Banner code injection.

33.4. MODULES NÂNG CAO ĐẶC TRƯNG - NEWSLOOKS ENGINE

Các tiện ích tối thượng tạo nên lợi thế quản lý của hệ thống: Auto Crawler, Auto AI Rewrite, Tự động Internal Link và Tích hợp Proxy.

33.4.1. Crawler - Hệ thống Cào Dữ Liệu Tự Động (CronJobs)

Controller core: CrawlJobController, CrawlNewsJob

Models thao tác: CrawlJob, CrawlImage, các pattern Crawler (DailyStrategy, LinkPagination).

Method	Endpoint Workflow (`/admin/crawl-jobs...`)	Mô tả Data Flow chi tiết
`GET`	`/`	Fetch & Render DataTables JSON các bản ghi cấu hình Job đang chạy (`tl_crawl_jobs`).
`GET/POST`	`/add` & `POST /`	Add/Update Crawler Job config: Map Config Target URL, thiết lập CSS Selectors (Title/Body/Time), set Tần suất (Cron rate), set Pagination (Next url / Load more), Map setting vào AI Content Modifier.
`POST`	`/preview`	Tool Submit Config -> Máy chủ thực thi Guzzle Request 1 bài ngẫu nhiên -> Cào Body -> Render thử UI trả về Browser cho Admin test trước khi Apply.
`GET`	`/dashboard`	Tổng hợp Chart Statistic: Số Queue đã chạy, % Error Catching Logs, Timeline jobs qua JSON feed.
`POST`	`/{id}/force-run-ai`	Triggler bắt máy chủ khởi chạy Worker AI Assistant ép buộc theo Job thủ công mà không cần chờ Timer Cronjob.
`GET`	`/{id}/status`	Endpoint định dạng Ajax Request Pooling: Client sẽ gọi 3s/1 lần để render Job Progress Bar đang cào.
`POST`	`/{id}/toggle-active`	Action bật / tắt trạng thái (Boolean) dừng cào hoặc tiếp tục cào định kỳ.

33.4.2. Lõi Trợ Lý AI (AI Content Generator & Rewriter)

Controller core: AIAssistantController

Tác động Models/Bảng: open_ai_settings, ai_api_logs.

Method	Thực thể Endpoint Data	Xử Lý Máy Chủ Lõi (Behind The Scenes)
`GET/POST`	`/admin/ai-settings` `core.blog.ai.setting`	Load & Config (1 Row) ở database cho API Keys, Model ID Default (VD: `gpt-4o-mini`), Model chuyên trách (Translate Node, Rewrite Node). Quản trị JSON Prompts. Webhook Mattermost setup.
`POST/PUT`	`/admin/generate-content-with-ai`	Manual mode: Trình duyệt bắn chuỗi Content qua Axios -> Server Build prompt theo cấu hình -> Call Model API (VD OpenAI) -> Wait stream -> Generate Result Push back trực tiếp qua Editor UI.
`GET`	`/admin/crawl-ai`	Auto mode: Cronjob trigger -> Server select Batch (VD: 5 bài cần cào Crawler chưa Modify) -> Build Workspace Chain API -> Translate Tone/Rewrite -> Map fallback Models (Nếu model 1 tạch server limit -> dùng model 2) -> Kết thúc gọi CURL Notify chốt Mattermost báo cáo Status. Update blog table.
`GET`	`/admin/crawl-news/{id}`	Lệnh Call API chạy độc quyền 1 Job Scraping chỉ định.
`GET`	`/admin/update-crawl-images`	Background API Worker scan bảng `crawl_images`, call Image URLs -> Storage vật lý -> Sync records map vào Media Manager DB và replace domain nội bộ vào Post Content HTML.
`GET/DEL`	`/admin/ai-logs` / `{logId}`	Module Audit: Ghi Data Tracking Call API request Payload/Response JSON Body, calculate lượng Token Input/Output tiêu hao -> Sinh Report Log hiển thị (Bảng `ai_api_logs`).

33.4.3. Quản Lý Liên Kết Nội Bộ Tự Động (Auto Internal Link)

Controller core: InternalLinkController

Mục tiêu: Tối ưu SEO On-Page bằng cách Cấu hình [Từ khóa] -> [URL liên kết], hệ thống tự Match content và replace Regex HTML thành Tag <a> hiển thị cho Client.

Method	Endpoint	Quy Trình Chức Năng
`GET/POST`	`/admin/internal-links`	Quản trị CRUD Table Mapping: Keyword Target -> Anchortext Link URL. Tùy chọn rule DoFollow/NoFollow.
`POST`	`/admin/internal-links/toggle-status`	API Pause/Resume cắm cờ Disable tạm thời cho 1 Rule từ khóa (Update Boolean `status`).
`GET/POST`	`/admin/internal-links/settings`	API form lưu config Server limits: Giới hạn tối đa số liên kết chèn tự động trên mỗi bài Content (VD: Tối đa 3 Link khác nhau).
`POST`	`/admin/internal-links/test`	Input Sandbox String Text -> Server gọi Service `InternalLinkProcessor` -> Chạy thuật toán Regex tránh thẻ HTML tồn tại `(<a,...>)` -> Trả Output Text chèn Tag `<a>` thử.
`POST`	`/admin/internal-links/preview-blog`	Input Blog ID -> Lấy content thật truy cập -> Pass qua Processor -> Render thử HTML. Cho Admin xem preview trước khi chèn để soi Layout.
`POST`	`/admin/internal-links/import-csv`	Handle file Upload Bulk: Parse dạng file CSV, import insert hàng ngàn Rules Keyword Mapping 1 lúc.

33.4.4. Thống Kê, System Tools & File Tiện Ích Hành Cấp

Trách nhiệm bảo vệ: Root Admin level.

Method	Routing API / System Handle	Hệ Sinh Thái Phân Tích & Bảo Trì
`GET`	`/admin/analytics`	Fetch Dashboard Graph Chart phân tích chỉ số web traffic Real-time (Truy xuất `tl_visitors`).
`POST`	`/admin/website-visitor-reports`	Endpoint lọc Data Export / Table list Logs chi tiết Logs Session vào web.
`POST`	`/admin/country-reports`, `browser...`	Aggregation Query -> Trả JSON Data biểu đồ tròn phân hóa Device (Mobile/PC), Country Map traffic.
`POST`	`core.content-replace.preview`	Tiện ích Update Mass Content: Truy vấn `Tìm (Old String) -> Thay (New String)`. Sử dụng Regex LIKE %. API sẽ Scan Content toàn DB xem có bao Record đang dính Cụm từ Cũ để Preview List.
`POST`	`core.content-replace.execute`	Action thực thi Lệnh REPLACE Database Query (`UPDATE fields SET content = REPLACE(content, 'old', 'new')`) -> Refresh Cache hệ thống.
`GET/POST`	System Backup (`/admin/backup..`)	Server Module gọi Command Line / Shell Command để Zip source code (`generate-backup-file`) hoặc dump Database tables SQL (`generate-database-backup`). Trả Response file .zip, .sql header Stream force Download. Xóa vật lý Backup sau lệnh Delete.

33.4.5. Quản Trị Hệ Thống Visual Theo Component (Theme Options / Widgets)

Cốt lõi của Framework System Page Builder kéo thả. Quản trị phân tách API JSON config Option cho Frontend Indexer.

Method	API Server Hook	Giao Việc Layout Frontend
`GET/POST`	`/admin/manage-widgets`	Component Hub UI. Trả Layout UI kéo thả các Widgets đăng ký từ Backend.
`POST`	`/admin/get-widget-input`	Frontend Editor kéo 1 thẻ widget (Ex: Lịch thi đấu) => Component gọi Backend hỏi Fields Setting (Mã HTML Input/Select) => Trả UI Form Input Params.
`POST`	`/admin/add-widget-sidebar`	Request Hook -> Thêm Item ID Widget vào Sidebar Component Box.
`POST`	`/admin/save-sidebar-widget-form`	Trigger Serialize toàn bộ Data Parameter Form Settings thành JSON Data Base64 -> Lưu Table `tl_widgets`.
`POST`	`/admin/widget-order-save`	Update lại Index Sortable thứ tự order Box.
`POST`	`/admin/save-theme-option-form`	Ghi đè toàn bộ Setting Hệ Theme Layout Component (Color, CSS Logo, Footer Text, Layout Width) vào cache config.
`POST`	`/admin/import-theme-option`	Đón Upload JSON Option Layout -> Validate JSON Parsing -> Merge Config đè lên layout Cũ Website.

34. CHUYÊN ĐỀ SÂU: HỆ THỐNG CÀO DỮ LIỆU & TRÍ TUỆ NHÂN TẠO (CRAWLER & AI)

Hệ thống tin tức NewsLooks được trang bị công cụ tự động hóa toàn diện từ bước thu thập dữ liệu thô (Scraping) đến bước tinh chỉnh nội dung bằng trí tuệ nhân tạo (AI Assistant) chống trùng lặp dữ liệu (Plagiarism) và tối ưu SEO.

34.1. Kiến Trúc Tự Động Hóa (Automation Architecture)

Hệ thống sử dụng Laravel Task Scheduling (Console/Kernel.php) kết hợp với Supervisor / Cronjob trên máy chủ để chạy ngầm các tiến trình (Worker).

Cronjob Core: * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1

Workers hoạt động liên tục:

CrawlNewsJob: Worker quét các Website cấu hình và tiến hành Bóc tách dữ liệu (Scrape Data).

AIUpdateJob: Worker kích hoạt AI xử lý lại các dữ liệu vừa cào.

ImageSyncJob: Worker tải ngầm mảng hình ảnh từ thẻ <img src="..."> của target về thư mục /storage local.

34.2. Chi Tiết: Module Crawler (Cào Dữ Liệu Tự Động)

A. Chu trình hoạt động (Data Scraping Lifecycle)

Admin thiết lập Crawl Job qua UI (/admin/crawl-jobs/add). Cung cấp Target URL (Ví dụ trang đối thủ hoặc báo mạng RSS).

Admin test cấu hình bộ lọc CSS Selectors (Dựa trên kỹ thuật DOM Crawler / Goutte PHP DOM Parser):

Link list Selector: Vị trí Class/ID thẻ <a> chứa bài viết trong danh mục.

Title Selector: Vị trí Header <h1> trong bài.

Content Selector: Vị trí thẻ div bọc nội dung văn bản bài.

Remove Elements: Các chuỗi class/id thừa không lấy (VD: .ads-banner, .author-bio, iframe) để nội dung được sạch.

Pagination Strategy: Crawler tự bấm Next page hay bấm Load More khi chuyển trang.

Khi Cronjob chạy, Kernel check DB tìm các Job có active = 1 và frequency_time <= NOW().

Kernel Request Service CrawlerService@execute($config). Dịch vụ này fetch HTML nguồn, parse cây DOM, chạy vòng lặp bóc tách Text và lưu Array.

Record dữ liệu thô được Insert vào bảng tl_blogs với trạng thái cấu hình (Draft hoặc Pending). Cột name_crawl được ghi lại URL nguồn để hệ thống đối soát không bao giờ cào trùng URL cũ.

Toàn bộ hình ảnh External Links trong bài cào được ghi tạm vào queue bảng crawl_images chờ Worker Tải Ảnh chạy.

B. Tables & Relational Database

Bảng crawl_jobs: Lưu thiết lập selectors, interval timer, trạng thái crawl của 1 Nguồn cấu hình.

Bảng crawl_images: Queue lưu URL ảnh ngoại lai chờ download. Map theo blog_id.

C. Cấu trúc Pattern Kỹ Thuật (Crawler System Strategy)
Hệ thống áp dụng Pattern Polymorphic Strategy cho phân đoạn hành vi Crawler:

TimeStrategy: Khởi tạo Interface. Cho phép HourlyStrategy (Chạy mỗi múi giờ), DailyStrategy (Mỗi ngày lúc 0h).

PaginationStrategy: Lựa chọn loại phân trang web đích. Hỗ trợ LinkPagination (Quét dạng URL/Page=1,2,3), ClickPagination (Quét các trang dạng ajax Load More).

34.3. Chi Tiết: Module Trợ Lý AI (AI Content Generator & Rewriter)

Module cốt lõi giúp xào bài (Content Spinning) hàng loạt. Nhận text thô từ Crawler -> Phối hợp với Open AI Models hoặc Local Models qua API -> Trả về bài Text mới có chất lượng ngữ nghĩa mượt mà, chống Copy-Paste.

A. Quản Trị Hệ Mô Hình (Fallback & Workspace Context Model)
Bảng open_ai_settings lưu thông tin API Key base và Cấu trúc chuỗi Model Chain. Hệ thống tích hợp tính năng Workspace Retry Pattern.

Gọi API mồi (gpt-4o-mini). Bị lỗi (Rate limit do token hết hoặc API Timeout)? -> Fallback sang Model dự phòng (gpt-3.5-turbo) -> Tiếp tục lỗi? Fallback (claude-haiku).

Tách biệt Model chuyên môn: Admin có quyền cấp Model đắt tiền/Thanh lịch cho các thao tác khó, Model rẻ cho Text dễ:

translate_model_name: Dịch văn bản ngoại ngữ (VD crawl báo Anh) (Nhẹ nhàng, độ khó vừa, dùng Model rẻ).

content_model_name: Trực tiếp viết lại Logic Nội dung HTML (Độ khó cao, không làm vỡ HTML Tags, dùng GPT-4).

B. Workflow Chạy AI Tự Động theo Lô (Auto Batching Execution)
Quá trình diễn ra tại file AIAssistantController@updateContentBlogs.

Lấy Queue: Worker gọi DB Query SELECT các tl_blogs đang ở trạng thái Pending, có nhãn name_crawl (chứng tỏ là Hàng Cào Dữ Liệu) và ai_processed = 0 (Chưa từng chạy AI).

Chunking HTML: Controller cắt content HTML thành các chunks vừa vặn với kích cỡ Tokens của khung Context Window API, bảo vệ không làm đứt chuỗi cấu trúc HTML Tags.

Thực thi 3 Operation Vòng lặp tuần tự:

(1) Node Translation: Dịch văn bản thô ngoại ngữ về Tiếng Việt (Thông qua Prompt System cấp quyền Role Translator).

(2) Node Meta Edit: Gọi Prompt viết lại Tiêu đề {blog_title} và Tóm tắt {short_details} theo format SEO, clickbait.

(3) Node Tone Edit: Gọi Prompt tùy chỉnh giọng văn body {blog_content} (Giọng báo chí, nghiêm túc, phong cách thể thao..).

HTML DOM Parser Re-matching: Sau khi AI Response chuỗi Text. Server gọi thư viện Parser HTML DOM map lại thẻ <p>, <h2>, <img src...> để bài đăng không bị gập gốc thẻ HTML.

Finalize DB & Bot Notification:

Cập nhật bài viết lên Publish để Visitor xem.

INSERT dữ liệu báo cáo Logging vào ai_api_logs (thống kê Cost $ đã tiêu, Token In/Out, ID Model nào đã gọi).

Trigger Curl Webhook đẩy Push Notification Message đến máy chủ Chat nội bộ Mattermost thông báo: ✅ "Hoàn thành: Trợ lý AI vừa xào xong 5 bài viết cập nhật lên hệ thống thành công".

Trường hợp Crash: Báo còi khẩn: ❌ "Bot AI Error: Hệ thống API ngắt kết nối hoặc Client Hết quota Tokens Limit. Lỗi: Insufficient quota" lên Error Channel Mattermost riêng.

C. Đặc tả Bộ Prompts System Injection
Sự thông minh của NewsLooks phụ thuộc vào kiến trúc gieo Prompts (Lưu file text System Role trong DB Settings). Nó chia Role rõ ràng:

Title Rewrite Prompt: Giao Role AI: "Là một biên tập viên báo chí giật tít kỳ cựu chuyên nghiệp, hãy viết lại dòng tiêu đề ({blog_title}) giới hạn khoảng 60 từ bám sát nhất nội dung bóng đá, chuẩn SEO."

Content Rewrite Prompt: Giao Role AI: "Viết lại dựa trên dàn bài HTML định dạng. Hãy xử lý giữ nguyên tuyệt đối cấu trúc thẻ bọc hình ảnh. Trình bày nội dung với phong vị của dân thể thao châm biếm sâu sắc. Từ khóa mục tiêu: {focus_keyword}."

(Admin hoàn toàn có thể hiệu chỉnh System Role Prompting này cho từng Operation độc lập ngay trên Web Backend UI Menu /admin/ai-settings để dễ dàng đổi góc nhìn content trang web thành trang giải trí, trang tin tức chính trị hay blog bốc phốt tùy ý mà không cần đụng 1 dòng code Backend nào).

Phiên bản v1.5 API Endpoints Documentation

Tổng quan

Tài liệu Frontend - NewsLooks Theme#

1. Tổng quan#

2. Yêu cầu từ Thethaoso.online#

3. AI Settings - Chi Tiết#

3.1. Tổng quan#

3.2. Cấu trúc Fields trong open_ai_settings#

3.3. Cấu hình các nhóm settings trong AI Settings Page#

3.3.1. Enable AI Assistant#

3.3.2. Default OpenAI Model#

3.3.3. OpenAI Secret Key#

3.3.4. AI Job Settings (AI Job Configuration)#

3.3.5. Custom AI Model Configuration#

3.3.6. Mattermost Integration#

3.3.7. AI Prompts Management#

3.4. AIAssistantController - Chi tiết Methods#

3.4.1. Constructor#

3.4.2. AI Settings Management#

3.4.3. AI Content Generation (Frontend)#

3.4.4. AI Crawl/Update System (Backend)#

3.4.5. AI Logs#

3.4.6. Internal Methods (Private/Helpers)#

3.4.7. Workflow của updateContentBlogs()#

3.4.8. Mattermost Notification Flow#

3.5. AI API Logs Table Schema#

3.6. Placeholder System#

3.7. AI Config Priority Flow#

4. Phân Tích Tính Năng#

4.1. Tính năng đã có ✅#

4.2. Tính năng cần phát triển thêm ❌#

5. Cấu trúc Controller#

5.1. FrontendController (src/Http/Controllers/Frontend/FrontendController.php)#

5.2. FrontendBlogController (src/Http/Controllers/Frontend/FrontendBlogController.php)#

5.3. NewsletterController (src/Http/Controllers/Frontend/NewsletterController.php)#

6. Các Route chính#

6.1. Route công khai (không cần đăng nhập)#

6.2. Route cần đăng nhập (User)#

6.3. Route Backend (Admin)#

7. Repository Layer#

7.1. FrontendBlogRepository (src/Repositories/FrontendBlogRepository.php)#

7.2. BlogCommentRepository (src/Repositories/BlogCommentRepository.php)#

8. Middleware#

9. Tên Route (Route Names)#

10. Cấu hình URL Prefix#

11. View Files#

12. Models liên quan#

13. Helpers hỗ trợ#

14. Sports Data Integration#

14.1. SportsDataHelper (app/Helpers/SportsDataHelper.php)#

14.2. Sports Widgets (Page Builder)#

14.3. Match Schedule Widget#

15. Models & Database#

15.1. Core Models#

15.2. Theme Models#

16. API Endpoints#

16.1. Public APIs#

16.2. Blog APIs#

17. Page Builder Widgets (Toàn bộ)#

17.1. Post/Blog Widgets#

17.2. Category/Tag Widgets#

17.3. Sports Widgets#

17.4. Common Widgets#

18. Crawl Data System (Hệ thống Cào Dữ liệu)#

18.1. CrawlJobController (app/Http/Controllers/CrawlJobController.php)#

18.2. CrawlJob Model (app/Models/CrawlJob.php)#

18.3. CrawlerService (app/Services/Crawler/CrawlerService.php)#

18.4. Crawler Strategy & Pagination#

18.5. Crawl Routes (Backend)#

19. AI Update Content System#

19.1. AIAssistantController (Core/Http/Controllers/AIAssistantController.php)#

19.2. AI Settings#

19.3. AI API Logs#

19.4. AI Routes (Backend - Auth Required)#

20. Các Models Quan trọng (Core)#

21. Các Helper Functions Quan trọng#

22. Tên Route Quan trọng (Route Names)#

22.1. Core Backend Routes#

22.2. Crawl Job Routes#

22.3. Theme Backend Routes#

22.4. Heatmap & Analytics Routes#