orquestrador/docs/adr/0001-separate-admin-and-customer-identity.md

ADR 0001 - Separar usuario de atendimento de conta administrativa interna

Status

Accepted

Contexto

Hoje o sistema possui um conceito principal de usuario em app/db/mock_models.py (User). Esse registro representa a identidade operacional do atendimento e nasce a partir de canais externos, como Telegram. Ele serve para vincular conversas, pedidos, locacoes, revisoes e contexto transacional do usuario final.

Para a frente de auto-incremento de tools, precisaremos de uma area interna com login, permissao, auditoria e publicacao controlada. Misturar essa conta interna com o User atual criaria problemas de seguranca, modelagem e isolamento de dominio.

Decisao

Vamos separar explicitamente dois dominios de identidade:

1. AtendimentoUser

   • Continua sendo o User atual do banco operacional/mock.
   • Representa clientes e pessoas atendidas por canais externos.
   • Continua vinculado a conversa, pedido, revisao, locacao e historico operacional.

2. StaffAccount

   • Sera uma nova entidade para acesso administrativo interno.
   • Representa funcionarios e administradores da empresa.
   • Sera usada para login no painel interno, configuracao do sistema, criacao/aprovacao de tools e auditoria.

Fronteira entre os dois tipos de conta

AtendimentoUser

• Banco: operacional/mock (MockBase)
• Origem: canal externo (channel, external_id)
• Autenticacao: indireta, via canal de atendimento
• Responsabilidade: atendimento ao cliente e contexto de negocio
• Nao deve receber credenciais de painel interno

StaffAccount

• Banco: administrativo/tools (Base)
• Origem: cadastro interno controlado
• Autenticacao: login web proprio
• Responsabilidade: administracao, configuracao e governanca de tools
• Nao deve ser usado para identificar cliente do atendimento

Racional para usar o banco administrativo/tools para StaffAccount

O projeto ja possui um banco administrativo ligado a Base, hoje usado para tools. Como a nova frente trata de governanca do sistema e nao de jornada do cliente final, o lugar mais coerente para StaffAccount e para os metadados de geracao/publicacao e esse mesmo dominio administrativo.

Isso reduz acoplamento com o banco operacional e evita misturar seguranca interna com dados de atendimento.

Entidades alvo derivadas desta decisao

As proximas fases devem introduzir, no banco administrativo, entidades como:

• StaffAccount
• StaffSession ou estrategia equivalente de token
• ToolDraft
• ToolGenerationJob
• ToolValidationRun
• ToolPublication
• AuditLog

O banco operacional continua com entidades como:

• User
• Order
• ReviewSchedule
• RentalContract
• ConversationTurn

Regras arquiteturais obrigatorias

1. Nenhuma rota administrativa deve reutilizar User do atendimento como identidade autenticada.
2. Nenhuma regra de atendimento deve depender de StaffAccount para funcionar.
3. O pipeline de geracao/publicacao de tools deve operar fora do caminho critico do atendimento.
4. Toda ativacao de tool gerada deve ser auditavel e vinculada a um StaffAccount.
5. O atendimento continua decidindo execucao com base no modelo; o painel administrativo apenas governa cadastro, validacao e publicacao.

Papel inicial de permissao

A primeira versao deve prever ao menos estes papeis:

• diretor: gerencia contas internas, aprova e publica tools, altera configuracoes sensiveis e cadastra novos colaboradores
• colaborador: consulta o fluxo operacional do bot, cria drafts de tools e acompanha o andamento ate a aprovacao

Estrutura tecnica sugerida

Banco administrativo (Base)

• app/db/models/staff_account.py
• app/db/models/tool_draft.py
• app/db/models/tool_generation_job.py
• app/db/models/audit_log.py

Repositorios

• app/repositories/staff_account_repository.py
• app/repositories/tool_draft_repository.py
• app/repositories/tool_generation_job_repository.py

Servicos

• app/services/admin/auth_service.py
• app/services/admin/tool_draft_service.py
• app/services/admin/tool_generation_service.py
• app/services/admin/audit_service.py

API interna

• app/api/routes/admin_auth.py
• app/api/routes/admin_tools.py
• app/api/routes/admin_audit.py

Fluxo alvo de alto nivel

1. StaffAccount faz login no painel interno.
2. Um colaborador cria um ToolDraft com nome, descricao e parametros.
3. Um job isolado gera a implementacao e executa validacoes.
4. O resultado fica disponivel para revisao humana.
5. Um diretor revisa, aprova e publica a tool.
6. A tool publicada passa a integrar o registry ativo sem afetar o dominio de identidade do atendimento.

Impacto nas proximas etapas

A partir desta decisao, as proximas implementacoes devem seguir esta ordem:

1. Criar StaffAccount e autenticacao administrativa.
2. Criar autorizacao por papel.
3. Criar entidades de draft/versionamento/validacao.
4. Criar pipeline isolado de geracao.
5. Criar painel e rotas administrativas.

Consequencias

Positivas

• Isola seguranca interna do atendimento ao cliente.
• Facilita auditoria e governanca.
• Evita acoplamento indevido entre canal externo e painel interno.
• Deixa clara a separacao entre operacao e administracao do sistema.

Custos

• Introduz novo conjunto de entidades e rotas.
• Exige autenticacao e autorizacao dedicadas.
• Aumenta a complexidade de bootstrap e persistencia do dominio administrativo.

Fora do escopo desta ADR

• Escolha definitiva do modelo para geracao de codigo.
• Implementacao do frontend administrativo.
• Definicao detalhada do sandbox de execucao das tools geradas.