🏥 Alpha Clinic

Sistema de Gestão de Clínicas SaaS Multi-Tenant

⚡ Início Rápido • 🏗️ Arquitetura • 📦 Módulos • 🧪 Testes • 📚 Documentação

ℹ️ Sobre este arquivo: o README raiz repete e reforça trechos críticos de /docs de forma deliberada para servir como landing page operacional. Considere-o uma cola rápida – mantenha este espelho sincronizado com as fontes oficiais indicadas nos links.

👋 Visão Geral e Propósito

O Alpha Clinic é um sistema de gestão SaaS (Software as a Service) multi-tenant projetado para escalar horizontalmente desenvolvido com Laravel + VueJS. A arquitetura resolve problemas comuns de isolamento de dados e manutenção de código em aplicações de grande porte.

O propósito central do projeto é servir como uma Implementação de Referência para arquiteturas Laravel modernas, demonstrando como desacoplar regras de negócio (Backend Service Layer) da interface de usuário (Frontend Modular Monolith). O sistema suporta múltiplas clínicas (Tenants) em uma única base de dados, utilizando isolamento lógico rigoroso em três níveis. As clínicas podem gerenciar filiais.

🤖 Instruções para Agentes de IA e Humanos

⚠️ LEITURA OBRIGATÓRIA: Antes de começar, leia o Kernel do Agente (ai-agent-ide-context-sync). Ele explica nossa filosofia "Docs First", o uso de Personas e os scripts de automação.

Sempre que ler este README.md da raiz, consulte as identidades em .ai-workspace/personas/README.md e o estado em .ai-workspace/memory/project-state.json.

🎯 Diferenciais Técnicos

Abaixo listamos as decisões arquiteturais que diferenciam este projeto de um CRUD padrão.

Backend & Core

Single Database Multi-Tenancy: Isolamento de dados via Global Scopes e TenantContext middleware, eliminando a sobrecarga de gerenciar múltiplos bancos de dados.
Service-Oriented Architecture (SOA): Controllers magros que delegam lógica para Services, facilitando testes unitários e reutilização (ex: API vs Web).
Strict Typing & DTOs: Uso intensivo de PHP 8.2 features, Data Transfer Objects e Enums para garantir integridade de dados entre camadas.
Orion API: Implementação de APIs RESTful completas com filtragem avançada, sorting e includes via tailflow/laravel-orion, reduzindo boilerplate.
Transactional Emails: Integração com MailerSend para alta entregabilidade de notificações transacionais.
Cloud Storage Ready: Configurado com Flysystem S3 para escalabilidade de armazenamento de arquivos (prontuários, exames).

Frontend & UX

Modular Monolith Frontend: Vue.js organizado por domínios (DDD), onde cada módulo possui suas próprias camadas de UI, Dados e Estado.
Offline-First Readiness: Protocolo de "Sync Endpoints" desenhado para suportar futura sincronização com aplicativos móveis em ambientes instáveis.
State Management Normalizado: Padrão "Catalog" com Pinia, evitando duplicação de entidades na memória e inconsistências de UI.
Type-Safe Forms: Validação robusta com Zod e Vee-Validate integrada aos tipos TypeScript gerados do backend.
Componentes Enterprise: Wrappers customizados (Global Components) sobre Ant Design Vue para padronização visual e comportamental.

DevOps & Qualidade

AI-Driven Development: Integração nativa com LLMs para análise de logs e auto-correção (Laravel Boost/MCP).
Test Pyramid Strategy: Cobertura abrangente com Unitários (PHPUnit/Vitest), Integração e E2E (Playwright).
Dockerized Environment: Ambiente de desenvolvimento padronizado via Laravel Sail/Docker.

🛰️ Insights Contextuais do Kernel

npm run ai:insights:add-event -- --source ci --type tests --severity high --message "Playwright falhou"
Registra eventos normalizados em .ai-workspace/analysis/insights/events/<data>-<fonte>.json.
npm run ai:insights:watch
Consolida todos os eventos e atualiza .ai-workspace/analysis/insights/insights.json com totais, alertas e recomendações.

Integração sugerida em CI (GitHub Actions):

- name: Registrar evento CI
  run: npm run ai:insights:add-event -- \
    --source ci --type tests --severity ${{ needs.tests.result == 'success' && 'info' || 'high' }} \
    --message "Vitest ${{ needs.tests.result }}"
- name: Atualizar insights
  run: npm run ai:insights:watch

(Substitua needs.tests.result conforme o job do pipeline e publique insights.json como artifact ou comentário automático.)

🔗 Veja também:

Tech Stack: Lista detalhada de todas as tecnologias.

DevOps: Infraestrutura e Deploy.

🛠️ Stack Tecnológica

Ferramentas selecionadas para garantir performance, tipagem estática e manutenibilidade.

Categoria	Tecnologia	Versão	Propósito
Backend	Laravel	`12.0`	Framework core.
	PHP	`8.2`	Linguagem base com strict typing.
	Laravel Sanctum	`4.2`	Autenticação SPA e API Tokens.
	Laravel Orion	`2.23`	APIs RESTful rápidas e padronizadas.
	MailerSend	`2.12`	Gateway transacional de e-mails.
	Flysystem S3	`3.0`	Abstração de armazenamento em nuvem.
Frontend	Vue.js	`3.5`	Framework reativo (Composition API).
	TypeScript	`5.6`	Superset tipado para JavaScript (Strict).
	Inertia.js	`2.0`	Monolito moderno (SPA sem complexidade de API).
	Tailwind CSS	`4.0`	Estilização utility-first (nova engine).
	Ant Design Vue	`4.2`	Biblioteca de componentes UI Enterprise.
	Pinia	`3.0`	Gerenciamento de estado global.
	TanStack Query	`5.0`	Gerenciamento de estado de servidor (caching).
	Vee-Validate + Zod	`4.15`	Validação de formulários e schemas.
	ApexCharts	`3.0`	Dashboards e visualização de dados.
	FullCalendar	`6.1`	Gestão complexa de agendas e eventos.
	Day.js	`1.11`	Manipulação leve de datas e timezones.
Dados	PostgreSQL	`14+`	Banco de dados relacional.
	Redis	`7.0`	Cache e Filas (recomendado para prod).
QA	Playwright	`1.57`	Testes End-to-End (E2E).
	Vitest	`4.0`	Testes Unitários de Componentes Frontend.
	PHPUnit	`11.5`	Testes Unitários e de Feature Backend.

🛡️ Implementações de Segurança

O sistema implementa múltiplas camadas de proteção seguindo as melhores práticas da OWASP Top 10 e padrões de segurança para aplicações SaaS multi-tenant.

📖 Documentação Completa: Security Implementations Guide

Proteções Implementadas

🔒 Proteção contra XSS (Cross-Site Scripting)

Editor TipTap: Migração do Quill (vulnerável) para TipTap com sanitização nativa
DOMPurify: Sanitização de todo conteúdo HTML dinâmico via helpers e composables
Componentes Protegidos: ChangelogModal, SessionHeader, PageHeader, UserMainLine
Arquivos: resources/js/utils/sanitize.ts, resources/js/composables/useSanitize.ts

