# Layer 1: Router — parse request, call service, return response
@router.post("/customers", response_model=CustomerSchema, status_code=201)
async def create_customer(data: CustomerCreateSchema, ctx = Depends(get_tenant_context)):
    return await service.create(ctx, data)

# Layer 2: Service — business logic, validation, orchestration
class CustomerService:
    async def create(self, ctx, data):
        if await self.repo.exists_by_email(data.email):
            raise DomainError("EMAIL_DUPLICATE", "Email đã tồn tại")
        customer = Customer(tenant_id=ctx.tenant_id, **data.model_dump())
        return await self.repo.save(customer)

# Layer 3: Repository — DB queries, ALWAYS filter tenant_id
def _base_query(self):
    return select(Customer).where(Customer.tenant_id == self.tenant_id)

# Customers
GET    /api/v1/customers?page=1&size=20&search=nguyen
POST   /api/v1/customers
PATCH  /api/v1/customers/{id}
DELETE /api/v1/customers/{id}          # soft delete

# Products
GET    /api/v1/products
POST   /api/v1/products
POST   /api/v1/customers/import/csv    # bulk import

# Pipeline
GET    /api/v1/pipeline/stages
POST   /api/v1/pipeline/deals
PATCH  /api/v1/pipeline/deals/{id}/move

# Promotions
GET    /api/v1/promotions
POST   /api/v1/promotions

# ZNS
POST   /api/v1/zalo/zns/send           # rate limit: 10 msg/s
GET    /api/v1/zalo/zns                # message history

SHOPIFY_API_VERSION = "2026-01"  # ← Luôn dùng version này
REQUIRED_SCOPES = "read_products,write_products,read_orders,read_inventory"

# Redirect URL cho OAuth
auth_url = (
    f"https://{shop_domain}/admin/oauth/authorize"
    f"?client_id={settings.SHOPIFY_CLIENT_ID}"
    f"&scope={REQUIRED_SCOPES}"
    f"&redirect_uri={settings.SHOPIFY_REDIRECT_URI}"
    f"&state={state}"
    f"&access_mode=offline"  # offline = permanent token
)

# Ingestion
POST   /api/v1/cdp/events              # push event vào Redis Stream
GET    /api/v1/cdp/events              # list events với filter

# Deduplication
GET    /api/v1/cdp/dedup/candidates    # list duplicate pairs
POST   /api/v1/cdp/dedup/merge        # merge 2 customer profiles
POST   /api/v1/cdp/dedup/dismiss      # bỏ qua cặp trùng

# Segments
GET    /api/v1/cdp/segments            # list segments
POST   /api/v1/cdp/segments            # tạo segment mới
GET    /api/v1/cdp/segments/{id}/members
POST   /api/v1/cdp/segments/{id}/refresh

# Analytics (Sprint 5)
GET    /api/v1/cdp/analytics?period=30d
GET    /api/v1/cdp/analytics/export/customers  # CSV StreamingResponse

{
  "event_type": "page_view | add_to_cart | purchase | login | custom",
  "source":     "web | mobile | shopify | zalo",
  "customer_id": "uuid",
  "session_id":  "uuid",
  "properties": {
    "page": "/products/ao-thun",
    "product_id": "uuid",
    "value": 350000
  },
  "timestamp": "2026-03-22T10:00:00Z"
}

# Chạy Cloudflare tunnel (dev environment)
cloudflared tunnel --url http://localhost:8000

# Webhook URL format
https://{tunnel-domain}/api/v1/zalo/webhook/3665862159615576892

# Khi domain lavongfishing.vn verified → dùng subdomain cố định
https://api.lavongfishing.vn/api/v1/zalo/webhook/3665862159615576892

# Zalo OA
POST   /api/v1/zalo/oa/connect         # kết nối OA với OAuth code
GET    /api/v1/zalo/oa                  # xem OA info
POST   /api/v1/zalo/oa/send            # gửi OA message

