FastInBox | Dados e persistencia
Esquema de Banco de Dados
Versao: 1.0 estrutural | Objetivo: baseline relacional para migracao da persistencia local
Documento tecnico de modelagem com entidades, cardinalidade, integridade e diretrizes de indexacao para suportar o fluxo de pedidos white label da plataforma.
1. Premissas de modelagem
- Modelo relacional com foco em consistencia transacional.
- Eventos operacionais registrados para rastreabilidade.
- Separacao entre identidade, pedido, pagamento e producao.
- Preparado para consultas por perfil e timeline de status.
2. Entidades principais
| Tabela | Objetivo | Chave primaria |
|---|---|---|
| users | Identidade e autorizacao | user_id (UUID) |
| clinics | Dados de marca e operacao da clinica | clinic_id (UUID) |
| patients | Cadastro de paciente | patient_id (UUID) |
| orders | Cabecalho transacional do pedido | order_id (UUID) |
| order_items | Itens individuais do pedido | order_item_id (UUID) |
| payments | Eventos de pagamento e conciliacao | payment_id (UUID) |
| production_events | Historico de status operacional | production_event_id (UUID) |
3. Relacionamentos
- clinics 1:N users (nutricionistas da clinica)
- users (nutricionista) 1:N patients
- patients 1:N orders
- orders 1:N order_items
- orders 1:N payments (suporte a reprocessamento futuro)
- orders 1:N production_events
A relacao orders -> production_events garante trilha temporal completa do ciclo operacional.
4. Regras de integridade
| Regra | Implementacao sugerida | Motivo |
|---|---|---|
| Codigo de pedido unico | UNIQUE (order_code) | Evitar colisao no acesso do paciente |
| Pagamento valido para producao | Constraint de transicao de status | Bloquear operacao sem autorizacao |
| Status coerente | Enum + validacao de transicao | Evitar salto de etapa invalido |
| Exclusao protegida | Soft delete ou restricao referencial | Preservar historico de auditoria |
5. Indexacao recomendada
- users(email), patients(email), orders(order_code) para busca direta.
- orders(status, delivery_date) para fila operacional.
- production_events(order_id, created_at) para timeline.
- payments(order_id, payment_status) para conciliacao.
A estrategia de indice prioriza consultas de tela e governanca, mantendo equilibrio entre leitura rapida e custo de escrita.
6. Politica de evolucao de schema
- Versionar migracoes com rollback explicito.
- Evitar mudancas destrutivas sem janela de compatibilidade.
- Formalizar dicionario de dados com semantica de campos.
- Adicionar trilhas de auditoria em tabelas sensiveis.
Essa abordagem reduz risco de quebra em sprint e facilita reproducao de ambiente em avaliacao tecnica.
7. Dicionario de campos criticos
| Tabela.Campo | Tipo sugerido | Regra | Observacao |
|---|---|---|---|
| users.role | ENUM | NOT NULL | Restringe acesso por perfil. |
| patients.restrictions | TEXT | NULL permitido | Restrições alimentares para montagem de item. |
| orders.order_code | VARCHAR | UNIQUE NOT NULL | Referencia usada na jornada do paciente. |
| orders.status | ENUM | NOT NULL | Transicao controlada por regra de negocio. |
| payments.payment_status | ENUM | NOT NULL | Somente aprovado libera fluxo de producao. |
| production_events.created_at | TIMESTAMP | NOT NULL | Base para timeline e auditoria. |
8. Backup, restauracao e auditoria
- Backup periodico com retencao por janela minima definida em politica interna.
- Teste de restauracao em ambiente isolado para validar recuperacao.
- Auditoria de alteracoes em status de pedido e eventos financeiros.
- Registro de autoria de mudancas criticas para rastreio de incidente.
- Controle de acesso administrativo com principio do menor privilegio.
Em evolucao para producao comercial, recomenda-se acoplar trilha de auditoria com politica de retencao e plano de resposta a incidentes.
9. Consultas criticas orientadas ao negocio
| Consulta | Tabelas envolvidas | Finalidade |
|---|---|---|
| Buscar pedido por codigo | orders, patients, order_items | Carregar a jornada do paciente sem ambiguidade |
| Listar fila de producao | orders, payments, production_events | Exibir apenas pedidos pagos e seu estado atual |
| Conciliar pagamento e pedido | orders, payments | Garantir que somente transacao aprovada libera producao |
| Acompanhar lead time operacional | orders, production_events | Medir tempo entre pagamento, preparo e entrega |
| Auditar acao sensivel | users, orders, production_events, payments | Reconstruir autoria e historico de mudanca |
10. Normalizacao e extensoes futuras
- Separar catalogo de ingredientes e embalagens em tabelas proprias quando houver reuso sistematico entre pedidos.
- Introduzir tabela de commissions para fechar trilha financeira sem depender apenas de campos calculados em orders.
- Criar tabela de delivery_windows para consolidar regras de expedicao por regiao, cozinha e frequencia.
- Expandir payments para suportar multiplas tentativas e conciliacao assicrona com gateway.
11. Prioridades de migracao da persistencia atual
| Prioridade | Escopo de migracao | Razao |
|---|---|---|
| 1 | users, patients e orders | Base do fluxo principal e das permissoes |
| 2 | order_items e payments | Fecham a integridade comercial e financeira |
| 3 | production_events | Habilitam auditoria e timeline persistente |
| 4 | clinics, factories e configuracoes | Escala de governanca multi-parceiro |