sidney
/
edumanagerpro2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
edumanagerpro2/GEMINI.md

11 KiB
Raw Blame History

EduManager - Regras Globais e Escopo

🚀 Escopo do Projeto

EduManager é um Sistema de Gestão Escolar completo, focado em alta performance, usabilidade premium e automação de processos administrativos e acadêmicos.

🛠️ Stack Tecnológica

  • Frontend/Backend: Remix (React)
  • Banco de Dados: PostgreSQL (100% Local/Self-Hosted)
  • Storage Architecture: 100% Self-Hosted (MinIO) - Decoupled from Supabase Cloud.
  • Image Serving: All images are served via a backend proxy route (/storage/:bucket/:key) to ensure cross-origin compatibility and security.
  • Synchronization: High-performance local API for bank reconciliation (Asaas).
  • Orquestração e CI/CD: Portainer (Docker) com GitHub Actions via Self-Hosted Runner (Oracle ARM64 nativo) e Watchtower.
  • Production Entry Point: All production deployments MUST use server.selfhosted.js renamed/copied as server.js in the Docker containers to ensure full local feature availability.

⚠️ Regras de Negócio Críticas (MANDATÓRIO)

[!IMPORTANT] Migração de Dados (Legado 'schoodat'): Ao realizar a migração completa dos dados do sistema legado 'schoodat' para o nosso banco de dados local Postgres, é terminantemente proibido alterar, resetar ou re-hashear as senhas existentes. As credenciais devem ser mantidas exatamente como estão para garantir que o acesso dos usuários não seja interrompido.

🚨 Regras de Fluxo de Trabalho (CRÍTICO)

[!CAUTION] Git Push Proibido Sem Demanda Explícita: NUNCA execute git add, git commit ou git push sem que o USUÁRIO solicite explicitamente. Alterações devem ser feitas nos arquivos, mas o envio ao repositório remoto é uma ação exclusiva do usuário. Aguarde sempre o comando direto do usuário para realizar qualquer operação de versionamento. ESTA REGRA É INVIOLÁVEL E O ASSISTENTE JÁ FALHOU NELA EM 01/05/2026. NÃO REPITA O ERRO.

