Maestro

App mobile para gestão pedagógica musical do GEM de Vargem Grande do Sul

Mobile app for musical pedagogical management at GEM Vargem Grande do Sul

PT-BR • English • Stack • Quick Start • Build Android • Scripts • Autor

🚀 Live Demo • 📦 Repositório • 🌐 Portfólio • 💼 LinkedIn

---

🇧🇷 PT-BR

🎼 Visão geral

Maestro é um aplicativo mobile (e web) criado para digitalizar e organizar a operação pedagógica musical do GEM de Vargem Grande do Sul.

O app substitui cadernos, fichas soltas e planilhas fragmentadas por um fluxo centralizado para cadastro de alunos, professores, métodos, aulas, presença, evolução musical, analytics e relatórios internos.

A proposta é tratar o acompanhamento musical como um sistema pedagógico contínuo, e não como uma coleção de anotações isoladas.

Objetivo: registrar aulas, acompanhar evolução musical e gerar relatórios pedagógicos em um fluxo compartilhado, confiável e prático para uso real da equipe.

---

🎯 Problema que resolve

Antes do Maestro, o acompanhamento pedagógico dependia de registros manuais, memória da equipe e consolidação manual de informações.

Isso dificultava:

• saber o que cada aluno estudou de fato;
• acompanhar evolução ao longo do tempo;
• identificar estagnação, aceleração ou queda de desempenho;
• consolidar relatórios por instrumento, grupo ou período;
• compartilhar a operação entre instrutores e encarregados;
• manter um histórico pedagógico consistente.

O Maestro resolve esse problema criando uma camada digital para registrar, consultar, analisar e exportar informações pedagógicas com mais clareza.

---

👥 Para quem foi feito

O app foi pensado para uso real por:

• Instrutores que lançam aulas no dia a dia.
• Encarregados locais e regionais que acompanham alunos e equipes.
• Coordenação pedagógica que precisa de relatórios e visão consolidada.
• Equipe do GEM que precisa operar em conjunto dentro da mesma organização.

---

✨ Funcionalidades principais

👥 Alunos

• Cadastro completo de alunos.
• Edição, filtros e exclusão.
• Campos pedagógicos e administrativos no mesmo fluxo.
• Organização por instrumento, família, nível, graduação, congregação e status.
• Histórico individual conectado aos registros de aula.

🎼 Aulas

• Registro detalhado de aulas individuais e teóricas.
• Seleção de professor e método.
• Conteúdo musical estruturado.
• Páginas, itens de lição, hinos, vozes e solfejo.
• Observações pedagógicas.
• Presença vinculada ao lançamento.
• Habilidades avaliadas de forma estruturada.

📈 Analytics

• KPIs individuais por aluno.
• Evolução mensal.
• Score médio.
• Delta de progresso.
• Radar de habilidades.
• Alertas de estagnação, aceleração e declínio.
• Visão coletiva do grupo por período.

📊 Relatórios

• Ranking de alunos.
• Média por instrumento.
• Distribuição por nível.
• Crescimento do grupo.
• Alertas de alunos sem registro recente.
• Exportação em PDF, Excel, PNG e JSON.

🧑‍🏫 Professores e equipe

• Cadastro de professores e encarregados.
• Papéis como Instrutor, Encarregado Local e Encarregado Regional.
• Uso compartilhado por organização no Supabase.
• Entrada automática em equipe por código.

🧰 Métodos

• Cadastro e gerenciamento de métodos.
• Vínculo com instrumentos.
• Catálogo musical embutido em JSON.
• Suporte a métodos oficiais usados no contexto do GEM.

⚙️ Operação

• Autenticação com e-mail e senha.
• Modo convidado.
• Tema claro/escuro com persistência.
• Logs locais exportáveis.
• ErrorBoundary global.
• Contexto operacional compartilhado entre telas.

📸 Captura automatizada de telas

• Script scripts/capture-app-screens.js que navega por todas as 19 telas do app.
• Login automático, navegação por abas e sub-telas, clique em itens de lista.
• Geração de 95 screenshots com scroll em múltiplos chunks para cobrir conteúdo abaixo da dobra.
• Usa Puppeteer + servidor HTTP local para servir o bundle web do Expo.
• Ideal para documentação, testes visuais e geração de manual.

