3dtours/ARCHITEC.md

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)

User (Người dùng)

• username: String (Unique)
• email: String (Unique)
• password: String (Hashed)
• role: String ['admin', 'Chủ sở hữu', 'editor', 'moderator', 'Thành viên']
• fullName: String
• avatarUrl: String
• agreedToRules: Boolean

Asset (Tệp tin/Phương tiện)

• filePath: String (Đường dẫn vật lý)
• fileSize: Number (Bytes)
• uploadedBy: ObjectId (Ref: User)
• coordinates: Object { lat: Number, lng: Number } (GPS từ EXIF)
• createdAt: Date

Scene (Cảnh 360)

• name/title: String
• description: String
• assetId: ObjectId (Ref: Asset)
• scene_url: String
• gps: Object { lat: Number, lng: Number }
• createdBy: ObjectId (Ref: User)
• privacy: String ['public', 'private', 'member', 'shared']
• status: String ['processing', 'completed', 'failed']
• shareToken: String (Dùng cho link truy cập nhanh)
• shareTokenExpires: Date
• sharedWith: Array [ObjectId (Ref: User)]
• sharedEmails: Array [String]
• views: Number
• viewHistory: Array [ { date: Date, count: Number } ]

Hotspot (Điểm điều hướng)

• parent_scene_id: ObjectId (Ref: Scene)
• target_scene_id: ObjectId (Ref: Scene)
• title: String
• description: String
• coordinates: Object { yaw: Number, pitch: Number }
• is_auto_return: Boolean (Tự động tạo link quay lại)

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 (Admin Only)

• 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

Cảnh 3D (Scenes)

• 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 (Hotspots)

• 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 (Assets)

• 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 & Hồ sơ (User Profile)

• 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ẻ

Hệ thống (System)

• 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
• POST /api/maintenance/reset-all: Xóa sạch dữ liệu (Dev only)

---

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.

---

6. Ghi chú cho Refactor

• Cần chuẩn hóa các đường dẫn tuyệt đối (hiện đang fix cứng /home/locpham/...).
• Chuyển đổi các logic xử lý file đồng bộ (fs.unlinkSync) sang bất đồng bộ để tối ưu I/O.
• Tách nhỏ apiRoutes.js thành các route con (admin, scenes, users, assets).
• Bổ sung Unit Test cho logic tính toán tọa độ Hotspot ngược.