# Relatorio Pre-Implementacao API V1

## Objetivo

Registrar, antes de qualquer alteracao em arquivos existentes, quais pontos do sistema atual precisarao ser tocados para implementar a primeira onda da camada adicional `/api/v1`, por que cada alteracao e necessaria, qual o risco associado e como sera garantido que a Ktalogu continuara funcionando exatamente como funciona hoje.

## Escopo Aprovado

- Infraestrutura:
  - `/api/v1/health`
  - `/api/v1/openapi`
  - `/api/v1/docs`
- Autenticacao:
  - `/api/v1/auth/login`
  - `/api/v1/auth/logout`
  - `/api/v1/auth/refresh`
  - `/api/v1/auth/me`
- Dominios:
  - `company`
  - `products`
  - `categories`
  - `quotes`
  - `payment-links`

## Arquivos Existentes Que Serao Alterados

### 1. `apps/admin/src/utils/supabase/middleware.ts`

- Motivo:
  - Hoje o middleware redireciona requisicoes sem sessao de cookie para `/`.
  - A nova API externa usara `Authorization: Bearer <jwt>` e precisa passar pelo app sem ser redirecionada.
- Alteracao planejada:
  - Isolar `/api/v1/*` da regra atual de redirect baseada em cookie.
  - Manter o comportamento atual das telas e das rotas antigas inalterado.
- Risco:
  - Medio.
  - Um bypass amplo demais poderia afrouxar a protecao de rotas existentes.
- Garantia de nao regressao:
  - O bypass sera restrito apenas ao prefixo exato `/api/v1/`.
  - As rotas atuais do dashboard continuarao protegidas pelo mesmo fluxo.
  - Serao adicionados testes para acesso negado sem autenticacao na nova camada.

### 2. `apps/admin/src/app/api/products/route.ts`

- Motivo:
  - A regra de produtos hoje esta concentrada nessa rota.
  - A nova API `/api/v1/products` nao pode duplicar essa regra.
- Alteracao planejada:
  - Extrair o nucleo de leitura/escrita para um service compartilhado.
  - Manter a rota antiga chamando o mesmo service.
- Risco:
  - Medio.
  - A rota atual e grande e possui validacoes importantes de produto, imagens, precificacao e catalogo.
- Garantia de nao regressao:
  - A extracao sera minima e cirurgica, sem alterar contrato da rota atual.
  - A rota antiga continuara exportando os mesmos handlers.
  - A API nova apenas reutilizara o mesmo service.
  - Havera testes de busca de produtos pela nova API.

### 3. `apps/admin/src/app/api/categories/route.ts`

- Motivo:
  - O CRUD atual de categorias ja existe e concentra validacoes de hierarquia e slug.
  - A nova API `/api/v1/categories` deve reaproveitar exatamente essa logica.
- Alteracao planejada:
  - Extrair listagem/criacao/validacoes para service compartilhado.
  - Manter a rota antiga usando o mesmo service.
- Risco:
  - Baixo para medio.
  - A regra e mais concentrada e bem delimitada do que a de produtos.
- Garantia de nao regressao:
  - Nenhuma mudanca de semantica da rota atual.
  - O contrato atual do dashboard permanece igual.
  - A API nova consumira o mesmo service.

### 4. `apps/admin/src/app/api/quotes/route.ts`

- Motivo:
  - A criacao e listagem de orcamentos ja existem e incluem regras de cliente, itens, compartilhamento e aprovacao futura.
  - A API `/api/v1/quotes` precisa reaproveitar essa logica sem duplicacao.
- Alteracao planejada:
  - Extrair o nucleo da criacao/listagem para service compartilhado.
  - Preservar o handler atual.
- Risco:
  - Medio a alto.
  - A rota atual possui regras extensas e pontos de integracao com itens e cliente tecnico.
- Garantia de nao regressao:
  - Extracao incremental, mantendo o handler atual como fachada.
  - Nenhuma tela sera alterada.
  - Testes cobrirao criacao de orcamento pela nova API.

### 5. `apps/admin/src/app/api/quotes/[id]/approve/route.ts`

- Motivo:
  - A aprovacao de orcamento e a geracao de pedido ja existem.
  - A nova API precisa expor a mesma operacao usando o mesmo fluxo atual.
- Alteracao planejada:
  - Extrair a aprovacao para service compartilhado.
  - Manter a rota antiga chamando esse service.
- Risco:
  - Medio.
  - Essa rota impacta um fluxo operacional critico.
- Garantia de nao regressao:
  - Sera preservado o uso da logica/RPC atual de aprovacao.
  - Nao havera mudanca no comportamento da rota antiga.
  - Havera testes cobrindo aprovacao de orcamento e geracao de pedido.

### 6. `apps/admin/src/app/api/financial/payment-links/route.ts`

- Motivo:
  - O dominio de payment links ja esta consolidado nessa rota.
  - A nova API `/api/v1/payment-links` deve compartilhar a mesma regra.
- Alteracao planejada:
  - Extrair listagem/criacao/atualizacao para service compartilhado.
  - Manter a rota antiga como adaptadora para o service.
- Risco:
  - Medio.
  - Existem regras de validacao de status, tipo, origem publica e codigo unico.
- Garantia de nao regressao:
  - Nenhuma mudanca na URL nem no contrato atual do backoffice.
  - A camada nova apenas reutilizara o service extraido.

## Arquivos Existentes Que Nao Devem Ser Alterados Nesta Onda

- `apps/public/**`
  - Fora do escopo da primeira onda da API administrativa versionada.
- `apps/owner/**`
  - Fora do escopo.
- `apps/admin/src/app/dashboard/**`
  - Nao sera alterado layout, fluxo ou comportamento de tela.
- `apps/admin/src/lib/whatsapp-manager.ts`
  - Explicitamente fora do escopo.

## Como Sera Garantido Que Nada Quebra

- A nova API sera criada como camada adicional isolada em `/api/v1`.
- Nenhuma rota atual sera removida, renomeada ou substituida.
- Quando houver regra dentro de rota atual:
  - ela sera extraida para um service compartilhado;
  - a rota antiga continuara funcionando;
  - a rota nova usara o mesmo service.
- O middleware sera alterado apenas no necessario para permitir `Bearer token` na nova camada.
- Serao criados testes para:
  - login API;
  - autenticacao;
  - busca de produtos;
  - criacao de orcamento;
  - aprovacao de orcamento;
  - geracao de pedido;
  - acesso negado sem autenticacao.

## Veredito

- A implementacao pode prosseguir dentro das restricoes aprovadas.
- O ponto mais sensivel e o middleware de autenticacao.
- O restante pode ser feito com risco controlado desde que a extracao para services compartilhados seja incremental e limitada ao escopo da primeira onda.