local_setup_guide.md

# Hướng dẫn Chạy Local - UI-VieNeu Backend

Tài liệu này ghi lại toàn bộ các bước để thiết lập và chạy dự án Video Subtitle & AI Voiceover ở môi trường máy tính cá nhân (Windows).

## 1. Cài đặt Công cụ Quản lý (uv)
Nếu máy bạn chưa có `uv`, hãy mở PowerShell và chạy lệnh sau:
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

## 2. Thiết lập Môi trường và Thư viện
Di chuyển vào thư mục dự án và cài bộ thư viện:
```powershell
# Cài đặt toàn bộ thư viện từ pyproject.toml vào thư mục .venv
uv sync
```

## 3. Khởi động Máy chủ Redis (Memurai)
Dự án cần Redis để làm "bưu điện" chuyển tin nhắn cho Celery.
- **Bước 1:** Mở **VSCode bằng quyền Administrator**.
- **Bước 2:** Chạy lệnh bật dịch vụ:
```powershell
Start-Service Memurai
```
*(Kiểm tra màu xanh trong RedisInsight để chắc chắn đã bật thành công)*

## 4. Chạy Hệ thống (Cần mở 2 Terminal song song)

### Terminal 1: Chạy Celery Worker (Xử lý AI & FFmpeg)
Sử dụng `uv run` để đảm bảo dùng đúng thư viện trong môi trường ảo:
```powershell
uv run celery -A worker worker --loglevel=info -P solo
```
> **Lưu ý:** Tham số `-P solo` là bắt buộc để Celery có thể chạy được trên hệ điều hành Windows.

### Terminal 2: Chạy FastAPI Server (Cổng kết nối API)
```powershell
uv run uvicorn main:app --reload
```
- API sẽ chạy tại: `http://127.0.0.1:8000`
- Tài liệu API (Swagger UI): `http://127.0.0.1:8000/docs`

---

## Các lỗi thường gặp và cách xử lý
1. **ModuleNotFoundError:** Hãy chắc chắn bạn luôn có chữ `uv run` ở đầu lệnh để nó nhận diện được thư viện trong `.venv`.
2. **ConnectionError (Redis):** Kiểm tra xem Memurai đã được Start chưa.
3. **Permission Denied:** Luôn chạy Terminal/VSCode với quyền Administrator khi can thiệp vào các Service như Memurai.