准备部署

CLAUDE.md

@@ -20,6 +20,19 @@ docker compose restart backend  # Restart a service
 
 **Backend** runs on `localhost:8000`, **Frontend** on `localhost:5173`. Both have hot-reload via volume mounts. Database changes requiring new columns need manual `ALTER TABLE` or `docker compose restart backend` (which triggers `Base.metadata.create_all`).
 
+### Production (dev/prod separation)
+
+Two **independent, self-contained** Compose files:
+
+- `docker-compose.yml` — **dev** (hot-reload, `docker compose up`). Leave untouched for local dev.
+- `docker-compose.prod.yml` — **prod**. Run with:
+  ```bash
+  docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build
+  ```
+  Secrets come from `.env.prod` (gitignored; copy from `.env.prod.example`). **Never run bare `docker compose up` on the server.**
+
+CRITICAL prod invariant: the backend **must run single-process**. The WebSocket `ConnectionManager` (`backend/app/websocket/manager.py`) is an in-memory singleton — `--workers N` / gunicorn multi-worker splits connections and silently breaks real-time messaging. `backend/Dockerfile.prod` is pinned to single-process; do not change. The frontend prod build is domain-agnostic (same-origin `/api/v1`, auto `wss://`). See [DEPLOYMENT.md](DEPLOYMENT.md) for the full VPS (Ubuntu 20.04 + host Nginx + certbot) walkthrough.
+
 ## Architecture
 
 ### Backend (FastAPI + SQLAlchemy 2.0 async)