CentroEduAAA

Sistema de gestão escolar em arquitetura monorepo, com API em Node.js/Express + Sequelize e frontend SPA em Vue 3 + Vite.

Visão Geral

O projeto atende fluxos de administração escolar para perfis admin, gestor, secretaria, professor, aluno e responsavel, cobrindo:

• gestão acadêmica (alunos, turmas, matrículas, notas, frequência, planejamento)
• comunicação (mural de avisos, notificações)
• documentação escolar (declarações, histórico, relatórios)
• operações administrativas (unidades, assinaturas, backups)

Stack Real do Projeto

API (api/)

• Node.js + Express
• Sequelize ORM
• PostgreSQL/MySQL (dialeto via api/config/config.json)
• Autenticação com JWT em cookie HttpOnly + CSRF + controle de sessões por dispositivo
• Upload/arquivos com Cloudinary e Cloudflare R2 (opcional)
• E-mail com Nodemailer (SMTP ou Ethereal fallback)
• Filas com Redis/BullMQ (opcional, para e-mails/documentos)

Client (client/)

• Vue 3 + Vite
• Pinia
• Vue Router
• Axios
• Tailwind CSS v4

Estrutura do Repositório

centroeduaaa/
├── api/
│   ├── app.js
│   ├── config/
│   ├── controllers/
│   ├── middleware/
│   ├── migrations/
│   ├── models/
│   ├── routes/
│   ├── services/
│   └── templates/
├── client/
│   ├── src/
│   │   ├── components/
│   │   ├── layout/
│   │   ├── router/
│   │   ├── services/
│   │   ├── stores/
│   │   └── views/
│   └── vite.config.js
└── README.md

Módulos Principais (API)

Rotas protegidas são centralizadas em api/routes/index.js. Principais domínios:

• autenticação e conta (auth, usuarios, pessoas)
• acadêmico (alunos, professores, turmas, matriculas, notas, presencas, aulas)
• planejamento (mapeamento curricular, conteudo anual, planejamento bimestral)
• calendário e eventos (anos letivos, periodos, eventos)
• comunicação (avisos, notificacoes)
• documentos (declaracoes, historico, relatorios, assinaturas)
• alimentação (cardapios, fichas de lanche)
• suporte operacional (uploads, backup, unidades, configuracoes de documento)

Autenticação e Segurança (estado atual)

• Login em POST /api/auth/login
• JWT assinado com JWT_SECRET (mínimo 32 chars)
• Token em cookie HttpOnly accessToken
• CSRF por cookie csrfToken + header X-CSRF-Token
• Sessões por dispositivo persistidas em UserSessions
  • listar sessões: GET /api/auth/sessions
  • encerrar sessão: DELETE /api/auth/sessions/:id
  • encerrar outras: POST /api/auth/sessions/revoke-others
• Recuperação de senha por link e por código

Requisitos

• Node.js 20+
• npm 10+
• Banco de dados configurado no api/config/config.json

Setup Local

1) API

cd api
npm install

Configure variáveis de ambiente em api/.env (mínimo recomendado):

JWT_SECRET=uma-chave-bem-grande-com-32-ou-mais-caracteres
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

Migrações e seed:

npx sequelize-cli db:migrate
npx sequelize-cli db:seed:all

Suba a API:

npm run dev
# ou
npm start

API roda em http://localhost:3333.

2) Client

cd client
npm install
npm run dev

Client roda em http://localhost:5173.

Scripts Disponíveis

API (api/package.json)

• npm start: inicia servidor
• npm run dev: inicia com watch
• npm run backup: backup local
• npm run restore: restore local
• npm run restore:r2: restore via R2

Client (client/package.json)

• npm run dev: ambiente de desenvolvimento
• npm run build: build de produção
• npm run preview: preview do build
• npm run test:e2e: testes E2E (Playwright)
• npm run lint: lint geral

Variáveis de Ambiente Úteis (API)

Obrigatória

• JWT_SECRET: chave JWT (mínimo 32 caracteres)

Comuns

• NODE_ENV
• FRONTEND_URL
• CSRF_ENABLED (true/false)
• RETURN_JWT_IN_BODY (true/false)
• ALLOW_QUERY_JWT (true/false, manter false em produção)
• LOG_LEVEL

E-mail

• EMAIL_HOST, EMAIL_PORT, EMAIL_SECURE, EMAIL_USER, EMAIL_PASS, EMAIL_FROM
• EMAIL_BRAND_NAME, EMAIL_BRAND_SUBTITLE, EMAIL_PRIMARY_COLOR, EMAIL_PRIMARY_COLOR_DARK

Cloudflare R2 (opcional)

• R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME, R2_PUBLIC_URL

Filas/Redis (opcional)

• REDIS_URL
• EMAIL_QUEUE_ENABLED, EMAIL_QUEUE_POLL_MS, EMAIL_QUEUE_BATCH_SIZE, EMAIL_QUEUE_STALE_MS
• DOCUMENT_QUEUE_ENABLED, DOCUMENT_QUEUE_CONCURRENCY, DOCUMENT_QUEUE_ATTEMPTS

Observações Importantes

• Não existe endpoint /healthz no estado atual.
• CORS permitido está definido em api/app.js (lista fixa de origens).
• URL base do client para API está em client/src/services/http.js (localhost no dev e domínio oficial em produção).
• api/config/config.json contém configuração de banco por ambiente; ajuste para seu cenário antes de subir.