fastapi-especificacao-tecnica

name	fastapi-especificacao-tecnica
description	Gerar especificação técnica para a equipe da camada FastAPI integrada ao Django. Usar sempre que o pedido envolver spec técnica, arquitetura, plano técnico ou detalhamento de implementação para FastAPI. Use when this capability is needed.
metadata	{"author":"AgtecPalmas"}

Objetivo

Produzir especificações técnicas acionáveis, alinhadas ao padrão real da camada FastAPI gerada neste projeto, com foco em arquitetura, contratos, segurança, testes e plano incremental de execução.

Referências locais obrigatórias

• core/management/commands/fastapi.py
• core/management/commands/fastapi_managers/
• core/management/commands/snippets/fastapi/
• core/management/commands/snippets/fastapi_project/
• docs/fastapi/index.md

Padrão arquitetural a respeitar

• Projeto FastAPI base em FastAPI/<nome_projeto>/.
• Entrada da aplicação em main.py com app.include_router(api_router).
• Roteamento central em core/routers.py com prefixo settings.api_str (padrão /api/v1).
• Organização por domínio em módulos com:
  • <app>/<model>/models.py
  • <app>/<model>/schemas.py
  • <app>/<model>/use_cases.py Concentra regras de negócio e acesso a dados; routers apenas orquestram.
  • <app>/<model>/routers.py Apenas para orquestração, sem lógica de negócio; use cases concentram regras e acesso a dados.
  • <app>/routers.py agregando rotas do app.
• Use cases devem concentrar regras de negócio e acesso a dados (routers apenas orquestram).
• Models em SQLAlchemy 2 (Mapped, mapped_column, relationship).
• Schemas em Pydantic (separação clara para create/update/read/search).
• Segurança baseada em OAuth2/JWT e checagem de permissões integradas ao domínio authentication.

Regras obrigatórias

• Modularizar endpoints com APIRouter e include_router.
• Declarar dependências com Depends (DB, auth, autorização, filtros).
• Declarar response_model nos endpoints para contrato explícito.
• Preferir async def para operações I/O-bound.
• Separar schema de entrada e saída para estabilidade de contrato.
• Definir estratégia de erros com exceções de domínio e status code consistente.

Como escrever a especificação técnica

Ao receber pedido de especificação para FastAPI, produzir o documento em Markdown com esta estrutura:

Metadados obrigatórios no topo do arquivo:

• Data: DD-MM-YYYY
• Status: draft | approved | in_progress | in_review | done | cancelled | superseded
• Task(s) de rastreabilidade: .ia/docs/tasks/todo/task-DD-MM-YYYY-<hash_alfanumerico_10>.md

1) Contexto e objetivo

• Problema de negócio.
• Resultado esperado.
• Escopo e fora de escopo.

2) Impacto arquitetural

• Apps e módulos FastAPI afetados.
• Dependências com Django (auth, permissões, modelos equivalentes).
• Mudanças em cache (Redis na camada FastAPI externa, quando aplicável — Redis não compõe a stack Django; ver .ia/docs/architecture/overview.md §2), observabilidade e configuração.

3) Contratos de API

• Endpoints propostos (método, rota, finalidade).
• Query params, payloads e response_model.
• Regras de paginação, busca e filtros.
• Erros esperados (4xx/5xx) por endpoint.

4) Modelagem de dados

• Entidades SQLAlchemy afetadas.
• Relacionamentos (ForeignKey, ManyToMany, herança CoreBase/CoreBaseInherit).
• Campos obrigatórios/opcionais e defaults.

5) Schemas e validação

• Schemas de entrada e saída (Create, Update, InDB, SearchFilter).
• Regras de validação e normalização.
• Campos sensíveis que devem ser omitidos na resposta.

6) Regras de negócio (use cases)

• Casos de uso novos/alterados.
• Fluxo de persistência e critérios de idempotência.
• Estratégia para evitar lógica de negócio em routers.

7) Segurança e autorização

• Dependências de autenticação/autorização.
• Permissões por ação (view, add, change, delete).
• Riscos e mitigação de exposição de dados.

8) Cache e observabilidade

• Chaves Redis afetadas na camada FastAPI externa (quando aplicável), estratégia de invalidação e refresh.
• Logs relevantes sem PII.
• Eventos/métricas úteis para operação.

9) Estratégia de testes

• Testes unitários de use cases.
• Testes de integração HTTP (pytest-asyncio + httpx.AsyncClient).
• Cenários mínimos: sucesso, validação, autorização, erro de negócio.

10) Plano incremental de implementação

• Fases pequenas e sequenciais.
• Arquivos por fase.
• Critérios de aceite por fase.

11) Riscos e pendências

• Riscos técnicos.
• Decisões pendentes.
• Premissas assumidas.

Regras de saída

• Escrever em português técnico, direto e sem ambiguidade.
• Usar caminhos de arquivo concretos quando sugerir alterações.
• Sempre listar arquivos FastAPI esperados por módulo impactado.
• Quando houver lacuna de contexto, declarar premissas explicitamente.
• Salvar as especificações em .ia/docs/specs/fastapi/ com nome descritivo e data no padrão <dominio>-<descricao-curta>-fastapi-spec-DD-MM-YYYY.md (ex.: sso-govbr-integracao-fastapi-spec-30-05-2026.md).

---

Source: AgtecPalmas/AgtecCore — distributed by TomeVault.