CNN Brasil Docs

Objetivo

Definir como documentar sistemas baseados em Domain-Driven Design (DDD), contemplando duas camadas de público: desenvolvedores e stakeholders de negócio. A documentação deve ser clara, rastreável e servir como referência para implementação, testes e evolução do sistema.

---

1. Documentação para Desenvolvedores

Público-alvo: engenheiros de software, QA, devops.

Foco: implementação e contratos do domínio.

1.1 Conteúdo recomendado

• Entidades e Agregados
  • Atributos, métodos e validações.
  • Exemplo: User com métodos ageInDays() e canRegister().
• Value Objects
  • Objetos imutáveis com regras de validação.
• Casos de Uso / Services
  • Pré-condições e pós-condições.
  • Fluxos detalhados de operações.
• Repositórios e Interfaces
  • Contratos para persistência e integração externa.
• Eventos de Domínio
  • Eventos disparados após alterações significativas do estado do domínio.
• Exemplos de DTOs e payloads
  • Entrada e saída de APIs ou serviços internos.
• Testes e Referências
  • Indicação de testes unitários, de integração e mocks correspondentes.

1.2 Formato sugerido

• Markdown ou wiki técnico no repositório.
• Diagramas UML / Mermaid (classes, sequências).
• Tabelas de atributos e métodos.
• Exemplos de payloads JSON ou PHP arrays.

1.3 Exemplo

Entidade: User

Atributo	Tipo	Regras / Validação
id	UUID	Obrigatório, único
name	string	Não vazio
age	int	>= 0
email	string	Formato válido

Métodos:

• ageInDays() → retorna idade em dias
• canRegister() → valida se usuário pode se registrar

Use Case: CreateUserUseCase

• Recebe CreateUserDTO, valida idade, persiste no UserRepository, dispara evento UserRegistered.

Exemplo DTO de Entrada:

{
  "name": "Sergio",
  "age": 30,
  "email": "sergio@example.com"
}

---

2. Documentação para Negócio

Público-alvo: Product Owners, analistas, stakeholders de negócio.

Foco: regras de negócio, subdomínios e processos.

2.1 Conteúdo recomendado

• Domínios e Subdomínios
  • Identificação clara dos Bounded Contexts e responsabilidades.
• Ubiquitous Language
  • Glossário de termos usados no domínio.
• Regras de Negócio
  • Validações e políticas essenciais, sem detalhar implementação.
• Eventos de Negócio
  • O que acontece no domínio, sem citar frameworks ou DTOs.
• Fluxos de Processo
  • Diagramas simples (BPMN, Mermaid) mostrando sequência de ações.

2.2 Formato sugerido

• Wiki ou documento de negócios (Notion).
• Diagramas de fluxo de processos ou mapas de domínio.
• Tabelas de regras, pré-condições e pós-condições.

2.3 Exemplo

Fluxo: Criar Usuário

1. Recebe dados do usuário.
2. Valida idade mínima de 18 anos.
3. Persistência no sistema (detalhes técnicos omitidos).
4. Usuário registrado dispara notificações internas.

Glossário:

• Usuário: pessoa que acessa o sistema.
• Registrar Usuário: criar conta válida dentro do sistema.

3. Checklist de Documentação DDD

• Definir Entidades e Agregados
  • Listar atributos, tipos e validações.
  • Registrar métodos relevantes e regras de negócio.
• Definir Value Objects
  • Especificar objetos imutáveis e validações associadas.
• Registrar Casos de Uso / Services
  • Pré-condições e pós-condições.
  • Fluxos detalhados de operações.
• Documentar Repositórios e Interfaces
  • Métodos de persistência e contratos para integrações externas.
• Eventos de Domínio
  • Listar eventos disparados por alterações críticas.
• Exemplos de DTOs / Payloads
  • Entrada e saída de APIs ou serviços internos.
• Referências de Testes
  • Indicar testes unitários, de integração e mocks correspondentes.
• Diagramas e Sequências
  • Diagramas UML ou Mermaid ilustrando relações e fluxos.