# Guia de desenvolvimento — Tikáh

Tudo que você precisa saber para rodar, testar e entender o sistema localmente.

---

## Subir o servidor

```bash
npm run dev
```

Acesse: **http://localhost:3000**

## Seguranca operacional

- `SECURITY.md` e a lista viva de auditoria; itens ticados devem ter evidencia em codigo, workflow ou procedimento documentado.
- Login por credenciais tem rate limit por IP + e-mail, e acoes sensiveis geram `AccessLog` com `details` sanitizado e `severity`.
- Tikáh Admin mascara segredos de SMTP/banco nas respostas; APIs publicas usam redaction defensivo para chaves com cara de segredo.
- Backups automatizados ficam em `.github/workflows/backup.yml`; o deploy executa healthcheck em `/api/health` apos o reload.
- DAST automatizado fica em `.github/workflows/dast.yml`; runbooks de WAF/CDN, rotacao de segredos, hardening de servidor e pentest ficam em `docs/`.
- 2FA administrativo fica em `/admin/seguranca` e `/tikah-admin/configuracoes/seguranca`; quando ativo, o login exige TOTP ou recovery code, e ativacao/desativacao/reset invalida sessoes antigas.
- `npm run security:readiness` e `/tikah-admin/configuracoes/seguranca` validam secrets, 2FA, Super Admin, banco, SMTP, alertas, backup, WAF e hardening antes de producao.
- Alertas de seguranca vao para log e podem ir por e-mail com `SECURITY_ALERT_EMAIL`.
- CSP dinamica fica em `proxy.ts` com nonce por request; producao remove `unsafe-inline` e HTML manual deve ler `x-nonce` quando precisar de script.

Se a porta 3000 já estiver em uso, o Next.js sobe em 3001, 3002, etc. — a porta aparece no terminal.

---

## Contas de demonstração

Senha única para todas: `Demo@2027Parkinson`

| E-mail | Role | Redireciona para |
|--------|------|-----------------|
| `daniel@huryz.com.br` | SUPER_ADMIN | `/tikah-admin` |
| `admin@enep.org.br` | ADMIN | `/admin` |
| `organizador@enep.org.br` | ORGANIZADOR | `/organizador` |
| `secretaria@enep.org.br` | SECRETARIA | `/organizador/credenciamento` |
| `laura.avaliadora@enep.org.br` | AVALIADOR | `/avaliador` |
| `mariana.faria@demo.org` | CONGRESSISTA | `/congressista` |

> Na página de login (`/login`) você pode clicar direto em qualquer perfil para preencher os campos automaticamente.

---

## Fluxo completo: criar um evento do zero

1. Acesse **http://localhost:3000**
2. Clique em **Solicitar implantação** ou use o WhatsApp flutuante
3. Nesta fase, a criação automática de evento está desativada por padrão
4. O novo organizador/evento deve ser criado manualmente no painel administrativo ou por operação assistida
5. Depois de configurado, acesse **http://localhost:3000/[slug-do-evento]** para validar o site público

---

## Mapa de rotas

### Público / Marketing

| URL | O que é |
|-----|---------|
| `/` | Landing page de venda do Tikáh |
| `/?lang=en` / `/?lang=es` | Landing publica do Tikáh traduzida para ingles ou espanhol; textos ficam em `lib/tikah-i18n.ts` com acentuacao UTF-8 real |
| `/demo` | Evento demo ENEP 2027 (dados fictícios, com banner de aviso) |
| `/login` | Login geral (Tikáh + demo accounts) |
| `/registro` | Redireciona para contato comercial; criacao automatica de organizador esta desativada por padrao |
| `/[slug]` | Site público do evento. Ex: `/neuromed2027` |
| `/[slug]/programacao` | Programacao publica filtravel por busca, dia, sala e tipo |
| `/[slug]/trabalhos` | Trabalhos aprovados e anais publicos com filtros |
| `/[slug]/login` | Login de participante com contexto do evento |
| `/[slug]/registro` | Cadastro de congressista para aquele evento |

### Dashboard do Organizador (`/organizador/...`)

