# Xu Hướng 24

`Xu Hướng 24` là một dự án cổng thông tin và tổng hợp tin tức tự động ứng dụng trí tuệ nhân tạo (AI), tích hợp các pipeline thu thập dữ liệu tin tức tự động, quản lý tài khoản người dùng, bình luận, lưu bài viết, và trang quản trị sao lưu (backup) hệ thống toàn diện.

## Thành phần chính
- **Backend (`/backend`)**: Phát triển bằng Fastify, cung cấp hệ thống RESTful API và cơ chế kết xuất shell phía máy chủ (SSR shells) tối ưu cho SEO, kết nối trực tiếp với database Supabase.
- **Astro Frontend (`/astro-fe`)**: Giao diện người dùng chính hoạt động trên production, xây dựng bằng Astro, React và Tailwind CSS. Kết hợp hoàn hảo giữa render tĩnh (static rendering) siêu nhanh và các tính năng tương tác động.
- **Giao diện truyền thống (`/frontend`)**: Bản build giao diện tĩnh dự phòng sử dụng Eleventy, Tailwind CSS và Vanilla JS.
- **Crawler Pipelines (`/crawl`)**: Các script thu thập, xử lý và phân loại tin tức tiếng Việt tự động.

## Cơ sở dữ liệu & Công nghệ
- **Cơ sở dữ liệu**: Supabase (PostgreSQL)
- **Các bảng chính**: `users` (người dùng), `categories` (danh mục), `news` (thông tin và nội dung bài viết đã xử lý), `news_raw` (dữ liệu thô thu thập về), `news_metrics` (lượt xem & độ phổ biến), `comments` (bình luận), `bookmarks` (bài viết đã lưu).
- **Triển khai / Hạ tầng**: Được tối ưu hóa cấu hình cho các nền tảng serverless như Netlify.

---

## Danh sách API chính

### API Công khai (Public Endpoints)
Các endpoint đều có tiền tố là URL của API Server (ví dụ: `https://api-xuhuong24.xyz`).

- `GET /news` - Lấy danh sách bài viết (hỗ trợ phân trang, bộ lọc danh mục và tìm kiếm từ khóa).
- `GET /news/:slug` - Lấy nội dung chi tiết bài viết đã qua xử lý AI.
- `GET /news/:slug/related` - Lấy danh sách bài viết liên quan theo danh mục và từ khóa.
- `GET /news/trending` - Lấy danh sách bài viết thịnh hành / có lượt xem cao nhất.
- `GET /categories` - Lấy danh sách danh mục bài viết (như Công nghệ, Kinh tế, Xã hội).
- `GET /search?q=:query` - Tìm kiếm bài viết theo từ khóa.
- `POST /auth/login` - Đăng nhập tài khoản bằng email & mật khẩu, trả về token JWT.
- `POST /auth/register` - Đăng ký tài khoản người dùng mới.

### API Người dùng (Cần xác thực Bearer Token)
Yêu cầu đính kèm token hợp lệ trong header `Authorization`.

- `GET /bookmarks` - Lấy danh sách bài viết người dùng đã lưu.
- `POST /bookmarks` - Lưu hoặc bỏ lưu một bài viết.
- `GET /comments?news_id=:id` - Lấy danh sách bình luận dưới bài viết.
- `POST /comments` - Viết bình luận mới dưới bài viết.

### API Quản trị viên (Cần quyền Admin)
Yêu cầu token của tài khoản có vai trò `admin`.

- `GET /admin/news` - Lấy danh sách toàn bộ bài viết để kiểm duyệt và quản lý.
- `GET /admin/backups` - Lấy danh sách các tệp sao lưu dữ liệu hiện có.
- `POST /admin/backups` - Tạo bản sao lưu (backup) dữ liệu các bảng cơ sở dữ liệu chính.
- `POST /admin/backups/:name/restore` - Khôi phục cơ sở dữ liệu từ tệp sao lưu được chỉ định.
- `GET /admin/backups/:name/download` - Tải xuống tệp sao lưu cụ thể.
- `DELETE /admin/backups/:name` - Xóa tệp sao lưu khỏi bộ nhớ cục bộ hệ thống.

---

## Hướng dẫn thiết lập môi trường

### 1. Chuẩn bị Cơ sở dữ liệu
Khởi tạo một dự án Supabase mới, chạy tệp SQL schema trong thư mục `backend/sql/schema.sql`.

### 2. Thiết lập Backend
```bash
cd backend
cp .env.example .env
npm install
npm run dev
```

Các biến môi trường quan trọng:
- `PORT` (mặc định: 4000)
- `SUPABASE_URL`
- `SUPABASE_SERVICE_ROLE_KEY`
- `FRONTEND_ORIGIN` (Ví dụ: http://localhost:8080 hoặc http://localhost:4321)
- `AUTH_JWT_SECRET`
- `ADMIN_EMAIL`
- `ADMIN_PASSWORD`

### 3. Thiết lập Astro Frontend
```bash
cd astro-fe
npm install
npm run dev
```

### 4. Quản lý Tài khoản Admin
Chạy script tự động tạo hoặc đồng bộ tài khoản admin được cấu hình trong `.env`:
```bash
cd backend
npm run admin
```

---

## Thiết kế Kiến trúc & Tối ưu hóa SEO
- **SSR Shells**: Hệ thống backend trả về các shell đã được render trước cho các đường dẫn `article` (chi tiết bài viết) và `category` (danh mục) giúp Googlebot dễ dàng cào dữ liệu và lập chỉ mục nội dung tối đa.
- **Ngăn chặn lập chỉ mục tìm kiếm lỗi**: Cấu hình thuộc tính `noindex` đặc biệt được triển khai cho trang tìm kiếm (`/search`) để tuân thủ hướng dẫn SEO của Google, tránh trùng lặp nội dung.
- **Metadata mạng xã hội**: Tự động kết xuất thẻ Open Graph (Facebook) và Twitter Card với các hình ảnh SEO tùy biến tuyệt đẹp cho từng liên kết tĩnh.