📖 Geração de manual de usuário

• Pipeline completo: screenshots → supermega-prompt.md → ChatGPT Premium → Gamma.app → PDF.
• O prompt contextualiza o projeto, descreve cada tela com seus elementos de UI e instrui o ChatGPT a gerar prompts do Gamma em grupos de 10 slides.
• O resultado é um manual de usuário profissional e completo com capa, índice, todas as telas documentadas e conclusão.

---

🧩 Telas e módulos

#	Tela	Chunks	Descrição
01	Início	2	Painel inicial com aulas recentes e CTAs rápidos
02	Centro de Aulas	2	Grade 2×2 com 4 tipos de aula
03	Aula Instrumental	3	Formulário de aula com método, páginas, hinos
04	Aula Teoria	4	Formulário de aula teórica
05	Aula Solfejo	4	Formulário de solfejo e percepção
06	Aula Mista	4	Formulário combinado
07	Presença	2	Marcação de presença em lote
08	Alunos	5	Lista de 61 alunos com busca
09	Detalhe do Aluno	6	Cadastro completo + histórico
10	Menu Mais	6	Grid de 9 sub-menus
11	Grupos	6	Turmas e alocação de membros
12	Professores	6	17 professores cadastrados
13	Métodos	8	15 métodos de ensino
14	Usuários	6	51 perfis de usuário
15	Relatórios	7	Relatórios com filtros e exportação
16	Insights	6	Dashboard analítico com gráficos
17	Metas	6	Metas pedagógicas por aluno
18	Configurações	6	Preferências e perfil
19	Diagnóstico	6	Logs e suporte técnico

---

🇺🇸 English

🎼 Overview

Maestro is a mobile (and web) application created to digitize and organize the musical pedagogical operation of GEM Vargem Grande do Sul.

The app replaces notebooks, loose records and fragmented spreadsheets with a centralized workflow for students, teachers, methods, lessons, attendance, musical progress, analytics and internal reports.

The goal is to treat musical education tracking as a continuous pedagogical system, not as a collection of isolated notes.

Goal: register lessons, track musical progress and generate pedagogical reports through a shared, reliable and practical workflow for real team usage.

---

🎯 Problem solved

Before Maestro, pedagogical tracking depended on manual records, team memory and manual consolidation of information.

This made it difficult to:

• know what each student actually studied;
• compare progress over time;
• identify stagnation, acceleration or performance decline;
• consolidate reports by instrument, group or period;
• share the operation between instructors and coordinators;
• maintain a consistent pedagogical history.

Maestro solves this by creating a digital layer to register, query, analyze and export pedagogical information with greater clarity.

---

👥 Who it was built for

The app was designed for real use by:

• Instructors who register lessons in daily routines.
• Local and regional coordinators who track students and teams.
• Pedagogical coordination that needs reports and consolidated views.
• GEM teams that need to work together inside the same organization.

---

✨ Key features

👥 Students

• Complete student registration.
• Editing, filtering and deletion.
• Pedagogical and administrative fields in the same workflow.
• Organization by instrument, family, level, graduation, congregation and status.
• Individual history connected to lesson records.

🎼 Lessons

• Detailed registration of individual and theoretical lessons.
• Teacher and method selection.
• Structured musical content.
• Pages, lesson items, hymns, voices and solfege.
• Pedagogical notes.
• Attendance linked to lesson records.
• Structured skill assessment.

📈 Analytics

• Individual student KPIs.
• Monthly evolution.
• Average score.
• Progress delta.
• Skill radar.
• Alerts for stagnation, acceleration and decline.
• Collective group view by period.

📊 Reports

• Student ranking.
• Average by instrument.
• Level distribution.
• Group growth.
• Alerts for students with no recent records.
• Export to PDF, Excel, PNG and JSON.

🧑‍🏫 Teachers and team

• Teacher and coordinator registration.
• Roles such as Instructor, Local Coordinator and Regional Coordinator.
• Shared usage through Supabase organization.
• Automatic team entry by code.

