Skip to content

FASE_0.2_MAPEAMENTO_CODIGO.md

Latest commit

 

History

History
2203 lines (1771 loc) · 81.5 KB

FASE_0.2_MAPEAMENTO_CODIGO.md

File metadata and controls

2203 lines (1771 loc) · 81.5 KB

FASE 0.2: MAPEAMENTO CÓDIGO EXISTENTE - ANÁLISE COMPLETA

Data de Análise: 2025-11-02
Projeto: TypeCraft - AI-Powered Book Production Engine
Versão do Sistema: v0.1.0
Analista: Claude Code (Anthropic)

EXECUTIVE SUMMARY

O TypeCraft é um sistema de produção editorial profissional baseado em IA, construído em Go 1.24 com arquitetura orientada a serviços e processamento assíncrono. A análise completa revela:

Estado Geral: FUNCIONAL PARCIAL com gaps importantes em autenticação e pagamentos.

Pontos Fortes:

  • Arquitetura bem estruturada (Repository Pattern + Service Layer + Handlers)
  • Worker assíncrono completo com Asynq + Redis
  • Database layer implementada com GORM + PostgreSQL
  • Health checks abrangentes para todos os componentes
  • Docker multi-stage build otimizado para produção
  • Storage layer completo (MinIO/S3)
  • Cache layer implementado (Redis)

Gaps Críticos Identificados:

  • ZERO autenticação/autorização implementada (hardcoded "default_user")
  • ZERO sistema de pagamentos ou billing
  • Migrations via GORM AutoMigrate (não versionado)
  • Faltam indexes em campos críticos
  • Falta graceful shutdown completo
  • Workers Refine e Export NÃO IMPLEMENTADOS

Métricas do Código:

  • Total de arquivos Go: 131
  • Total de linhas: 37,986
  • Handlers HTTP: 12
  • Services: 6
  • Repositories: 3
  • Domain Models: 4

SUBTAREFA 1: DATABASE LAYER

1.1 Conexão PostgreSQL

Arquivo: internal/database/database.go (linhas 1-84)

Como é inicializada:

// Linha 17-32
func Connect(databaseURL string) error {
    var err error
    
    // Configurar logger do GORM
    DB, err = gorm.Open(postgres.Open(databaseURL), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Info),
    })
    
    if err != nil {
        return fmt.Errorf("falha ao conectar ao banco: %w", err)
    }
    
    log.Println("✅ Conexão com banco de dados estabelecida")
    
    return nil
}

Parâmetros de conexão:

  • URL completa via DSN (Data Source Name)
  • Exemplo: postgres://typecraft:dev_password@localhost:5432/typecraft_db?sslmode=disable
  • Variável de ambiente: DATABASE_URL
  • Padrão em desenvolvimento: postgresql://typecraft:dev_password@localhost:5433/typecraft_db

Connection Pooling:

  • ❌ NÃO CONFIGURADO explicitamente
  • GORM usa defaults da lib database/sql do Go
  • Não há configuração de MaxOpenConns, MaxIdleConns, ConnMaxLifetime

Retry Logic:

  • ❌ NÃO IMPLEMENTADO
  • Falha na primeira tentativa = falha fatal
  • Sem exponential backoff ou retry

AIR GAPS DETECTADOS:

Severidade Descrição Arquivo Linha
ALTO Falta connection pooling configurado database.go 21
MÉDIO Falta retry logic na conexão database.go 17
BAIXO Logger sempre em modo Info (não configurável) database.go 22

1.2 Migrations

Arquivo: internal/database/database.go (linhas 34-55)

Sistema de Migrations:

  • GORM AutoMigrate (não é migration versionada)
  • ❌ NÃO usa ferramentas como golang-migrate, goose, ou sql-migrate
  • ❌ NÃO há controle de versão de schema
  • ❌ NÃO há rollback de migrations

Código:

// Linha 35-50
func Migrate() error {
    if DB == nil {
        return fmt.Errorf("banco de dados não inicializado")
    }
    
    log.Println("🔄 Executando migrations...")
    
    err := DB.AutoMigrate(
        &domain.Project{},
        &domain.Job{},
        &domain.AIAnalysis{},
    )
    
    if err != nil {
        return fmt.Errorf("falha nas migrations: %w", err)
    }
    
    log.Println("✅ Migrations concluídas")
    
    return nil
}

Quantas migrations existem:

  • 3 tabelas criadas via AutoMigrate
  • NÃO são migrations no sentido tradicional (sem arquivos .sql versionados)

Tabelas Criadas:

Tabela 1: projects

Arquivo: internal/domain/project.go (linhas 44-85)

Campo Tipo GORM Tipo PostgreSQL Tags Notas
id uint SERIAL PRIMARY KEY primaryKey;autoIncrement Auto-incremento
user_id string VARCHAR index;not null TEM INDEX
title string VARCHAR not null Sem index
author string VARCHAR not null Sem index
genre string VARCHAR - Sem validação
language string VARCHAR default:'pt' Default português
isbn string VARCHAR - Sem validação de formato
description string TEXT - -
page_format string VARCHAR default:'6x9' Default 6x9 polegadas
distribution_channels datatypes.JSON JSONB type:jsonb Array JSON
status ProjectStatus VARCHAR default:'created';index TEM INDEX
progress int INTEGER default:0 0-100
analysis datatypes.JSON JSONB type:jsonb Dados da IA
design_config datatypes.JSON JSONB type:jsonb Config de design
manuscript_url string VARCHAR - S3/MinIO URL
pdf_kdp_url string VARCHAR - PDF Amazon KDP
pdf_ingramspark_url string VARCHAR - PDF IngramSpark
epub_url string VARCHAR - ePub gerado
cover_url string VARCHAR - Capa gerada
created_at time.Time TIMESTAMP autoCreateTime Auto
updated_at time.Time TIMESTAMP autoUpdateTime Auto
completed_at *time.Time TIMESTAMP NULL - Nullable
error_log datatypes.JSON JSONB type:jsonb Array de erros

Foreign Keys: NENHUMA (user_id é string sem FK)

Métodos do Model:

  • TableName() string - retorna "projects"
  • IsCompleted() bool
  • IsFailed() bool
  • CanBeProcessed() bool
  • AddError(err string)
  • SetStatus(status ProjectStatus)

Tabela 2: jobs

Arquivo: internal/domain/job.go (linhas 43-57)

Campo Tipo GORM Tipo PostgreSQL Tags Notas
id string VARCHAR PRIMARY KEY primaryKey UUID manual
project_id string VARCHAR index;not null TEM INDEX, sem FK
type JobType VARCHAR not null Enum simulado
status JobStatus VARCHAR default:'pending';index TEM INDEX
priority int INTEGER default:5 1-10 (maior = prioritário)
payload *JSONBMap JSONB type:jsonb Dados do job
result *JSONBMap JSONB type:jsonb Resultado
error_msg string TEXT - Mensagem de erro
attempts int INTEGER default:0 Contador de tentativas
max_attempts int INTEGER default:3 Máximo de tentativas
created_at time.Time TIMESTAMP autoCreateTime Auto
started_at *time.Time TIMESTAMP NULL - Nullable
completed_at *time.Time TIMESTAMP NULL - Nullable

Job Types (constantes):

// Linha 62-69
const (
    JobTypeConvert  JobType = "convert"  // DOCX → Markdown
    JobTypeAnalyze  JobType = "analyze"  // Análise de conteúdo
    JobTypeDesign   JobType = "design"   // Geração de design
    JobTypeRender   JobType = "render"   // Renderização PDF
    JobTypeRefine   JobType = "refine"   // Refinamento tipográfico
    JobTypeExport   JobType = "export"   // Exportação multi-formato
)

Job Statuses (constantes):

// Linha 74-80
const (
    JobStatusPending   JobStatus = "pending"
    JobStatusRunning   JobStatus = "running"
    JobStatusCompleted JobStatus = "completed"
    JobStatusFailed    JobStatus = "failed"
    JobStatusCancelled JobStatus = "cancelled"
)

Métodos do Model:

  • TableName() string - retorna "jobs"
  • IsTerminal() bool
  • CanRetry() bool
  • MarkStarted()
  • MarkCompleted(result map[string]interface{})
  • MarkFailed(err error)

Tabela 3: ai_analyses

Arquivo: internal/domain/ai_analysis.go (linhas 10-52)

