Guia de Desenvolvimento - TechBlog API

Este guia fornece um passo a passo completo para desenvolver o projeto TechBlog API, um blog técnico profissional focado em artigos de alta qualidade sobre Java, arquitetura e engenharia de software. Seguimos princípios de DDD (Domain-Driven Design), Spring Modulith, SOLID e DRY, com arquitetura modular em Java 21 + Spring Boot 3.5.8.

Baseado na documentação viva: PRODUCT.md, ARCHITECTURE.md, DDD.md, PRD.md, SPEC.md e CONTRIBUTING.md.

1. Introdução ao Projeto

Visão Geral

O TechBlog API é uma plataforma de blog técnico com quatro bounded contexts principais:

• Publishing: Ciclo de vida de artigos (criação, edição, publicação).
• Engagement: Interações sociais (comentários, favoritos).
• Analytics: Métricas de leitura e engajamento.
• IAM (Identity & Access): Autenticação e autorização via JWT.

Tecnologias core: Java 21, Spring Boot 3.5.8, PostgreSQL, Flyway, Testcontainers, Redis (futuro).

Estrutura de Pacotes (Spring Modulith)

com.techblog.api
  .modules
    .publishing
      .domain      # Entidades, Value Objects, Eventos
      .application # Use cases, DTOs, Serviços
      .infrastructure # Repositórios JPA, Configs
      .presentation # Controllers REST
    .engagement
    .analytics
    .iam

2. Configuração Inicial do Projeto

2.1. Pré-requisitos

• JDK 21
• Maven 3.9+
• PostgreSQL (local ou via Docker)
• VS Code com extensão GitHub Copilot

2.2. Clonando e Configurando o Projeto

1. Clone o repositório:

   git clone <repo-url>

2. Configure o banco de dados em src/main/resources/application.yml:

   spring:
     datasource:
       url: jdbc:postgresql://localhost:5432/techblog
       username: your_user
       password: your_password
     jpa:
       hibernate:
         ddl-auto: validate
     flyway:
       enabled: true

3. Execute o projeto:

   ./mvnw spring-boot:run

2.3. Estrutura de Migrations com Flyway

As migrations estão em src/main/resources/db/migration/. Exemplo de criação de tabela para Artigo:

1. Crie um arquivo V1__Create_Article_Table.sql:

   CREATE TABLE articles (
       id UUID PRIMARY KEY,
       title VARCHAR(255) NOT NULL,
       slug VARCHAR(255) UNIQUE NOT NULL,
       content_markdown TEXT NOT NULL,
       status VARCHAR(20) NOT NULL,
       author_id UUID NOT NULL,
       published_at TIMESTAMP,
       created_at TIMESTAMP NOT NULL,
       updated_at TIMESTAMP,
       deleted_at TIMESTAMP
   );

2. Execute as migrations:

   ./mvnw flyway:migrate

Para novas tabelas, sempre crie migrations incrementais (V2__, V3__, etc.) e teste com Testcontainers.

2.4. Configuração de Dependências no pom.xml

O pom.xml já inclui dependências essenciais. Para adicionar novas (ex.: Redis), edite e rode:

./mvnw dependency:resolve

3. Fluxo de Desenvolvimento

Siga este fluxo para manter consistência e documentação viva:

1. Novo Requisito ou Feature

   • Abra o chat do Copilot e use o prompt /plan-qna <descrição da feature>.
   • Exemplo: /plan-qna Implementar funcionalidade de favoritar artigos no módulo engagement.
   • O agent plan gera docs/plans/favoritar-artigo-plan.md com análise, tarefas e riscos.

2. Revisão do Plano

   • Leia e ajuste o plano manualmente. Ele serve como documentação oficial.

3. Implementação por Módulo

   • Escolha o agent do módulo (ex.: engagement para favoritos).
   • Prompt: Implemente docs/plans/favoritar-artigo-plan.md no módulo engagement.
   • O agent gera código focado no módulo, seguindo DDD.

4. Testes

   • Para controllers, selecione a classe e digite: Gere os testes seguindo o prompt integration-test.
   • Usa Testcontainers para PostgreSQL e RestAssured para endpoints.

5. Atualização da Documentação

   • Peça ao agent: "Atualize DDD.md e ARCHITECTURE.md para refletir essa mudança baseada no plano."
   • Commit com mensagens atômicas (ex.: feat(engagement): add articles).

6. Revisão e Merge

   • Faça PR com referência ao plano. Execute testes e linting.

4. Usando Agents e Prompts

Agents são especializados por contexto; prompts são templates reutilizáveis.

Agents Disponíveis

• plan: Para planejamento de features (/plan-qna).
• publishing: Para Publishing Context.
• engagement: Para Engagement Context.
• analytics: Para Analytics Context.
• iam: Para Identity & Access.

Prompts Principais

• new-module: Cria estrutura de novo módulo (ex.: Use o prompt new-module para criar módulo 'analytics').
• integration-test: Gera testes de integração com Testcontainers.
• security-review: Análise de segurança no código.

Exemplo de uso: Para criar um novo módulo, digite no chat: Use o prompt new-module para criar módulo 'analytics'.

5. Exemplos Práticos

Exemplo 1: Criar Estrutura do Módulo Publishing

1. Use prompt: Use o prompt new-module para criar módulo 'publishing'.
2. O agent cria pacotes: domain, application, infrastructure, presentation.
3. Adicione Aggregate Root Artigo em domain.

Exemplo 2: Configurar Autenticação JWT no IAM

1. Planeje: /plan-qna Configurar JWT no módulo iam.
2. Implemente: Implemente o plano no módulo iam.
3. Adicione dependências: java-jwt, configure Spring Security.

Exemplo 3: Criar Migration para Comentários

1. Crie V2__Create_Comments_Table.sql:

   CREATE TABLE comments (
       id UUID PRIMARY KEY,
       article_id UUID REFERENCES articles(id),
       author_email VARCHAR(255),
       content TEXT NOT NULL,
       created_at TIMESTAMP NOT NULL,
       updated_at TIMESTAMP,
       deleted_at TIMESTAMP
   );

2. Teste: Execute ./mvnw flyway:migrate e verifique no banco.

Exemplo 4: Implementar Endpoint de Favorites

1. Planeje com /plan-qna.
2. No módulo engagement, crie FavoriteService em application.
3. Controller em presentation com endpoint POST /articles/{id}/favorite.
4. Teste com integration-test.

6. Manutenção da Documentação Viva

• Sempre atualize docs após mudanças: Use agents para refletir alterações em DDD.md, ARCHITECTURE.md, SPEC.md.
• Versione junto ao código: Commits incluem mudanças em docs.
• Feedback loop: Ajuste agents/prompts se necessário (ex.: edite publishing.agent.md).

7. Boas Práticas

• Commits: Pequenos e atômicos (ex.: feat(publishing): create Article entity).
• Testes: 85% cobertura; use Testcontainers para isolamento.
• Segurança: RBAC com Spring Security; evite exposição de entidades JPA.
• Performance: Cache com Redis; otimize queries para P95 < 150ms.
• DDD: Lógica de negócio no domínio; use records para DTOs/VOs.

Para dúvidas, consulte CONTRIBUTING.md ou abra issue no repo.