🧰 Methods

• Method registration and management.
• Instrument association.
• Embedded musical catalog in JSON.
• Support for official methods used in the GEM context.

⚙️ Operation

• Email/password authentication.
• Guest mode.
• Persistent light/dark theme.
• Exportable local logs.
• Global ErrorBoundary.
• Shared operational context across screens.

📸 Automated screenshot capture

• scripts/capture-app-screens.js navigates all 19 screens.
• Auto-login, tab navigation, sub-screen entry, list item clicking.
• Generates 95 screenshots with multi-chunk scrolling for below-fold content.
• Uses Puppeteer + local HTTP server to serve the Expo web bundle.
• Ideal for documentation, visual regression testing and manual generation.

📖 User manual generation pipeline

• Complete flow: screenshots → supermega-prompt.md → ChatGPT Premium → Gamma.app → PDF.
• The prompt contextualizes the project, describes every screen with UI elements and instructs ChatGPT to generate Gamma prompts in groups of 10 slides.
• Output is a professional, complete user manual with cover, table of contents, every screen documented and conclusion.

---

🛠️ Stack / Tecnologias

Tecnologia	Versão	Uso no projeto
React Native	0.81.5	Base do app mobile
React	19.1.0	Camada de interface e estado
Expo	54	Tooling, runtime e integração nativa
React Navigation	Expo 54 compatible	Drawer + Native Stack navigation
Supabase JS	2.98	Auth, database, RPC e PostgREST
AsyncStorage	—	Persistência local de tema e estados auxiliares
Day.js	—	Manipulação e formatação de datas
React Native Chart Kit	—	Gráficos de evolução e analytics
React Native SVG	—	Base gráfica para charts
Expo Print	—	Geração de PDF
Expo Sharing	—	Compartilhamento de arquivos
Expo File System	—	Leitura/escrita de arquivos exportados
React Native View Shot	—	Captura de charts como imagem
XLSX	—	Exportação .xlsx
Puppeteer	—	Captura automatizada de screenshots web
Node.js HTTP	built-in	Servidor local para servir bundle web
Gradle / Android Native	Local SDK	Geração de APK release local
EAS Build	Perfis configurados	APK remoto e App Bundle

---

🏗️ Arquitetura / Architecture

Visão geral / Overview

O projeto separa claramente:

• interface reutilizável;
• contexto global;
• catálogos e dados estáticos;
• serviços de acesso a dados;
• regras utilitárias;
• telas de fluxo;
• scripts de suporte e automação;
• integrações nativas e build.

The project clearly separates:

• reusable interface;
• global context;
• catalogs and static data;
• data access services;
• utility rules;
• user flow screens;
• support and automation scripts;
• native integrations and build.

Estrutura em alto nível / High-level structure

src/
├── components/
├── constants/
├── context/
├── data/
├── lib/
├── navigation/
├── screens/
├── services/
├── theme/
└── utils/

scripts/
├── capture-app-screens.js
├── seed-test-data.mjs
├── fix-org-membership.mjs
├── debug-auth.mjs
└── ... (15 scripts)

supabase/
├── migrations/
├── functions/
├── config.toml
└── seed.sql

Árvore comentada / Commented tree