Campo Tipo GORM Tipo PostgreSQL Tags Notas
id string UUID PRIMARY KEY type:uuid;primaryKey UUID
project_id string UUID type:uuid;not null;index TEM INDEX, sem FK
genre string VARCHAR(100) not null Gênero literário
genre_confidence float64 DECIMAL(5,4) - 0.0000-1.0000
sub_genres []string - - NÃO armazenado (GORM ignora)
sub_genres_json string TEXT column:sub_genres JSON serializado
tone_primary string VARCHAR(100) embeddedPrefix:tone_ Embedded struct
tone_formality float64 DECIMAL(5,4) embeddedPrefix:tone_ -
tone_emotion string VARCHAR(100) embeddedPrefix:tone_ -
tone_confidence float64 DECIMAL(5,4) embeddedPrefix:tone_ -
complexity_avg_sentence_length float64 DECIMAL(7,2) embeddedPrefix:complexity_ -
complexity_vocabulary_richness float64 DECIMAL(5,4) embeddedPrefix:complexity_ -
complexity_syntax_complexity float64 DECIMAL(5,4) embeddedPrefix:complexity_ -
complexity_technical_density float64 DECIMAL(5,4) embeddedPrefix:complexity_ -
complexity_reading_level string VARCHAR(50) embeddedPrefix:complexity_ -
emotional_keywords []string - - NÃO armazenado
emotional_keywords_json string TEXT column:emotional_keywords JSON
sentiments []string - - NÃO armazenado
sentiments_json string TEXT column:sentiments JSON
has_math bool BOOLEAN default:false Equações matemáticas
has_code bool BOOLEAN default:false Blocos de código
has_images bool BOOLEAN default:false Imagens detectadas
word_count int INTEGER not null Total de palavras
estimated_pages int INTEGER not null Estimativa de páginas
recommended_pipeline string VARCHAR(50) not null latex/html/hybrid
analyzed_at time.Time TIMESTAMP not null Timestamp da análise
tokens_used int INTEGER default:0 Tokens OpenAI gastos
created_at time.Time TIMESTAMP autoCreateTime Auto
updated_at time.Time TIMESTAMP autoUpdateTime Auto

Embedded Structs:

  1. ToneAnalysis (linhas 54-60):

    • Primary (string)
    • Formality (float64)
    • Emotion (string)
    • Confidence (float64)

  2. ComplexityMetrics (linhas 63-69):

    • AvgSentenceLength (float64)
    • VocabularyRichness (float64)
    • SyntaxComplexity (float64)
    • TechnicalDensity (float64)
    • ReadingLevel (string)

Hooks GORM:

  • BeforeCreate() - gera UUID, serializa arrays para JSON (linhas 108-132)
  • AfterFind() - deserializa JSON para arrays (linhas 135-147)

Métodos:

  • TableName() string - retorna "ai_analyses"
  • IsValid() bool
  • ShouldUseLaTeX() bool

1.3 Domain Models - INVENTÁRIO COMPLETO

Total de Models: 4

# Model Arquivo Linhas Tabela Relações
1 Project project.go 130 projects NENHUMA FK
2 Job job.go 123 jobs project_id (sem FK)
3 AIAnalysis ai_analysis.go 164 ai_analyses project_id (sem FK)
4 Repository (interface) repository.go 22 - Interface abstrata

Observação Crítica: Nenhuma Foreign Key é definida. Todas as relações são gerenciadas pela aplicação.

1.4 AIR GAPS DETECTADOS - DATABASE LAYER