| URL | O que é |
|-----|---------|
| `/organizador` | Painel com métricas do evento |
| `/organizador/meu-site` | Renomear slug + conectar domínio próprio + instruções DNS |
| `/organizador/landing-page` | Editor visual da landing do evento |
| `/organizador/configuracoes` | Dados do evento, lotes, categorias, áreas de submissão |
| `/organizador/participantes` | Lista e edição de participantes |
| `/organizador/submissoes` | Gerenciar resumos submetidos |
| `/organizador/submissoes/atribuir` | Atribuir pareceristas |
| `/organizador/propostas` | Configurar chamada de propostas de atividades em grupo |
| `/organizador/avaliadores` | Cadastrar e gerenciar avaliadores |
| `/organizador/programacao` | Sessões e grade do evento |
| `/organizador/programacao/nova` | Nova sessao com convidados, sala, streaming e validacao de choque |
| `/organizador/credenciamento` | Secretaria, check-in via QR code, caixa/turno, material, acesso a salas, offline, recibo e cracha individual |
| `/organizador/etiquetas` | Impressão de etiquetas de cracha em A4 |
| `/organizador/certificados` | Gerar e enviar certificados |
| `/organizador/comunicacao` | Cartas segmentadas, preview, copias, automacoes e historico de e-mails |
| `/organizador/relatorios` | Relatórios e exportação CSV |

### Dashboard do Congressista (`/congressista/...`)

| URL | O que é |
|-----|---------|
| `/congressista` | Painel do participante |
| `/congressista/inscricao` | Realizar inscrição e ver recibo |
| `/congressista/submissao` | Submeter e editar resumos |
| `/congressista/propostas` | Enviar e editar propostas de atividades em grupo |
| `/congressista/programacao` | Programação completa e agenda pessoal de favoritos |
| `/congressista/certificados` | Baixar certificados |
| `/congressista/perfil` | Editar dados do perfil |

### Dashboard do Avaliador (`/avaliador/...`)

| URL | O que é |
|-----|---------|
| `/avaliador` | Painel com trabalhos atribuídos |
| `/avaliador/trabalhos` | Lista de resumos para avaliar |
| `/avaliador/paineis` | Avaliar apresentações de pôsteres |

### Area do Palestrante (`/palestrante/...`)

| URL | O que e |
|-----|---------|
| `/palestrante` | Agenda do convidado/palestrante, confirmacao, recusa e conflito |
| `/palestrante/perfil` | Perfil publico, foto, mini-curriculo, voo e hospedagem |

### Admin do evento (`/admin/...`)

| URL | O que é |
|-----|---------|
| `/admin` | Dashboard administrativo com métricas gerais |
| `/admin/usuarios` | Gerenciar todos os usuários |
| `/admin/inscricoes` | Ver todas as inscrições |
| `/organizador/inscricoes` | Configurar atividades, cupons, sócios, comprovantes, estornos e exportações |
| `/admin/financeiro` | Relatório financeiro |
| `/admin/configuracoes` | Configuração de SMTP do evento |

### Super Admin Tikáh (`/tikah-admin/...`)

| URL | O que é |
|-----|---------|
| `/tikah-admin` | Dashboard da plataforma: tenants, eventos, usuários |
| `/tikah-admin/tenants` | Listar e editar todos os tenants (plano, status, domínio) |
| `/tikah-admin/configuracoes/privacidade` | Politica de privacidade global da plataforma |
| `/tikah-admin/configuracoes/smtp` | SMTP global da plataforma |
| `/tikah-admin/configuracoes/banco` | Configuração de banco de dados de produção |

---

## Comandos úteis

```bash
# Subir servidor de dev
npm run dev

# Buildar para produção (valida TypeScript e gera otimizações)
npm run build

# Auditoria de dependencias de producao
npm audit --audit-level=high --omit=dev

# Resetar banco e recriar dados de demonstração
npm run db:reset

# Só rodar o seed (sem resetar)
npm run seed

# Regenerar o Prisma Client após mudar o schema
npx prisma generate

# Criar nova migration após mudar o schema
npx prisma migrate dev --name nome_da_migration

# Abrir o Prisma Studio (interface visual do banco)
npx prisma studio
```

---

## Banco de dados

- Arquivo local: `dev.db` (SQLite, na raiz do projeto)
- O banco é criado/atualizado automaticamente pelas migrations
- Para inspecionar visualmente: `npx prisma studio` → abre em http://localhost:5555
- O schema fica em `prisma/schema.prisma`
- O seed (dados de demonstração) fica em `prisma/seed.ts`

---

## Fluxos recentes importantes