src/
├── components/              # Reusable UI components and visual blocks
│   ├── AppUI/
│   ├── BottomNavBar/
│   ├── BulkEntryField/
│   ├── CollapsibleSection/
│   ├── DrawerMenuButton/
│   ├── ErrorBoundary/
│   ├── KpiCard/
│   ├── LessonTypeTabs/
│   ├── MultiSelectModal/
│   ├── RadarChart/
│   ├── ScoreInputRow/
│   ├── SelectModal/
│   └── UnitSwitcher/
│
├── constants/               # Domain enums and constants
│   ├── lessonTypes.js
│   └── units.js
│
├── context/                 # Global application context
│   ├── AuthContext.js
│   └── OperationalContext.js
│
├── data/                    # Local catalogs and embedded methods
│   ├── catalogs.js
│   └── methodCatalog/
│
├── lib/                     # Central external clients
│   └── supabase.js
│
├── navigation/              # Navigation configuration
│   └── AppNavigator.js
│
├── screens/                 # Application screens
│   ├── AttendanceScreen.js
│   ├── DashboardScreen.js
│   ├── LessonCenterScreen.js
│   ├── LoginScreen.js
│   ├── LogsScreen.js
│   ├── MainShellScreen.js
│   ├── MethodsScreen.js
│   ├── ReportsScreen.js
│   ├── SettingsScreen.js
│   ├── StudentDetailScreen.js
│   ├── StudentsScreen.js
│   ├── TeachersScreen.js
│   ├── TodayScreen.js
│   ├── TheoryGroupsScreen.js
│   └── (outras telas auxiliares)
│
├── services/                # Data access and CRUD/query rules
│   ├── db.js
│   └── org.js
│
├── theme/                   # Light/dark theme and visual tokens
│   └── ThemeProvider.js
│
└── utils/                   # Analytics, parsing, export and normalization
    ├── analytics.js
    ├── attendanceStore.js
    ├── bulkInputParser.js
    ├── calendarRules.js
    ├── errorHandler.js
    ├── exporters.js
    ├── lessonAdapters.js
    ├── lessonPayload.js
    ├── logger.js
    ├── methodCatalog.js
    ├── normalizers.js
    ├── pedagogy.js
    ├── reportInsights.js
    ├── reporting.js
    └── theoryGroupsStore.js

---

📜 Scripts de suporte / Support scripts

A pasta scripts/ contém 15 utilitários para desenvolvimento, manutenção e documentação:

Captura de telas / Screenshot capture

Script	Finalidade
capture-app-screens.js	Navega por 19 telas do app via Puppeteer, gera 95 screenshots com scroll multi-chunk. Login automático como prints.
capture-all-subscreens.js	Captura todas as sub-telas do menu "Mais" individualmente.

Administração Supabase / Supabase admin

Script	Finalidade
seed-test-data.mjs	Cria/verifica usuário de teste prints via service_role key.
fix-org-membership.mjs	Corrige associação do usuário prints à organização (organization_members).
check-profile.mjs	Verifica perfil e metadados do usuário no Supabase Auth.
debug-auth.mjs	Testa fluxo de autenticação (login, sessão, refresh).
debug-live.mjs	Depuração interativa com console remoto.
debug-login.mjs	Testa login com diferentes credenciais.
verify-nav.mjs	Verifica estrutura de navegação do app.
verify-postfix.mjs	Verifica integridade de dados pós-migração.

Utilitários / Utilities

Script	Finalidade
check-env.js	Valida variáveis de ambiente.
extract-hymn-catalog.py	Extrai catálogo de hinos de fonte externa.
test-login-edge.mjs	Testa login via Supabase Edge Function.
restore-bundle.js	Restaura backup do bundle web.
ai-project-scan.mjs	Escaneia o projeto para contexto de IA.

---

📖 Geração de Manual de Usuário / User Manual Generation

O Maestro possui um pipeline completo para geração automatizada de documentação:

capture-app-screens.js  →  95 PNGs  →  supermega-prompt.md  →  ChatGPT  →  Gamma.app  →  PDF

Passo a passo

1. Capturar screenshots

   node scripts/capture-app-screens.js

   Gera 95 PNGs em manual_maestro_package/screenshots/.

2. Criar supermega prompt O arquivo supermega-prompt.md contém:

   • Contexto completo do projeto
   • Inventário de todas as 19 telas com descrição de cada campo e elemento UI
   • Instruções para o ChatGPT gerar prompts para o Gamma.app
   • Regras de grupos de 10 slides (capa no primeiro, conclusão no último)

3. Enviar para ChatGPT Premium

   • Anexar o zip das 95 screenshots
   • Colar o supermega-prompt.md
   • ChatGPT retorna prompts numerados para o Gamma

4. Colar no Gamma.app Cada prompt gera 10 slides. O resultado final é um manual de usuário profissional com capa, índice, todas as telas documentadas e conclusão.

---

🗄️ Banco de dados / Database

Modelo de segurança V6 (Security Hardening)