🚦 Rate Limiting (Proteção contra Força Bruta)

Limitadores de taxa configurados por endpoint:

Login: 5 req/min por IP
Registro: 10 req/hora por IP
Password Reset: 5 req/min por IP
Uploads: 20 req/min por usuário
API Geral: 120 req/min

Configuração: app/Providers/AppServiceProvider.php

🔐 Segurança de Sessão

Criptografia: SESSION_ENCRYPT=true (dados criptografados no Redis/File)
Cookies Seguros: SESSION_SECURE_COOKIE=true (produção, apenas HTTPS)
SameSite Policy: SESSION_SAME_SITE=lax (proteção CSRF)
HTTP Only: Cookies inacessíveis via JavaScript

🔒 Security Headers HTTP

Middleware customizado (app/Http/Middleware/SecurityHeaders.php) que adiciona:

X-Frame-Options: Proteção contra Clickjacking
X-Content-Type-Options: Previne MIME sniffing
Content-Security-Policy: Controle rigoroso de recursos permitidos
Strict-Transport-Security: Força HTTPS (produção)
Permissions-Policy: Bloqueia acesso a câmera, microfone, geolocalização

🌐 CORS Restritivo

Configuração em config/cors.php permite apenas origens autorizadas:

APP_URL (produção)
localhost:5173 (Vite dev)
supports_credentials: true (autenticação via cookies)

📤 Validação de Upload de Arquivos

Validação rigorosa em app/Http/Requests/UploadRequest.php:

Verificação de extensão (mimes)
Verificação de MIME type real (mimetypes)
Limite de tamanho (5MB)
Armazenamento isolado por tenant

🏢 Multi-tenancy Seguro

Trait TenantOwned: Isolamento automático de dados por business_id
Middleware TenantRequestContext: Validação de contexto em cada requisição
Global Scopes: Aplicados automaticamente em todos os modelos

🔍 Auditoria de Dependências

Monitoramento contínuo de vulnerabilidades:

npm audit    # 0 vulnerabilities
composer audit  # No security advisories

Score de Segurança: ✅ 100/100

Vulnerabilidades Resolvidas:

✅ XSS via Quill Editor (CVE GHSA-4943-9vgg-gr5r)
✅ XSS via v-html sem sanitização
✅ Força bruta em endpoints de autenticação
✅ Vazamento de sessão via cookies inseguros
✅ CORS permissivo
✅ Upload de arquivos maliciosos

Próximos Passos Recomendados (Produção):

2FA (Two-Factor Authentication) para administradores
Monitoramento com Sentry/Bugsnag
CSP com Nonces (remover unsafe-inline)
Auditoria de acesso a dados sensíveis (LGPD/HIPAA)

🏗️ Arquitetura e Padrões

🔄 Ciclo de Vida da Requisição (End-to-End)

O fluxo de dados é bidirecional e estritamente tipado, garantindo integridade desde o clique do usuário até a persistência no banco.

Frontend (Origem)

Interaction: Usuário interage com o Componente Vue (ex: <AppointmentForm>).
Validation (Client-Side): Zod valida o schema do formulário em tempo real (UX imediata).
Store/Action: O componente dispara uma ação na Pinia Store ou TanStack Query Mutation.
HTTP Client: Axios intercepta a requisição, anexa o Token Bearer e o X-Localization.

Backend (Processamento)

Middleware (TenantContext): Intercepta a requisição, identifica o business_id (via Header ou Sessão) e injeta no contexto global.
FormRequest: Valida os dados de entrada novamente (Segurança/Regra de Negócio).
Controller: Apenas orquestra. Recebe dados validados e chama o Serviço.
Service Layer: Contém a regra de negócio real (ex: "Não pode agendar se médico estiver de férias").
Repository/Model: Acesso ao banco protegido por Global Scopes de Tenant (TenantOwned).
API Resource: Transforma o Model em JSON, removendo campos sensíveis.

Frontend (Retorno)

Reactivity: A resposta atualiza o Cache do TanStack Query, refletindo instantaneamente na UI sem reload.

🎨 Estrutura de Módulos (Frontend)

O frontend Vue.js organiza-se por Domínio (DDD) e utiliza Factories para padronização. A arquitetura vai muito além de componentes visuais.

graph TD
    M[Module: Appointments] --> Data[Data Layer]
    M --> Domain[Domain Layer]
    M --> UI[UI Layer]
    M --> Catalog[Catalog Layer]
    
    Data --> Factory[entityApiFactory.ts]
    Factory --> API[api.ts: Axios + Interceptors]
    Data --> Keys[keys.ts: Query Keys]
    
    Domain --> Models[model.ts: Interfaces]
    Domain --> Validation[validation.ts: Zod Schemas]
    
    Catalog --> Store[store.ts: Pinia]
    Catalog --> Selectors[selectors.ts: Computed Logic]
    
    UI --> Components[Vue Components]

Camadas Internas do Módulo

Data Layer (data/):
- API: Gerado via createEntityApi, lida com CRUD e normalização de dados.
- Queries: Hooks do TanStack Query (useList, useById) gerados via entityQueriesFactory.
- Lookups: Dicionários estáticos ou dinâmicos para preenchimento de selects.
Domain Layer (domain/):
- Models: Interfaces TypeScript puras que espelham o backend.
- Validation: Schemas Zod para validação de formulários.
Catalog Layer (catalog/):
- Store: Estado global normalizado (Pinia) para evitar prop drilling.
- Selectors: Lógica de seleção e filtros reusáveis sobre o estado.
UI Layer (ui/):
- Components: Componentes "burros" que recebem dados via props ou consomem Hooks.

Camadas Globais (Core)

Service HTTP (services/http.ts):
- Interceptors: Gerenciamento automático de ETag (Cache) e Tokens.
- Retry Logic: Re-tentativa automática em falhas de rede (429, 503).
Factories (common/):
- createEntityApi: Reduz boilerplate gerando métodos padrão de API e Queries.
- FilterProviderRegistry: Sistema dinâmico de filtros globais.

🔗 Veja também:

Arquitetura de Projeto: Visão completa dos padrões.

Catalog Pattern: Detalhes do gerenciamento de estado.

🎨 Design System da Documentação

Nossa documentação segue uma Filosofia de "Docs as Code", onde a documentação é tratada com o mesmo rigor e versionamento do código-fonte. O objetivo é reduzir a Carga Cognitiva de quem lê (seja um desenvolvedor júnior, sênior ou um Agente de IA), padronizando a estrutura visual e informacional.

🧠 Filosofia & Estratégia

