# Hướng dẫn sử dụng Pixi

Tài liệu này hướng dẫn sử dụng **Pixi** để quản lý môi trường và dependencies trong dự án, thay thế cho workflow truyền thống `pip` + `venv`.

## 1. Pixi là gì?

Pixi là một công cụ quản lý package và môi trường hiệu năng cao. Trong dự án này, Pixi giúp:
-   **Đồng bộ môi trường**: Đảm bảo mọi dev đều chạy cùng phiên bản python và thư viện.
-   **Tự động hóa tasks**: Chạy test, lint, build UI chỉ với một lệnh.
-   **Cross-platform**: Hoạt động tốt trên Windows, Linux, macOS.

Bạn cần cài đặt Pixi trước khi bắt đầu: [Hướng dẫn cài đặt](https://pixi.sh/latest/#installation) | [Tài liệu chính thức](https://pixi.sh/latest/)

> **Lưu ý quan trọng**: Dự án này sử dụng cấu trúc `skeleton` được quản lý bởi `pixi`. Bạn cần dùng `pixi` cho **MỌI DÒNG LỆNH** bạn nhập vào console.

## 2. Pixi vs Pip/Venv

Nếu bạn quen dùng `pip` và `venv`, đây là bảng so sánh nhanh:

| Tính năng | Pip + Venv | Pixi |
| :--- | :--- | :--- |
| **Tạo môi trường** | `python -m venv venv` | Tự động khi chạy `pixi install` hoặc `pixi run` |
| **Kích hoạt env** | `venv\Scripts\activate` | `pixi shell` (hoặc `pixi run <cmd>` không cần activate) |
| **Cài thư viện** | `pip install <package>` | `pixi add <package>` |
| **Gỡ thư viện** | `pip uninstall <package>` | `pixi remove <package>` |
| **File cấu hình** | `requirements.txt` | `pixi.toml` (chính) & `pixi.lock` (phiên bản chính xác) |
| **Tốc độ** | Bình thường | **Siêu nhanh** (nhờ sử dụng `uv` ở bên dưới) |

## 3. Pixi & uv

Pixi sử dụng [uv](https://github.com/astral-sh/uv) - một trình cài đặt và giải quyết dependency cực nhanh được viết bằng Rust. Điều này có nghĩa là việc cài đặt gói và tạo môi trường diễn ra gần như tức thì. Bạn không cần cài riêng `uv`, Pixi đã tích hợp sẵn nó.

## 4. Hướng dẫn nhanh (Cheat Sheet)

### Bắt đầu
```bash
# Cài đặt dependencies (tạo môi trường trong .pixi/)
pixi install
```

### Chạy ứng dụng & Công cụ
Thay vì kích hoạt môi trường, bạn có thể chạy lệnh trực tiếp qua `pixi run`:

```bash
# Chạy ứng dụng
pixi run start

# Chạy chế độ development (tự động compile UI)
pixi run dev

# Chạy test
pixi run test

# Compile UI
pixi run compile-ui
```

### Quản lý Dependencies
```bash
# Thêm package python (từ conda-forge hoặc pypi)
pixi add requests
pixi add --pypi python-dotenv

# Thêm package cho dev (ví dụ: pytest)
pixi add --feature dev pytest
```

### Vào Shell (Tương tự `activate`)
```bash
# Mở terminal mới với môi trường đã kích hoạt
pixi shell

# Sau khi vào shell, bạn có thể gọi python trực tiếp
python main.py
```

## 5. Troubleshooting cho người mới

-   **Q: Tôi gõ `python main.py` báo lỗi thiếu thư viện?**
    -   A: Bạn chưa kích hoạt môi trường. Hãy dùng `pixi run start` HOẶC gõ `pixi shell` trước.
-   **Q: Tôi muốn cài thư viện bằng `pip install` được không?**
    -   A: **Không nên**. Hãy dùng `pixi add --pypi <tên-gói>` để Pixi ghi lại vào `pixi.toml`. Nếu bạn dùng `pip install` thủ công, đồng nghiệp của bạn sẽ không có thư viện đó.