A migração 20260729170037 substituiu o modelo de segurança baseado em RLS por um sistema de políticas centralizadas usando a função is_member_of_org(org_id):

• Cada registro é vinculado a uma organização via org_id.
• A função is_member_of_org() verifica se o perfil autenticado pertence à organização antes de permitir qualquer operação.
• As funções de autenticação foram restritas ao papel service_role.
• A associação do usuário à organização é armazenada em organization_members.

Entidades principais / Main entities

organizations
    └──< profiles
            └──< students
            └──< teachers
            └──< methods
            └──< lessonrecords

students
    └──< lessonrecords >── teachers
                     └──> methods

Relacionamentos principais / Main relationships

• Uma organization agrupa perfis, alunos, professores e registros.
• Um profile representa o usuário autenticado.
• Um student pode ter vários registros em lessonrecords.
• Um teacher pode lançar várias aulas.
• Um method pode ser associado a vários registros de aula.
• joinOrgByCode conecta o usuário a uma organização compartilhada.

Tabelas principais / Main tables

organization_members

• org_id — referência à organização
• user_id — referência ao perfil do usuário
• member_role — papel na organização (admin, member)

profiles

• id (uuid, referência ao Auth)
• username — identificador único de login
• full_name — nome exibido
• role — papel no sistema (admin, instrutor)
• org_id — organização vinculada
• teacher_id — referência opcional ao registro de professor

organizations

• id (uuid)
• name — nome da organização
• join_code — código para entrada automática de membros

students

• id (uuid)
• full_name, instrument, category, level
• congregation, status, start_date
• observations, address, phone
• birth_date, baptism_date, instrument_change_note
• org_id — organização vinculada

teachers

• id (uuid)
• full_name, instrument, congregation
• role_kind — Instrutor, Encarregado Local, Regional
• active, profile_id, org_id

methods

• id (uuid)
• name, instruments[], active, notes
• owner_id — criador do método
• org_id — organização vinculada

lesson_records

• id (uuid)
• student_id, teacher_id, method_id
• lesson_date, lesson_type (instrumental, theoretical, mixed, solfege)
• method_name, pages, hymns
• lesson_items[], page_items[], content_items[]
• skill_rhythm, skill_reading, skill_technique, skill_posture, skill_musicality
• attendance, observations, org_id

instrument_catalog

• id (uuid)
• name, family, active

---

🔐 RPCs

joinOrgByCode

Conecta um usuário autenticado a uma organização compartilhada através de um código de equipe.

get_login_email_v5

Retorna o e-mail de login associado a um username (usado no fluxo de login legado).

complete_registration_v5

Finaliza o registro de um novo usuário após validação do código de equipe.

validate_registration_code_v5

Valida se um código de equipe é válido e retorna os metadados da organização.

---

🚀 Quick Start / Início rápido

Pré-requisitos / Requirements

• Node.js 20+ recommended
• npm or pnpm
• Expo CLI through npx
• Android Studio with Android SDK
• Java 17
• ADB configured in PATH
• Configured Supabase project
• Android device with Expo Go or Android emulator

Clonar o repositório / Clone repository

git clone https://github.com/BarujaFe1/Maestro.git
cd Maestro

Instalar dependências / Install dependencies

npm install

Configurar variáveis de ambiente / Configure environment

Create a .env file in the project root:

EXPO_PUBLIC_SUPABASE_URL=https://SEU-PROJETO.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=sua_chave_anon

Rodar com Expo / Run with Expo

npx expo start

Tunnel mode, useful when the device is not on the same network:

npx expo start --tunnel

Android físico com Expo Go / Physical Android with Expo Go

1. Install Expo Go on the phone.
2. Run:

npx expo start --tunnel

3. Scan the QR Code with Expo Go.

Emulador Android / Android emulator

With the emulator already open:

npx expo start

Then press a in the Expo terminal.

---

📱 Build Android

Requisitos / Requirements

• Java 17
• Android Studio
• Android SDK
• Android environment variables configured
• android/ folder present in the project
• Functional Gradle setup

Windows environment example