# ZNS
POST   /api/v1/zalo/zns/send           # gửi ZNS (rate: 10 msg/s)
GET    /api/v1/zalo/zns                # history

# Campaigns
GET    /api/v1/campaigns               # list với filter status/type
POST   /api/v1/campaigns               # tạo campaign
POST   /api/v1/campaigns/{id}/launch   # kích hoạt gửi
POST   /api/v1/campaigns/{id}/cancel   # hủy

# AI Agent
POST   /api/v1/agent/chat              # chat với AI Agent

# Knowledge Base
GET    /api/v1/knowledge/documents
POST   /api/v1/knowledge/documents     # upload PDF/DOCX/TXT (max 20MB)
DELETE /api/v1/knowledge/documents/{id}
GET    /api/v1/knowledge/analytics

# 1. Sync file sang deploy directory
cp wiki/index.html wiki-deploy/src/index.html

# 2. Rebuild container (nếu chưa dùng volume)
cd wiki-deploy && docker compose up -d --build

# 3. Verify wiki đang chạy
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/
# Kết quả phải là: 200

# 1. Clone repo
git clone git@github.com:hypercommerce/platform.git
cd platform/backend

# 2. Python venv
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# 3. Environment
cp .env.example .env
# Điền các biến bắt buộc: DATABASE_URL, REDIS_URL, SECRET_KEY

# 4. Start services
docker compose up -d postgres redis minio

# 5. Migrate & seed
alembic upgrade head
python scripts/seed_data.py --rows 50

# 6. Run dev server
uvicorn app.main:app --reload --port 8000
# → http://localhost:8000/docs

cd ../frontend
npm install
cp .env.example .env.local
# VITE_API_URL=http://localhost:8000
npm run dev
# → http://localhost:5173

cd backend
pytest tests/unit -v                    # Unit tests
pytest tests/unit --cov=app --cov-report=term-missing
# Kết quả mong đợi: coverage ≥ 70%

Authorization: Bearer <access_token>
X-Tenant-ID: <tenant_uuid>
Content-Type: application/json

{
  "code": "EMAIL_DUPLICATE",
  "message": "Email đã tồn tại trong tenant này",
  "details": {}
}

# Production deploy
./scripts/deploy.sh v1.0.0

# Manual rollback
docker compose up -d --no-deps api   # restart với image cũ

# Health check sau deploy
curl https://api.hypercommerce.vn/health
# Expected: {"status":"ok","timestamp":"..."}

# Cài WireGuard trên cả 3 VPS
apt install wireguard -y

# Phân bổ IP private:
# VPS-1 (Web/API): 10.0.0.1
# VPS-2 (Worker):  10.0.0.2
# VPS-3 (DB):      10.0.0.3

# Chỉ expose public: port 80/443 trên VPS-1
# PostgreSQL bind: 10.0.0.3 (KHÔNG bind 0.0.0.0)
# Redis bind:      10.0.0.1 (KHÔNG bind 0.0.0.0)

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M)
BACKUP_DIR=/backups

# PostgreSQL dump
docker exec hypercommerce-postgres pg_dumpall -U postgres \
  | gzip > $BACKUP_DIR/pg_${DATE}.sql.gz

# Giữ lại 7 ngày gần nhất
find $BACKUP_DIR -name "pg_*.sql.gz" -mtime +7 -delete

# Push sang remote (Cloudflare R2 hoặc Vietnix Object Storage)
rclone sync $BACKUP_DIR remote:hypercommerce-backups --max-age 7d

echo "Backup hoàn thành: pg_${DATE}.sql.gz"

# ── PRE-FLIGHT (2 ngày trước) ───────────────────────────────
# 1. Cài PostgreSQL 16 trên VPS-3, test kết nối
# 2. Xác nhận WireGuard VPS-1 ↔ VPS-3 thông
# 3. Test restore từ backup gần nhất vào VPS-3
# 4. Thông báo maintenance: Email + Zalo OA broadcast trước 24h

