3D Tool Suite — AI 2D → 3D Web Application

Nền tảng chuyển đổi ảnh 2D thành mô hình 3D thông minh với OpenAI Multimodal Vision, Three.js Viewport và kiến trúc đa nhà cung cấp (Meshy, Tripo3D, Mock Engine).

Ứng dụng độc lập thứ 4 trong bộ công cụ 3D Tool Suite, hỗ trợ quy trình công việc trọn vẹn từ tải ảnh, phân tích hình học, tạo lưới đa giác 3D, xem trực quan trong trình duyệt đến tải về tệp GLB/STL.

---

1. Requirements (Yêu Cầu Hệ Thống)

• Node.js: Phiên bản >= 18.0.0 (Khuyên dùng Node 20 hoặc 24 LTS)
• NPM: Phiên bản >= 9.0.0
• PHP: Phiên bản >= 8.0 (Hỗ trợ PHP 8.1, 8.2, 8.3)
• Trình duyệt: Chrome, Firefox, Edge hoặc Safari hỗ trợ WebGL 2.0 và WebAssembly (WASM).

---

2. Installation (Cài Đặt)

# 1. Di chuyển vào thư mục dự án
cd Tach_Model_3D

# 2. Cài đặt các gói phụ thuộc Node.js
npm install

# 3. Tạo tệp cấu hình môi trường từ mẫu
cp .env.example .env

---

3. Environment Variables (Biến Môi Trường)

Tệp cấu hình .env.example cung cấp đầy đủ các tham số mẫu:

Biến Môi Trường	Ý Nghĩa	Giá Trị Mặc Định / Ví Dụ
OPENAI_API_KEY	Khóa API OpenAI (GPT-4o Vision)	sk-proj-...
DATABASE_URL	Chuỗi kết nối Database	postgresql://user:pass@localhost:5432/ai_3d_db
STORAGE_ENDPOINT	Endpoint S3 hoặc Cloudflare R2	https://<account-id>.r2.cloudflarestorage.com
STORAGE_BUCKET	Tên Bucket lưu trữ	3d-models-bucket
STORAGE_ACCESS_KEY	Access Key của Object Storage	your-access-key
STORAGE_SECRET_KEY	Secret Key của Object Storage	your-secret-key
IMAGE_TO_3D_API_KEY	Khóa API tạo mô hình 3D chung	msy_... hoặc tpo_...
MOCK_AI	Bật chế độ giả lập OpenAI	false (hoặc true khi dev)
MOCK_3D	Bật chế độ giả lập 3D (sample.glb)	false (hoặc true khi dev)
APP_SECRET_KEY	Chuỗi muối ký Signed Storage URLs	a_secure_random_key_min_32_chars

Warning

Tuyệt đối không commit tệp .env chứa khóa bí mật lên Git repository! Tệp .gitignore đã được cấu hình tự động bảo vệ.

---

4. Database Setup (Thiết Lập Cơ Sở Dữ Liệu)

Dự án hỗ trợ 2 chế độ cơ sở dữ liệu:

1. Client / In-Memory Mode (Mặc định cho Local Development):
   • Tự động hoạt động ngay không cần cài đặt SQL Server.
2. PostgreSQL / MySQL (Production):
   • Áp dụng cấu trúc bảng trong database/schema.sql:

     psql -U postgres -d ai_3d_db -f database/schema.sql
     

   • Hoặc triển khai qua Prisma ORM:

     npx prisma db push
     

---

5. Running Development Mode (Chạy Chế Độ Phát Triển)

Khởi chạy Vite Development Server:

npm run dev

Mở trình duyệt tại: http://localhost:5173/

Hoặc khởi chạy cùng máy chủ PHP backend:

php -S 127.0.0.1:8000

Truy cập trực tiếp ứng dụng AI 3D: http://127.0.0.1:8000/ai-2d-to-3d.php

---

6. Running Mock Mode (Chế Độ Giả Lập Không Tốn Credit)

Để phát triển giao diện hoặc kiểm thử mà không tốn bất kỳ chi phí API credit nào:

1. Thiết lập trong tệp .env:

   MOCK_AI=true
   MOCK_3D=true
   

2. Hoặc kích hoạt nhanh qua Query Parameter trên trình duyệt:

   http://localhost:5173/?mock=true
   

