136 lines
5.9 KiB
Markdown
136 lines
5.9 KiB
Markdown
# 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. |