Add CRM stub flag, deploy/backup scripts, CI and prod runbook

- CRM_USE_STUB: local runs no longer reach the live CRM. With only the
  Checkbox stub, a stub receipt would still move the real order to PACKED.
  Refused in production, same as CHECKBOX_USE_STUB.
- scripts/deploy.sh: backup, fast-forward main, build, health check and
  code rollback on failure. scripts/backup.sh: pg_dump with verification
  and 14-day rotation (used by cron and deploy.sh).
- Gitea Actions CI: ruff + pytest, oxlint + build.
- DEPLOY.md runbook; CLAUDE.md rules for safe local development.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

backend/app/api/deps.py

@@ -10,13 +10,11 @@ from fastapi import Depends, HTTPException, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.config import settings
 from app.core.security import TokenError, decode_access_token
 from app.db.models.user import User, UserRole
 from app.db.session import get_session
 from app.services.checkbox.client import CheckboxClient, get_checkbox_client
-from app.services.crm.client import CrmClient
-from app.services.crm.exo_client import ExoCrmClient
+from app.services.crm.client import CrmClient, get_crm_client
 from app.services.task_queue import TaskQueue, get_task_queue
 
 bearer_scheme = HTTPBearer(auto_error=False)
@@ -92,10 +90,6 @@ AdminUser = Annotated[User, Depends(require_admin)]
 CashierUser = Annotated[User, Depends(require_cashier)]
 
 
-def get_crm_client() -> CrmClient:
-    return ExoCrmClient(settings)
-
-
 CrmClientDep = Annotated[CrmClient, Depends(get_crm_client)]
 
 

backend/app/core/config.py

@@ -61,6 +61,9 @@ class Settings(BaseSettings):
     crm_secret_key: str = ""
     crm_shop_key: str = ""
     crm_sid: int = 1
+    # Стаб вместо реальной CRM: иначе локальный worker переводил бы боевые заказы
+    # в PACKED после стаб-чеков Checkbox. В проде запрещено.
+    crm_use_stub: bool = False
 
     # --- Nova Poshta ---
     # Ключи НП хранятся у касс (`cash_registers.np_api_key_enc`). Эта переменная

backend/app/services/crm/client.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+from functools import lru_cache
 from typing import Protocol
 
+from app.core.config import settings
 from app.schemas.orders import OrderOut
 
 
@@ -15,3 +17,18 @@ class CrmClient(Protocol):
     async def get_orders(self, *, status: str) -> list[OrderOut]: ...
 
     async def set_status(self, *, order_id: str, status: str) -> None: ...
+
+
+@lru_cache
+def get_crm_client() -> CrmClient:
+    """Один экземпляр на процесс: стаб копит выставленные статусы в памяти."""
+    if settings.crm_use_stub:
+        if settings.is_production:
+            raise RuntimeError("CRM_USE_STUB=true заборонено в production")
+        from app.services.crm.stub_client import StubCrmClient
+
+        return StubCrmClient()
+
+    from app.services.crm.exo_client import ExoCrmClient
+
+    return ExoCrmClient(settings)

backend/app/services/crm/stub_client.py

@@ -1,4 +1,4 @@
-"""Фикстурный CRM-клиент для тестов — не ходит в сеть."""
+"""Фикстурный CRM-клиент: тесты и локальный запуск (`CRM_USE_STUB=true`) — не ходит в сеть."""
 
 from __future__ import annotations
 

backend/app/worker.py

@@ -20,7 +20,7 @@ from app.core.logging import configure_logging, get_logger
 from app.db.session import SessionFactory
 from app.services import receipts as receipts_service
 from app.services.checkbox.client import CheckboxRateLimitedError, get_checkbox_client
-from app.services.crm.exo_client import ExoCrmClient
+from app.services.crm.client import get_crm_client
 from app.services.nova_poshta.np_client import NpTrackingClient
 from app.services.orders import sync_np_statuses
 
@@ -35,7 +35,7 @@ async def startup(ctx: dict[str, Any]) -> None:
     configure_logging()
     ctx["np_client"] = NpTrackingClient()
     ctx["checkbox_client"] = get_checkbox_client()
-    ctx["crm_client"] = ExoCrmClient(settings)
+    ctx["crm_client"] = get_crm_client()
     log.info("worker_starting", environment=settings.environment)
 
 

backend/tests/test_crm_client_factory.py

@@ -0,0 +1,37 @@
+"""Выбор реализации CRM-клиента по `CRM_USE_STUB`."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+
+from app.core.config import settings
+from app.services.crm.client import get_crm_client
+from app.services.crm.exo_client import ExoCrmClient
+from app.services.crm.stub_client import StubCrmClient
+
+
+@pytest.fixture(autouse=True)
+def _fresh_factory() -> Iterator[None]:
+    get_crm_client.cache_clear()
+    yield
+    get_crm_client.cache_clear()
+
+
+def test_real_client_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(settings, "crm_use_stub", False)
+    assert isinstance(get_crm_client(), ExoCrmClient)
+
+
+def test_stub_when_enabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(settings, "crm_use_stub", True)
+    monkeypatch.setattr(settings, "environment", "local")
+    assert isinstance(get_crm_client(), StubCrmClient)
+
+
+def test_stub_forbidden_in_production(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(settings, "crm_use_stub", True)
+    monkeypatch.setattr(settings, "environment", "production")
+    with pytest.raises(RuntimeError, match="CRM_USE_STUB"):
+        get_crm_client()