3. Luồng Mock Mode tự động:

   \text{Upload} \longrightarrow \text{Mock OpenAI Analysis} \longrightarrow \text{Mock 3D Generation} \longrightarrow \text{sample.glb} \longrightarrow \text{3D Viewport}

---

7. Configuring OpenAI (Cấu Hình OpenAI)

1. Đăng ký tài khoản tại OpenAI Platform.
2. Tạo API Key mới với quyền truy cập mô hình gpt-4o.
3. Gán khóa vào tệp .env:

   OPENAI_API_KEY=sk-proj-your-api-key-here
   

4. Hoặc nhập trực tiếp trên giao diện người dùng qua nút "API Keys" ở góc trên bên phải màn hình (khóa được mã hóa và lưu trữ cục bộ trong trình duyệt của bạn).

---

8. Configuring 3D Provider (Cấu Hình Nhà Cung Cấp 3D)

Hệ thống hỗ trợ cơ chế linh hoạt chuyển đổi giữa các nhà cung cấp 3D:

Meshy API

• Đăng ký tài khoản tại Meshy.ai.
• Thiết lập:

  MESHY_API_KEY=msy_your_meshy_api_key_here
  

Tripo3D API

• Đăng ký tài khoản tại Tripo3D.
• Thiết lập:

  TRIPO_API_KEY=tpo_your_tripo_api_key_here
  

---

9. Testing (Kiểm Thử Tự Động)

Hệ sinh thái tích hợp sẵn bộ kiểm thử đa tầng bao phủ toàn diện 105 / 105 Test Cases (100% Passed):

# Chạy toàn bộ 5 bộ kiểm thử cùng một lúc:
npm test

# Chạy riêng từng bộ kiểm thử cụ thể:
npm run test:unit         # Unit tests (OpenAI, Providers, Storage, State machine)
npm run test:frontend     # Frontend component tests (Upload, Pipeline, Viewer, Error)
npm run test:integration  # REST API Integration tests (PHP CLI)
npm run test:e2e          # E2E 8-step complete journey
npm run test:security     # Security & Observability validation

---

10. Quality Gate (Hàng Rào Kiểm Định Chất Lượng)

Tuân thủ nghiêm ngặt nguyên tắc Phase 20 Quality Gate:

"Không chuyển milestone tiếp theo nếu milestone hiện tại còn lỗi blocking."

# Thực thi toàn bộ hàng rào 8 tiêu chí kiểm định chất lượng:
npm run quality-gate

# Các lệnh kiểm định độc lập:
npm run typecheck         # Gate 1: TypeScript type checking (0 errors)
npm run lint              # Gate 2: Code hygiene & secret leak scanner
npm run test              # Gate 3, 4, 5, 8: Chạy trọn bộ 105 tests
npm run build             # Gate 6: Production bundling
npm run check:migrations  # Gate 7: Database & Prisma migration check

Chi tiết xem tại tài liệu docs/AI_3D_QUALITY_GATE.md.

---

11. Deployment (Triển Khai Sản Phẩm)

Đóng gói mã nguồn (Build)

npm run build

Lệnh trên sẽ tự động kiểm tra TypeScript (tsc), đóng gói tối ưu với Vite vào thư mục dist/ và đồng bộ hóa các launcher PHP.

Triển khai Nginx & Docker

Tham khảo tài liệu hướng dẫn chuyên sâu:

• Kiến Trúc Hệ Thống (docs/AI_3D_ARCHITECTURE.md)
• Đặc Tả REST API (docs/AI_3D_API.md)
• Hướng Dẫn Cài Đặt Chi Tiết (docs/AI_3D_SETUP.md)
• Hướng Dẫn Triển Khai Production (docs/AI_3D_DEPLOYMENT.md)

---

Giấy Phép & Bảo Mật

Dự án tuân thủ nghiêm ngặt các tiêu chuẩn bảo mật dữ liệu người dùng:

• Ownership Isolation: User A không được phép truy cập hoặc chỉnh sửa tác vụ của User B.
• Signed Storage URLs: Bảo vệ liên kết tải mô hình bằng chữ ký HMAC-SHA256 có thời hạn.
• Secret Redaction: Tự động lọc sạch 100% API keys, database errors và stack traces trước khi gửi về máy khách.