- **Descricao contratual:** `descricao.md` foi atualizado em 2026-05-08 como inventario detalhado do escopo atual da Tikáh, cobrindo modulos publicos, dashboards, inscricoes, financeiro, cientifico, presencial, certificados, relatorios, LGPD e pontos que dependem de producao.
- **Deploy em tikah.com.br:** `DEPLOY_TIKAH.md` traz o passo a passo de AlmaLinux, GitHub Actions self-hosted runner, PM2, reverse proxy, secrets, backup e checklist de seguranca.
- **Senha temporaria da landing:** definir `TIKAH_SITE_PASSWORD` com uma senha longa e aleatoria e `TIKAH_SITE_LOCK_USERNAME="tikah"` no servidor/Secrets ativa Basic Auth no site publico; `/api/health` fica livre para monitoramento.
- **Uploads endurecidos:** `lib/upload-security.ts` centraliza validacao por MIME, extensao e assinatura real para comprovantes, propostas e fotos.
- **Multi-tenant:** telas e APIs operacionais devem resolver o evento pelo tenant do organizador ou pela inscricao do congressista/avaliador. Evite usar evento publicado global em novos fluxos de participante.
- **Agenda pessoal:** `/congressista/programacao` mostra a programacao completa, permite favoritar sessoes e monta "Minha agenda"; favoritos ficam em `session_favorites`.
- **Propostas em grupo:** `/organizador/propostas` publica chamada com prazo, formatos e anexo opcional; `/congressista/propostas` envia e edita propostas ate a data limite.
- **Prazos:** resumos enviados podem ser editados ate `submissionEnd` quando o status ainda e `RASCUNHO` ou `SUBMETIDO`; propostas podem ser editadas ate `ProposalCall.deadline`.
- **Etapa cientifica:** `/organizador/submissoes` configura tipos de trabalho, limites, criterios com pesos, media/conceito, min/max de avaliadores, desempate e publicacao. Congressistas podem enviar trabalho completo por versoes; avaliadores podem declarar conflito manualmente.
- **Anais:** `/api/organizador/anais` gera PDF consolidado com capa, sumario, filtros e ISBN/ISSN configuraveis em `/organizador/configuracoes`.
- **Programacao e palestrantes:** `/organizador/programacao` cria sessoes com convidados, streaming e bloqueio de choque de horario. `/[slug]/programacao` publica a grade filtravel; `/api/organizador/programacao/export` gera PDF/Word/Excel/iCal e `/api/organizador/palestrantes/export` gera relatorio de convites/conflitos/viagem.
- **Area do palestrante:** `/palestrante` permite confirmar/recusar convites e declarar conflito; `/palestrante/perfil` coleta foto, mini-curriculo, voo e hospedagem.
- **Comunicacao e cartas:** `/organizador/comunicacao` permite selecionar modelo por idioma, editar assunto/HTML, gerar preview com variaveis, enviar para segmentos (todos, pagos, pendentes, autores, aprovados, avaliadores, palestrantes e presentes), copiar secretaria/organizador e acompanhar campanhas/logs.
- **Credenciamento e secretaria:** `/organizador/credenciamento` busca participantes, alerta pagamento/comprovante/socio pendente, registra check-in com local, controla caixa/turno/divergencia, retirada de material, acesso a sessoes por QR/capacidade/categoria, modo tablet/offline com sincronizacao, emite cracha individual/recibo e cria inscricoes presenciais com atividades e acompanhante.
- **LGPD:** `/privacidade` e `/[slug]/privacidade` exibem politicas publicas; `/tikah-admin/configuracoes/privacidade` edita a politica da plataforma; `/organizador/configuracoes`, aba LGPD, edita politica/consentimentos do evento, processa solicitacoes e aciona anonimizacao de inativos; `/congressista/perfil` mostra consentimentos e abre solicitacao de exclusao/anonimizacao.
- **Arquivos:** recibos e certificados sao gerados sob demanda. Anexos enviados por congressistas em propostas sao preservados em `public/uploads/propostas/[eventSlug]` no dev e devem ir para storage externo em producao.
- **Dominio oficial:** em producao, a landing institucional roda em `tikah.com.br` e os eventos em `tikah.com.br/[slug]`. O slug e uma rota dinamica do Next, nao uma pasta fisica; ao renomear, o sistema preserva links antigos com redirecionamento 308.
- **Marca Tikáh:** a landing institucional usa paleta grafite/teal/ciano com acento ambar para diferenciar do Akoryz.
- **Ciano claro Tikáh:** use `text-[#22D3EE]` para manter o hex oficial explicito nos destaques textuais da interface.
- **Hero institucional:** o titulo destacado usa um gradiente unico do ciano `#22D3EE` ao ambar `#F59E0B`, e a descricao destaca termos-chave de mercado em PT/EN com `text-[#22D3EE]`.
- **Troca de idioma:** a interface nao deve exibir seletor de idioma na landing Tikáh, no site publico do evento ou no admin da landing; `?lang=` permanece apenas por compatibilidade.
- **Landing sem verde:** nao use verde/emerald nos destaques da landing institucional; use `#22D3EE` em `Como funciona`, dominio, preco, checks e CTA `Solicitar implantacao`.
- **Contato publico:** rodape da landing mostra `contato@tikah.com.br` e `(16) 99329-6208`; clicar no e-mail copia para a area de transferencia com aviso visual.
- **Contato na landing:** os botoes de e-mail dos CTAs tambem copiam para a area de transferencia com aviso visual; a secao de implantacao assistida permanece no codigo, mas esta oculta da landing publica.
- **Indicadores e cards:** os indicadores do hero usam contador crescente em `components/landing/landing-stats.tsx`, disparado depois de scroll quando o bloco chega perto do centro da tela; cards de funcionalidades/preco usam fonte maior (`text-base` nos titulos, `text-sm` nas descricoes).
- **Exemplos de dominio:** a demonstracao de endereco usa placeholders genericos `seunome`, `seuevento` e `seuevento.com.br`.
- **Site modelo:** a demo publica deve aparecer como `site modelo`; menu `Ver site modelo`, CTA `Acessar site modelo` com icone de globo e destaque/link ciano sublinhado no hero para `/demo`.
- **Navegacao da landing:** nao apontar CTAs comerciais para `#contato`; `Solicitar implantacao` e `/registro` levam ao WhatsApp publico. O logo do cabecalho usa `/` e, na home, rola suavemente para o topo.
- **Nome Tikáh:** a landing institucional tem a secao `#nome`, primeira opcao do menu, explicando a origem Maori de `tika` e usando o trocadilho curto de "tickar" tarefas importantes como feitas.
- **Publicacao do evento:** o organizador controla se o site esta em `RASCUNHO` ou `PUBLICADO`, com preview autenticado antes da abertura publica.
- **Tikáh Admin:** `/tikah-admin` consolida tenants/eventos, inscricoes pagas, receita, taxa Tikáh, previsao de repasses e comandos de criacao de pastas por tenant.
- **Certificados personalizados:** `/organizador/certificados` permite escolher modelo visual, fonte, cores, heranca da identidade do evento e previa antes de emitir PDFs.
- **Landing do cliente:** o site publico do tenant (`/[slug]`) deve reaproveitar os mesmos blocos ricos do site modelo a partir de `landingConfig` e dos cadastros do evento. `/organizador/landing-page` configura ordem, visibilidade, status de publicacao, textos e itens de hero, estatisticas, datas, submissao, local, hospedagem, patrocinadores, historia, instrucoes, eventos anteriores, banners, noticias, diretoria/comissoes, normas e palestrantes.
- **Harmonia de paleta:** componentes novos da landing do evento devem receber cores por props derivadas de `getPalette(config.palette)` e overrides `customPrimary/customSecondary/customAccent`. Hover, sombras, gradientes, atmosferas e bordas devem usar `primary`, `secondary`, `accent`, `cardBg`, `cardBorder`, `sectionBg` e `darkBg`, sem hardcode visual que fique fora da paleta do cliente.