# ── MAINTENANCE WINDOW (2:00 AM) ────────────────────────────
# T+00:00 — Bật maintenance mode (Nginx → 503)
docker exec hypercommerce-nginx sh -c \
  'echo "maintenance" > /etc/nginx/maintenance.flag && nginx -s reload'

# T+00:01 — Graceful stop Celery
docker exec hypercommerce-celery \
  celery -A app.workers.celery_app control shutdown

# T+00:03 — Stop FastAPI
docker compose stop api

# T+00:04 — Dump toàn bộ DB từ VPS-2
docker exec hypercommerce-postgres pg_dumpall -U postgres \
  | gzip > /tmp/migrate_$(date +%Y%m%d).sql.gz

# T+00:10 — Copy sang VPS-3
scp /tmp/migrate_*.sql.gz root@10.0.0.3:/tmp/

# T+00:12 — Restore vào VPS-3 PostgreSQL
ssh root@10.0.0.3 "gunzip -c /tmp/migrate_*.sql.gz | \
  docker exec -i hypercommerce-postgres psql -U postgres"

# T+00:20 — Verify row counts khớp
ssh root@10.0.0.3 "docker exec hypercommerce-postgres psql -U postgres \
  -c 'SELECT schemaname, tablename, n_live_tup FROM pg_stat_user_tables \
  ORDER BY n_live_tup DESC LIMIT 10'"

# T+00:22 — Cập nhật DATABASE_URL trên VPS-1
sed -i 's/DATABASE_URL=.*/DATABASE_URL=postgresql+asyncpg:\/\/postgres:password@10.0.0.3:5432\/hyperdb/' \
  /opt/hypercommerce/.env

# T+00:23 — Start FastAPI + Celery
docker compose up -d api celery celery-beat

# T+00:25 — Smoke test
curl -s http://localhost:8000/health | jq .status
# Expected: "ok"

# T+00:28 — Tắt maintenance mode
docker exec hypercommerce-nginx sh -c \
  'rm -f /etc/nginx/maintenance.flag && nginx -s reload'

# ── ROLLBACK (nếu smoke test fail) ──────────────────────────
# Revert DATABASE_URL về VPS-2, restart services
# Tắt maintenance mode, thông báo "bảo trì kéo dài"

# ── GIAI ĐOẠN 1: Setup replica (không ảnh hưởng user) ───────
# Trên VPS-2 (Primary) — postgresql.conf
wal_level = replica
max_wal_senders = 3
wal_keep_size = 512MB

# Tạo replication user
psql -U postgres -c "CREATE ROLE replicator REPLICATION LOGIN PASSWORD 'rep_pass';"

# Trên VPS-3 (Standby) — basebackup từ primary
pg_basebackup -h 10.0.0.2 -U replicator -p 5432 \
  -D /var/lib/postgresql/data --wal-method=stream -P

# Chờ replica lag < 100ms (kiểm tra liên tục)
psql -h 10.0.0.2 -U postgres \
  -c "SELECT pg_wal_lsn_diff(pg_current_wal_lsn(), sent_lsn) AS lag_bytes FROM pg_stat_replication;"

# ── GIAI ĐOẠN 2: Cutover (~60 giây) ───────────────────────
# T+00: Graceful stop Celery
docker exec hypercommerce-celery celery -A app.workers.celery_app control shutdown

# T+05: Stop FastAPI
docker compose stop api

# T+08: Promote VPS-3 thành Primary
ssh root@10.0.0.3 "pg_ctl promote -D /var/lib/postgresql/data"

# T+10: Update DATABASE_URL → VPS-3
sed -i 's/@10.0.0.2:5432/@10.0.0.3:5432/' /opt/hypercommerce/.env

# T+12: Restart services
docker compose up -d api celery celery-beat

# T+40: Verify /health = 200
curl -s http://localhost:8000/health
# Total downtime: ~40–60 giây