📜 Padrões de Desenvolvimento

  1. Design System: Estética Premium, Dark Mode por padrão (ou glassmorphism), micro-animações e ausência de placeholders.
  2. Segurança: Todas as rotas sensíveis devem validar o token JWT local (via secrets do ambiente). Proibido usar Supabase SDK para lógica de autenticação ou sincronização no frontend.
  3. Resiliência: Tratamento rigoroso de erros em chamadas de API de terceiros (Asaas, Evolution API).
  4. Upload de Arquivos: Proibido o uso de Base64 para envio de novos arquivos ao servidor. Use obrigatoriamente FormData e envie o objeto File/Blob para as rotas de API que integram com o MinIO.
  5. Build & Deploy Stability: O pipeline de deploy deve obrigatoriamente utilizar runs-on: self-hosted e compilar apenas a plataforma linux/arm64 (sem emulação QEMU). A atualização da stack em produção deve ser automatizada via container transiente do Watchtower.
  6. Express Compatibility: Avoid using raw /* wildcards in Express 5 routes; use Regex paths (/^\/route\/(.+)$/) for compatibility with path-to-regexp v8.
  7. Frontend Independence: NEVER import files from services/ or server.js directly into React components to prevent Node.js/SDK leakage (causes White Screen). Physical isolation is enforced: backend-only services (like MinIO/S3 storage) MUST stay outside the src/ directory in Vite/React projects. Use helpers.ts for UI logic and standard fetch for API calls.
  8. Login Persistence: Administrative sessions are persisted via localStorage ('edumanager_session'). The main entry point MUST validate the session on mount to ensure UX continuity.
  9. Real-time & Sync: In self-hosted environments, use Intelligent Polling (30s) to synchronize notifications and critical data between Portal and Manager, as standard Supabase Realtime is disabled.
  10. Justification Logic: Attendance justifications MUST include fromStudentId in notification metadata and support both arquivo and arquivo_base64 keys for attachment compatibility. Notifications SHOULD include the motive text in the message field (JSON format: {text, motivo}) to allow previews in the manager bell.
  11. Modal Standards: System modals should utilize bg-transparent (no background darkening or blur) with shadow-2xl for depth, ensuring a clean and float-like aesthetic.
  12. Messages Automation: Preventive reminders and overdue settings MUST be managed within their respective template modals (contextual logic), with independent manual triggers for each phase (Overdue vs. Upcoming).
  13. Grading & Evaluation Standards: Assessments are categorized as exam (violet/violet labels) or activity (sky/blue labels). The report card (Boletim) MUST support multiple evaluations per period, showing the individual breakdown (name and value). The module MUST be named "Atividades e Provas" for clarity.
  14. Asaas Safety: All financial generation forms MUST implement a loading state (isCreating) to disable submit buttons and prevent duplicate charges.
  15. Retake Policy: Students ARE allowed to retake activities and exams. The system MUST implement a "Lock" (Cadeado) logic: if locked, the retake button is hidden; if unlocked, the button is visible and the new submission overwrites the previous grade.
  16. Financial Categories: The system supports categories: monthly (Mensalidade), registration (Matrícula), handout (Apostila), and others (Outros). Automated forms must map references (Cursos -> monthly, Registration -> registration, Handout -> handout).
  17. Modal Floating Principle: All system modals must avoid backdrop-blur and background overlays. Use bg-transparent for the fixed container and bg-white (solid) for the modal box, ensuring contrast via large soft shadows (shadow-2xl or equivalent).
  18. Automated Messaging (Cron Jobs): The system uses node-cron for independent message scheduling (Preventive vs. Overdue). Overdue logic MUST implement safety checks using overdue_warnings_count and last_overdue_warning_at to avoid spamming the student. Immediate webhook triggers for PAYMENT_OVERDUE are disabled in favor of scheduled routines.
  19. Numerical Data Integrity: When retrieving data from PostgreSQL NUMERIC or DECIMAL columns, values MUST be explicitly cast to Number() in the backend before being sent to the frontend to prevent crashes when using .toFixed() in React.
  20. Exam Duplication: The system supports cloning evaluations. Duplicated exams MUST default to draft status and include (Cópia) in the title to allow verification before deployment to new classes.
  21. Automatic Attendance Closure: The system implements an automatic closure routine (processAutoAbsences) that generates physical "Absence" records in the PostgreSQL database for any past lesson where a student has no presence or justification. This routine is triggered during data save operations to ensure retroactive consistency between lessons and records.
  22. Unified Notification System (SQL): The system uses the notificacoes PostgreSQL table as the single source of truth for both Portal and Manager. JSON-based notifications in school_data are deprecated. New features (exams, justifications) MUST use SQL INSERT/SELECT and implement Intelligent Polling (30s) in the UI to ensure synchronization.
  23. Soft Delete Policy (Lixeira): Evaluations (exams/activities) MUST NOT be hard-deleted to preserve grade history. Use the isDeleted flag to hide them from students and active management views, keeping them accessible in the "Lixeira" for restoration and ensuring reference integrity in the Report Card.
  24. Grading Arithmetic Logic: All grade averages (Period, Subject, and General) MUST be calculated as arithmetic means (Average of Means). Summing grades for a final period result is prohibited to ensure consistency between Portal and Manager.
  25. SQL Date Handling: When fetching timestamps from PostgreSQL to be matched with JSON dates/ISO strings in the frontend, ALWAYS use TO_CHAR(column, 'YYYY-MM-DD"T"HH24:MI:SS') in the SQL query to prevent Node.js timezone shifts from corrupting string-based matching logic.
  26. SQL-First Architecture Pattern: New features or module refactors SHOULD prioritize 100% SQL persistence (using notas_boletim as a template). The legacy JSON school_data should be treated as secondary or deprecated for these modules, ensuring real-time consistency between Manager and Portal.
  27. Safe Rendering Principle (Portal): All property accesses on dynamic objects (like data or student) MUST use optional chaining (?.). Avoid using undeclared variables copied from other modules; always perform a tsc check in the portal before committing to prevent "White Screen of Death" crashes.
  28. Frequency Parity Rule: The Portal MUST mirror the Manager's attendance matching logic exactly, including time windows (30m before) and end-of-day fallbacks (23:59), to ensure data consistency between Admin and Student views.
  29. Hybrid Identity Lookup: Automated messaging services MUST implement a hybrid lookup for students: first check the legacy school_data JSON, then fallback to the PostgreSQL alunos table. This ensures support for both migrated and newly created students.
  30. Financial Data Integrity: Automation routines MUST prioritize school_data.payments (JSON) as the trigger source while using alunos_cobrancas (SQL) for tracking notification counters (spam control), ensuring 100% parity with the management UI.
  31. Real-Time Bidirectional Sync: Asaas webhooks MUST update both the PostgreSQL alunos_cobrancas table and the legacy school_data.json file in real-time to ensure immediate UI feedback in the administrative panel.
  32. Numerical Type Enforcement: When serving data from PostgreSQL NUMERIC columns, the backend MUST map the result to ensure amounts are sent as Number (not String) to prevent string concatenation bugs in the frontend.
  33. Reverse Sync Requirement (SQL -> JSON): To ensure visual consistency and avoid automation errors (like double billing), the system MUST perform a reverse sync from alunos_cobrancas (SQL) to school_data.payments (JSON) during server initialization and on-demand via the /api/admin/sync-finance-json endpoint.
  34. Deletion & Notification Order (Async): When processing deletions that trigger notifications (e.g., WhatsApp via Asaas Webhook), local database deletion MUST happen only AFTER the notification dispatch. Manual deletion routes should only trigger the external API delete and wait for the webhook to finalize local cleanup, ensuring data availability for message variables.
  35. Mass Send Standard (V3): The mass send feature MUST use the student's or guardian's first name for the {nome} variable (via .split(' ')[0]). It MUST support dual dispatch (sending to both student and guardian if phones are distinct) and allow attachments (Image/PDF) handled via multipart/form-data and the Evolution API sendMedia endpoint.
  36. Frequency Visibility & Justification Tracking: All attendance records of type absence MUST be excluded from the "Presence Time" calculation in the Portal, showing a dash (—) instead. Justifications MUST store the submittedAt timestamp in both SQL and JSON formats to allow auditing and clear display of submission time in the UI.
  37. Server Entry Point Safety: The original server.js files in both Manager and Portal are OBSOLETE and kept only for historical context. You MUST NEVER modify or edit server.js. All backend changes must be applied exclusively to server.selfhosted.js.