Pular para o conteúdo principal

Sistema Syens

Repositório: educacao

Sistema de gestão educacional para redes públicas de ensino. Roda em multiescola (multitenant) na mesma instância: uma única aplicação atende várias mantenedoras (clientes) e, dentro de cada uma, várias escolas. Cobre o ciclo escolar completo — pessoas, turmas, matrículas, notas, frequência, documentação, censo, transporte e alimentação. É a maior e mais antiga base de código da Appolus (~627 models e mais de 3.000 migrations).

Manual de uso (não técnico): Sistema Syens.

Usuários, perfis, contexto e permissões​

Entender esse esquema é o primeiro passo do onboarding: quase toda tela e toda query do sistema dependem dele.

Autenticação. Login por Devise. Cada User está ligado a uma Person (que pode ser um Profissional) e a um perfil (Perfil).

Contexto (multitenancy). Os dados são escopados por três níveis, representados em UserContext (app/models/user_context.rb):

  1. Mantenedora (Customer/cliente) — a rede de ensino. Um usuário pode ter acesso a mais de uma (allowed_customers).
  2. Escola — a unidade. As escolas que um usuário enxerga vêm dos seus vínculos (Vinculo) de profissional. superadministrador?, adm? e quem é da Secretaria de Educação enxergam todas as escolas da mantenedora.
  3. Ano letivo — recorta o período dos dados.

Regra de ouro: nunca vaze dados entre escolas ou mantenedoras. Toda consulta nova deve respeitar o contexto.

Perfis e permissões. Cada usuário tem um Perfil, que reúne Permissao. Uma permissão é o par papel (role) × ação (create, read, update, destroy). A autorização usa CanCan (app/models/ability.rb):

  • superadministrador? recebe can :manage, :all.
  • Para os demais, as permissões do perfil viram regras CanCan. Quando o perfil tem as 4 ações de um papel, ele recebe manage daquele recurso.

Os papéis disponíveis ficam em config/locales/roles.yml. Para criar um papel novo de permissão:

  1. Adicione o nome do papel em config/locales/roles.yml.
  2. Rode bundle exec rake roles:update (executa o RolesUpdater, que cria as 4 ações no banco e remove papéis que saíram da lista).
  3. Atribua o papel ao(s) perfil(is) desejado(s).

Menus. O menu lateral é montado a partir de config/menu.yml, que apenas inclui os arquivos de config/menu/ — um por área de uso: secretariat, school, secretary_teacher, pedagogue, principal, school_transport, nutrition, programs, ead, data e security. O que cada usuário vê é filtrado pelas suas permissões.

Stack​

  • Linguagem: Ruby 2.6.10
  • Framework: Rails 3.2
  • Banco: PostgreSQL
  • Autenticação: Devise
  • Autorização: CanCan (app/models/ability.rb)
  • Jobs: Sidekiq + Redis
  • Auditoria: audited
  • Front-end: ERB + Bootstrap, Vue 2 e React 15 (legado), Webpack 5
  • Armazenamento: AWS S3 (aws-sdk)
  • Testes: RSpec; features Gherkin (features/, especificacao/)

Como rodar localmente​

Passo a passo resumido (guia completo em docs/project_setup.md e docs/installing_a_new_environment.md):

  1. Dependências de sistema (macOS): brew install openssl@1.1 bison gmp libffi libyaml readline zlib e brew install --force icu4c@74.
  2. Ruby e Node via asdf (as versões já estão no .tool-versions): asdf install ruby 2.6.10 e asdf install nodejs 22.
  3. Gems: instale o bundler 1.17.3, compile o charlock_holmes 0.7.6 apontando para o icu4c@74 (comando exato no guia) e rode bundle.
  4. JavaScript: npm install -g yarn e depois yarn.
  5. Banco: suba um PostgreSQL e restaure um dump de desenvolvimento (peça o link ao time) com bin/local-to-local <arquivo-dump> <nova-senha>.
  6. Assets: npm run watch recompila os módulos antigos (Babel); o Webpack (app/webpack) sobe junto com o foreman.

Com Docker Compose: copie config/database.postgres.yml para config/database.yml, rode docker-compose run webpack yarn, docker-compose run web bin/bundle exec rake db:create e docker-compose up.

Variáveis de ambiente​

Configuradas em .env.dev. As principais:

  • DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, DB_PASSWORD — conexão com o PostgreSQL.
  • REDIS_URL — Redis usado pelo Sidekiq.
  • ENCRYPTION_KEY — chave de criptografia de dados sensíveis.
  • MAILER_SENDER — remetente padrão dos e-mails.
  • BIOMETRIC_READINGS_API_KEY, FACE_RECOGNIZER_API_URL — integrações de biometria e reconhecimento facial.
  • LGPD_URL — endpoint do fluxo de LGPD.
  • SMAR_CUSTOMER_ID — identificador de integração externa.
  • NEW_RELIC_AGENT_ENABLED — liga/desliga o monitoramento do New Relic.

Padrões do projeto​

Além do MVC, o app/ tem camadas próprias: services/ e actions/ (regra de negócio), queries/ (consultas), policies/, presenters/, serializers/, forms/, validators/, workers/ (Sidekiq), uploaders/, enumerations/, parsers/ e adapters/.

Convenções específicas (Rails 3 / Ruby 2.6):

  • Código em inglês; textos de interface via i18n (config/locales, pt-BR).
  • Sem ApplicationRecord — models herdam de ActiveRecord::Base.
  • Strong parameters via attr_accessible (não params.permit).
  • Evite sintaxe de Ruby 2.7+ e APIs de Rails 4+.
  • Multitenancy em primeiro lugar: escope tudo à escola/mantenedora.
  • O repositório traz um CLAUDE.md com o contexto do projeto.

BigPicture​

Módulos do Sistema Syens

Deploy​

CI no GitHub Actions (RuboCop, ESLint, build do Webpack e testes). Imagens Docker (Dockerfile, Dockerfile.sedu); a infraestrutura AWS é provisionada pelo InfraSpawn (syens.tf).