# Tài liệu Kiến trúc Hệ thống 3D Tours Tài liệu này tổng hợp toàn bộ cấu trúc hệ thống phục vụ quá trình refactor dự án. ## 1. Mô hình Dữ liệu (Database Schema - MongoDB) ### 1.1. User (Người dùng) - `_id`: ObjectId - `username`: String (Unique, bắt buộc) - `email`: String (Unique, bắt buộc) - `password`: String (Hashed) - `role`: String ['admin', 'moderator', 'user', 'guest'] (Chuẩn hóa mới) - `fullName`: String - `avatarUrl`: String (Đường dẫn stream ảnh đại diện) - `agreedToRules`: Boolean (Trạng thái đồng ý điều khoản) - `storage.used`: Number (Dung lượng đã dùng - bytes) - `storage.quota`: Number (Hạn mức dung lượng - bytes) - `createdAt`: Date - `updatedAt`: Date ### 1.2. Asset (Tệp tin/Phương tiện) - `_id`: ObjectId - `filePath`: String (Đường dẫn vật lý) - `fileSize`: Number (Bytes) - `uploadedBy`: ObjectId (Ref: User) - `coordinates`: Object { `lat`: Number, `lng`: Number } (Tọa độ GPS trích xuất từ EXIF) - `createdAt`: Date ### 1.3. Tour (Cấu trúc Tour - Đề xuất mới) - `_id`: ObjectId - `name`: String (Tên của tour) - `description`: String (Mô tả tổng quát) - `location`: Object { `lat`: Number, `lng`: Number } (Vị trí trung tâm của tour) - `createdBy`: ObjectId (Ref: User) - `rootSceneId`: ObjectId (Ref: Scene - Cảnh khởi đầu) - `privacy`: String ['public', 'private', 'member', 'shared'] - `scenes`: Array [ObjectId (Ref: Scene)] (Danh sách các cảnh thuộc tour) - `createdAt`: Date - `updatedAt`: Date ### 1.4. Scene (Cảnh 360) - `_id`: ObjectId - `tourId`: ObjectId (Ref: Tour - Tour cha sở hữu) - `name`: String (Tên cảnh) - `description`: String (Mô tả chi tiết cảnh) - `assetId`: ObjectId (Ref: Asset) - `scene_url`: String (Đường dẫn ảnh đã xử lý) - `gps`: Object { `lat`: Number, `lng`: Number } (Vị trí địa lý riêng của cảnh) - `createdBy`: ObjectId (Ref: User) - `uploadedAt`: Date (Thời gian gốc của ảnh được upload) - `status`: String ['processing', 'completed', 'failed'] - `shareToken`: String (Dùng cho link chia sẻ) - `shareTokenExpires`: Date - `sharedWith`: Array [ObjectId (Ref: User)] - `sharedEmails`: Array [String] - `views`: Number (Tổng lượt xem) - `viewHistory`: Array [ { `date`: Date, `count`: Number } ] - `createdAt`: Date ### 1.5. Hotspot / Link (Điểm điều hướng & Liên kết) - `_id`: ObjectId - `parent_scene_id`: ObjectId (Ref: Scene - Cảnh chứa điểm này) - `target_scene_id`: ObjectId (Ref: Scene - Cảnh đích đến) - `target_tour_id`: ObjectId (Ref: Tour - Dùng cho liên kết sang tour khác) - `title`: String (Tên của liên kết/hotspot) - `description`: String - `coordinates`: Object { `yaw`: Number, `pitch`: Number } - `is_auto_return`: Boolean (Đánh dấu link quay lại tự động) ### 1.6. Setting (Cấu hình hệ thống) - `timezone`: String (Mặc định: 'Asia/Ho_Chi_Minh') - `language`: String (Mặc định: 'vi') --- ## 2. Danh sách API Endpoints ### Quản trị hệ thống (AdminController.js & SystemController.js) - `POST /api/admin/backup`: Xuất toàn bộ DB và Uploads (Zip) - `POST /api/admin/restore`: Khôi phục hệ thống từ file Zip - `GET /api/admin/maintenance/stray-files`: Tìm file rác (không có trong DB) - `POST /api/admin/maintenance/cleanup`: Dọn dẹp dữ liệu mồ côi - `GET /api/admin/users`: Quản lý danh sách người dùng (Phân trang) - `PUT /api/admin/users/:id`: Cập nhật User (Quyền, Password...) - `DELETE /api/admin/users/:id`: Xóa User và dọn dẹp data liên quan - `GET /api/system/settings`: Lấy cấu hình (Timezone, Lang) - `PUT /api/system/settings`: Cập nhật cấu hình hệ thống ### Cảnh 3D (SceneController.js) - `POST /api/scenes`: Tạo mới (Upload ảnh, Resize 8K, Inject GPS) - `GET /api/scenes`: Lấy danh sách hiển thị trên bản đồ (Theo quyền truy cập) - `GET /api/scenes/:id`: Chi tiết một cảnh - `PUT /api/scenes/:id`: Cập nhật Metadata, Privacy hoặc thay thế ảnh - `DELETE /api/scenes/:id`: Xóa Scene và các scene con liên kết (BFS) - `GET /api/share/:sceneId`: Trang trung gian hỗ trợ Open Graph (FB/Zalo) ### Điểm điều hướng (HotspotController.js) - `GET /api/hotspots/:scene_id`: Lấy danh sách điểm tương tác của cảnh - `POST /api/hotspots/create`: Tạo mới (Hỗ trợ tự động tạo link ngược) - `PUT /api/hotspots/update/:id`: Cập nhật vị trí/tiêu đề - `DELETE /api/hotspots/delete/:id`: Xóa hotspot ### Tài sản & Media (AssetController.js) - `GET /api/assets/view/:assetId`: Stream ảnh panorama (Có Referer & Token Verification) - `GET /api/assets/view_avatar/:filename`: Stream ảnh đại diện - `GET /api/me/assets`: Kho ảnh của tôi - `DELETE /api/assets/:id`: Xóa file vật lý và bản ghi - `GET /api/me/assets/top-large`: Thống kê file chiếm dung lượng lớn ### Người dùng & Xác thực (AuthController.js & UserController.js) - `POST /api/auth/register`: Đăng ký tài khoản - `POST /api/auth/login`: Đăng nhập (Trả về JWT) - `GET /api/me/profile`: Thông tin cá nhân & Quota lưu trữ - `PUT /api/me/profile`: Cập nhật hồ sơ & Avatar - `GET /api/users/search`: Tìm kiếm người dùng để chia sẻ --- ## 3. Trung tâm Xử lý Hình ảnh (Backend Worker) - **Công nghệ**: BullMQ + Redis + Sharp. - **Hàng đợi**: `image-processing`. - **Công việc**: 1. Resize ảnh Equirectangular sang 8K. 2. Inject tọa độ GPS vào metadata (Exiftool/ExifHelper). 3. Cập nhật trạng thái `Scene` từ `processing` -> `completed`. --- ## 4. Kiến trúc Frontend ### Thành phần chính: - **Bản đồ**: Leaflet.js + MarkerCluster. - **Trình xem 360**: Pannellum. - **Quản lý trạng thái**: LocalStorage (Lưu JWT, vị trí map, scene đang xem). ### Luồng logic đặc biệt: 1. **Bảo mật ảnh**: Ảnh được stream qua API thay vì link trực tiếp. API yêu cầu xác thực `Referer` (chống hotlinking) và `JWT` hoặc `ShareToken`. 2. **Chia sẻ (Privacy Cascading)**: Khi đổi Privacy của Scene mẹ, các Scene con trong chuỗi Tour sẽ được đồng bộ quyền truy cập và Token. 3. **Open Graph**: Route `/api/share/:id` chèn Meta Tags động và Watermark 360 badge vào ảnh thumbnail để hiển thị đẹp trên mạng xã hội. --- ## 5. Các Middleware Bảo mật - `authMiddleware.js`: Xác thực JWT (`protect`, `optionalAuth`). - `securityMiddleware.js`: - `verifyReferer`: Chặn truy cập trực tiếp từ trình duyệt/site khác. - `setNoCacheHeaders`: Chặn lưu cache các tài sản nhạy cảm. - `quotaMiddleware.js`: Kiểm tra dung lượng lưu trữ dựa trên Role người dùng.