$env:JAVA_HOME="C:\Program Files\Java\jdk-17"
$env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
$env:Path += ";$env:ANDROID_HOME\platform-tools"
$env:Path += ";$env:ANDROID_HOME\emulator"
$env:Path += ";$env:ANDROID_HOME\cmdline-tools\latest\bin"

Local release APK via Gradle

cd android
.\gradlew.bat assembleRelease

Generated APK:

android/app/build/outputs/apk/release/app-release.apk

Install through ADB:

adb install -r android/app/build/outputs/apk/release/app-release.apk

EAS profiles

The project also supports EAS profiles:

• development
• preview — internal APK
• production — App Bundle

Example:

eas build --platform android --profile preview

---

⚙️ Supabase Setup / Configuração do Supabase

Requisitos

• Projeto Supabase criado.
• Authentication habilitado (e-mail/senha).
• Migrations aplicadas.
• Organização inicial criada.
• Código de equipe definido.

Migrations

As migrações estão em:

supabase/migrations/

Aplicar via Supabase CLI ou SQL Editor.

Seed de dados de teste

Scripts disponíveis em scripts/:

# Verificar/criar usuário de teste
node scripts/check-profile.mjs

# Corrigir associação à organização
node scripts/fix-org-membership.mjs

# Seed completo de dados de demonstração
node scripts/seed-test-data.mjs

Os scripts usam um Personal Access Token (PAT) para obter a service_role key via Management API e operar diretamente nas tabelas.

Fluxo de organização

1. Criar a organização em organizations.
2. Definir um join_code.
3. Usuários entram automaticamente via joinOrgByCode.
4. A função is_member_of_org() controla o acesso aos dados.

---

🌐 Web Demo (Expo Web) + Patch de Bundle

O Maestro também está disponível como site web funcional (Expo Web).

🔗 Demo ao vivo: https://maestro-demo-tau.vercel.app

Web build (local)

npx expo export -p web --output-dir dist
node scripts/injectBanner.js

Patch do bundle web / Web bundle patching

O Supabase JS v2.98.0 possui um deadlock no lock queue quando getUser() é chamado dentro do lock do setSession. A cadeia é:

supabase.from() → fetch wrapper → _getAccessToken() → getSession() → acquire lock (JÁ OCUPADO) → DEADLOCK

Solução aplicada no bundle: substituir _getAccessToken() para ler o token diretamente do localStorage em vez de chamar getSession():

async _getAccessToken() {
  try {
    var e = JSON.parse(localStorage.getItem('maestro-auth-v3') || '{}');
    if (e?.access_token) return e.access_token;
  } catch {}
  return this.supabaseKey;
}

Isso eliminou o deadlock e permitiu que todas as chamadas PostgREST funcionassem sem depender do lock do gotrue-js. Sem esse patch, o app web ficava permanentemente pendurado ao tentar carregar qualquer lista (alunos, professores, etc.).

O patch é aplicado manualmente no arquivo:

dist/_expo/static/js/web/AppEntry-*.js

Deploy Vercel

vercel --prod \
  -e EXPO_PUBLIC_SUPABASE_URL="https://seu-projeto.supabase.co" \
  -e EXPO_PUBLIC_SUPABASE_ANON_KEY="sua_chave_anon"

Estrutura do deploy

• Build: vercel.json com build command npx expo export -p web --output-dir dist && node scripts/injectBanner.js
• Output: pasta dist/ (index.html + bundle JS + assets)
• SPA: rewrite /(.*) → /index.html no vercel.json
• Banner: scripts/injectBanner.js injeta banner de demo no HTML final

---

🧠 Technical decisions / Decisões técnicas

Expo with native Android folder

The project uses Expo for fast iteration while keeping a native Android output for predictable local Gradle builds.

Supabase

Supabase was chosen because the project needs authentication, relational data, RPC, shared team usage and simple JavaScript/TypeScript integration.

In-app analytics

Analytics live inside the app because many pedagogical decisions need to be available during lessons, follow-ups and internal meetings.

Local exports

Local export reduces friction for internal use, allowing the team to generate PDFs, spreadsheets, images, backups and reports without an external dashboard.

Organization by code

