api/modules/cards/api.py - master - systemsstrategyy/Treker

api/modules/cards/api.py
56 строк3 KB
SystemsStrategy
Initial import
02 июл 2026, 15:15
02 июл 2026, 15:159624ed1
"""Публичный in-process интерфейс модуля `cards` для остальных модулей.

Другие агенты (Quality / Comms / Views) импортируют ТОЛЬКО отсюда.
Прямые импорты из `api.modules.cards.models` или внутренних service-слоёв
запрещены (см. root `конвенций разработки` правило #4).

Зеркалит паттерн `api/modules/auth/api.py` (UserDirectory) и
`api/modules/spaces/api.py` (SpaceDirectory).

Foundation Agent публикует **минимальный stub** для closing issue #22
(Quality нужен `get_internal_id` для join'ов с soft-FK card_id в
checklist_runs). Kanban Agent может расширять — добавлять
`get_card_summary`, `list_cards_by_space`, etc.
"""

from __future__ import annotations

from uuid import UUID

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from api.modules.cards.models import Card


class CardDirectory:
    """Чтение публичных данных карточек для других модулей.

    Используется:
    - Quality: `ChecklistService.get_runs_for_card` — soft-FK `card_id`
      хранится как BigInteger, нужен resolve UUID → int.
    - Comms: индексация в search, отправка нотификаций.
    - Views: агрегация kanban / calendar / list.
    """

    @staticmethod
    async def get_internal_id(db: AsyncSession, *, uid: UUID) -> int | None:
        """Internal int id карточки по её UUID.

        Возвращает None если карточка не существует или soft-deleted
        (`deleted_at IS NOT NULL`). Используется ТОЛЬКО для in-process
        JOIN'ов в других модулях — нигде в публичных API/JSON не появляется
        (это нарушение слоя; внешний API всегда оперирует `uid`).
        """
        result = await db.scalar(select(Card.id).where(Card.uid == uid, Card.deleted_at.is_(None)))
        # mypy: db.scalar возвращает Any | None; явный cast для --strict
        return int(result) if result is not None else None

    @staticmethod
    async def exists(db: AsyncSession, *, uid: UUID) -> bool:
        """Проверка существования карточки по UUID (без soft-deleted).

        Удобнее `get_internal_id` когда нужно только подтвердить факт
        существования (например, валидация в Pydantic-схеме).
        """
        return (await CardDirectory.get_internal_id(db, uid=uid)) is not None