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.