TypeCraft Air Gaps Analysis Report

Generated: 2025-11-03 23:17 UTC Scope: Frontend-Backend Integration Status: 🔴 CRITICAL GAPS FOUND

Executive Summary

Análise completa comparando:

Backend: 67 endpoints implementados (cmd/api/main.go)
Frontend: 38+ endpoints chamados (web/src/lib/api/*.ts)

Criticidade

🔴 CRITICAL (P0): 8 gaps - bloqueiam funcionalidades existentes no UI
🟡 WARNING (P1): 15 gaps - endpoints orphaned (backend implementado, frontend não usa)
🟢 INFO (P2): 5 gaps - inconsistências de schema/nomenclatura

🔴 CRITICAL AIR GAPS (P0)

1. DESIGN ENDPOINTS - Sobrecarga de chamadas ⚠️

Frontend chama (design.ts):

POST /projects/{id}/design/generate          ✅ EXISTE
GET /fonts                                     ✅ EXISTE
GET /fonts/pairings?genre={genre}             ❌ NÃO EXISTE
POST /design/colors/generate                   ❌ NÃO EXISTE
GET /design/templates                          ❌ NÃO EXISTE
POST /projects/{id}/design/template            ❌ NÃO EXISTE
POST /projects/{id}/design/validate            ❌ NÃO EXISTE
GET /projects/{id}/design/metrics              ❌ NÃO EXISTE
POST /projects/{id}/design                     ❌ NÃO EXISTE
POST /projects/{id}/design/reset               ❌ NÃO EXISTE

Backend implementa (cmd/api/main.go:412-413):

v1.POST("/projects/:id/design/generate", designHandler.GenerateDesign)
v1.GET("/fonts", designHandler.ListFonts)

Impacto: Frontend DesignCustomizer component vai falhar ao chamar 8 endpoints não implementados.

Localização:

Frontend: web/src/lib/api/design.ts:59-149 (10 funções)
Backend: cmd/api/main.go:412-413 (apenas 2 routes)

Fix requerido: Implementar 8 endpoints faltantes no backend OU remover chamadas do frontend.

2. RENDER ENDPOINTS - Sobrecarga de chamadas ⚠️

Frontend chama (render.ts):

POST /projects/{id}/render/html               ✅ EXISTE
POST /projects/{id}/render/pdf                ✅ EXISTE
GET /projects/{id}/render/status              ✅ EXISTE
POST /projects/{id}/render/epub               ❌ NÃO EXISTE
POST /projects/{id}/render/mobi               ❌ NÃO EXISTE
GET /projects/{id}/render/history             ❌ NÃO EXISTE
POST /projects/{id}/render/{renderId}/cancel  ❌ NÃO EXISTE
POST /projects/{id}/render/{renderId}/retry   ❌ NÃO EXISTE
GET /projects/{id}/render/{renderId}/logs     ❌ NÃO EXISTE
POST /projects/{id}/render/batch              ❌ NÃO EXISTE

Backend implementa (cmd/api/main.go:416-418):

v1.POST("/projects/:id/render/html", renderHandler.RenderHTML)
v1.POST("/projects/:id/render/pdf", renderHandler.RenderPDF)
v1.GET("/projects/:id/render/status", renderHandler.GetRenderStatus)

Impacto: Frontend vai falhar ao tentar gerar EPUB/MOBI ou usar funcionalidades de histórico/cancel/retry.

Localização:

Frontend: web/src/lib/api/render.ts:109-190 (7 funções extras)
Backend: cmd/api/main.go:416-418 (3 routes apenas)

Fix requerido: Implementar 7 endpoints faltantes OU remover do UI as opções de EPUB/MOBI/History.

3. PROJECTS ENDPOINTS - Chamadas inválidas ⚠️

Frontend chama (projects.ts):

GET /projects/{id}/download?type={pdf|epub}   ❌ NÃO EXISTE
GET /projects/{id}/stats                      ❌ NÃO EXISTE
POST /projects/{id}/duplicate                 ❌ NÃO EXISTE
GET /projects/{id}/export                     ❌ NÃO EXISTE

Backend implementa:

projects.GET("/:id/jobs", projectHandler.GetProjectJobs)  // Diferente de /stats
// Nenhum endpoint /download, /stats, /duplicate, /export

Impacto: Download de PDFs/EPUBs vai falhar (endpoint crítico!).

Localização:

Frontend: web/src/lib/api/projects.ts:105-135
Backend: Endpoints ausentes

Fix requerido: Implementar 4 endpoints críticos, especialmente /download.

4. ANALYSIS ENDPOINTS - Endpoint crítico ausente 🔴

Frontend chama (analysis.ts:108):

GET /projects/{projectId}/metrics   ❌ Backend usa DIFERENTE endpoint

Backend implementa (main.go:407):

v1.GET("/projects/:id/metrics", analysisHandler.GetProjectMetrics)  ✅ EXISTE

Status: ✅ MATCHING - False alarm, endpoint existe mas path é idêntico.

Action: Validar se analysisHandler.GetProjectMetrics retorna dados esperados pelo frontend.

5. COVER GENERATION - Endpoint AI faltante ⚠️

Frontend chama (CoverGenerator/index.tsx:88):

POST /projects/{projectId}/cover/generate     ✅ CONDICIONAL (if aiHandler != nil)

Backend implementa (main.go:386):

if aiHandler != nil {
    aiGroup.POST("/:project_id/cover/generate", aiHandler.GenerateCover)
}

Impacto: Se aiHandler == nil, endpoint não registra. Frontend recebe 404.

Localização:

Frontend: web/src/components/CoverGenerator/index.tsx:88
Backend: cmd/api/main.go:380-390 (conditional)

Fix requerido: Garantir aiHandler sempre inicializado OU frontend detectar se AI está habilitado.

6. AUTHENTICATION - Backend não valida tokens 🔴 CRÍTICO

Frontend envia (client.ts:54):

headers: {
  Authorization: `Bearer ${session.accessToken}`
}

Backend espera:

// NENHUM middleware de autenticação visível em main.go
// Rotas não têm proteção JWT

Impacto: Backend está aceitando requests sem autenticação! Potencial vulnerabilidade.

Localização:

Frontend: web/src/lib/api/client.ts:54
Backend: cmd/api/main.go (nenhum middleware de auth)

Fix requerido: URGENTE - Implementar middleware JWT para validar tokens NextAuth.

7. CORS - Configuração ausente 🔴 CRÍTICO

Frontend origem: https://seuredator.com.br

Backend CORS (main.go:237-245):

config := cors.DefaultConfig()
config.AllowOrigins = []string{
    "http://localhost:3000",
    "http://localhost:5173",  // Vite dev
}

Impacto: Produção vai receber CORS errors! Frontend em seuredator.com.br será bloqueado.

Localização: cmd/api/main.go:237-245

Fix requerido: URGENTE - Adicionar https://seuredator.com.br ao AllowOrigins.

8. HEALTH CHECK - Endpoint chamado incorretamente ⚠️

Frontend chama (api.ts:114):

GET /health

Backend implementa (main.go:355-360):

router.GET("/health", healthHandler.HealthCheck)
router.GET("/health/live", healthHandler.LivenessCheck)
router.GET("/health/ready", healthHandler.ReadinessCheck)

Status: ✅ MATCHING - Endpoint existe.

Action: Validar resposta de /health é compatível com expectativas do frontend.

🟡 ORPHANED ENDPOINTS (P1) - Backend implementado, Frontend NÃO USA

Backend Modules SEM UI correspondente

1. SCIENTIFIC PUBLISHING SUITE (17 endpoints)

// Citations (6 endpoints)
POST /scientific/citations
GET /scientific/citations
GET /scientific/citations/:id
GET /scientific/citations/:id/format
GET /scientific/bibliography
GET /scientific/export/bibtex
GET /scientific/export/ris

// Math (4 endpoints)
POST /scientific/math/detect
POST /scientific/math/validate
GET /scientific/math/commands
POST /scientific/math/number

// Charts & Statistics (4 endpoints)
POST /scientific/charts/validate
POST /scientific/charts/histogram
POST /scientific/statistics/calculate
POST /scientific/statistics/outliers

Impacto: Módulo científico inteiro invisível no frontend.

Recomendação: Criar Scientific Dashboard (FASE 7).

2. QA SUITE (12 endpoints)

// Typography QA (2 endpoints)
POST /qa/typography
POST /qa/typography/pages

// Content QA - OpenAI (5 endpoints)
POST /qa/content/grammar
POST /qa/content/consistency
POST /qa/content/facts
POST /qa/content/style
POST /qa/content/document

// Print QA (4 endpoints)
POST /qa/print/validate
POST /qa/print/readiness
POST /qa/print/standard
POST /qa/print/image

Impacto: Módulo QA inteiro sem UI (Sprint 6 completado mas não exposto).

Recomendação: Criar QA Dashboard (FASE 7 - PRIORIDADE ALTA).

3. MARKETING AUTOMATION (8 endpoints)

// Book Trailer (2 endpoints)
POST /projects/:id/marketing/trailer
GET /projects/:id/marketing/trailer/:jobId

// Social Media (3 endpoints)
POST /projects/:id/marketing/social
POST /projects/:id/marketing/social/batch
GET /projects/:id/marketing/social/:jobId

// Amazon KDP (3 endpoints)
POST /projects/:id/marketing/kdp/optimize
GET /marketing/kdp/categories
GET /marketing/kdp/keywords

Impacto: Módulo marketing invisível (Sprint 6 completo mas sem UI).

Recomendação: Criar Marketing Dashboard (FASE 7 - PRIORIDADE ALTA).

4. COLOR MANAGEMENT (3 endpoints)

POST /color/convert/rgb-to-cmyk
POST /color/validate/image
GET /color/profiles

Impacto: Funcionalidade de print-readiness invisível.

Recomendação: Adicionar ao Print Readiness Dashboard (FASE 7).

5. IMAGING OPTIMIZATION (4 endpoints)

POST /imaging/optimize
POST /imaging/optimize/batch
GET /imaging/config/:destination
POST /imaging/mockup/generate

Impacto: 3D Mockup generator invisível (Módulo 4 Sprint 5).

Recomendação: Integrar em workflow de export OU criar dashboard.

6. TYPOGRAPHY AI (2 endpoints)

POST /typography/recommend
POST /layouts/suggest

Impacto: Recomendações AI de tipografia não expostas.

Recomendação: Integrar no TypographySelector component (web/src/components/TypographySelector.tsx).

7. PROCESSING ENDPOINTS (3 endpoints)

POST /processing/convert
POST /processing/pdf
POST /processing/manuscript

Impacto: Conversão direta de arquivos não exposta (alternativa ao workflow via Projects).

Recomendação: Adicionar utilitário de conversão rápida no dashboard.

8. EXPORT ADVANCED (2 endpoints)

POST /export/pdf
POST /export/pdf-x

Impacto: Conversão PDF → PDF/X para impressão não exposta.

Recomendação: Integrar em Print Readiness Dashboard.

🟢 SCHEMA INCONSISTENCIES (P2)

1. Project Status Enums

Frontend espera (dashboard/page.tsx:140-145):

status: "created" | "uploading" | "analyzing" | "designing" | "rendering" | "completed" | "failed"

Backend retorna (verificar em internal/domain/project.go):

// PRECISA VALIDAÇÃO - comparar com definição StatusProcessing, etc

Action: Validar enums match exatamente.

2. Render Options - Parametros extras no frontend

Frontend envia (render.ts:158-173):

pdf_quality?: 'draft' | 'standard' | 'high' | 'print'
compression?: boolean
embed_fonts?: boolean
pdf_version?: '1.4' | '1.5' | '1.6' | '1.7'
watermark?: string
// ... 10+ campos

Backend aceita (verificar internal/handlers/render_handler.go):

// PRECISA VALIDAÇÃO - verificar struct RenderRequest

Action: Validar backend aceita todos os campos do frontend.

3. Cover Generation Enums

Frontend envia (CoverGenerator/index.tsx:88):

genre: 'fiction' | 'non-fiction' | 'academic' | 'poetry' | 'art' | 'children' | 'technical'
mood: 'dark' | 'vibrant' | 'minimal' | 'baroque' | 'elegant' | 'mysterious' | 'playful' | 'serious'
aspect_ratio: '6x9' | '5.5x8.5' | '8x10' | 'square' | 'a4'

Backend espera (verificar internal/handlers/ai_handler.go):

// PRECISA VALIDAÇÃO - verificar struct GenerateCoverRequest

Action: Validar enums são idênticos.

4. Analysis Response Schema

Frontend espera (useProjects hook usa analysis data):

// Verificar em web/src/lib/hooks/useProjects.ts que schema esperado

Backend retorna (analysisHandler.AnalyzeProject):

// Verificar struct em internal/handlers/analysis_handler.go

Action: Validar schemas match.

5. Pagination Metadata

Frontend usa (projects.ts:33-50):

{ data: projects[], meta: { total, page, per_page } }

Backend retorna (verificar):

// Verificar ListProjects response structure

Action: Validar metadata format.

📋 PRIORITY FIX LIST

P0 - DEPLOY BLOCKERS (Fix ANTES do deploy)

✅ CORS Configuration - Adicionar seuredator.com.br
- File: cmd/api/main.go:237-245
- Add: config.AllowOrigins = append(config.AllowOrigins, "https://seuredator.com.br")
🔴 Authentication Middleware - Proteger rotas
- File: cmd/api/main.go (após linha 245)
- Add: JWT validation middleware
🔴 Projects /download endpoint - Implementar
- Handler: internal/handlers/project_handler.go
- Route: projects.GET("/:id/download", projectHandler.DownloadFile)

P1 - POST DEPLOY (Fix depois)

Implementar Design endpoints faltantes (8 endpoints)
Implementar Render endpoints faltantes (7 endpoints)
Implementar Projects utility endpoints (3 endpoints: stats, duplicate, export)
Validar schemas match (5 áreas)

P2 - ROADMAP (FASE 7)

Criar QA Dashboard
Criar Marketing Dashboard
Criar Scientific Dashboard
Criar Print Readiness Dashboard
Integrar Typography AI recommendations

🎯 NEXT ACTIONS

Immediate (before Cloud Run deploy completes):

Fix CORS (1 linha)
Add JWT middleware (criar arquivo novo)
Implement /download endpoint (reutilizar export logic)

After Deploy: 4. Run E2E functional tests (FASE 3) 5. Fix P1 issues iteratively 6. Plan FASE 7 dashboard creation

Generated by: Claude Code (Constituição Vértice v3.0) Report Owner: Juan CS Last Updated: 2025-11-03 23:17 UTC

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TypeCraft Air Gaps Analysis Report

Executive Summary

Criticidade

🔴 CRITICAL AIR GAPS (P0)

1. DESIGN ENDPOINTS - Sobrecarga de chamadas ⚠️

2. RENDER ENDPOINTS - Sobrecarga de chamadas ⚠️

3. PROJECTS ENDPOINTS - Chamadas inválidas ⚠️

4. ANALYSIS ENDPOINTS - Endpoint crítico ausente 🔴

5. COVER GENERATION - Endpoint AI faltante ⚠️

6. AUTHENTICATION - Backend não valida tokens 🔴 CRÍTICO

7. CORS - Configuração ausente 🔴 CRÍTICO

8. HEALTH CHECK - Endpoint chamado incorretamente ⚠️

🟡 ORPHANED ENDPOINTS (P1) - Backend implementado, Frontend NÃO USA

Backend Modules SEM UI correspondente

1. SCIENTIFIC PUBLISHING SUITE (17 endpoints)

2. QA SUITE (12 endpoints)

3. MARKETING AUTOMATION (8 endpoints)

4. COLOR MANAGEMENT (3 endpoints)

5. IMAGING OPTIMIZATION (4 endpoints)

6. TYPOGRAPHY AI (2 endpoints)

7. PROCESSING ENDPOINTS (3 endpoints)

8. EXPORT ADVANCED (2 endpoints)

🟢 SCHEMA INCONSISTENCIES (P2)

1. Project Status Enums

2. Render Options - Parametros extras no frontend

3. Cover Generation Enums

4. Analysis Response Schema

5. Pagination Metadata

📋 PRIORITY FIX LIST

P0 - DEPLOY BLOCKERS (Fix ANTES do deploy)

P1 - POST DEPLOY (Fix depois)

P2 - ROADMAP (FASE 7)

🎯 NEXT ACTIONS

FilesExpand file tree

AIR_GAPS_REPORT.md

Latest commit

History

AIR_GAPS_REPORT.md

File metadata and controls

TypeCraft Air Gaps Analysis Report

Executive Summary

Criticidade

🔴 CRITICAL AIR GAPS (P0)

1. DESIGN ENDPOINTS - Sobrecarga de chamadas ⚠️

2. RENDER ENDPOINTS - Sobrecarga de chamadas ⚠️

3. PROJECTS ENDPOINTS - Chamadas inválidas ⚠️

4. ANALYSIS ENDPOINTS - Endpoint crítico ausente 🔴

5. COVER GENERATION - Endpoint AI faltante ⚠️

6. AUTHENTICATION - Backend não valida tokens 🔴 CRÍTICO

7. CORS - Configuração ausente 🔴 CRÍTICO

8. HEALTH CHECK - Endpoint chamado incorretamente ⚠️

🟡 ORPHANED ENDPOINTS (P1) - Backend implementado, Frontend NÃO USA

Backend Modules SEM UI correspondente

1. SCIENTIFIC PUBLISHING SUITE (17 endpoints)

2. QA SUITE (12 endpoints)

3. MARKETING AUTOMATION (8 endpoints)

4. COLOR MANAGEMENT (3 endpoints)

5. IMAGING OPTIMIZATION (4 endpoints)

6. TYPOGRAPHY AI (2 endpoints)

7. PROCESSING ENDPOINTS (3 endpoints)

8. EXPORT ADVANCED (2 endpoints)

🟢 SCHEMA INCONSISTENCIES (P2)

1. Project Status Enums

2. Render Options - Parametros extras no frontend

3. Cover Generation Enums

4. Analysis Response Schema

5. Pagination Metadata

📋 PRIORITY FIX LIST

P0 - DEPLOY BLOCKERS (Fix ANTES do deploy)

P1 - POST DEPLOY (Fix depois)

P2 - ROADMAP (FASE 7)

🎯 NEXT ACTIONS