# Phát triển và chạy local

> Loại chính: Tutorial/How-to  
> Kết quả: chạy được backend, web và test offline mà không gọi cloud

## Điều kiện

- Python 3.11+
- Node.js và pnpm tương thích lockfile
- Docker Desktop/Engine

## Thiết lập backend và datastore

```powershell
docker compose -f infra/docker/docker-compose.yml up -d postgres qdrant
Set-Location apps/ai-service
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test,metrics,observability]"
$env:EMBEDDING_PROVIDER = "disabled"
$env:ANSWER_PROVIDER = "disabled"
python -m uvicorn main:app --port 8079
```

Kiểm tra ở terminal khác:

```powershell
Invoke-RestMethod http://localhost:8079/health
Invoke-RestMethod http://localhost:8079/ready
```

Mode disabled là smoke test không cần AWS/corpus; nó không có năng lực RAG production.
Trên Windows nên restart uvicorn trực tiếp thay vì phụ thuộc `--reload` khi debug
startup/provider state.

## Chạy web

```powershell
Set-Location D:\VSF-DUOCTHU
pnpm install --frozen-lockfile
$env:AI_SERVICE_URL = "http://localhost:8079"
pnpm --filter web dev
```

Mở `http://localhost:3000`. Trong mode disabled, gửi câu hỏi phải tạo refusal có
kiểm soát thay vì crash.

## Chạy RAG thật

Chỉ thực hiện khi Qdrant có collection + manifest đúng và môi trường có quyền AWS:

```powershell
$env:QDRANT_URL = "http://localhost:6333"
$env:QDRANT_COLLECTION = "duocthu_v1"
$env:EMBEDDING_PROVIDER = "cohere-v4"
$env:EMBEDDING_DIMENSIONS = "1024"
$env:AWS_REGION = "us-east-1"
$env:ANSWER_PROVIDER = "bedrock-converse"
python -m uvicorn main:app --port 8079
```

Startup phải fail nếu manifest không khớp. Gửi request thử:

```powershell
$body = @{
  query = "Chống chỉ định của paracetamol là gì?"
  subject_scope = "human"
  intent = "fact_lookup"
  conversation_id = "local-001"
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri http://localhost:8079/v1/rag/query `
  -ContentType "application/json" -Body $body
```

## Chạy test

```powershell
Set-Location apps/ai-service
$env:EMBEDDING_PROVIDER = "disabled"
python -m pytest -q
python -m ruff check .

Set-Location ../../ingestion
python -m pip install -e ".[dev]"
python -m pytest -q

Set-Location ..
pnpm --filter web lint
pnpm --filter web build
```

Một số test live datastore sẽ skip nếu hạ tầng không có. Web chưa có test runner;
thay đổi UI/BFF cần browser smoke test cho answerable, clarify, verify_pdf và abstain.

## Dừng local infra

```powershell
docker compose -f infra/docker/docker-compose.yml down
```

Không thêm tùy chọn xoá volume nếu chưa chủ động muốn xoá dữ liệu local.