---

## O que funciona localmente vs o que precisa de servidor real

| Funcionalidade | Local | Produção |
|----------------|-------|----------|
| Criar conta e evento automaticamente | desativado | desativado por padrao; implantacao inicial e manual/assistida |
| Publicar evento e ver site | ✅ | ✅ |
| Inscrições, submissões, avaliações | ✅ | ✅ |
| Credenciamento por QR | ✅ | ✅ |
| Certificados PDF | ✅ | ✅ |
| Renomear slug | ✅ | ✅ |
| Envio de e-mails (SMTP) | ⚠️ Precisa configurar SMTP no painel do admin | ✅ |
| Domínio personalizado (ex: `meuevento.com.br`) | ❌ Precisa de DNS real + servidor público | ✅ |
| Upload de fotos de palestrantes | ✅ | ✅ |

> O `setup-tenant.sh` é apenas um utilitário de manutenção manual para servidores Linux. O fluxo automático de criação de pastas acontece via Node.js e funciona em qualquer sistema operacional.

---

## Estrutura de arquivos principal

```
app/
  page.tsx                    ← Landing de venda do Tikáh
  demo/page.tsx               ← Evento demo ENEP
  [tenant]/page.tsx           ← Site público de cada evento
  [tenant]/login/             ← Login de participante
  [tenant]/registro/          ← Cadastro de participante
  login/page.tsx              ← Login geral
  registro/page.tsx           ← Redireciona para contato comercial
  tikah-admin/                ← Super Admin
  (dashboard)/
    organizador/              ← Dashboard do organizador
    congressista/             ← Dashboard do congressista
    avaliador/                ← Dashboard do avaliador
    admin/                    ← Dashboard admin do evento

lib/
  auth.ts                     ← Configuração NextAuth (JWT, sessão, roles)
  events.ts                   ← Helpers: getPublishedEvent, getOrganizerEvent
  slug.ts                     ← Geração e validação de slugs
  reserved-slugs.ts           ← Slugs que nunca podem ser usados por tenants
  domain-map.ts               ← Mapa domain→slug para custom domains
  email.ts                    ← Envio de e-mails via SMTP
  prisma.ts                   ← Singleton do Prisma Client

prisma/
  schema.prisma               ← Schema do banco (modelos, relações)
  seed.ts                     ← Dados de demonstração
  migrations/                 ← Histórico de migrations

components/
  dashboard/sidebar.tsx       ← Menu lateral (role-based)
  dashboard/meu-site-client.tsx ← Formulário de slug e domínio
  tikah-admin/                 ← Componentes do painel super admin
  landing/                    ← Componentes da landing do evento

data/
  domain-map.json             ← Gerado automaticamente (domain → slug)

public/
  uploads/tenants/[slug]/     ← Uploads de cada tenant (fotos, banners)
```

