Add COD-in-transit summary and received tab to the dashboard

- GET /orders/summary: count and sum of cash-on-delivery for parcels not
  yet picked up (excludes received, refused, deleted/unknown TTNs, paid COD);
  shown as a card above the tabs.
- New «Полученные» tab: orders with NP received codes (9, 10, 11, 106) move
  there automatically, regardless of receipt; 106 is now a final status.

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

backend/app/api/v1/orders.py

@@ -6,7 +6,7 @@ from fastapi import APIRouter, Depends, HTTPException, Request, status
 
 from app.api.deps import CashierUser, CrmClientDep, SessionDep, require_any
 from app.db.models.audit import AuditAction
-from app.schemas.orders import OrderRowOut, OrderUpdateIn
+from app.schemas.orders import OrderRowOut, OrdersSummaryOut, OrderUpdateIn
 from app.services import audit
 from app.services import orders as orders_service
 from app.services import receipts as receipts_service
@@ -29,6 +29,14 @@ async def list_orders(
     return [OrderRowOut.from_order(order, receipts.get(order.id)) for order in orders]
 
 
+@router.get("/summary", response_model=OrdersSummaryOut)
+async def orders_summary(session: SessionDep) -> OrdersSummaryOut:
+    count, kopecks = await orders_service.cod_in_transit(session)
+    return OrdersSummaryOut(
+        cod_in_transit_count=count, cod_in_transit_amount=f"{kopecks / 100:.2f}"
+    )
+
+
 @router.patch("/{order_id}", response_model=OrderRowOut, response_model_by_alias=False)
 async def update_order(
     order_id: str,

backend/app/schemas/orders.py

@@ -122,6 +122,13 @@ class OrderRowOut(BaseModel):
         )
 
 
+class OrdersSummaryOut(BaseModel):
+    """`GET /orders/summary` — сводка над таблицей заказов."""
+
+    cod_in_transit_count: int
+    cod_in_transit_amount: str
+
+
 class OrderGoodIn(BaseModel):
     """Позиция заказа из формы редактирования. `amount` считает сервер."""
 

backend/app/services/orders.py

@@ -8,7 +8,7 @@ from datetime import UTC, datetime
 from decimal import ROUND_HALF_UP, Decimal
 from typing import Any
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.db.models.order import Order
@@ -25,9 +25,15 @@ _NP_BATCH_SIZE = 100
 # посылку, заказ уходит во вкладку «Отказы».
 NP_REFUSAL_STATUS_CODES = ("102", "103", "105", "108")
 
-# Коды NP "відправлення отримано" и отказы — после них статус ТТН больше не
-# опрашивается.
-_NP_FINAL_STATUS_CODES = ("9", "10", "11", *NP_REFUSAL_STATUS_CODES)
+# Коды NP "відправлення отримано" (106 — отримано і створено ЄН зворотньої
+# доставки) — заказ уходит во вкладку «Полученные».
+NP_RECEIVED_STATUS_CODES = ("9", "10", "11", "106")
+
+# Получено или отказ — после этого статус ТТН больше не опрашивается.
+_NP_FINAL_STATUS_CODES = (*NP_RECEIVED_STATUS_CODES, *NP_REFUSAL_STATUS_CODES)
+
+# "Видалено" / "Номер не знайдено" — денег по такой ТТН не будет.
+_NP_DEAD_STATUS_CODES = ("2", "3")
 
 # Поля, которые кассир может править в карточке заказа (кроме goods/total).
 _EDITABLE_FIELDS = (
@@ -43,6 +49,7 @@ class OrderTab(enum.StrEnum):
     NO_RECEIPT = "no_receipt"
     HAS_RECEIPT = "has_receipt"
     REFUSED = "refused"
+    RECEIVED = "received"
 
 
 class OrderEditError(Exception):
@@ -96,14 +103,19 @@ async def sync_orders_from_crm(session: AsyncSession, crm: CrmClient) -> None:
 
 
 async def list_orders(session: AsyncSession, *, tab: OrderTab) -> list[Order]:
-    """Заказы вкладки. Отказ клиента важнее наличия чека: такой заказ показывается
-    только в «Отказах», даже если по нему уже создан ЕТТН-чек."""
+    """Заказы вкладки. Статус посылки важнее наличия чека: полученный заказ
+    показывается только в «Полученных», отказ — только в «Отказах», даже если по
+    нему уже создан ЕТТН-чек."""
     refused = Order.np_status_code.in_(NP_REFUSAL_STATUS_CODES)
-    not_refused = Order.np_status_code.is_(None) | ~refused
+    received = Order.np_status_code.in_(NP_RECEIVED_STATUS_CODES)
+    in_transit = Order.np_status_code.is_(None) | Order.np_status_code.not_in(
+        _NP_FINAL_STATUS_CODES
+    )
     tab_filter = {
         OrderTab.REFUSED: refused,
-        OrderTab.NO_RECEIPT: Order.receipt_created_at.is_(None) & not_refused,
-        OrderTab.HAS_RECEIPT: Order.receipt_created_at.is_not(None) & not_refused,
+        OrderTab.RECEIVED: received,
+        OrderTab.NO_RECEIPT: Order.receipt_created_at.is_(None) & in_transit,
+        OrderTab.HAS_RECEIPT: Order.receipt_created_at.is_not(None) & in_transit,
     }[tab]
     result = await session.scalars(
         select(Order)
@@ -114,6 +126,23 @@ async def list_orders(session: AsyncSession, *, tab: OrderTab) -> list[Order]:
     return list(result)
 
 
+async def cod_in_transit(session: AsyncSession) -> tuple[int, int]:
+    """Наложка в пути: (кол-во посылок, сумма в копейках).
+
+    Учитываются только посылки, которые ещё не забрали и по которым нет отказа:
+    финальный статус NP ("отримано"/отказ) или оплата наложки их исключают.
+    """
+    result = await session.execute(
+        select(func.count(), func.coalesce(func.sum(Order.np_cod_amount_kopecks), 0))
+        .where(Order.is_deleted.is_(False))
+        .where(Order.np_cod_amount_kopecks.is_not(None))
+        .where(Order.np_status_code.not_in((*_NP_FINAL_STATUS_CODES, *_NP_DEAD_STATUS_CODES)))
+        .where(Order.np_payment_status.is_distinct_from("Payed"))
+    )
+    count, total = result.one()
+    return count, total
+
+
 async def sync_np_statuses(session: AsyncSession, np: NovaPoshtaClient) -> None:
     """Обновляет статус ТТН, сумму и статус оплаты наложки по заказам в пути.
 

backend/tests/test_orders_router.py

@@ -79,6 +79,11 @@ def _patch_orders_service(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(orders_router.orders_service, "list_orders", fake_list)
     monkeypatch.setattr(orders_router.orders_service, "delete_order", fake_delete)
 
+    async def fake_cod_in_transit(session: object) -> tuple[int, int]:
+        return 3, 245050
+
+    monkeypatch.setattr(orders_router.orders_service, "cod_in_transit", fake_cod_in_transit)
+
     async def fake_update(
         session: object, order_id: str, data: object
     ) -> tuple[Order, list[str]] | None:
@@ -238,3 +243,17 @@ class TestUpdateOrder:
         response = client.patch("/api/v1/orders/1", json={**_UPDATE_BODY, "goods": []})
 
         assert response.status_code == 422
+
+
+class TestSummary:
+    @pytest.mark.parametrize("role", [UserRole.ADMIN, UserRole.CASHIER, UserRole.VIEWER])
+    def test_returns_cod_in_transit(self, client: TestClient, role: UserRole) -> None:
+        app.dependency_overrides[get_current_user] = lambda: _user(role)
+
+        response = client.get("/api/v1/orders/summary")
+
+        assert response.status_code == 200
+        assert response.json() == {
+            "cod_in_transit_count": 3,
+            "cod_in_transit_amount": "2450.50",
+        }

backend/tests/test_orders_service.py

@@ -16,6 +16,7 @@ from app.services.orders import (
     OrderTab,
     _parse_crm_datetime,
     _to_kopecks,
+    cod_in_transit,
     list_orders,
     update_order,
 )
@@ -185,8 +186,48 @@ class TestListOrders:
         assert "orders.np_status_code IN ('102', '103', '105', '108')" in sql
         assert "receipt_created_at" not in sql
 
+    def test_received_tab_filters_by_received_codes_only(self) -> None:
+        sql = _list_where(OrderTab.RECEIVED)
+        assert "orders.np_status_code IN ('9', '10', '11', '106')" in sql
+        assert "receipt_created_at" not in sql
+
     @pytest.mark.parametrize("tab", [OrderTab.NO_RECEIPT, OrderTab.HAS_RECEIPT])
-    def test_other_tabs_exclude_refusals(self, tab: OrderTab) -> None:
+    def test_other_tabs_exclude_received_and_refusals(self, tab: OrderTab) -> None:
         sql = _list_where(tab)
-        assert "NOT IN ('102', '103', '105', '108')" in sql
+        assert "NOT IN ('9', '10', '11', '106', '102', '103', '105', '108')" in sql
         assert "receipt_created_at" in sql
+
+
+class _CapturingExecuteSession:
+    def __init__(self) -> None:
+        self.statement: Any = None
+
+    async def execute(self, statement: Any) -> Any:
+        self.statement = statement
+
+        class _Result:
+            def one(self) -> tuple[int, int]:
+                return 2, 150000
+
+        return _Result()
+
+
+class TestCodInTransit:
+    def test_excludes_received_refused_and_paid(self) -> None:
+        session = _CapturingExecuteSession()
+        result = asyncio.run(cod_in_transit(session))  # type: ignore[arg-type]
+        sql = str(
+            session.statement.compile(
+                dialect=postgresql.dialect(), compile_kwargs={"literal_binds": True}
+            )
+        )
+
+        assert result == (2, 150000)
+        assert "sum(orders.np_cod_amount_kopecks)" in sql
+        assert "orders.is_deleted IS false" in sql
+        assert "orders.np_cod_amount_kopecks IS NOT NULL" in sql
+        assert (
+            "orders.np_status_code NOT IN "
+            "('9', '10', '11', '106', '102', '103', '105', '108', '2', '3')" in sql
+        )
+        assert "orders.np_payment_status IS DISTINCT FROM 'Payed'" in sql