aiox-core 5.0.7 → 5.0.8

package/docs/guides/supabase-ops-handoff.md

@@ -0,0 +1,768 @@
+# AIOX-Pro Access Ops Handoff
+
+**Version:** 3.0.0
+**Last Updated:** 2026-04-19
+**Status:** Active
+
+---
+
+## Overview
+
+Este handoff não é para descoberta genérica de Supabase.
+
+Ele existe para operações repetíveis do AIOX-Pro access/licensing, onde o projeto, o serviço e o fluxo já são conhecidos. O foco aqui é permitir que o squad-creator gere tasks específicas para operações como:
+
+- criar novo acesso
+- liberar Pro para um e-mail existente
+- reenviar verificação
+- confirmar e-mail por admin
+- reset de senha
+- diagnosticar por que um login/acesso falhou
+
+O documento precisa ser profundo o suficiente para evitar que a task gerada repita investigação desnecessária ou tome atalhos perigosos.
+
+---
+
+## Fixed Context
+
+Para este fluxo, os fatos já conhecidos são:
+
+- serviço real: `https://aiox-license-server.vercel.app`
+- projeto Supabase correto: `aios-license-server`
+- project ref: `evvvnarpwcdybxdvcwjh`
+- auth backend: Supabase Auth do projeto `evvvnarpwcdybxdvcwjh`
+- entitlement/buyer oracle: tabela `public.buyers`
+- tabelas auxiliares relevantes:
+  - `public.buyer_validations`
+  - `public.licenses`
+  - `public.activations`
+
+**Regra:** para operações de acesso AIOX-Pro, não gastar tempo redescobrindo projeto. Começar direto deste contexto.
+
+---
+
+## What We Already Learned In Practice
+
+Este fluxo já foi executado manualmente e os aprendizados abaixo devem ser tratados como conhecimento operacional consolidado:
+
+- `POST /api/v1/auth/check-email` é o pré-check oficial do backend
+  - ele retorna `isBuyer` e `hasAccount`
+  - ele deve ser o primeiro oracle de estado do usuário
+
+- `POST /api/v1/auth/login` é o segundo oracle
+  - se retornar `EMAIL_NOT_VERIFIED`, o problema é confirmação de e-mail
+  - se retornar `INVALID_CREDENTIALS`, o problema é senha
+  - se retornar `200`, auth está funcional
+
+- no projeto `evvvnarpwcdybxdvcwjh`, o login real depende do Supabase Auth
+
+- o entitlement Pro não vem de `public.licenses`
+  - o oracle operacional para buyer é `public.buyers`
+  - se `buyers` não tiver o e-mail ativo, `check-email` não sobe `isBuyer`
+
+- `public.licenses` e `public.activations` são importantes para licença e máquinas
+  - mas não são o primeiro write para “liberar acesso”
+
+- não é necessário ativar licença em máquina para concluir onboarding/access ops
+  - ativação consome seat/estado operacional e deve ficar fora de tasks de provisionamento básico
+
+---
+
+## Operational Goal
+
+Toda task derivada deste handoff deve responder claramente:
+
+- o usuário já existe no auth?
+- o e-mail está confirmado?
+- o e-mail já está liberado em `buyers`?
+- o fluxo final no serviço real funciona?
+
+---
+
+## Known Endpoints
+
+Endpoints do serviço real que importam:
+
+- `POST /api/v1/auth/check-email`
+- `POST /api/v1/auth/signup`
+- `POST /api/v1/auth/login`
+- `POST /api/v1/auth/activate-pro`
+- `POST /api/v1/auth/request-reset`
+- `POST /api/v1/auth/resend-verification`
+
+UI/flow auxiliar:
+
+- reset de senha: `https://aiox-license-server.vercel.app/reset-password`
+
+---
+
+## Endpoint Semantics
+
+### `POST /api/v1/auth/check-email`
+
+Usar para classificar o caso antes de qualquer write.
+
+Resposta de interesse:
+
+- `isBuyer: boolean`
+- `hasAccount: boolean`
+- `email`
+
+Interpretação:
+
+- `isBuyer=false`, `hasAccount=false`
+  - falta conta e falta entitlement
+- `isBuyer=false`, `hasAccount=true`
+  - conta existe, falta buyer
+- `isBuyer=true`, `hasAccount=false`
+  - caso inconsistente ou migração parcial; investigar auth
+- `isBuyer=true`, `hasAccount=true`
+  - provisioning quase completo; validar login
+
+### `POST /api/v1/auth/signup`
+
+Usar somente quando `hasAccount=false`.
+
+Saída útil:
+
+- `userId`
+- `message`
+
+### `POST /api/v1/auth/login`
+
+Usar para validar se o usuário consegue de fato entrar.
+
+Saídas/erros úteis:
+
+- `200` com `accessToken`, `userId`, `emailVerified`
+- `EMAIL_NOT_VERIFIED`
+- `INVALID_CREDENTIALS`
+
+### `POST /api/v1/auth/request-reset`
+
+Usar para recovery padrão quando não for desejável reset manual por admin.
+
+### `POST /api/v1/auth/resend-verification`
+
+Usar quando a conta existe mas ainda depende do inbox do usuário.
+
+---
+
+## Tables That Matter
+
+### `public.buyers`
+
+Oracle de entitlement Pro.
+
+Campos relevantes:
+
+- `email`
+- `source`
+- `purchased_at`
+- `is_active`
+- `metadata`
+
+Regra prática:
+
+- se o e-mail não está ativo em `buyers`, `check-email` não vai retornar `isBuyer: true`
+- para “liberar acesso Pro”, este é o write primário
+
+### `public.buyer_validations`
+
+Cache/registro de validação de buyer por usuário autenticado.
+
+Campos relevantes:
+
+- `user_id`
+- `email`
+- `is_valid`
+- `validated_at`
+- `expires_at`
+
+Regra prática:
+
+- é tabela de apoio/cache
+- não é o primeiro write para grant manual
+- pode ser inspecionada em diagnóstico, mas o provisioning deve preferir `buyers`
+
+### `public.licenses`
+
+Licenças emitidas pelo backend.
+
+Campos relevantes:
+
+- `key`
+- `customer_email`
+- `features`
+- `max_seats`
+- `expires_at`
+- `user_id`
+
+Regra prática:
+
+- relevante para emissão/licença existente
+- não usar como primeiro mecanismo de grant manual de acesso
+
+### `public.activations`
+
+Ativações por máquina.
+
+Campos relevantes:
+
+- `license_id`
+- `machine_id`
+- `activated_at`
+- `deactivated_at`
+
+Regra prática:
+
+- só entra em cena quando o problema é ativação/seat/machine lifecycle
+- não é etapa padrão de criar acesso ou reset de senha
+
+---
+
+## Non-Negotiable Rules
+
+- não redescobrir projeto Supabase para AIOX-Pro access ops
+- não escrever em `full-agent` para resolver licensing
+- não inferir schema diferente do que já está confirmado acima
+- não encerrar tarefa sem validar no serviço real
+- não expor `service_role`, `anon`, JWT, reset token ou access token
+- não consumir seat/activation sem necessidade explícita
+- não escrever em `licenses` para resolver um caso que é apenas buyer/auth
+- não usar `buyer_validations` como substitute de `buyers`
+
+---
+
+## Mandatory Diagnostic Order
+
+Toda task deve seguir esta ordem, mesmo quando parecer óbvio o que está errado:
+
+1. `check-email`
+2. `login` se houver senha (read-only, classifica auth rapidamente)
+3. `auth admin` por e-mail
+4. `buyers` por e-mail
+5. `buyer_validations` apenas se houver dúvida de cache/estado intermediário
+6. `licenses` por `customer_email` apenas se o problema incluir licença
+7. `activations` apenas se o problema incluir máquina/seat
+
+> Esta ordem é a mesma da seção [Better Triage Order In Practice](#better-triage-order-in-practice) abaixo — única lista canônica. `check-email + login` classifica a maioria dos casos sem write.
+
+Justificativa:
+
+- esta ordem minimiza writes
+- evita tocar licença quando o problema é apenas auth
+- evita tocar auth quando o problema é apenas buyer
+- evita consumir seat durante suporte básico
+
+---
+
+## Decision Tree
+
+### Case A
+
+`check-email => isBuyer=false, hasAccount=false`
+
+Fazer:
+
+1. `signup`
+2. confirmar e-mail por admin se acesso imediato for necessário
+3. inserir `buyers`
+4. revalidar `check-email`
+5. validar `login`
+
+### Case B
+
+`check-email => isBuyer=false, hasAccount=true`
+
+Fazer:
+
+1. localizar auth user
+2. inserir `buyers` se ausente
+3. se login falhar por `EMAIL_NOT_VERIFIED`, confirmar e-mail por admin ou reenviar verificação
+4. revalidar `check-email`
+5. validar `login`
+
+### Case C
+
+`check-email => isBuyer=true, hasAccount=true`, mas login falha por `EMAIL_NOT_VERIFIED`
+
+Fazer:
+
+1. confirmar e-mail por admin ou reenviar verificação
+2. revalidar `login`
+
+### Case D
+
+`check-email => isBuyer=true, hasAccount=true`, mas login falha por `INVALID_CREDENTIALS`
+
+Fazer:
+
+1. `request-reset` se o fluxo for self-service
+2. ou update manual de senha por admin se o suporte precisar entregar senha provisória
+3. validar `login`
+
+### Case E
+
+`check-email => isBuyer=true, hasAccount=false`
+
+Fazer:
+
+1. tratar como estado inconsistente
+2. inspecionar auth admin
+3. criar conta somente se confirmar ausência de user
+4. não tocar licença antes de resolver auth
+
+---
+
+## Standard Validation Sequence
+
+Toda task deve terminar com esta sequência:
+
+1. validar `check-email`
+2. validar `login` se houver senha conhecida
+3. só validar `activate-pro` se o objetivo da task for ativação real em máquina
+
+Estados esperados:
+
+- acesso liberado:
+  - `isBuyer: true`
+  - `hasAccount: true`
+- login funcionando:
+  - status `200`
+  - `emailVerified: true`
+
+Se a task não consegue provar esses estados, ela não está concluída.
+
+---
+
+## Evidence Pack Required
+
+Toda execução operacional deve sair com um pacote mínimo de evidências:
+
+- resultado inicial de `check-email`
+- existência ou ausência do usuário no auth
+- existência ou ausência do e-mail em `buyers`
+- writes executados
+- resultado final de `check-email`
+- resultado final de `login`, se aplicável
+
+Formato esperado do resumo:
+
+- `initial_check`
+- `auth_state`
+- `buyer_state`
+- `writes`
+- `final_check`
+- `final_login`
+
+---
+
+## Playbook 1: Criar Novo Acesso Pro
+
+### Use When
+
+- o e-mail ainda não tem conta
+- o e-mail precisa ganhar acesso Pro
+- há senha inicial definida para onboarding/manual setup
+
+### Inputs
+
+- `email`
+- `password`
+- origem da liberação, ex.: `manual`
+- motivo operacional
+
+### Steps
+
+1. checar `POST /api/v1/auth/check-email`
+2. se `hasAccount: false`, criar conta com `signup`
+3. localizar usuário no `auth admin`
+4. confirmar e-mail por admin se a operação exigir acesso imediato
+5. verificar se existe registro em `public.buyers`
+6. se não existir, inserir buyer ativo
+7. revalidar `check-email`
+8. validar `login`
+
+### Writes Allowed
+
+- criar `auth user`
+- inserir linha em `buyers`
+- update admin de confirmação de e-mail
+
+### Writes Not Allowed
+
+- criar activation
+- inventar linha em `licenses`
+- alterar outras tabelas fora do fluxo
+
+### Success Criteria
+
+- `isBuyer: true`
+- `hasAccount: true`
+- `login` retorna `200`
+- `emailVerified: true`
+
+### Minimal Data Write
+
+- `auth user`
+- `public.buyers`
+
+---
+
+## Playbook 2: Liberar Pro Para Conta Já Existente
+
+### Use When
+
+- o usuário já tem conta
+- o problema é só falta de entitlement
+
+### Steps
+
+1. checar `POST /api/v1/auth/check-email`
+2. confirmar que `hasAccount: true`
+3. verificar `public.buyers` por e-mail
+4. se ausente, inserir buyer ativo
+5. revalidar `check-email`
+6. validar `login` se a senha for conhecida
+
+### Writes Allowed
+
+- inserir ou corrigir `buyers`
+- update admin de confirmação de e-mail, se necessário para destravar login
+
+### Success Criteria
+
+- `isBuyer: true`
+- conta existente preservada
+- nenhum write extra além de `buyers`, salvo necessidade explícita
+
+---
+
+## Playbook 3: Reenviar Verificação de E-mail
+
+### Use When
+
+- a conta existe
+- o login falha por e-mail não confirmado
+- não é desejável confirmar por admin imediatamente
+
+### Steps
+
+1. confirmar que a conta existe
+2. chamar `POST /api/v1/auth/resend-verification`
+3. registrar que o usuário precisa abrir o link recebido
+4. se a operação exigir liberação imediata, usar o Playbook 4
+
+### Output Contract
+
+- informar explicitamente se ainda há dependência de ação do usuário
+- não reportar “acesso resolvido” se ainda depende do inbox
+
+### Success Criteria
+
+- endpoint responde com sucesso
+- comunicação deixa claro que a ação do usuário ainda é necessária
+
+---
+
+## Playbook 4: Confirmar E-mail Por Admin
+
+### Use When
+
+- existe conta
+- e-mail não confirmado
+- é necessário desbloquear acesso imediatamente sem esperar inbox
+
+### Steps
+
+1. localizar o usuário no `auth admin`
+2. aplicar update admin com `email_confirm: true`
+3. revalidar login
+
+### Why This Exists
+
+- evita bloquear acesso imediato por dependência do inbox
+- é o caminho de suporte quando a operação não pode esperar e-mail do usuário
+
+### Success Criteria
+
+- `email_confirmed_at` preenchido
+- `login` retorna `200`
+
+### Caution
+
+- usar somente quando o processo permitir override administrativo
+
+---
+
+## Playbook 5: Reset de Senha
+
+### Use When
+
+- o usuário esqueceu a senha
+- não é necessário impor uma senha manual por admin
+
+### Steps
+
+1. confirmar se a conta existe
+2. chamar `POST /api/v1/auth/request-reset`
+3. orientar uso de `https://aiox-license-server.vercel.app/reset-password`
+4. não mudar entitlement durante reset
+
+### Important Distinction
+
+- reset de senha não corrige buyer
+- reset de senha não corrige e-mail não confirmado
+- reset de senha é só para credenciais
+
+### Success Criteria
+
+- request-reset responde com sucesso
+- usuário consegue seguir o fluxo de recuperação
+
+---
+
+## Playbook 6: Definir Nova Senha Manualmente
+
+### Use When
+
+- suporte precisa definir uma senha inicial ou temporária
+- a operação é administrativa e explícita
+
+### Steps
+
+1. localizar usuário no `auth admin`
+2. atualizar a senha por admin
+3. validar `login` com a nova senha
+
+### When Preferred Over Request Reset
+
+- onboarding assistido
+- suporte executivo/manual
+- ambiente onde a senha inicial precisa ser entregue explicitamente
+
+### Success Criteria
+
+- login com a nova senha funciona
+- nenhuma outra tabela é alterada sem necessidade
+
+---
+
+## Playbook 7: Diagnosticar Falha de Acesso
+
+### Use When
+
+- o usuário diz “não consigo entrar”
+- o acesso Pro não ativa
+- não está claro se o problema é auth, buyer ou licença
+
+### Diagnostic Order
+
+1. `check-email`
+2. `auth admin users` por e-mail
+3. `buyers` por e-mail
+4. `login`
+5. `licenses` por `customer_email`
+6. `buyer_validations` por `email` ou `user_id`
+
+### Better Triage Order In Practice
+
+Use esta priorização:
+
+1. `check-email`
+2. `login`
+3. `auth admin`
+4. `buyers`
+5. `buyer_validations`
+6. `licenses`
+7. `activations`
+
+Motivo:
+
+- `check-email + login` já classificam a maioria dos casos sem write
+
+### Interpretation
+
+- `isBuyer: false` e `hasAccount: false`
+  - falta conta e falta entitlement
+- `isBuyer: false` e `hasAccount: true`
+  - conta existe, falta buyer
+- `isBuyer: true` e login falha por `EMAIL_NOT_VERIFIED`
+  - buyer ok, falta confirmação de e-mail
+- `isBuyer: true` e login falha por credenciais
+  - entitlement ok, problema é senha
+
+- `isBuyer: true`, login ok, ativação falha
+  - sair do escopo de access ops e abrir investigação de licença/activation
+
+---
+
+## Minimal Command/Action Contract For Tasks
+
+Uma task boa para o squad-creator não deve pedir “investigar como fazer”.
+
+Ela deve declarar explicitamente:
+
+1. quais leituras fará primeiro
+2. qual write mínimo fará em cada ramo da árvore de decisão
+3. qual validação final provará o sucesso
+4. quais writes estão proibidos naquele caso
+
+Exemplo de contrato ruim:
+
+- “verificar Supabase e resolver acesso”
+
+Exemplo de contrato bom:
+
+- “rodar check-email; se hasAccount=false criar auth user; se buyer ausente inserir em buyers; confirmar e-mail por admin apenas se acesso imediato for necessário; validar check-email e login”
+
+---
+
+## Expected Task Outputs
+
+Toda task gerada a partir deste handoff deve devolver:
+
+- ação executada
+- e-mail alvo
+- writes realizados
+- estado final de `check-email`
+- estado final de `login`, se aplicável
+- pendências restantes, se houver
+
+Também deve devolver:
+
+- classificação do caso na árvore de decisão
+- motivo para cada write executado
+- confirmação explícita de que nenhuma activation/seat foi consumida, salvo pedido explícito
+
+---
+
+## Squad-Creator Task Briefs
+
+### Brief A: Criar Novo Acesso AIOX-Pro
+
+```md
+Criar task operacional para criar um novo acesso AIOX-Pro no backend de licensing já conhecido.
+
+Contexto fixo:
+- serviço: https://aiox-license-server.vercel.app
+- projeto Supabase: evvvnarpwcdybxdvcwjh
+- oracle de buyer: public.buyers
+
+A task deve:
+- rodar check-email e classificar o caso
+- receber email e senha inicial
+- criar conta se não existir
+- confirmar email por admin quando necessário para liberação imediata
+- inserir buyer ativo se ausente
+- validar via check-email e login
+- listar writes permitidos e proibidos
+
+Done:
+- isBuyer=true
+- hasAccount=true
+- login 200
+```
+
+### Brief B: Liberar Pro Para Conta Existente
+
+```md
+Criar task operacional para liberar entitlement Pro para uma conta já existente no AIOX-Pro.
+
+Contexto fixo:
+- serviço: https://aiox-license-server.vercel.app
+- projeto Supabase: evvvnarpwcdybxdvcwjh
+- tabela de entitlement: public.buyers
+
+A task deve:
+- confirmar existência da conta
+- inserir buyer ativo apenas se ausente
+- confirmar e-mail por admin apenas se login falhar por não verificado
+- revalidar check-email
+- validar login se houver senha fornecida
+
+Done:
+- isBuyer=true
+- conta preservada
+```
+
+### Brief C: Reenviar Verificação
+
+```md
+Criar task operacional para reenviar verificação de email do AIOX-Pro.
+
+Contexto fixo:
+- serviço: https://aiox-license-server.vercel.app
+- projeto Supabase: evvvnarpwcdybxdvcwjh
+
+A task deve:
+- confirmar que a conta existe
+- chamar resend-verification
+- reportar claramente se ainda depende de ação do usuário
+- proibir conclusão “resolvido” sem prova de login, salvo se o objetivo explícito for apenas reenvio
+```
+
+### Brief D: Confirmar E-mail Por Admin
+
+```md
+Criar task operacional para confirmar por admin o email de uma conta do AIOX-Pro.
+
+Contexto fixo:
+- auth backend: Supabase Auth do projeto evvvnarpwcdybxdvcwjh
+
+A task deve:
+- localizar user por email
+- aplicar email_confirm=true
+- validar login após a confirmação
+- explicitar que não deve tocar buyers/licenças se o problema for apenas verificação
+```
+
+### Brief E: Reset de Senha
+
+```md
+Criar task operacional para reset de senha do AIOX-Pro.
+
+Contexto fixo:
+- serviço: https://aiox-license-server.vercel.app
+- página de recovery: https://aiox-license-server.vercel.app/reset-password
+
+A task deve:
+- confirmar existência da conta
+- chamar request-reset
+- reportar o próximo passo para o usuário
+- explicitar que reset não resolve buyer nem verificação de e-mail
+```
+
+### Brief F: Diagnóstico de Falha de Acesso
+
+```md
+Criar task operacional para diagnosticar por que um usuário não consegue acessar o AIOX-Pro.
+
+Contexto fixo:
+- serviço: https://aiox-license-server.vercel.app
+- projeto Supabase: evvvnarpwcdybxdvcwjh
+- tabelas relevantes: buyers, buyer_validations, licenses, activations
+
+A task deve:
+- rodar check-email
+- testar login cedo para classificar o erro
+- verificar auth user
+- verificar buyers
+- classificar a falha em: falta conta, falta buyer, email não confirmado, senha inválida ou problema de licença
+- listar o próximo playbook exato a executar
+```
+
+---
+
+## Definition Of Done
+
+- task parte do contexto fixo correto
+- task não perde tempo redescobrindo projeto/licensing
+- task executa apenas o playbook relevante
+- task valida no serviço real
+- resultado final fica objetivo e auditável
+
+---
+
+_Last Updated: 2026-04-19 | AIOX Ops_