---

## Modelo de negócio

- **Sem mensalidade** — o organizador usa o sistema sem pagar nada adiantado
- **8% sobre inscrições pagas** — única cobrança, descontada automaticamente
- **Repasse em até 5 dias úteis** após o pagamento de cada inscrição

---

## Variáveis de ambiente (`.env`)

```env
DATABASE_URL=file:./dev.db
NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000

# Opcional — domínio oficial da plataforma (usado pelo proxy para custom domains)
PLATFORM_DOMAIN=tikah.com.br

# Opcional em producao inicial: senha temporaria da landing/site publico
TIKAH_SITE_LOCK_USERNAME=tikah
TIKAH_SITE_PASSWORD=
TIKAH_SITE_LOCK_ENABLED=true
```

`NEXTAUTH_URL` deve apontar para `https://tikah.com.br` em producao.
## Atualizacao multi-evento

- `/organizador/eventos` lista o historico de edicoes do tenant, cria novas edicoes e duplica uma edicao existente.
- O seletor lateral troca o evento ativo do painel de organizador/admin.
- `getOrganizerEvent(session)` respeita o cookie `tikah-active-event-id` quando o evento pertence ao tenant do usuario.

## Atualizacao idiomas

- `/organizador/landing-page`, aba `Idiomas`, habilita PT/EN/ES e salva traducoes em `landingConfig.i18n`.
- O site publico do tenant aceita `?lang=pt`, `?lang=en` e `?lang=es`; quando mais de um idioma esta ativo, mostra seletor no cabecalho.
- Textos fixos do sistema publico do evento ficam em `lib/event-i18n.ts`; conteudo editavel da landing vem das traducoes cadastradas pelo organizador.
- `/organizador/configuracoes`, aba `E-mails`, possui filtro PT/EN/ES e salva cada modelo com `EmailTemplate.locale`.
- `/organizador/landing-page`, aba `Gestao do site`, concentra banners agendados, noticias, diretoria/comissoes e normas de inscricao com anexos.
- `/organizador/inscricoes` concentra a etapa comercial da inscricao: atividades opcionais, cupons patrocinados, base de socios quites, analise de comprovantes, estornos e relatorios CSV/XLS.
- Em `/congressista/inscricao`, o participante aceita termos versionados, escolhe atividades, envia comprovante quando a categoria exige, informa cupom, CNA e acompanhante. O sistema bloqueia choques de horario e categorias/atividades esgotadas.
- Pagamentos sao processados pelo Asaas: PIX exibe QR Code/copia e cola dentro da Tikáh, boleto exibe linha digitavel e cartao e capturado no formulario da Tikáh sem enviar o participante para o Mercado Pago ou outro checkout externo.
- A aba `Secoes` da landing permite marcar cada bloco como `Publicado`, `Em revisao` ou `Rascunho`; somente blocos publicados aparecem no site publico.