Single Source of Truth: Se não está na doc, não existe "oficialmente".
Consistência Visual: Todo arquivo do mesmo tipo deve ter a mesma "cara", facilitando o scan visual.
Navegabilidade: Links cruzados ("Veja também") e Breadcrumbs são obrigatórios para evitar becos sem saída.
IA-Friendly: Estruturas claras ajudam Agentes de IA a entenderem o contexto e recuperarem informações com precisão.
Padronização de Títulos: Títulos devem ser claros e descritivos. Utilize âncoras (links com #) para referenciar seções específicas dentro dos documentos, facilitando a navegação direta.

📄 Detalhamento dos Templates

Abaixo, detalhamos cada template disponível, sua filosofia de uso e a explicação de seus blocos internos.

1. Folder README (`tmp--global--doc-folder-readme.md`)

Propósito: Atuar como o "Index" ou "Capa" de cada diretório. Nenhum diretório deve existir sem um README explicativo.
Visão: Quem entra na pasta deve entender em 5 segundos: O que tem aqui? Quem cuida disso? O que é importante?
Estrutura Interna:
- 🎯 Visão Geral: O "Pitch" do diretório. Resumo executivo.
- 📑 Conteúdo: Lista curada dos arquivos mais importantes (não liste tudo, apenas o vital).
- 🤝 Convenções Locais: Regras que só valem ali (ex: "Aqui usamos Snake Case").

2. Entidade de Dados (`tmp--global--doc-entity.md`)

Propósito: Documentar um "Objeto de Negócio" (Model) de ponta a ponta (Banco -> Backend -> Frontend).
Visão: Eliminar a necessidade de abrir o banco de dados para entender uma tabela.
Estrutura Interna:
- 📋 Metadados: Tabela, Model, se é Multi-tenant, se tem Soft Delete.
- 🏗 Estrutura de Dados: Diagrama ERD (Mermaid) e Dicionário de Dados (Tabela de colunas).
- 🔒 Regras & Policies: Quem pode criar, editar, ver? (Authorization).
- 💻 Implementação: Rotas da API, Observers, e onde estão os arquivos Vue relacionados.

3. Padrão Técnico (`tmp--global--doc-tech-pattern.md`)

Propósito: Registrar decisões de arquitetura e padrões de código (ADRs - Architecture Decision Records).
Visão: Evitar "re-inventar a roda" e debates circulares. Se decidimos um padrão, ele vira lei.
Estrutura Interna:
- 🎯 Contexto & Problema: A "dor" que originou o padrão. Por que mudamos?
- 💡 Solução Proposta: O "remédio". Diagramas conceituais e explicação teórica.
- 🛠 Implementação: Como fazer na prática (Snippets de código, estrutura de pastas).
- ⚠️ Anti-Patterns: O que NÃO fazer. Vacinas contra erros comuns.

4. Tarefa / Feature (`___tasks/template.md`)

Propósito: Especificação técnica de uma demanda antes de escrever código (Tech Spec).
Visão: "Pensar antes de codar". Reduzir retrabalho alinhando expectativas técnicas e de negócio.
Estrutura Interna:
- 🎯 Objetivos (DoD): Definition of Done. Lista de checkboxes clara do que é "Pronto".
- 🛠 Plano de Implementação: Checklist técnico dividido em Backend, Frontend e Validação.
- ❓ Dúvidas & Riscos: Mapeamento prévio de bloqueios (ex: dependência de API externa).

5. Análise / RFC (`tmp--global--doc-analysis-rfc.md`)

Propósito: Investigação profunda de problemas complexos ou propostas de grandes mudanças (Request for Comments).
Visão: Debugar com método científico (Hipótese -> Teste -> Conclusão).
Estrutura Interna:
- 🧐 Problema / Cenário: Descrição rica do cenário (Logs, contexto).
- 🧪 Hipóteses: Tabela de suspeitas e status de validação.
- 🔍 Processo: Diário de bordo da investigação (Logs, Queries, Tentativas).
- 💡 Conclusão: Veredito final e recomendação de correção.

6. Guia do Usuário (`tmp--global--doc-user-guide.md`)

Propósito: Ensinar o usuário final a realizar uma tarefa no sistema.
Visão: Empatia total. Linguagem simples, sem "technobabble" (jargão técnico).
Estrutura Interna:
- 👣 Passo a Passo: Instruções numeradas e sequenciais.
- 📸 Screenshots: Imagens ilustrativas (obrigatório).
- ❓ FAQ / Troubleshooting: "Se der erro, faça isso". Antecipar frustrações.

7. Bug Report (`tmp--global--doc-test-case.md`)

Propósito: Padronizar o relato de erros para facilitar a reprodução e correção.
Visão: Um bug mal relatado é um bug não corrigido. Fatos > Opiniões.
Estrutura Interna:
- 🔄 Passos para Reproduzir: Receita de bolo para causar o erro.
- 📸 Evidências: Prints, Logs do Backend, Logs do Console (obrigatório).
- 🕵️‍♂️ Análise Técnica: Espaço para o dev documentar a causa raiz (Root Cause Analysis).

8. Regra de Negócio (`tmp--global--doc-business-rule.md`)

Propósito: Isolar e documentar uma lógica de negócio complexa e reutilizável.
Visão: Regras de negócio não devem ficar escondidas em if/else no código. Devem ser explícitas.
Estrutura Interna:
- 📜 Definição Detalhada: A regra em português claro.
- 🧪 Cenários (Gherkin): "Dado que... Quando... Então...". Testes de aceitação legíveis.
- 💻 Implementação: Onde essa regra vive no código (Service/Class) e snippet.

9. Item de Tech Stack (`tmp--global--doc-tech-stack.md`)

Propósito: Justificar e explicar o uso de uma tecnologia específica no projeto.
Visão: Cada dependência é um compromisso. Precisamos saber por que "casamos" com ela.
Estrutura Interna:
- 🏆 Por que escolhemos?: Motivação técnica e de negócio.
- 🏗 Implementação: Como configuramos isso aqui? (Não copie a doc oficial, explique a nossa config).
- ⚠️ Desafios: Pegadinhas e lições aprendidas (Knowledge Base).

Tip

Acesso Rápido: Os templates ficam em node_modules/ai-agent-ide-context-sync/modules/templates/assets/. Copie o conteúdo "raw" e seja feliz!

🧩 Componentização Frontend

Adotamos uma filosofia de Wrapper Pattern rigorosa. Não utilizamos componentes de bibliotecas de terceiros (como Ant Design Vue) diretamente nas páginas de negócio.

🏛️ Filosofia

Desacoplamento: Isolamos a biblioteca de UI do código de negócio.
Padronização: Garantimos consistência visual e comportamental (ex: máscaras, validações).
Produtividade: Componentes pré-configurados para o domínio de saúde.

📦 Componentes Globais

Todos os componentes residem em resources/js/components/ e são documentados em Global Components.

Categoria	Componentes Principais	Descrição
Forms	`FieldInput`, `FieldSelect`	Inputs padronizados com validação e máscaras.
UI	`AppModal`, `GlobalButton`	Elementos visuais base e interativos.
Layout	`AppShell`, `Card`	Estrutura macro e containers de conteúdo.
Lists	`ListCard`, `Pagination`	Exibição de coleções de dados.
Visual	`ChartComponents`	Gráficos e dashboards (ApexCharts).
Calendar	`CalendarComponents`	Agendas e cronogramas (FullCalendar).

🔗 Veja também:

Guia de Componentes Globais: Documentação completa.

Estrutura de Módulos: Como usar componentes nos módulos.

📦 Funcionalidades e Módulos

O sistema é dividido em módulos funcionais isolados, cobrindo 100% das operações de uma clínica moderna e garantindo cobertura total das entidades do sistema.

🏥 Core & Administração (SaaS)

Businesses (Tenants): Gestão da Clínica, Configurações de Marca, Fuso Horário e Localização (Business).
Business Units: Gestão de Filiais/Unidades de atendimento físicas (BusinessUnit, BusinessUnitHour).
Market Verticals: Segmentação de nicho da clínica (ex: Dental, Psicologia) para personalização (MarketVertical).
Plans & Subscription: Gestão de Planos SaaS, Limites e Ciclos de Cobrança (Plan, PlanTranslation).
Modules Management: Ativação/Desativação de módulos de sistema (Feature Toggles) (Module, PlanModule).

🔐 Acesso & Segurança

Auth & Session: Login, Registro, Recuperação, Token de Acesso Pessoal e Sessão (User, PersonalAccessToken, Session).
Roles & Permissions: Controle de acesso granular (RBAC) e Matriz de Permissões (Role, Permission, RolePermission).
Memberships: Vínculo entre Usuário e Clínica com controle de status e papéis (Membership).
API Keys: Gestão de chaves de API para integrações externas e webhooks (ApiKey).

📅 Operação Clínica & Agenda

Appointments: Agendamento, Status (Confirmado, Cancelado, Atendido) e Reagendamento (Appointment).
Integrations: Sincronização com calendários externos como Google/Outlook (AppointmentIntegration, CalendarIntegration).
Patients: Prontuário Eletrônico (PEP), Dados Demográficos e Vínculos (UserPatient).
Anamnesis: Fichas de Anamnese dinâmicas com perguntas e respostas (AnamnesisQuestion, AnamnesisAnswer).
Professionals: Cadastro de Corpo Clínico e gestão de profissionais (UserProfessional).
Work Schedules: Escalas de trabalho, turnos e bloqueios de agenda (UserWorkSchedule, ScheduleOverride).
Feedback (NPS): Coleta de avaliação e feedback de pacientes pós-consulta (PatientFeedback).

💰 Financeiro & Vendas

Sales & Budgets: Criação de Orçamentos, Vendas e Pedidos (Sale, SaleItem).
Transactions: Controle de Pagamentos, Estornos, Fluxo de Caixa (Transaction).
Services: Catálogo de procedimentos e serviços oferecidos (Service, ServiceTranslation).
Service Packages: Pacotes promocionais e tratamentos seriados (ServicePackage, ServicePackageItem).
Taxonomies: Categorias de Serviços e Classificações (ServiceCategory, Taxonomy).
Professionals Services: Vínculo de serviços habilitados por profissional (ProfessionalService).

⚙️ Configurações & Sistema

Notifications: Central de Notificações e Configurações de Preferência (SystemNotification, NotificationSetting).
Docs & Templates: Gestão de documentos, Termos e Modelos (Doc, DocUser).
Lookups: Tabelas auxiliares e Dicionários de Dados (Lookup).
Auditing & Logs: Logs de Auditoria, Rastreabilidade e Jobs (UserChangelogView, Job, FailedJob).
Cache & Locks: Gestão de Cache Distribuído e Concorrência (Cache, CacheLock).

❓ FAQ (Perguntas Frequentes)

Geral

O que é um Tenant? R: É uma "Business" ou Clínica. Cada clínica tem seus dados isolados das outras (Multi-Tenancy).
Posso instalar em servidor compartilhado? R: Sim, mas recomenda-se VPS (DigitalOcean/AWS) devido ao uso de filas (Redis) e workers.
O sistema é compatível com LGPD/GDPR? R: Sim, possui recursos de Soft Deletes, Logs de Auditoria e exportação de dados.
Existe aplicativo móvel? R: Atualmente é um PWA (Progressive Web App) totalmente responsivo.
Como atualizo o sistema? R: Via git pull, composer install, php artisan migrate e npm run build (DevOps).

Técnico

Por que Inertia.js e não API REST separada? R: Para reduzir a complexidade de manter duas rotas, serializadores e estados duplicados. O Inertia oferece a experiência de SPA com a produtividade de Monolito.
O que é o TenantContext? R: É um singleton que armazena o ID da clínica atual durante a requisição (Multi-Tenancy).
Como adiciono uma nova coluna no banco? R: Crie uma Migration padrão do Laravel. O sistema é banco único, então a alteração reflete para todos os tenants.
Posso usar UUIDs? R: O sistema usa IDs incrementais por padrão para performance de indexação, mas suporta UUIDs se configurado (PostgreSQL).
Onde ficam as regras de validação? R: No Backend em FormRequests (Controllers) e no Frontend em schemas Zod.
Como debugar erros em produção? R: Os logs são salvos em storage/logs. Recomendamos usar o laravel_boost.AiLogProcessor (Error Handling).
O que é o "Sync Endpoint"? R: Um padrão de API que retorna apenas dados alterados desde a última sincronização (Sync Endpoints).

Desenvolvimento

Como crio um novo módulo? R: Siga o Guia de Criação de Entidades.
Preciso saber Vue.js avançado? R: Conhecimentos de Composition API e Pinia são essenciais.
Como rodo os testes apenas de um arquivo? R: php artisan test tests/Feature/MeuTeste.php (PHPUnit) ou npx vitest meu-componente (Vitest).
O CSS não está aplicando, o que fazer? R: Verifique se o npm run dev está rodando ou se fez o build do Tailwind v4.
Posso usar jQuery? R: Não. O projeto é estritamente Vue.js/Reactive.
Como adiciono uma nova tradução? R: Adicione as chaves em lang/pt_BR/module.php e use {{ $t('module.key') }} (i18n).
O que é o laravel-orion? R: Uma lib que gera endpoints de API CRUD automaticamente baseada em Models e Policies.
Como criar um usuário admin via terminal? R: Use o seeder: php artisan db:seed --class=InitialAccessSeeder (Factories & Seeders).

Banco de Dados & Performance

O banco aguenta quantos tenants? R: Com PostgreSQL bem tunado, milhares. O isolamento é lógico (Multi-Tenancy).
Como funcionam os índices? R: Toda tabela tenant-aware deve ter índice composto (business_id, column).
Redis é obrigatório? R: Opcional em dev, altamente recomendado em produção para Cache e Filas.
Como fazer backup de um tenant específico? R: O backup é do banco inteiro. A restauração parcial requer scripts customizados (DevOps).
Onde são salvos os arquivos de upload? R: Localmente em storage/app/public ou S3 (configurável via .env) (Flysystem S3).

Segurança

Como funciona a autenticação? R: Laravel Sanctum (Cookies para Web, Tokens para API externa).
Um tenant pode ver dados de outro? R: Não. O TenantOwned scope impede isso no nível da query SQL (Multi-Tenancy).
As senhas são criptografadas? R: Sim, usando Bcrypt/Argon2 (padrão Laravel).
Existe Log de Auditoria? R: Sim, alterações críticas são registradas na tabela user_changelog_views (Observers).
Como rotacionar API Keys? R: O usuário pode revogar e gerar novas chaves no painel de configurações.

🔗 Veja também:

Catálogo de Entidades: Detalhes de banco de dados.

Estrutura de Pastas: Onde encontrar cada coisa.

🔐 Segurança e Multi-Tenancy

A segurança é garantida em três níveis de profundidade:

Nível de Rota (Middleware):
- O TenantRequestContext garante que toda requisição tenha um business_id válido associado.
- Tentativas de acesso cruzado (Cross-Tenant) são bloqueadas na raiz.
Nível de Aplicação (Policies & Permissions):
- Integração com spatie/laravel-permission (via adapter customizado) para controle granular de funcionalidades (ex: appointments.create).
- Laravel Policies (EnforcesTenantOwnership) verificam se o recurso solicitado (ex: Paciente ID 50) pertence ao Business ID atual.
Nível de Banco de Dados (Global Scopes):
- A Trait TenantOwned aplica automaticamente where('business_id', $currentId) em todas as queries Eloquent.
- Isso previne vazamento de dados mesmo se o desenvolvedor esquecer de filtrar manualmente.

🧪 Estratégia de Testes

Nossa pirâmide de testes é:

Testes Unitários Backend (PHPUnit): Para Services e Helpers isolados.
- Comando: php artisan test --filter=NomeDoTeste
Testes Unitários Frontend (Vitest): Para componentes Vue, Stores e Hooks.
- Comando: npm run test
- Ferramentas: Vue Test Utils, MSW (Mock Service Worker).
Testes de Integração Backend (PHPUnit): Para Controllers e fluxos de API (tests/Feature e tests/Integration).
- Foco: Garantir que o JSON retornado está correto e o banco foi alterado.
Testes E2E (Playwright): Para fluxos críticos do usuário no navegador.
- Cenários: "Agendar consulta", "Fazer Login", "Criar Paciente".
- Comando: npm run test:e2e

💡 Dica: Use o diretório tests/playwright/changelog para criar testes de reprodução de bugs antes de corrigi-los.

🚀 Instalação e Configuração

Pré-requisitos

Opção A: Com Laravel Sail (Recomendado) ⛵

O Sail é uma interface leve para interagir com o Docker no ambiente Laravel.

Instale as dependências
```
composer install
npm install
```
Inicie o Sail
```
./vendor/bin/sail up -d
```

Setup Inicial

cp .env.example .env
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate --seed

Acesse a Aplicação
- URL: http://localhost:80 (O Sail expõe na porta 80 por padrão, configure no docker-compose.yml se necessário)

Opção B: Com Docker Compose Puro 🐳

Para quem prefere gerenciar os containers diretamente sem o wrapper do Sail.

Configure o Ambiente
```
cp .env.example .env
```
Inicie os Containers
```
docker-compose up -d
```

Setup da Aplicação Execute os comandos dentro do container app:

docker-compose exec app composer install
docker-compose exec app php artisan key:generate
docker-compose exec app php artisan migrate --seed

Acesse a Aplicação
- URL: http://localhost:8080 (Porta definida no docker-compose.yml)

Opção C: Manualmente (Sem Docker) 🛠️

Para rodar serviços nativamente na máquina do jeito antigo (requer PHP, Node e Postgres instalados).

Instalação e Configuração

composer install
npm install
cp .env.example .env
php artisan key:generate

Banco de Dados
- Crie um banco PostgreSQL vazio (ex: clinica).
- Configure o .env (DB_HOST, DB_PASSWORD, etc).
- Rode as migrações: php artisan migrate --seed
Executar
```
composer dev
```
Acesse a Aplicação
- URL: http://localhost:8000

🔐 Segurança e Variáveis de Ambiente

📋 Configuração de Variáveis de Ambiente

O projeto utiliza variáveis de ambiente para configuração sensível. NUNCA commite arquivos .env no repositório.

Setup Inicial

Copie o arquivo de exemplo:
```
cp .env.example .env
```

Configure as variáveis obrigatórias:

# Aplicação
APP_KEY=                    # Gerado via: php artisan key:generate
APP_ENV=local              # local, staging, production
APP_DEBUG=true             # false em produção
APP_URL=http://localhost:8000

# Banco de Dados
DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=sistema_clinica
DB_USERNAME=postgres
DB_PASSWORD=sua_senha_aqui

# AI Services (Opcional)
AI_GEMINI_API_KEY=sua_chave_gemini_aqui
AI_OPENAI_API_KEY=sua_chave_openai_aqui

# Email (Produção)
MAILERSEND_API_KEY=sua_chave_mailersend_aqui

# Storage S3 (Produção)
AWS_ACCESS_KEY_ID=sua_access_key_aqui
AWS_SECRET_ACCESS_KEY=sua_secret_key_aqui
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=seu_bucket_aqui

Gere a chave da aplicação:
```
php artisan key:generate
```

Variáveis Críticas

Variável	Descrição	Obrigatório	Ambiente
`APP_KEY`	Chave de criptografia Laravel	✅ Sim	Todos
`DB_PASSWORD`	Senha do banco de dados	✅ Sim	Todos
`AI_GEMINI_API_KEY`	Google Gemini API (IA)	⚠️ Opcional	Dev/Prod
`AI_OPENAI_API_KEY`	OpenAI API (IA)	⚠️ Opcional	Dev/Prod
`MAILERSEND_API_KEY`	Envio de emails transacionais	⚠️ Prod	Produção
`AWS_ACCESS_KEY_ID`	S3 Storage (arquivos)	⚠️ Prod	Produção
`AWS_SECRET_ACCESS_KEY`	S3 Storage (arquivos)	⚠️ Prod	Produção

📖 Documentação completa: Ver SECURITY.md para políticas de segurança e melhores práticas.

🛡️ Proteções de Segurança Ativas

Este repositório possui proteções automáticas contra commits acidentais de credenciais:

Pre-commit Hooks (git-secrets)

Status: ✅ Configurado

O git-secrets bloqueia automaticamente commits que contenham:

✅ AWS Access Keys e Secret Keys
✅ Google Gemini API Keys (AIzaSy...)
✅ OpenAI API Keys (sk-proj-...)
✅ MailerSend API Keys (mlsn....)
✅ Supabase Tokens (sbp_...)
✅ Render API Tokens (rnd_...)
✅ ClickUp API Keys (pk_...)

Teste de funcionamento:

# Criar arquivo com credencial fake
echo "AIzaSyTest123456789012345678901234567" > test-secret.txt

# Tentar commitar (deve ser bloqueado)
git add test-secret.txt
git commit -m "test"
# ❌ Resultado esperado: Commit bloqueado!

# Limpar teste
rm test-secret.txt

GitHub Secrets Scanning (Recomendado)

Para ativar detecção automática de credenciais no GitHub:

Acesse: https://github.com/anarkaike/sistema-clinica-new/settings/security_analysis
Ative Secret scanning
Ative Push protection
Ative Dependabot alerts

📖 Guia completo: Ver documentação em .gemini/antigravity/brain/.../github-secrets-scanning-guide.md

🔒 Boas Práticas de Segurança

Nunca commite credenciais
- Use .env files (já em .gitignore)
- Use variáveis de ambiente
- Use secrets managers em produção
Rotação de credenciais
- API keys: a cada 90 dias
- Senhas de banco: a cada 6 meses
- APP_KEY: após incidentes de segurança
Senhas fortes
- Mínimo 16 caracteres
- Mix de letras, números e símbolos
- Use gerenciadores de senha
Mantenha dependências atualizadas
```
composer update
npm update
```
Revise código antes de commitar
```
git diff --cached
```

📖 Mais informações: Ver SECURITY.md para política completa de segurança.

🔑 Ambiente Demo (Dados Pré-populados)

O Ambiente Demo é um cenário pronto para uso imediato, populado automaticamente pelos Seeders durante a instalação (migrate --seed).

Objetivo: Permitir testes rápidos, demonstração de funcionalidades e desenvolvimento sem a necessidade de cadastrar dados manualmente. O banco já vem com:

🏢 Clínicas (Tenants) configuradas.
👥 Usuários com diferentes perfis e permissões.
📅 Agendamentos, Pacientes e Prontuários fictícios.

Use as credenciais abaixo para explorar os diferentes perfis:

Role	E-mail	Senha	Acesso
Super Admin	`[email protected]`	`password`	Acesso total ao sistema e configurações globais.
Clinic Owner	`[email protected]`	`password`	Gestão completa de uma clínica (Tenant).
Manager	`[email protected]`	`password`	Gestão operacional (sem acesso a financeiro sensível).
Doctor	`[email protected]`	`password`	Agenda, Prontuários e Anamneses.
Receptionist	`[email protected]`	`password`	Agendamento e cadastro de pacientes.
Patient	`[email protected]`	`password`	Visualização de agendamentos e histórico próprio.

Nota: A senha padrão para todos os usuários demo é password.

📚 Mapa da Documentação

Abaixo, a estrutura completa em árvore da nossa documentação:

docs/
- .ai-workspace/ (SSoT local do workspace)
  - README.md: Visão geral do workspace e estrutura mínima.
  - memory/: Estado do projeto e memória operacional.
  - analysis/: Relatórios, insights e diagnósticos.
  - tasks/: Kanban e backlog ativo do projeto.
- node_modules/ai-agent-ide-context-sync/ (Kernel + módulos)
  - README.md: Visão geral do kernel e CLI.
  - modules/: Módulos oficiais (core, analysis, templates, etc.).
  - cli/: Entrypoints e comandos do ai-doc.
- 20--changelog/ (Registro de Mudanças)
  - README.md: Histórico de versões, releases e atualizações do sistema.
- 30--user-manual/ (Documentação para Usuários Finais)
  - README.md: Índice do manual do usuário.
  - 00--getting-started.md: Guia de primeiros passos para novos usuários.
  - 33--flows/: Documentação detalhada de fluxos de uso (ex: Agendamento).
- 40--tech-manual/ (Manual Técnico e Arquitetura)
  - README.md: Visão geral técnica e mapa do manual técnico.
  - 00--nomenclatura.md: Convenções de nomes para código, banco de dados e arquivos.
  - i18n.md: Guia de Internacionalização e tradução.
  - 20--project-architecture-patterns/ (Padrões de Arquitetura)
    - README.md: Índice de padrões arquiteturais.
    - backend-patterns/: Padrões de Backend (Controllers, Services, Repositories).
    - database-patterns/: Padrões de Banco de Dados (Migrations, Seeders, Multi-tenancy).
    - frontend-patterns/: Padrões de Frontend (Vue, Pinia, Componentes).
    - tests-patterns/: Estratégias e padrões de Testes (Unitários, E2E).
  - 40--entities/ (Dicionário de Dados)
    - README.md: Índice e mapa de relacionamento das entidades.
    - 11--new-entity-guide.md: Guia passo-a-passo para criar novas entidades.
    - 22--entity-page-list.md: Mapeamento de Entidades vs Páginas do Sistema.
    - entities/: Documentação detalhada de cada entidade (Model).
      - anamnesis.entity.md: Fichas de Anamnese.
      - appointment.entity.md: Agendamentos e Consultas.
      - business.entity.md: Clínicas (Tenants).
      - business_unit.entity.md: Unidades de Negócio.
      - doc.entity.md: Documentos e Arquivos (GED).
      - lookup.entity.md: Tabelas Auxiliares e Dicionários.
      - market_vertical.entity.md: Segmentos de Mercado.
      - membership.entity.md: Vínculo Usuário-Clínica.
      - module.entity.md: Módulos do Sistema.
      - notification.entity.md: Notificações do Sistema.
      - patient.entity.md: Pacientes.
      - permission.entity.md: Permissões de Acesso.
      - plan.entity.md: Planos e Assinaturas SaaS.
      - role.entity.md: Papéis de Usuário.
      - sale.entity.md: Vendas e Orçamentos.
      - sale_item.entity.md: Itens de Venda.
      - service.entity.md: Serviços Oferecidos.
      - service_package.entity.md: Pacotes de Serviços.
      - taxonomy.entity.md: Categorias e Classificações.
      - transaction.entity.md: Transações Financeiras.
      - user_professional.entity.md: Profissionais de Saúde.
      - users.entity.md: Usuários do Sistema.
      - work_schedule.entity.md: Escalas de Trabalho.
  - 50--devops/ (Infraestrutura)
    - README.md: Visão geral de DevOps.
    - render-blueprint.md: Configuração de Deploy no Render.
  - 60--known-errors/ (Base de Conhecimento)
    - README.md: Soluções para erros conhecidos.
  - 80--backlog/ (Débitos Técnicos)
    - README.md: Lista de melhorias e débitos técnicos.
- 55--tech-stack/ (Pilha Tecnológica)
  - README.md: Visão geral das tecnologias utilizadas.
  - ant-design-vue.md: Biblioteca de Componentes UI.
  - apexcharts.md: Biblioteca de Gráficos.
  - dayjs.md: Manipulação de Datas e Horas.
  - flysystem-s3.md: Armazenamento de Arquivos (S3).
  - fullcalendar.md: Componente de Calendário.
  - inertia.md: Protocolo de Monólito Moderno.
  - laravel.md: Framework PHP Backend.
  - laravel-orion.md: API REST e JSON-API.
  - laravel-sanctum.md: Autenticação SPA/API.
  - mailersend.md: Serviço de Envio de Emails.
  - php.md: Linguagem de Programação Backend.
  - phpunit.md: Framework de Testes Backend.
  - pinia.md: Gerenciamento de Estado Global.
  - playwright.md: Testes End-to-End (E2E).
  - postgresql.md: Sistema de Banco de Dados Relacional.
  - redis.md: Cache e Filas em Memória.
  - tailwind-css.md: Framework CSS Utilitário.
  - tanstack-query.md: Gerenciamento de Estado de Servidor.
  - typescript.md: Superset Tipado de JavaScript.
  - vee-validate-zod.md: Validação de Formulários e Schemas.
  - vitest.md: Runner de Testes Unitários Frontend.
  - vue.md: Framework JavaScript Reativo.
- 70--external/ (Recursos Externos)
  - README.md: Links e referências externas.
  - EvolutionAPI.postman_collection.json: Collection Postman da API de Mensagens.
- 80--analyses-wip/ (Análises em Progresso - Docs)
  - README.md: Índice de análises e rascunhos (documentação).
- 90--legacies/ (Legado)
  - README.md: Documentação de sistemas e códigos legados.
  - history/: Histórico de banco de dados e decisões.
    - DATABASE_ERD.md: Diagrama ER de versões anteriores.
    - MULTI_TENANT_SECURITY.md: Análise de segurança multi-tenant legada.
    - SEEDERS.md: Histórico de estratégias de seeders.
    - TABELAS_MULTI_TENANT.md: Estrutura de tabelas legadas.
  - legacy-system-react/: Dump e schemas do sistema antigo em React.
    - 0000_baseline_schema.sql: Schema base SQL.
    - 0001_baseline_rls.sql: Row Level Security (RLS) SQL.
    - 0002_baseline_seeds.sql: Seeds base SQL.
    - 0003_database_objects.sql: Objetos de banco SQL.
    - 0004_expand_demo_schedules.sql: Expansão de agendamentos demo SQL.
    - schema.ts: Schema TypeScript do sistema legado.
- 99--tmps/ (Temporários)
  - README.md: Área de arquivos temporários e descartáveis.
  - theme.json: Configuração de tema temporária.
- node_modules/ai-agent-ide-context-sync/modules/templates/assets/ (Modelos de Documentação)
  - README.md: Guia de uso dos templates.
  - tmp--global--doc-folder-readme.md: Template para README de diretório.
  - tmp--global--doc-entity.md: Template para documentação de Entidade.
  - tmp--global--doc-tech-pattern.md: Template para Padrão Técnico.
  - tmp--global--doc-analysis-rfc.md: Template para RFC ou Análise Técnica.
  - tmp--global--doc-user-guide.md: Template para Guia do Usuário.
  - tmp--global--doc-business-rule.md: Template para Regra de Negócio.
  - tmp--global--doc-tech-stack.md: Template para Item de Stack Tecnológica.

❓ FAQ (Perguntas Frequentes)

Geral

O que é um Tenant? R: É uma "Business" ou Clínica. Cada clínica tem seus dados isolados das outras (Multi-Tenancy).
Posso instalar em servidor compartilhado? R: Sim, mas recomenda-se VPS (DigitalOcean/AWS) devido ao uso de filas (Redis) e workers.
O sistema é compatível com LGPD/GDPR? R: Sim, possui recursos de Soft Deletes, Logs de Auditoria e exportação de dados.
Existe aplicativo móvel? R: Atualmente é um PWA (Progressive Web App) totalmente responsivo.
Como atualizo o sistema? R: Via git pull, composer install, php artisan migrate e npm run build (DevOps).

Técnico

Por que Inertia.js e não API REST separada? R: Para reduzir a complexidade de manter duas rotas, serializadores e estados duplicados. O Inertia oferece a experiência de SPA com a produtividade de Monolito.
O que é o TenantContext? R: É um singleton que armazena o ID da clínica atual durante a requisição (Multi-Tenancy).
Como adiciono uma nova coluna no banco? R: Crie uma Migration padrão do Laravel. O sistema é banco único, então a alteração reflete para todos os tenants.
Posso usar UUIDs? R: O sistema usa IDs incrementais por padrão para performance de indexação, mas suporta UUIDs se configurado (PostgreSQL).
Onde ficam as regras de validação? R: No Backend em FormRequests (Controllers) e no Frontend em schemas Zod.
Como debugar erros em produção? R: Os logs são salvos em storage/logs. Recomendamos usar o laravel_boost.AiLogProcessor (Error Handling).
O que é o "Sync Endpoint"? R: Um padrão de API que retorna apenas dados alterados desde a última sincronização (Sync Endpoints).

Desenvolvimento

Como crio um novo módulo? R: Siga o Guia de Criação de Entidades.
Preciso saber Vue.js avançado? R: Conhecimentos de Composition API e Pinia são essenciais.
Como rodo os testes apenas de um arquivo? R: php artisan test tests/Feature/MeuTeste.php (PHPUnit) ou npx vitest meu-componente (Vitest).
O CSS não está aplicando, o que fazer? R: Verifique se o npm run dev está rodando ou se fez o build do Tailwind v4.
Posso usar jQuery? R: Não. O projeto é estritamente Vue.js/Reactive.
Como adiciono uma nova tradução? R: Adicione as chaves em lang/pt_BR/module.php e use {{ $t('module.key') }} (i18n).
O que é o laravel-orion? R: Uma lib que gera endpoints de API CRUD automaticamente baseada em Models e Policies.
Como criar um usuário admin via terminal? R: Use o seeder: php artisan db:seed --class=InitialAccessSeeder (Factories & Seeders).

Banco de Dados & Performance

O banco aguenta quantos tenants? R: Com PostgreSQL bem tunado, milhares. O isolamento é lógico (Multi-Tenancy).
Como funcionam os índices? R: Toda tabela tenant-aware deve ter índice composto (business_id, column).
Redis é obrigatório? R: Opcional em dev, altamente recomendado em produção para Cache e Filas.
Como fazer backup de um tenant específico? R: O backup é do banco inteiro. A restauração parcial requer scripts customizados (DevOps).
Onde são salvos os arquivos de upload? R: Localmente em storage/app/public ou S3 (configurável via .env) (Flysystem S3).

Segurança

Como funciona a autenticação? R: Laravel Sanctum (Cookies para Web, Tokens para API externa).
Um tenant pode ver dados de outro? R: Não. O TenantOwned scope impede isso no nível da query SQL (Multi-Tenancy).
As senhas são criptografadas? R: Sim, usando Bcrypt/Argon2 (padrão Laravel).
Existe Log de Auditoria? R: Sim, alterações críticas são registradas na tabela user_changelog_views (Observers).
Como rotacionar API Keys? R: O usuário pode revogar e gerar novas chaves no painel de configurações.

Documentação markdown mantida com 💜

Name		Name	Last commit message	Last commit date
Latest commit History 762 Commits
.ai-doc		.ai-doc
.ai-workspace		.ai-workspace
.claude		.claude
.codex/environments		.codex/environments
.cursor		.cursor
.gemini		.gemini
.github		.github
.google		.google
.junie		.junie
.playwright-mcp		.playwright-mcp
.trae		.trae
.windsurf		.windsurf
api		api
app		app
bootstrap		bootstrap
build		build
conf		conf
config		config
cypress		cypress
database		database
docs-new		docs-new
docs		docs
exemplos		exemplos
packages/nanobot-lib		packages/nanobot-lib
public		public
resources		resources
routes		routes
scripts		scripts
storage		storage
stubs/entity		stubs/entity
tests		tests
tmp		tmp
.aitouch		.aitouch
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.ai-global		.env.ai-global
.env.example		.env.example
.env.example.render		.env.example.render
.env.openhands		.env.openhands
.env.production-openhands		.env.production-openhands
.env.testing		.env.testing
.env.testing.example		.env.testing.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.env		.mcp.env
.mcp.json.example		.mcp.json.example
.npmrc		.npmrc
.windsurfrules		.windsurfrules
AGENTS.md		AGENTS.md
AI-COST-GUIDE.md		AI-COST-GUIDE.md
CLAUDE.md		CLAUDE.md
DELIVERY-SUMMARY-JUNIODEVIA-CONCIERGE-PM-PO.md		DELIVERY-SUMMARY-JUNIODEVIA-CONCIERGE-PM-PO.md
Dockerfile		Dockerfile
ECOSYSTEM-PLAYBOOK.md		ECOSYSTEM-PLAYBOOK.md
ECOSYSTEM-QUICKSTART.md		ECOSYSTEM-QUICKSTART.md
GEMINI.md		GEMINI.md
GLOBAL-AI-SETUP-COMPLETE.md		GLOBAL-AI-SETUP-COMPLETE.md
MIGRATION-SUMMARY-GEMINI-TO-CODEX.md		MIGRATION-SUMMARY-GEMINI-TO-CODEX.md
MULTI-AI-ARCHITECTURE.md		MULTI-AI-ARCHITECTURE.md
OPENHANDS-ENV-CONFIG.md		OPENHANDS-ENV-CONFIG.md
OPENHANDS-EXECUTIVE-SUMMARY.md		OPENHANDS-EXECUTIVE-SUMMARY.md
OPENHANDS-FINAL-DELIVERY.md		OPENHANDS-FINAL-DELIVERY.md
OPENHANDS-QUICKSTART.md		OPENHANDS-QUICKSTART.md
OPENHANDS-SUITE.md		OPENHANDS-SUITE.md
PROMPT_FOR_VPS_AGENT.md		PROMPT_FOR_VPS_AGENT.md
QUICK-SETUP-MULTI-AI.md		QUICK-SETUP-MULTI-AI.md
README-dev.md		README-dev.md
README-docker.md		README-docker.md
README-php84.md		README-php84.md
README.md		README.md
SECURITY.md		SECURITY.md
TELEGRAM-CONFIG-FIX.md		TELEGRAM-CONFIG-FIX.md
all_tests_output.txt		all_tests_output.txt
all_tests_result.txt		all_tests_result.txt
artisan		artisan
boost.json		boost.json
cleanup_mamp.py		cleanup_mamp.py
clickup_map.json		clickup_map.json
composer.json		composer.json
composer.lock		composer.lock
create-user-timeout.png		create-user-timeout.png
cypress.config.ts		cypress.config.ts
debug-stats.png		debug-stats.png
delete-problematic-tests.sh		delete-problematic-tests.sh
docker-compose.yml		docker-compose.yml
error_log.txt		error_log.txt
extract-icons.js		extract-icons.js
files_to_keep.txt		files_to_keep.txt
final-icon-validation.cjs		final-icon-validation.cjs
fix-refresh-database.cjs		fix-refresh-database.cjs
fix-refresh-database.js		fix-refresh-database.js
fix_env.sh		fix_env.sh
form-estado-atual.png		form-estado-atual.png
integration-test.md		integration-test.md
jsconfig.json		jsconfig.json
list_routes.php		list_routes.php
logfile		logfile
opencode.json		opencode.json
openhands-package.json		openhands-package.json
openmemory.md		openmemory.md

Folders and files

Latest commit

History

Repository files navigation

🏥 Alpha Clinic

Sistema de Gestão de Clínicas SaaS Multi-Tenant

👋 Visão Geral e Propósito

🤖 Instruções para Agentes de IA e Humanos

🎯 Diferenciais Técnicos

Backend & Core

Frontend & UX

DevOps & Qualidade

🛰️ Insights Contextuais do Kernel

🛠️ Stack Tecnológica

🛡️ Implementações de Segurança

Proteções Implementadas

🔒 Proteção contra XSS (Cross-Site Scripting)

🚦 Rate Limiting (Proteção contra Força Bruta)

🔐 Segurança de Sessão

🔒 Security Headers HTTP

🌐 CORS Restritivo

📤 Validação de Upload de Arquivos

🏢 Multi-tenancy Seguro

🔍 Auditoria de Dependências

Score de Segurança: ✅ 100/100

🏗️ Arquitetura e Padrões

🔄 Ciclo de Vida da Requisição (End-to-End)

Frontend (Origem)

Backend (Processamento)

Frontend (Retorno)

🎨 Estrutura de Módulos (Frontend)

Camadas Internas do Módulo

Camadas Globais (Core)

🎨 Design System da Documentação

🧠 Filosofia & Estratégia

📄 Detalhamento dos Templates

1. Folder README (tmp--global--doc-folder-readme.md)

2. Entidade de Dados (tmp--global--doc-entity.md)

3. Padrão Técnico (tmp--global--doc-tech-pattern.md)

4. Tarefa / Feature (___tasks/template.md)

5. Análise / RFC (tmp--global--doc-analysis-rfc.md)

6. Guia do Usuário (tmp--global--doc-user-guide.md)

7. Bug Report (tmp--global--doc-test-case.md)

8. Regra de Negócio (tmp--global--doc-business-rule.md)

9. Item de Tech Stack (tmp--global--doc-tech-stack.md)

🧩 Componentização Frontend

🏛️ Filosofia

📦 Componentes Globais

📦 Funcionalidades e Módulos

🏥 Core & Administração (SaaS)

🔐 Acesso & Segurança

📅 Operação Clínica & Agenda

💰 Financeiro & Vendas

⚙️ Configurações & Sistema

❓ FAQ (Perguntas Frequentes)

Geral

Técnico

Desenvolvimento

Banco de Dados & Performance

Segurança

🔐 Segurança e Multi-Tenancy

🧪 Estratégia de Testes

🚀 Instalação e Configuração

Pré-requisitos

Opção A: Com Laravel Sail (Recomendado) ⛵

Opção B: Com Docker Compose Puro 🐳

Opção C: Manualmente (Sem Docker) 🛠️

🔐 Segurança e Variáveis de Ambiente

📋 Configuração de Variáveis de Ambiente

Setup Inicial

Variáveis Críticas

🛡️ Proteções de Segurança Ativas

Pre-commit Hooks (git-secrets)

GitHub Secrets Scanning (Recomendado)

🔒 Boas Práticas de Segurança

🔑 Ambiente Demo (Dados Pré-populados)

📚 Mapa da Documentação

❓ FAQ (Perguntas Frequentes)

Geral

Técnico

1. Folder README (`tmp--global--doc-folder-readme.md`)

2. Entidade de Dados (`tmp--global--doc-entity.md`)

3. Padrão Técnico (`tmp--global--doc-tech-pattern.md`)

4. Tarefa / Feature (`___tasks/template.md`)

5. Análise / RFC (`tmp--global--doc-analysis-rfc.md`)

6. Guia do Usuário (`tmp--global--doc-user-guide.md`)

7. Bug Report (`tmp--global--doc-test-case.md`)

8. Regra de Negócio (`tmp--global--doc-business-rule.md`)

9. Item de Tech Stack (`tmp--global--doc-tech-stack.md`)

Packages