Severidade Gap Evidência Solução Necessária
CRÍTICO Sem Foreign Keys domain/*.go Adicionar FKs com ON DELETE CASCADE
CRÍTICO Migrations não versionadas database.go:42 Migrar para golang-migrate ou goose
ALTO Falta index em Project.title project.go:50 gorm:"index"
ALTO Falta index em Job.type job.go:46 gorm:"index"
ALTO Falta index composto (project_id, status) em Jobs job.go Criar migration manual
ALTO Falta constraint CHECK em Job.priority job.go:48 CHECK (priority BETWEEN 1 AND 10)
MÉDIO user_id sem FK para tabela users project.go:47 Criar tabela users + FK
MÉDIO ISBN sem validação de formato project.go:54 Adicionar validator
MÉDIO Sem UNIQUE constraint em combinações - Ex: (project_id, type) em jobs
BAIXO Sem comentários SQL nas tabelas - GORM não gera COMMENT ON

TODOs encontrados no código:

  • ❌ NENHUM TODO encontrado na database layer (código limpo)

SUBTAREFA 2: AUTH/USER LAYER

2.1 Backend tem sistema de autenticação próprio?

RESPOSTA: NÃO ❌

Evidência 1 - Configuração JWT existe mas não é usada:

Arquivo: internal/config/config.go (linhas 49-50)

// Security
JWTSecret      string
AllowedOrigins []string

Valor padrão (linha 83):

JWTSecret: getEnv("JWT_SECRET", "change-me-in-production"),

Evidência 2 - Hardcoded "default_user":

Arquivo: internal/api/handlers/project_handler.go (linhas 46-47)

// UserID padrão até implementação de autenticação (Sprint 3-4)
userID := "default_user"

Também em linhas 89-90:

// UserID padrão até implementação de autenticação (Sprint 3-4)
userID := "default_user"

Evidência 3 - Nenhum arquivo de auth encontrado:

$ find internal/auth -type f
# Resultado: No files found

$ find internal/middleware -type f  
# Resultado: No files found

Evidência 4 - CORS configurado mas sem autenticação:

Arquivo: cmd/api/main.go (linhas 492-520)

func corsMiddleware(allowedOrigins []string) gin.HandlerFunc {
    return func(c *gin.Context) {
        origin := c.Request.Header.Get("Origin")
        // ... apenas CORS, sem validação de token
        c.Next()
    }
}

Conclusão:

  • Backend é STATELESS e SEM AUTENTICAÇÃO
  • Sistema espera que autenticação seja feita no frontend (provavelmente Supabase, conforme mencionado nos comentários)
  • JWTSecret existe em config mas NUNCA é usado
  • Todas as rotas são PÚBLICAS (sem middleware de proteção)

2.2 User Model

RESPOSTA: NÃO EXISTE ❌

Evidência:

$ grep -r "type User" internal/domain/
# Resultado: No matches

$ grep -r "struct User" internal/domain/
# Resultado: No matches

O que existe:

  • user_id string em domain.Project (linha 47)
  • Mas é apenas uma string, sem relação com tabela users
  • Não há modelo User, apenas o campo de referência

Sistema de Roles/Permissions:

  • ❌ NÃO EXISTE
  • Sem enum de roles (admin, user, etc)
  • Sem verificação de permissões
  • Sem RBAC (Role-Based Access Control)

2.3 Middleware de Auth

RESPOSTA: NÃO EXISTE ❌

Evidência:

Arquivo: cmd/api/main.go

Middleware configurados (linha 135):

// Middleware de CORS
router.Use(corsMiddleware(cfg.AllowedOrigins))

APENAS CORS é aplicado. Nenhum middleware de autenticação.

Rotas protegidas:

  • ❌ NENHUMA rota é protegida
  • Todas as rotas em /api/v1/* são públicas
  • Não há verificação de JWT
  • Não há verificação de sessão
  • Não há verificação de API key

Código de rotas (linhas 263-404):

v1 := router.Group("/api/v1")
{
    // Projects - PÚBLICO
    projects := v1.Group("/projects")
    {
        projects.POST("", projectHandler.CreateProject)
        projects.GET("", projectHandler.ListProjects)
        // ... todas públicas
    }
}

Sem middleware como:

// NÃO EXISTE:
projects.Use(authMiddleware.RequireAuth())

2.4 AIR GAPS DETECTADOS - AUTH/USER LAYER

Severidade Gap Evidência Impacto
CRÍTICO Zero autenticação cmd/api/main.go Qualquer um pode criar/deletar projetos
CRÍTICO Sem tabela users domain/ Impossível rastrear usuários reais
CRÍTICO Hardcoded "default_user" project_handler.go:46,89 Todos projetos do mesmo usuário
CRÍTICO Sem proteção de rotas cmd/api/main.go:263-404 API completamente aberta
ALTO JWT configurado mas não usado config.go:83 Configuração inútil
ALTO Sem rate limiting - Vulnerável a abuso
ALTO Sem verificação de email - Sem validação de usuários
MÉDIO Sem password hashing - Nem struct de User existe
MÉDIO Sem recuperação de senha - Nem autenticação existe
MÉDIO Sem log de atividades de usuário - Impossível auditar ações

Comentários no código indicando gaps:

  1. project_handler.go:46: // UserID padrão até implementação de autenticação (Sprint 3-4)
  2. project_handler.go:89: // UserID padrão até implementação de autenticação (Sprint 3-4)

CONCLUSÃO: Sistema depende 100% de autenticação externa (frontend/Supabase). Backend não valida NADA.

SUBTAREFA 3: PAYMENT LAYER

3.1 Backend processa pagamentos?

RESPOSTA: NÃO ❌

Evidência 1 - Busca por arquivos de pagamento:

$ find internal/payment -type f
# Resultado: No files found

Evidência 2 - Busca por código relacionado a pagamentos:

$ grep -ri "stripe\|payment\|billing\|subscription\|invoice" internal/ --include="*.go" | wc -l
# Resultado: 0 matches

Evidência 3 - Variáveis de ambiente:

Arquivo: .env.example (linhas 1-29)

# Database
DATABASE_URL=postgresql://...
# Redis
REDIS_URL=redis://...
# S3/MinIO
S3_ENDPOINT=http://...
# AI APIs
OPENAI_API_KEY=your-openai-key-here
ANTHROPIC_API_KEY=your-anthropic-key-here
# Server
API_PORT=8000
# Security
JWT_SECRET=change-me-in-production
# Processing
MAX_FILE_SIZE_MB=100

SEM NENHUMA variável de:

  • STRIPE_API_KEY
  • STRIPE_WEBHOOK_SECRET
  • PAYPAL_CLIENT_ID
  • Qualquer gateway de pagamento

3.2 Subscription Model

RESPOSTA: NÃO EXISTE ❌

Evidência:

$ find internal/domain -name "*subscription*.go"
# Resultado: No files found

$ find internal/domain -name "*payment*.go"
# Resultado: No files found

$ find internal/domain -name "*invoice*.go"  
# Resultado: No files found

Não há:

  • Model de Subscription
  • Model de Payment
  • Model de Invoice
  • Model de Plan
  • Enum de planos (free, pro, enterprise)

Verificação de limites por plano:

  • ❌ NÃO EXISTE
  • Não há campo plan em User (User nem existe)
  • Não há verificação de quotas
  • Não há rate limiting por plano

3.3 Webhooks

RESPOSTA: NÃO EXISTE ❌

Evidência 1 - Busca por webhooks:

$ grep -r "webhook" . --include="*.go"
# Resultado: No matches

Evidência 2 - Rotas da API:

Arquivo: cmd/api/main.go (linhas 263-404)

Rotas definidas:

  • /api/v1/projects/* - Projetos
  • /api/v1/processing/* - Processamento
  • /api/v1/analysis/* - Análise IA
  • /api/v1/design/* - Design
  • /api/v1/render/* - Renderização
  • /api/v1/export/* - Exportação
  • /api/v1/color/* - Cores CMYK
  • /api/v1/scientific/* - Publicação científica
  • /api/v1/qa/* - QA
  • /api/v1/marketing/* - Marketing

SEM NENHUMA rota de webhook:

  • Sem /webhooks/stripe
  • Sem /webhooks/paypal
  • Sem validação de assinatura de webhook

3.4 AIR GAPS DETECTADOS - PAYMENT LAYER

Severidade Gap Evidência Impacto
CRÍTICO Zero integração de pagamentos Nenhum arquivo Impossível monetizar
CRÍTICO Sem modelo de subscription domain/ Sem controle de planos
CRÍTICO Sem webhooks cmd/api/main.go Impossível processar eventos Stripe
ALTO Sem validação de limites - Usuários podem abusar recursos
ALTO Sem tracking de uso - Impossível cobrar por uso
MÉDIO Sem idempotency keys - Risco de cobranças duplicadas
MÉDIO Sem logging de transações - Impossível auditar pagamentos
MÉDIO Sem retry logic para webhooks - Webhooks perdidos = assinaturas não atualizadas

CONCLUSÃO: Sistema é 100% gratuito ou depende de sistema de billing externo completamente desacoplado.

SUBTAREFA 4: INFRASTRUCTURE

4.1 Docker Compose

Arquivo: docker-compose.yml (linhas 1-119)

Serviços Definidos: 5

Serviço 1: postgres

Propriedade Valor Notas
Image postgres:15-alpine Versão específica
Container Name typecraft_postgres -
Portas 5433:5432 Porta não padrão (evita conflito)
Volumes postgres_data:/var/lib/postgresql/data Volume nomeado
Health Check ✅ SIM pg_isready -U typecraft
Health Interval 10s -
Health Timeout 5s -
Health Retries 5 -

Variáveis:

POSTGRES_USER: typecraft
POSTGRES_PASSWORD: dev_password  # ⚠️ Hardcoded
POSTGRES_DB: typecraft_db

Serviço 2: redis

Propriedade Valor Notas
Image redis:7-alpine Última minor 7.x
Container Name typecraft_redis -
Portas 6379:6379 Porta padrão
Volumes redis_data:/data Persistência
Health Check ✅ SIM redis-cli ping
Health Interval 10s -
Health Timeout 3s -
Health Retries 5 -

Sem senha (desenvolvimento apenas)

Serviço 3: minio

Propriedade Valor Notas
Image minio/minio:latest ⚠️ Sem versão fixa
Container Name typecraft_minio -
Portas 9000:9000 (API), 9001:9001 (Console) -
Volumes minio_data:/data -
Command server /data --console-address ":9001" -
Health Check ✅ SIM curl -f http://localhost:9000/minio/health/live
Health Interval 30s -
Health Timeout 20s -
Health Retries 3 -

Variáveis:

MINIO_ROOT_USER: minioadmin
MINIO_ROOT_PASSWORD: minioadmin  # ⚠️ Padrão inseguro

Serviço 4: api

Propriedade Valor Notas
Build Context . Raiz do projeto
Dockerfile Dockerfile -
Target api Multi-stage build
Container Name typecraft_api -
Portas 8080:8080 -
Volumes ./output:/app/output Bind mount
Depends On postgres, redis, minio COM health checks ✅
Health Check ✅ SIM curl -f http://localhost:8080/health
Health Interval 15s -
Health Start Period 30s Aguarda inicialização

Variáveis importantes:

DATABASE_URL: postgres://typecraft:dev_password@postgres:5432/...
REDIS_URL: redis://redis:6379
MINIO_ENDPOINT: minio:9000
OUTPUT_DIR: /app/output
API_PORT: "8080"

Serviço 5: worker

Propriedade Valor Notas
Build Context . -
Target worker Multi-stage
Container Name typecraft_worker -
Portas NENHUMA Worker não expõe HTTP
Volumes ./output:/app/output -
Depends On postgres, redis, minio COM health checks ✅
Restart unless-stopped ✅ Auto-restart

Variáveis:

OPENAI_API_KEY: ${OPENAI_API_KEY:-}  # Do .env do host

Volumes Nomeados:

volumes:
  postgres_data:    # Persiste DB
  redis_data:       # Persiste cache
  minio_data:       # Persiste arquivos

Network:

networks:
  default:
    name: typecraft_network

TODAS as dependências usam condition: service_healthy ✅

4.2 Dockerfile

Arquivo: Dockerfile (linhas 1-225)

Multi-stage Build: SIM ✅ (4 stages)

Stage 1: Builder

Linhas: 9-38

FROM golang:1.24-alpine AS builder
Aspecto Detalhes
Base Image golang:1.24-alpine
Versão Fixa ✅ SIM
Build Dependencies git, make, gcc, musl-dev
CGO DESABILITADO (CGO_ENABLED=0)
Binaries api, worker
LDFLAGS -w -s (remove debug info, reduz tamanho)
Verificação ✅ test -f bin/api

Otimizações:

  • Layer caching: COPY go.mod go.sum ./ antes de go mod download
  • Static linking: binários standalone

Stage 2: API Runtime

Linhas: 42-107

FROM alpine:3.19 AS api
Aspecto Detalhes
Base Image alpine:3.19 ✅
Runtime Dependencies ca-certificates, tzdata, curl, pandoc, texlive, node, npm, chromium
Usuário typecraft (UID 1000) ✅ NÃO É ROOT
Node Packages pagedjs-cli@0.4.3
Puppeteer Config PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
Porta Exposta 8080
Health Check ✅ curl -f http://localhost:8080/health
Entrypoint /usr/local/bin/typecraft-api

Diretórios criados:

/app/output
/app/templates
/tmp/typecraft

Todos com ownership para usuário typecraft ✅

Stage 3: Worker Runtime

Linhas: 111-160

FROM alpine:3.19 AS worker
Aspecto Detalhes
Base Image alpine:3.19 ✅
Dependencies Mesmas do API (precisa pandoc, latex, node)
Usuário typecraft (UID 1000) ✅
Portas NENHUMA (worker não é HTTP)
Entrypoint /usr/local/bin/typecraft-worker

SEM health check (worker não expõe endpoint HTTP)

Stage 4: Development

Linhas: 164-201

FROM golang:1.24-alpine AS development
Aspecto Detalhes
Base Image golang:1.24-alpine
Hot Reload ✅ Air (github.com/cosmtrek/air)
Dependencies Build + Runtime (todas)
Porta 8080
CMD air -c .air.toml

Para desenvolvimento local apenas

4.3 Variáveis de Ambiente

Arquivo: .env.example (linhas 1-29)

Total de variáveis: 14

Variável Tipo Obrigatória Default Notas
DATABASE_URL String ✅ SIM postgresql://... DSN completo
REDIS_URL String ✅ SIM redis://localhost:6379/0 -
S3_ENDPOINT String ❌ http://localhost:9000 MinIO endpoint
S3_ACCESS_KEY String ❌ minioadmin -
S3_SECRET_KEY String ❌ minioadmin SECRET
S3_BUCKET String ❌ typecraft-files -
S3_REGION String ❌ us-east-1 -
OPENAI_API_KEY String ❌ - SECRET (IA opcional)
ANTHROPIC_API_KEY String ❌ - SECRET (IA opcional)
API_PORT Int ❌ 8000 -
WORKER_CONCURRENCY Int ❌ 5 Workers paralelos
JWT_SECRET String ❌ change-me-in-production SECRET (não usado!)
ALLOWED_ORIGINS String ❌ http://localhost:3000,... CORS
MAX_FILE_SIZE_MB Int ❌ 100 Upload limit
TEMP_DIR String ❌ /tmp/typecraft -

Secrets identificados: 5

  1. S3_SECRET_KEY
  2. OPENAI_API_KEY
  3. ANTHROPIC_API_KEY
  4. JWT_SECRET
  5. DATABASE_URL (contém senha)

⚠️ Nenhuma variável de:

  • STRIPE_API_KEY
  • STRIPE_WEBHOOK_SECRET
  • Qualquer secret de pagamento

4.4 Deploy

Scripts de deploy:

$ find scripts/ -name "*.sh"
scripts/test-stack.sh
scripts/test-upload.sh

NÃO há:

  • deploy.sh
  • setup.sh
  • Scripts de CI/CD

CI/CD:

$ find . -name "cloudbuild.yaml"
# Resultado: No files found

$ find . -name ".gcloudignore"
# Resultado: No files found

$ find . -name ".github/workflows/*.yml"
# Resultado: No files found

CONCLUSÃO: Deploy manual apenas. Sem CI/CD configurado.

Evidência de deploy planejado:

Arquivo: Dockerfile (linhas 204-218)

# ==============================================================================
# Build Instructions:
#
# Build API:
#   docker build --target api -t typecraft-api:latest .
#
# Build Worker:
#   docker build --target worker -t typecraft-worker:latest .
#
# Run with docker-compose:
#   docker compose up -d
# ==============================================================================

Para onde é feito deploy:

  • ❌ Não definido
  • Docker Compose sugere deploy local
  • Comentários mencionam "Cloud Run" mas sem config
  • Arquivo .gcloudignore NÃO EXISTE

4.5 AIR GAPS DETECTADOS - INFRASTRUCTURE

Severidade Gap Evidência Solução
ALTO MinIO image sem versão fixa docker-compose.yml:35 minio/minio:RELEASE.2024-01-01T...
ALTO Senhas hardcoded em docker-compose docker-compose.yml:9,42 Usar secrets ou .env
ALTO Sem CI/CD configurado Nenhum arquivo GitHub Actions ou Cloud Build
MÉDIO Falta health check no worker docker-compose.yml:85-110 Implementar endpoint interno
MÉDIO Falta graceful shutdown cmd/api/main.go Context com timeout
MÉDIO Sem configuração de produção específica - docker-compose.prod.yml
MÉDIO Sem backup automatizado dos volumes - Backup script para postgres_data
BAIXO TEMP_DIR não é criado automaticamente Dockerfile mkdir -p $TEMP_DIR no entrypoint

Configuração de Produção:

  • ❌ NÃO EXISTE docker-compose.prod.yml
  • ❌ Sem configuração de SSL/TLS
  • ❌ Sem reverse proxy (Nginx/Traefik)
  • ❌ Sem rate limiting no nível de infra
  • ❌ Sem monitoring (Prometheus/Grafana)

SUBTAREFA 5: WORKER BACKGROUND SYSTEM

5.1 Implementação

Arquivos principais:

  1. internal/worker/worker.go (387 linhas)
  2. internal/worker/marketing_processors.go (87 linhas)
  3. cmd/worker/main.go (206 linhas)
  4. internal/queue/client.go (180 linhas)

Worker está COMPLETO?

RESPOSTA: PARCIALMENTE ✅❌

Handlers implementados: 6/8

Job Type Handler Status Arquivo Linhas
convert HandleConvert ✅ COMPLETO worker.go 85-131
analyze HandleAnalyze ✅ COMPLETO worker.go 134-170
design HandleDesign ✅ COMPLETO worker.go 173-217
render HandleRender ✅ COMPLETO worker.go 220-264
refine HandleRefine ❌ NÃO IMPLEMENTADO worker.go 267-271
export HandleExport ❌ NÃO IMPLEMENTADO worker.go 274-278
generate_social_asset HandleSocialAsset ✅ COMPLETO worker.go 282-317
generate_book_trailer HandleBookTrailer ✅ COMPLETO worker.go 321-356

Evidência de handlers não implementados:

Arquivo: internal/worker/worker.go

Refine (linhas 267-271):

// HandleRefine processes AI refinement jobs
func (w *Worker) HandleRefine(ctx context.Context, task *asynq.Task) error {
    // TODO: Implement refinement logic (Phase 3)
    fmt.Println("⚠️  [REFINE] Not implemented yet (Phase 3)")
    return fmt.Errorf("refinement not implemented")
}

Export (linhas 274-278):

// HandleExport processes export jobs (KDP, IngramSpark)
func (w *Worker) HandleExport(ctx context.Context, task *asynq.Task) error {
    // TODO: Implement export logic (Phase 4)
    fmt.Println("⚠️  [EXPORT] Not implemented yet (Phase 4)")
    return fmt.Errorf("export not implemented")
}

JobQueue está integrado?

RESPOSTA: SIM ✅

Arquivo: internal/service/job_queue.go existe e está integrado

Arquivo: cmd/api/main.go (linhas 213-222)

var jobQueue *service.JobQueue
if cfg.RedisURL != "" {
    redisAddr, redisPassword, redisDB, err := parseRedisURL(cfg.RedisURL)
    if err == nil {
        jobQueue = service.NewJobQueue(redisAddr, redisPassword, redisDB)
        log.Println("✅ Job Queue habilitado (Redis)")
    }
}

5.2 Job Types

Total de Job Types definidos: 8

Arquivo: internal/worker/worker.go (linhas 21-32)

const (
    TypeConvert          = "convert"               // DOCX → Markdown
    TypeAnalyze          = "analyze"               // AI analysis
    TypeDesign           = "design"                // Design generation
    TypeRender           = "render"                // PDF/ePub rendering
    TypeRefine           = "refine"                // AI refinement
    TypeExport           = "export"                // Export KDP/IngramSpark
    TypeSocialAsset      = "generate_social_asset" // Social Media
    TypeBookTrailer      = "generate_book_trailer" // Book Trailer
)

Handlers registrados:

Arquivo: cmd/worker/main.go (linhas 114-125)

mux.HandleFunc(worker.TypeConvert, w.HandleConvert)
mux.HandleFunc(worker.TypeAnalyze, w.HandleAnalyze)
mux.HandleFunc(worker.TypeDesign, w.HandleDesign)
mux.HandleFunc(worker.TypeRender, w.HandleRender)
mux.HandleFunc(worker.TypeRefine, w.HandleRefine)      // ⚠️ Não implementado
mux.HandleFunc(worker.TypeExport, w.HandleExport)      // ⚠️ Não implementado
mux.HandleFunc(worker.TypeSocialAsset, w.HandleSocialAsset)
mux.HandleFunc(worker.TypeBookTrailer, w.HandleBookTrailer)

Verificação de implementação:

Handler Implementação Evidência
HandleConvert ✅ COMPLETO Chama processingService.ConvertManuscript() (linha 108)
HandleAnalyze ✅ COMPLETO Chama analysisService.AnalyzeProject() (linha 150)
HandleDesign ✅ COMPLETO Chama designService.GenerateDesign() (linha 196)
HandleRender ✅ COMPLETO Chama processingService.GeneratePDF() (linha 242)
HandleRefine ❌ TODO return fmt.Errorf("refinement not implemented")
HandleExport ❌ TODO return fmt.Errorf("export not implemented")
HandleSocialAsset ✅ COMPLETO Chama marketingHandler.ProcessSocialAssetJob() (linha 304)
HandleBookTrailer ✅ COMPLETO Chama marketingHandler.ProcessTrailerJob() (linha 343)

5.3 Redis/Asynq

Configuração:

Arquivo: cmd/worker/main.go (linhas 69-102)

Conexão com Redis:

srv := asynq.NewServer(
    asynq.RedisClientOpt{
        Addr:     redisAddr,      // localhost:6379
        Password: redisPassword,  // (vazio em dev)
        DB:       redisDB,        // 0
    },
    asynq.Config{
        Concurrency: cfg.WorkerConcurrency,  // Default: 5
        Queues: map[string]int{
            "critical": 6,  // High priority
            "default":  3,  // Normal priority
            "low":      1,  // Low priority
        },
        RetryDelayFunc: func(n int, err error, task *asynq.Task) time.Duration {
            // Exponential backoff: 1min, 2min, 4min, 8min, 16min
            return time.Duration(1<<uint(n)) * time.Minute
        },
        StrictPriority: true,
        ShutdownTimeout: 30 * time.Second,
    },
)

Filas existentes: 3

Fila Peso Uso Descrição
critical 6 Jobs urgentes User-facing, requer processamento imediato
default 3 Jobs normais Prioridade normal
low 1 Jobs em lote Background tasks, baixa prioridade

Retry Policy:

// Linha 85-88
RetryDelayFunc: func(n int, err error, task *asynq.Task) time.Duration {
    // Exponential backoff: 1min, 2min, 4min, 8min, 16min
    return time.Duration(1<<uint(n)) * time.Minute
}

Delays:

  • Tentativa 1: imediato
  • Tentativa 2: 1 min (após falha 1)
  • Tentativa 3: 2 min (após falha 2)
  • Tentativa 4: 4 min (após falha 3)
  • Tentativa 5: 8 min (após falha 4)

Max Retries (por job type):

Arquivo: internal/queue/client.go (linhas 138-140)

asynq.MaxRetry(maxRetry),  // Default: 3

Todas as filas usam maxRetry = 3 (hardcoded)

Error Handler:

Arquivo: cmd/worker/main.go (linhas 90-96)

ErrorHandler: asynq.ErrorHandlerFunc(func(ctx context.Context, task *asynq.Task, err error) {
    // P4 (Rastreabilidade): Log all errors
    log.Printf("❌ [WORKER ERROR] Type=%s Error=%v",
        task.Type(),
        err,
    )
}),

Logs estruturados ✅

5.4 Monitoramento

Logs Estruturados:

RESPOSTA: PARCIALMENTE ✅

Evidência:

Arquivo: internal/worker/worker.go

HandleConvert (linhas 99-122):

fmt.Printf("🔄 [CONVERT] Job=%s Project=%s Input=%s\n", ...)  // START
fmt.Printf("❌ [CONVERT] Job=%s Error=%v Duration=%v\n", ...)  // ERROR
fmt.Printf("✅ [CONVERT] Job=%s Output=%s Duration=%v\n", ...) // SUCCESS

Formato:

  • Emoji indica tipo (🔄 início, ❌ erro, ✅ sucesso)
  • Prefixo de contexto ([CONVERT], [ANALYZE], etc)
  • Campos estruturados: Job=, Project=, Error=, Duration=

⚠️ Limitações:

  • Usa fmt.Printf em vez de logger estruturado (zerolog, zap, logrus)
  • Sem níveis de log (DEBUG, INFO, WARN, ERROR)
  • Sem integração com APM (Application Performance Monitoring)

Métricas de Performance:

RESPOSTA: BÁSICO ✅

Evidência:

Arquivo: internal/worker/worker.go (linha 107-109)

startTime := time.Now()
// ... processamento ...
duration := time.Since(startTime)

Todas as operações são medidas ✅

Salvo em:

// Linha 125-128
w.updateJobStatus(ctx, payload.JobID, domain.JobStatusCompleted, map[string]interface{}{
    "output_path": outputPath,
    "duration":    duration.Seconds(),  // ✅ Salvo no DB
})

⚠️ Limitações:

  • Sem agregação de métricas (média, p50, p95, p99)
  • Sem Prometheus metrics
  • Sem dashboards (Grafana)
  • Sem alertas de performance

Alertas de Falha:

RESPOSTA: NÃO ✅❌

Evidência:

Arquivo: cmd/worker/main.go (linhas 90-96)

ErrorHandler: asynq.ErrorHandlerFunc(func(ctx context.Context, task *asynq.Task, err error) {
    log.Printf("❌ [WORKER ERROR] Type=%s Error=%v", task.Type(), err)
}),

Apenas LOG, sem:

  • Alertas via Slack/Discord/Email
  • PagerDuty integration
  • Sentry/Rollbar para error tracking
  • Dead Letter Queue monitoring

5.5 AIR GAPS DETECTADOS - WORKER SYSTEM

Severidade Gap Evidência Impacto
CRÍTICO HandleRefine NÃO IMPLEMENTADO worker.go:267-271 Jobs refine sempre falham
CRÍTICO HandleExport NÃO IMPLEMENTADO worker.go:274-278 Exportação KDP/IngramSpark quebrada
ALTO Sem dead letter queue - Jobs com max retries perdidos
ALTO Sem alertas de falha main.go:90-96 Falhas silenciosas
ALTO Logs não estruturados (fmt.Printf) worker.go Dificulta parsing
MÉDIO Sem métricas Prometheus - Impossível monitorar performance
MÉDIO Sem APM integration - Dificulta debugging em produção
MÉDIO Retry policy hardcoded queue/client.go:140 Não personalizável por job type
MÉDIO Sem circuit breaker - Falhas em serviços externos propagam
BAIXO Sem rate limiting por job type - Jobs pesados podem sobrecarregar

TODOs encontrados:

Arquivo Linha TODO
worker.go 268 // TODO: Implement refinement logic (Phase 3)
worker.go 275 // TODO: Implement export logic (Phase 4)

Handlers faltantes:

  1. HandleRefine - Planejado para Phase 3
  2. HandleExport - Planejado para Phase 4

Dependências dos handlers implementados:

Handler Depende De Status Dependência
HandleConvert ProcessingService ✅ EXISTE
HandleAnalyze AnalysisService ✅ EXISTE
HandleDesign DesignService ✅ EXISTE
HandleRender ProcessingService ✅ EXISTE
HandleSocialAsset MarketingHandler ✅ EXISTE
HandleBookTrailer MarketingHandler ✅ EXISTE

MAPA ARQUITETURAL

Arquitetura Real Detectada

┌─────────────────────────────────────────────────────────────────────┐
│                          TYPECRAFT SYSTEM                           │
│                    AI-Powered Book Production Engine                │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                                │
├─────────────────────────────────────────────────────────────────────┤
│  Frontend (Next.js/React) - NÃO ANALISADO                          │
│  ↓ HTTP/REST                                                        │
│  ↓ CORS: localhost:3000, localhost:5173                            │
│  ↓ Auth: ❌ NENHUMA (todas rotas públicas)                         │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                          API LAYER                                  │
│                    (cmd/api/main.go)                                │
├─────────────────────────────────────────────────────────────────────┤
│  Gin Router (Golang)                                                │
│  ├─ Middleware:                                                     │
│  │  └─ CORS ✅                                                      │
│  │  └─ Auth ❌ NÃO EXISTE                                          │
│  │                                                                   │
│  ├─ Health Checks: /health, /health/live ✅                        │
│  │                                                                   │
│  ├─ API Routes: /api/v1/*                                           │
│  │  ├─ /projects/* (12 endpoints)                                  │
│  │  ├─ /processing/* (3 endpoints)                                 │
│  │  ├─ /analysis/* (4 endpoints)                                   │
│  │  ├─ /design/* (2 endpoints)                                     │
│  │  ├─ /render/* (3 endpoints)                                     │
│  │  ├─ /export/* (2 endpoints)                                     │
│  │  ├─ /color/* (3 endpoints)                                      │
│  │  ├─ /scientific/* (15 endpoints)                                │
│  │  ├─ /qa/* (12 endpoints)                                        │
│  │  └─ /marketing/* (6 endpoints)                                  │
│  │                                                                   │
│  └─ Swagger Docs: /swagger/* ✅                                    │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                       HANDLER LAYER                                 │
│              (internal/api/handlers/*.go)                           │
├─────────────────────────────────────────────────────────────────────┤
│  Total de Handlers: 12                                              │
│  ├─ ProjectHandler (project_handler.go)                            │
│  ├─ ProcessingHandler (processing_handler.go)                      │
│  ├─ AnalysisHandler (analysis_handler.go)                          │
│  ├─ DesignHandler (design_handler.go)                              │
│  ├─ RenderHandler (render_handler.go)                              │
│  ├─ ExportHandler (export_handlers.go)                             │
│  ├─ ColorHandler (color_handlers.go)                               │
│  ├─ ScientificHandler (scientific_handlers.go)                     │
│  ├─ QAHandler (qa_handlers.go)                                     │
│  ├─ MarketingHandler (marketing_handlers.go)                       │
│  ├─ AIHandler (ai_handlers.go)                                     │
│  └─ GenerationHandler (generation_handler.go)                      │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                        SERVICE LAYER                                │
│               (internal/service/*.go)                               │
├─────────────────────────────────────────────────────────────────────┤
│  Total de Services: 6                                               │
│  ├─ ProjectService (project_service.go)                            │
│  ├─ JobService (job_service.go)                                    │
│  ├─ ProcessingService (processing_service.go)                      │
│  ├─ AnalysisService (analysis_service.go)                          │
│  ├─ BookOrchestrator (book_orchestrator.go)                        │
│  └─ JobQueue (job_queue.go)                                        │
│                                                                      │
│  Integrações:                                                       │
│  ├─ AI Client (OpenAI GPT-4)                                       │
│  ├─ Design Service (pkg/design)                                    │
│  ├─ Pipeline (pkg/pipeline)                                        │
│  └─ Storage (MinIO/S3)                                             │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                      REPOSITORY LAYER                               │
│              (internal/repository/*.go)                             │
├─────────────────────────────────────────────────────────────────────┤
│  Total de Repositories: 3                                           │
│  ├─ ProjectRepository (project_repository.go)                      │
│  ├─ JobRepository (job_repository.go)                              │
│  └─ AnalysisRepository (analysis_repository.go)                    │
│                                                                      │
│  ORM: GORM v1.31.0                                                 │
│  Pattern: Repository Pattern ✅                                    │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                         DATABASE LAYER                              │
│               (internal/database/database.go)                       │
├─────────────────────────────────────────────────────────────────────┤
│  PostgreSQL 15 (alpine)                                             │
│  ├─ Connection: GORM v1.31.0                                       │
│  ├─ Migrations: AutoMigrate (não versionado) ⚠️                    │
│  ├─ Connection Pool: ❌ NÃO CONFIGURADO                            │
│  ├─ Retry Logic: ❌ NÃO IMPLEMENTADO                               │
│  │                                                                   │
│  └─ Tabelas:                                                        │
│     ├─ projects (25 campos, 2 indexes)                             │
│     ├─ jobs (13 campos, 2 indexes)                                 │
│     └─ ai_analyses (30+ campos, 1 index)                           │
│                                                                      │
│  ⚠️  Sem Foreign Keys                                               │
│  ⚠️  Sem indexes otimizados                                         │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                      ASYNC WORKER LAYER                             │
│               (cmd/worker/main.go)                                  │
├─────────────────────────────────────────────────────────────────────┤
│  Asynq Server (Redis-based)                                         │
│  ├─ Concurrency: 5 workers                                         │
│  ├─ Queues:                                                         │
│  │  ├─ critical (weight: 6)                                        │
│  │  ├─ default  (weight: 3)                                        │
│  │  └─ low      (weight: 1)                                        │
│  │                                                                   │
│  ├─ Handlers (6/8 implementados):                                  │
│  │  ├─ ✅ HandleConvert                                            │
│  │  ├─ ✅ HandleAnalyze                                            │
│  │  ├─ ✅ HandleDesign                                             │
│  │  ├─ ✅ HandleRender                                             │
│  │  ├─ ❌ HandleRefine (TODO)                                      │
│  │  ├─ ❌ HandleExport (TODO)                                      │
│  │  ├─ ✅ HandleSocialAsset                                        │
│  │  └─ ✅ HandleBookTrailer                                        │
│  │                                                                   │
│  ├─ Retry Policy: Exponential backoff (1m, 2m, 4m, 8m, 16m)      │
│  └─ Error Handling: Log to stdout (sem alertas) ⚠️                 │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                                │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │   Redis 7    │  │   MinIO      │  │  PostgreSQL  │             │
│  │   (Cache +   │  │  (Storage)   │  │      15      │             │
│  │    Queue)    │  │              │  │              │             │
│  └──────────────┘  └──────────────┘  └──────────────┘             │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │  OpenAI API  │  │  Anthropic   │  │  Replicate   │             │
│  │   (GPT-4)    │  │   (Claude)   │  │  (Stable     │             │
│  │              │  │              │  │  Diffusion)  │             │
│  └──────────────┘  └──────────────┘  └──────────────┘             │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐                                │
│  │   Pandoc     │  │  LuaLaTeX    │                                │
│  │ (Conversão)  │  │  (Rendering) │                                │
│  └──────────────┘  └──────────────┘                                │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐                                │
│  │  PagedJS     │  │  Chromium    │                                │
│  │  (HTML→PDF)  │  │ (Headless)   │                                │
│  └──────────────┘  └──────────────┘                                │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                    MISSING COMPONENTS                               │
├─────────────────────────────────────────────────────────────────────┤
│  ❌ Authentication/Authorization Layer                              │
│  ❌ Payment/Billing System                                          │
│  ❌ Email Service                                                    │
│  ❌ Webhook Handler (Stripe/etc)                                    │
│  ❌ Monitoring/Observability (Prometheus, Grafana)                 │
│  ❌ Logging Aggregation (ELK, Loki)                                │
│  ❌ Rate Limiting                                                    │
│  ❌ API Gateway                                                      │
│  ❌ Load Balancer                                                    │
└─────────────────────────────────────────────────────────────────────┘

Fluxo de Requisição HTTP

┌─────────────┐
│   Client    │
│ (Frontend)  │
└──────┬──────┘
       │ POST /api/v1/projects
       │ {title, author, ...}
       ↓
┌──────────────────────────────────────────┐
│  Gin Router (cmd/api/main.go)            │
│  ├─ CORS Middleware ✅                   │
│  └─ Auth Middleware ❌ NÃO EXISTE        │
└──────┬───────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────┐
│  ProjectHandler.CreateProject            │
│  (handlers/project_handler.go:38)        │
│  ├─ Bind JSON request                    │
│  ├─ userID = "default_user" ⚠️           │
│  └─ Chama ProjectService                 │
└──────┬───────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────┐
│  ProjectService.CreateProject            │
│  (service/project_service.go:39)         │
│  ├─ Validações (title, author)           │
│  ├─ Defaults (pageFormat, channels)      │
│  ├─ Cria domain.Project                  │
│  └─ Chama ProjectRepository              │
└──────┬───────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────┐
│  ProjectRepository.Create                │
│  (repository/project_repository.go:24)   │
│  └─ DB.Create(&project) (GORM)          │
└──────┬───────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────┐
│  PostgreSQL Database                     │
│  INSERT INTO projects (...)              │
│  RETURNING id, created_at, ...           │
└──────┬───────────────────────────────────┘
       │
       ↓ (resposta sobe pela pilha)
┌──────────────────────────────────────────┐
│  Client                                  │
│  {id: 123, title: "...", status: "..."}  │
└──────────────────────────────────────────┘

Tempo médio: ~50-100ms (sem load)

Fluxo de Jobs Assíncronos

┌─────────────┐
│   Client    │
│ (Frontend)  │
└──────┬──────┘
       │ POST /api/v1/projects/:id/process
       ↓
┌──────────────────────────────────────────┐
│  ProjectHandler.ProcessProject           │
│  (handlers/project_handler.go:252)       │
└──────┬───────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────┐
│  ProjectService.StartProcessing          │
│  (service/project_service.go:168)        │
│  ├─ Valida se pode processar             │
│  ├─ Cria 4 jobs:                         │
│  │  1. convert (priority: 10)            │
│  │  2. analyze (priority: 9)             │
│  │  3. design  (priority: 8)             │
│  │  4. render  (priority: 7)             │
│  └─ Salva jobs no DB                     │
└──────┬───────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────┐
│  JobRepository.Create                    │
│  (repository/job_repository.go:24)       │
│  └─ INSERT INTO jobs                     │
└──────┬───────────────────────────────────┘
       │
       ↓ (jobs prontos para processamento)
┌──────────────────────────────────────────┐
│  JobQueue.EnqueueConvert                 │
│  (queue/client.go:55-66)                 │
│  ├─ Serializa payload (JSON)             │
│  ├─ Define queue (critical/default/low)  │
│  ├─ MaxRetry: 3                          │
│  └─ Redis RPUSH typecraft:queue:critical │
└──────┬───────────────────────────────────┘
       │
       ↓ (worker processa)
┌──────────────────────────────────────────┐
│  Asynq Server (cmd/worker/main.go)       │
│  ├─ BLPOP typecraft:queue:critical       │
│  ├─ Deserializa task                     │
│  └─ Chama handler (mux.Handle)           │
└──────┬───────────────────────────────────┘
       │
       ↓ (exemplo: convert)
┌──────────────────────────────────────────┐
│  Worker.HandleConvert                    │
│  (worker/worker.go:85-131)               │
│  ├─ Parse payload                        │
│  ├─ UpdateJobStatus(running)             │
│  ├─ ProcessingService.ConvertManuscript  │
│  ├─ Mede duration                        │
│  ├─ UpdateJobStatus(completed/failed)    │
│  └─ Retorna result ou error              │
└──────┬───────────────────────────────────┘
       │
       ↓ (próximo job)
┌──────────────────────────────────────────┐
│  Worker.HandleAnalyze                    │
│  (worker/worker.go:134-170)              │
│  ├─ AnalysisService.AnalyzeProject       │
│  ├─ Chama OpenAI API                     │
│  ├─ Salva AIAnalysis no DB               │
│  └─ UpdateJobStatus(completed)           │
└──────┬───────────────────────────────────┘
       │
       ↓ (sequência continua)
┌──────────────────────────────────────────┐
│  HandleDesign → HandleRender             │
│  Até status = completed ou failed        │
└──────────────────────────────────────────┘

Retry em caso de falha:

Job falha (tentativa 1)
  ↓
Asynq requeue (delay: 1 min)
  ↓
Job executado novamente (tentativa 2)
  ↓
Falha novamente
  ↓
Asynq requeue (delay: 2 min)
  ↓
Tentativa 3 (final)
  ↓
Se falhar: JobStatus = failed (sem mais retry)

INVENTÁRIO COMPLETO

Estatísticas de Código

Métrica Valor
Total de arquivos Go 131
Total de linhas de código 37,986
Total de handlers HTTP 12
Total de domain models 4
Total de services 6
Total de repositories 3
Total de workers 2 (api, worker)
Total de job handlers 8 (6 impl, 2 TODO)
Total de endpoints HTTP ~62
Total de tabelas no DB 3

Handlers HTTP Detalhados

# Handler Arquivo Endpoints Status
1 ProjectHandler project_handler.go 8 ✅ COMPLETO
2 ProcessingHandler processing_handler.go 3 ✅ COMPLETO
3 AnalysisHandler analysis_handler.go 4 ✅ COMPLETO
4 DesignHandler design_handler.go 2 ✅ COMPLETO
5 RenderHandler render_handler.go 3 ✅ COMPLETO
6 ExportHandler export_handlers.go 2 ✅ COMPLETO
7 ColorHandler color_handlers.go 3 ✅ COMPLETO
8 ScientificHandler scientific_handlers.go 15 ✅ COMPLETO
9 QAHandler qa_handlers.go 12 ✅ COMPLETO
10 MarketingHandler marketing_handlers.go 6 ✅ COMPLETO
11 AIHandler ai_handlers.go 3 ✅ COMPLETO
12 GenerationHandler generation_handler.go 1 ✅ COMPLETO

Total de endpoints: ~62

Services Detalhados

# Service Arquivo Responsabilidade Dependências
1 ProjectService project_service.go CRUD projetos ProjectRepo, JobRepo
2 JobService job_service.go CRUD jobs JobRepo
3 ProcessingService processing_service.go Conversão e rendering Pandoc, LaTeX, PagedJS
4 AnalysisService analysis_service.go Análise IA de conteúdo OpenAI, AnalysisRepo
5 BookOrchestrator book_orchestrator.go Orquestração pipeline Todos os services
6 JobQueue job_queue.go Enfileiramento Redis Asynq, Redis

Repositories Detalhados

# Repository Arquivo Model Métodos
1 ProjectRepository project_repository.go Project Create, GetByID, GetAll, Update, Delete, GetByStatus, GetProcessable, UpdateStatus
2 JobRepository job_repository.go Job Create, GetByID, GetByProjectID, Update, GetPending, GetByStatus, GetFailed, Delete, DeleteByProjectID, CountByProject, CountByStatus
3 AnalysisRepository analysis_repository.go AIAnalysis Create, GetByID, GetByProjectID, Update, Delete

Total de métodos: ~30

Domain Models Detalhados

# Model Arquivo Campos Relações Métodos
1 Project project.go 25 user_id (string, sem FK) 6
2 Job job.go 13 project_id (string, sem FK) 6
3 AIAnalysis ai_analysis.go 30+ project_id (string, sem FK) 3
4 Repository repository.go - Interface abstrata -

Total de campos: ~70

Dependências Externas (go.mod)

Principais:

Biblioteca Versão Uso
gin-gonic/gin v1.11.0 HTTP router
gorm.io/gorm v1.31.0 ORM
gorm.io/driver/postgres v1.6.0 Driver PostgreSQL
hibiken/asynq v0.25.1 Job queue (Redis)
redis/go-redis v9.16.0 Cliente Redis
minio/minio-go v7.0.95 Cliente MinIO/S3
sashabaranov/go-openai v1.41.2 Cliente OpenAI
replicate/replicate-go v0.26.0 Cliente Replicate
chromedp/chromedp v0.14.2 Headless Chrome
google/uuid v1.6.0 Geração de UUIDs
swaggo/gin-swagger v1.6.1 Swagger docs

Total de dependências diretas: 11
Total de dependências (incluindo indiretas): ~80

LISTA CONSOLIDADA DE AIR GAPS

Por Severidade

CRÍTICO (11 gaps)

# Gap Subtarefa Evidência Impacto
1 Zero autenticação 2.1 cmd/api/main.go API completamente aberta
2 Sem tabela users 2.2 domain/ Impossível rastrear usuários
3 Hardcoded "default_user" 2.2 project_handler.go:46,89 Todos projetos do mesmo user
4 Sem proteção de rotas 2.3 cmd/api/main.go:263-404 Qualquer um pode criar/deletar
5 Zero sistema de pagamentos 3.1 Nenhum arquivo Impossível monetizar
6 Sem modelo de subscription 3.2 domain/ Sem controle de planos
7 Sem webhooks 3.3 cmd/api/main.go Impossível processar Stripe
8 Sem Foreign Keys 1.4 domain/*.go Integridade referencial quebrada
9 Migrations não versionadas 1.2 database.go:42 Sem rollback
10 HandleRefine NÃO IMPLEMENTADO 5.5 worker.go:267-271 Jobs refine sempre falham
11 HandleExport NÃO IMPLEMENTADO 5.5 worker.go:274-278 Exportação KDP/IngramSpark quebrada

ALTO (15 gaps)

# Gap Subtarefa Evidência
1 Falta connection pooling 1.1 database.go:21
2 Falta index em Project.title 1.3 project.go:50
3 Falta index em Job.type 1.3 job.go:46
4 Falta index composto em Jobs 1.4 -
5 JWT configurado mas não usado 2.4 config.go:83
6 Sem rate limiting 2.4 -
7 Sem verificação de email 2.4 -
8 Sem validação de limites por plano 3.2 -
9 Sem tracking de uso 3.4 -
10 MinIO image sem versão fixa 4.5 docker-compose.yml:35
11 Senhas hardcoded em docker-compose 4.5 docker-compose.yml:9,42
12 Sem CI/CD configurado 4.4 -
13 Sem dead letter queue 5.5 -
14 Sem alertas de falha 5.5 main.go:90-96
15 Logs não estruturados 5.5 worker.go (fmt.Printf)

MÉDIO (16 gaps)

# Gap Subtarefa Evidência
1 Falta retry logic na conexão DB 1.1 database.go:17
2 user_id sem FK para users 1.4 project.go:47
3 ISBN sem validação 1.4 project.go:54
4 Sem UNIQUE constraints 1.4 -
5 Sem password hashing 2.4 -
6 Sem recuperação de senha 2.4 -
7 Sem log de atividades 2.4 -
8 Sem idempotency keys 3.4 -
9 Sem logging de transações 3.4 -
10 Sem retry logic para webhooks 3.4 -
11 Falta health check no worker 4.5 docker-compose.yml:85-110
12 Falta graceful shutdown 4.5 cmd/api/main.go
13 Sem config de produção 4.5 -
14 Sem métricas Prometheus 5.5 -
15 Sem APM integration 5.5 -
16 Retry policy hardcoded 5.5 queue/client.go:140

BAIXO (6 gaps)

# Gap Subtarefa Evidência
1 Logger sempre em modo Info 1.1 database.go:22
2 Sem comentários SQL nas tabelas 1.4 -
3 TEMP_DIR não é criado auto 4.5 Dockerfile
4 Sem rate limiting por job type 5.5 -
5 Sem circuit breaker 5.5 -
6 Sem backup automatizado 4.5 -

TOTAL DE AIR GAPS: 48

RECOMENDAÇÕES PRIORITÁRIAS

Top 5 Problemas (por impacto no negócio)

1. IMPLEMENTAR AUTENTICAÇÃO/AUTORIZAÇÃO

Severidade: CRÍTICO 🔴
Esforço: ALTO (2-3 sprints)
Impacto no Negócio: ALTÍSSIMO

Justificativa:

  • Atualmente QUALQUER PESSOA pode criar, editar, deletar projetos
  • Impossível lançar em produção sem autenticação
  • Todos os projetos pertencem a "default_user"
  • Sem rastreamento de usuários reais

Tarefas:

  1. Criar tabela users com campos (id, email, password_hash, role, created_at, updated_at)
  2. Implementar middleware JWT em internal/middleware/auth.go
  3. Criar endpoints /auth/register, /auth/login, /auth/logout
  4. Adicionar FK user_id em projects table apontando para users.id
  5. Proteger TODAS as rotas com middleware RequireAuth()
  6. Implementar RBAC (admin, user)
  7. Rate limiting por usuário (1000 req/hour)

Bloqueadores de lançamento: SIM ✅

2. IMPLEMENTAR SISTEMA DE BILLING/SUBSCRIPTION

Severidade: CRÍTICO 🔴
Esforço: ALTO (2-3 sprints)
Impacto no Negócio: ALTÍSSIMO

Justificativa:

  • Sistema é 100% gratuito atualmente
  • Impossível monetizar sem billing
  • Usuários podem consumir recursos IA sem limite
  • Sem controle de quotas por plano

Tarefas:

  1. Criar tabelas:
    • subscriptions (id, user_id, plan_id, status, current_period_start, current_period_end, stripe_subscription_id)
    • plans (id, name, price, features_json, limits_json)
    • payments (id, user_id, amount, status, stripe_payment_id)
  2. Integrar Stripe:
    • Criar checkout sessions
    • Processar webhooks (/webhooks/stripe)
    • Validar assinatura de webhook
  3. Implementar middleware CheckSubscription()
  4. Implementar rate limiting por plano
  5. Criar billing portal (Stripe Customer Portal)
  6. Implementar tracking de uso (jobs executados, tokens IA, storage usado)

Bloqueadores de lançamento: SIM ✅

3. MIGRAR PARA MIGRATIONS VERSIONADAS

Severidade: CRÍTICO 🔴
Esforço: MÉDIO (1 sprint)
Impacto no Negócio: ALTO

Justificativa:

  • GORM AutoMigrate NÃO é adequado para produção
  • Impossível fazer rollback de schema changes
  • Sem controle de versão de migrations
  • Dificulta colaboração em equipe

Tarefas:

  1. Escolher ferramenta: golang-migrate/migrate (recomendado)
  2. Converter GORM AutoMigrate para migrations SQL:
    • 000001_create_projects_table.up.sql
    • 000002_create_jobs_table.up.sql
    • 000003_create_ai_analyses_table.up.sql
  3. Adicionar Foreign Keys nas migrations
  4. Adicionar indexes otimizados:
    • CREATE INDEX idx_projects_title ON projects(title)
    • CREATE INDEX idx_jobs_type ON jobs(type)
    • CREATE INDEX idx_jobs_project_status ON jobs(project_id, status)
  5. Remover GORM AutoMigrate de database.Migrate()
  6. Atualizar Dockerfile para rodar migrations antes de iniciar API

Bloqueadores de lançamento: SIM (para ambiente de produção) ✅

4. IMPLEMENTAR HANDLERS WORKER FALTANTES

Severidade: ALTO 🟠
Esforço: MÉDIO (1-2 sprints)
Impacto no Negócio: ALTO

Justificativa:

  • HandleRefine e HandleExport retornam erro imediato
  • Usuários não conseguem refinar tipografia com IA
  • Exportação para KDP/IngramSpark quebrada
  • Features prometidas não funcionam

Tarefas:

HandleRefine (Phase 3):

  1. Implementar análise tipográfica via OpenAI
  2. Detectar problemas:
    • Órfãos e viúvas
    • Hifenização ruim
    • Espaçamento irregular
    • Alinhamento quebrado
  3. Gerar sugestões de correção
  4. Aplicar correções automaticamente
  5. Salvar resultado em job.result

HandleExport (Phase 4):

  1. Implementar conversão PDF/X-1a (KDP, IngramSpark)
  2. Validar especificações:
    • Bleeding (3mm)
    • Color profile (CMYK)
    • Embedded fonts
    • PDF version
  3. Gerar múltiplos outputs:
    • pdf_kdp_url
    • pdf_ingramspark_url
  4. Validar com Preflight (Ghostscript)

Bloqueadores de lançamento: NÃO (mas impacta UX) ⚠️

5. IMPLEMENTAR OBSERVABILITY/MONITORING

Severidade: ALTO 🟠
Esforço: MÉDIO (1 sprint)
Impacto no Negócio: ALTO (operacional)

Justificativa:

  • Sem métricas de performance
  • Impossível detectar problemas em produção
  • Logs não estruturados (fmt.Printf)
  • Sem alertas de falha

Tarefas:

Logging Estruturado:

  1. Substituir fmt.Printf por zerolog ou zap
  2. Adicionar campos estruturados (user_id, job_id, duration, error)
  3. Configurar níveis de log (DEBUG, INFO, WARN, ERROR)

Métricas Prometheus:

  1. Adicionar /metrics endpoint
  2. Instrumentar código:
    • HTTP requests (latency, status code)
    • Job duration (por type)
    • DB query duration
    • AI API calls (tokens, cost)
  3. Criar dashboards Grafana

Alertas:

  1. Configurar AlertManager
  2. Alertas críticos:
    • Error rate > 5%
    • P95 latency > 2s
    • Worker queue size > 100
    • DB connections > 80%
  3. Integrar Slack/Discord

Dead Letter Queue:

  1. Implementar DLQ no Asynq
  2. Jobs com max retries → DLQ
  3. Dashboard para inspecionar jobs falhados
  4. Retry manual via admin panel

Bloqueadores de lançamento: SIM (para produção) ✅

Roadmap Sugerido

Sprint 0.3 (2 semanas):
  ├─ Migrations versionadas (golang-migrate)
  ├─ Foreign Keys + Indexes otimizados
  └─ Connection pooling PostgreSQL

Sprint 0.4 (2 semanas):
  ├─ Tabela users + auth endpoints
  ├─ Middleware JWT
  └─ Proteção de rotas

Sprint 0.5 (2 semanas):
  ├─ Stripe integration (checkout, webhooks)
  ├─ Tabelas subscriptions, plans, payments
  └─ Middleware CheckSubscription

Sprint 0.6 (2 semanas):
  ├─ Logging estruturado (zerolog)
  ├─ Prometheus metrics
  └─ Grafana dashboards + alertas

Sprint 1.0 (2 semanas):
  ├─ HandleRefine implementado
  ├─ HandleExport implementado
  └─ Dead Letter Queue

Sprint 1.1 (1 semana):
  ├─ CI/CD (GitHub Actions)
  ├─ docker-compose.prod.yml
  └─ Deploy para Cloud Run (ou equivalente)

Total: 11 semanas (~3 meses) até MVP production-ready

APÊNDICES

A. Comandos de Análise Usados

# Contagem de arquivos Go
find . -name "*.go" | wc -l

# Contagem de linhas de código
find . -name "*.go" -exec wc -l {} + | tail -1

# Busca de TODOs
grep -r "TODO" --include="*.go"

# Busca de autenticação
grep -ri "auth\|jwt" internal/ --include="*.go"

# Busca de pagamentos
grep -ri "stripe\|payment" internal/ --include="*.go"

# Busca de webhooks
grep -r "webhook" . --include="*.go"

# Busca de User model
grep -r "type User\|struct User" internal/domain/

# Lista de handlers
find internal/api/handlers -name "*.go" -not -name "*_test.go"

# Lista de services
find internal/service -name "*.go" -not -name "*_test.go"

B. Evidências de Código (Snippets Críticos)

Hardcoded "default_user"

// internal/api/handlers/project_handler.go:46-47
// UserID padrão até implementação de autenticação (Sprint 3-4)
userID := "default_user"

Handlers não implementados

// internal/worker/worker.go:267-271
func (w *Worker) HandleRefine(ctx context.Context, task *asynq.Task) error {
    // TODO: Implement refinement logic (Phase 3)
    fmt.Println("⚠️  [REFINE] Not implemented yet (Phase 3)")
    return fmt.Errorf("refinement not implemented")
}
// internal/worker/worker.go:274-278
func (w *Worker) HandleExport(ctx context.Context, task *asynq.Task) error {
    // TODO: Implement export logic (Phase 4)
    fmt.Println("⚠️  [EXPORT] Not implemented yet (Phase 4)")
    return fmt.Errorf("export not implemented")
}

GORM AutoMigrate (não versionado)

// internal/database/database.go:42-46
err := DB.AutoMigrate(
    &domain.Project{},
    &domain.Job{},
    &domain.AIAnalysis{},
)

C. Estrutura de Diretórios

typecraft/
├── cmd/
│   ├── api/          # Servidor HTTP (Gin)
│   ├── worker/       # Worker assíncrono (Asynq)
│   ├── analyze/      # CLI para análise
│   ├── design/       # CLI para design
│   └── render/       # CLI para rendering
│
├── internal/
│   ├── api/
│   │   └── handlers/ # 12 handlers HTTP
│   ├── service/      # 6 services
│   ├── repository/   # 3 repositories
│   ├── domain/       # 4 models
│   ├── database/     # Conexão + migrations
│   ├── worker/       # 8 job handlers
│   ├── queue/        # Asynq client
│   ├── cache/        # Redis client
│   ├── storage/      # MinIO client
│   ├── config/       # Configurações
│   └── health/       # Health checks
│
├── pkg/
│   ├── pipeline/     # Pipeline de rendering
│   ├── design/       # Design service
│   ├── epub/         # ePub generation
│   ├── latex/        # LaTeX compiler
│   ├── converter/    # Pandoc wrapper
│   └── typography/   # Style engine
│
├── web/              # Frontend (Next.js) - NÃO ANALISADO
├── templates/        # Templates LaTeX/HTML
├── scripts/          # Scripts de setup/test
├── docker-compose.yml
├── Dockerfile        # Multi-stage (4 stages)
├── .env.example
├── go.mod
└── go.sum

D. Dependências Críticas

Runtime (Produção):

  • gin-gonic/gin - HTTP router
  • gorm.io/gorm - ORM
  • hibiken/asynq - Job queue
  • redis/go-redis - Redis client
  • minio/minio-go - Storage client
  • sashabaranov/go-openai - OpenAI client

Ferramentas Externas:

  • pandoc - Conversão de documentos
  • lualatex - Rendering LaTeX
  • pagedjs-cli - HTML → PDF
  • chromium - Headless browser

Total de dependências Go: ~80

CONCLUSÃO

O TypeCraft é um sistema FUNCIONAL PARCIAL com arquitetura bem estruturada, mas com gaps críticos que impedem lançamento em produção:

  1. Zero autenticação (API totalmente aberta)
  2. Zero sistema de billing (impossível monetizar)
  3. Migrations não versionadas (arriscado em produção)
  4. 2 workers não implementados (features quebradas)
  5. Sem observability (impossível monitorar)

Estado Atual: Adequado para DESENVOLVIMENTO/MVP, inadequado para PRODUÇÃO.

Tempo estimado para produção: 3 meses (11 sprints).

Prioridade máxima: Autenticação + Billing (bloqueadores absolutos).

Documento gerado em: 2025-11-02
Linhas do documento: 2,500+
Análise baseada em: 131 arquivos, 37,986 linhas de código
Gaps identificados: 48 (11 críticos, 15 altos, 16 médios, 6 baixos)

Assinatura:
Claude Code (Anthropic) - TypeCraft Code Analyzer v0.1.0