Pular para o conteúdo principal

Status: Approved · v2 · SPEC-CONTRACTS-STRUCTURE-001

depends_on: SPEC-DOMAIN-BASE-001

used_by: IS-ZERO-00.2, IS-MVP-15.1

Estrutura do pacote de contratos

O pacote @raizfc/contracts é a única fonte compartilhada para tipos de transporte e vocabulário técnico entre web, mobile, API e mocks. Ele deve permanecer TypeScript puro, sem dependência de React, Expo, Next, NestJS, ORM, decorators ou bibliotecas de validação runtime.

Estrutura canônica​

packages/contracts/
  package.json
  tsconfig.json
  src/
    index.ts
    base.ts
    api.ts
    errors.ts
    pagination.ts
    money.ts
    assets.ts
    permissions.ts
    enums.ts
    constants.ts
    auth/
    territory/
    entities/
    dto/
    api/

Regras obrigatórias​

  • IDs são string; contratos não revelam UUID/ObjectId/sequence.
  • Datas são aliases de string ISO-8601, nunca Date.
  • Dinheiro usa { amountInCents: number; currency: "BRL" } e inteiros seguros.
  • DTO público, autenticado e de gestão são tipos distintos.
  • Request/response de endpoint ficam em src/api; entidades de transporte reutilizáveis ficam em src/dto.
  • Union types literais são preferidos a enum TypeScript quando não existe ganho de runtime.
  • Nenhum any; unknown deve ser refinado fora do pacote.
  • Não duplicar tipos em apps ou API.

Dependências permitidas​

O pacote não depende de nenhum outro pacote interno. Dependências externas devem ser zero no MVP.

Export público​

Consumidores importam apenas de @raizfc/contracts ou subpaths oficialmente exportados. Paths profundos para src/ são proibidos.

Convenções de nomes​

  • PublicTeamDto: leitura pública.
  • TeamManagementDto: gestão autorizada.
  • CreateTeamRequest / CreateTeamResponse: operação.
  • TeamSummaryDto: referência leve embutida.
  • TeamPrivateDto só existe quando uma necessidade autenticada real foi especificada.

Nomes como TeamData, TeamInfo, ResponseObject ou IModel são proibidos por não expressarem visibilidade e intenção.

Exemplo base​

export type ID = string;
export type ISODateString = string;
export type Currency = "BRL";

export type MoneyAmount = Readonly<{
  amountInCents: number;
  currency: Currency;
}>;

export type AuditMetadata = Readonly<{
  createdAt: ISODateString;
  updatedAt: ISODateString;
  version: number;
}>;

Ciclos e direção​

Arquivos base não importam domínios. DTOs podem importar tipos base e summaries; arquivos de API podem importar DTOs. Um DTO nunca importa um request/response de API. Revisões devem bloquear ciclos entre domínios.

Versionamento​

Mudanças aditivas são preferidas. Remoções, renomes ou mudanças semânticas exigem análise de impacto em mocks, services, hooks, API, EPs e consumidores. O pacote mantém changelog interno quando o desenvolvimento começar.

Critérios de aceite​

  • Package compila isoladamente.
  • Zero imports de frameworks.
  • Export map cobre somente APIs públicas.
  • Todos os domínios do MVP possuem DTOs mínimos.
  • Nenhum DTO público expõe dados de gestão/privados.