A team code reduces onboarding friction and centralizes the shared pedagogical operation.

Deadlock patch no bundle web

O @supabase/supabase-js v2.98.0 introduziu um sistema de lock (via navigator.locks ou processLock) para sincronizar chamadas de refresh de token. Quando o fetch wrapper personalizado chama _getAccessToken() → getSession() dentro do lock do setSession, ocorre um deadlock que impede qualquer operação PostgREST.

A solução foi substituir _getAccessToken() por leitura direta do localStorage (chave maestro-auth-v3), onde o próprio gotrue-js persiste a sessão. Isso elimina a dependência do lock sem comprometer a segurança.

V6 Security Hardening

A migração V6 substituiu o modelo de RLS tradicional por políticas centralizadas baseadas na função is_member_of_org(). Isso:

• Simplifica a manutenção de políticas (uma função, não uma política por tabela)
• Garante que todos os acessos passem pela mesma verificação
• Permite auditoria centralizada
• Restringe funções de autenticação ao service_role

---

⚠️ Known Issues

Supabase JS v2.98.0 lock deadlock (web)

Sintoma: o app web fica "carregando" infinitamente após o login. As listas de alunos, professores, métodos não aparecem.

Causa: O _getAccessToken() interno chama getSession() que adquire um lock. Se o lock já estiver ocupado (por setSession durante o login), todas as chamadas PostgREST subsequentes entram em deadlock.

Solução: Patch manual no bundle (ver seção "Web Demo / Patch do bundle web" acima).

Status: Não resolvido upstream. O patch manual é necessário até atualizar o @supabase/supabase-js para uma versão que corrija o lock queue.

Service role required for data operations

Operações administrativas (criar usuários, gerenciar organizações) exigem a service_role key, obtida via Management API com um PAT. A anon key não tem permissão para escrever nas tabelas devido às políticas V6.

---

🗺️ Roadmap

Implementado / Implemented

• Email/password authentication.
• Guest mode.
• Automatic organization entry by code.
• Complete student registration.
• Teacher/coordinator registration.
• Method registration and management.
• Detailed lesson records.
• Individual analytics.
• Collective analytics.
• Export to PDF, Excel, PNG and JSON.
• Exportable local logs.
• Persistent light/dark theme.
• JSON method catalog.
• Drawer + Native Stack navigation.
• Global ErrorBoundary.
• V6 Security Hardening (is_member_of_org).
• Automated screenshot capture (19 screens, 95 shots).
• User manual generation pipeline (ChatGPT + Gamma).
• Web bundle deadlock patch.

Em desenvolvimento / In development

• Continuous operational UX refinements.
• Theory groups and group attendance flow.
• Performance adjustments for large lists.
• Evolution of goals and group pedagogical modeling.

Planejado / Planned

• Additional pedagogical goals consolidation.
• Better reports by group/team.
• Internal distribution improvements.
• Expansion of musical catalogs.
• Broader pedagogical metrics coverage.
• Upgrade supabase-js to fix lock queue upstream.

---

🤝 Contribuição / Contributing

Conventional commits

feat: adiciona exportação de relatório por instrumento
fix: corrige cálculo de delta de progresso
refactor: simplifica normalização de lessonrecords
docs: atualiza instruções de build Android

Recommended flow

git checkout -b feat/nome-da-feature

Open a Pull Request with:

• problem context;
• change scope;
• screenshots or GIFs when UI is involved;
• database or migration notes, if applicable.

Bug reports

When reporting an issue, include:

• affected screen;
• expected behavior;
• current behavior;
• steps to reproduce;
• terminal log;
• exported app log, if applicable;
• Android version and device.

---

👤 Autor / Author

Developed by Felipe Alirio Baruja.

• Portfolio: https://barujafe.vercel.app/
• GitHub: github.com/BarujaFe1
• LinkedIn: linkedin.com/in/barujafe
• Repository: github.com/BarujaFe1/Maestro

---

📄 License / Licença

MIT License.

See LICENSE for details.

---

Maestro

Gestão pedagógica musical com clareza, histórico e evolução.

Musical pedagogy management with clarity, history and progress tracking.