---
tags: [projeto, escola-musica, codeigniter, php]
created: 2026-03-10
updated: 2026-05-05
status: ativo
---

# AG-Music - Sistema de Escola de Musica

## Stack
- **Backend:** CodeIgniter 4.6.1, PHP, MySQL (`ag_music_banco`)
- **Frontend:** Views com Tailwind CSS + SweetAlert2

## Modulos Principais

### Sistema de Comissoes
- **Modelo atual**: Comissao por ANO DE MATRICULA do aluno (tabela `comissao_anual`)
- **Override por matricula**: campos `comissao_override_tipo/valor/motivo`
- Resolucao: override > comissao_anual > fallback professor
- Model: `ComissaoAnualModel::resolverComissao()` - metodo central
- Limite: 4 aulas pagas por aluno/mes
- Detalhes: [[Comissoes]] | [[Comissao Override]]

### Financeiro
- Cards, abas, contas, transferencias
- Views: `direcao/financeiro/index.php` E `direcao/financeiro.php` (ambos devem ser iguais)
- Detalhes: [[Financeiro - Cards e Contas]]

### WhatsApp
- Bloqueio matriculas inativas, resposta automatica, opcao invalida
- Detalhes: [[WhatsApp Melhorias]]

### Taxa de Matricula
- Campos: `matriculas.valor_matricula` (decimal) + `valor_matricula_status` (pendente/pago/isento)
- Gera lancamento financeiro tipo `taxa_matricula` (se valor > 0 e nao isento)

### App Professor e Assinatura Digital
- App mobile, API REST, assinatura digital
- Detalhes: [[App Professor e Assinatura]]

## Estrutura Principal
- **Controllers:** `FinanceiroController`, `MatriculaController`, `ProfessorController`
- **Models:** `ComissaoAnualModel`, `ProfessorModel`, `MatriculaModel`, `AulaModel`, `ContaFinanceiraModel`
- **Views:** `direcao/financeiro/index.php`, `direcao/professores.php`

## Deploy
- Procedimento completo: [[Deploy - Procedimento]]
- Servidor: `server.whmservidor.com`
- Caminho: `/home/agmusiccom/public_html/sistema.agmusic/`
- **IMPORTANTE**: Sempre sincronizar `financeiro/index.php` -> `financeiro.php` (cp + chown)

## Regra Tecnica Critica (CodeIgniter Model)
**NUNCA** usar `$this->xxxModel->update()` para updates parciais em `matriculas` ou `aulas`. Os Models tem `validationRules` com campos `required` que rejeitam silenciosamente. Alguns campos nem estao em `allowedFields`.

Sempre:
```php
$db = \Config\Database::connect();
$db->table('matriculas')->where('id', $id)->update($data);
```

Detalhes: [[Matricula Cancelar Trancar]] | [[Aula Edicao Conflitos]]

## Novidades 2026-05-05 (sessão grande)

### Permissões RBAC
- Tipo direção tem `is_superuser` + tabela `usuario_permissoes` com 15 módulos
- `PermissaoModel::pode($modulo)` + AuthFilter aceita `modulo=alunos` em rotas
- Menu lateral esconde itens sem permissão. Tela `/direcao/usuarios-direcao` (só superuser) com cards
- Detalhes: [[Permissoes RBAC]]

### Feriados + Cron
- Tabela `feriados` (21 nacionais + móveis 2026/2027), config `pausar_em_feriados`
- LembreteService e CobrancaService bloqueiam disparos automáticos em feriado
- Cron diário 08h BRT marca aulas como concluídas (comissão 100%)
- Endpoint: `/cron/marcar-aulas-feriado?token=agm-cron-7Hk29Lqp2Mz5RtVx`
- Detalhes: [[Feriados Automacoes]]

### Analytics
- `/direcao/analytics` com Chart.js — KPIs com delta% vs ano anterior, tabela mensal
- 8 KPIs + 1 gráfico de linha (6 métricas) + 3 pizzas + top 10 professores + tabela 12 meses
- Detalhes: [[Analytics Modulo]]

### Monitoramento de Aulas v2
- Grid responsivo (3/2/1 colunas), 5 abas (Ao vivo / Agendadas / Concluídas / Faltas / Todas)
- Timeline cronológica de 6 tipos de evento do app professor (presente/início/pausa/retomada/fim)
- Refresh automático 10s
- Detalhes: [[Monitoramento Aulas v2]]

### Bradesco — diagnóstico final
- Migração completa para mTLS Portal Developers (`/auth/server-mtls/v2/token`) ✅
- Auth funciona, mas `gerarBoleto` retorna `"IDENTIFICADOR DO PRODUTO NÃO CADASTRADO"` (carteira 09) ou `"DADOS INCONSISTENTES - 0840"` (carteira 26)
- 130+ testes confirmam: problema é no contrato bancário, não no código
- Bug do `cpssoa_jurid` invertido com `nseq_contr` no banco corrigido (era a inversão)
- Espécie do título corrigida para 02 (DM Duplicata Mercantil)
- Status: aguardando Bradesco vincular a carteira correta no contrato 0005346382
- Detalhes: [[Boleto Bradesco]]

## ⚠️ Bugs CRÍTICOS de produção (lições da sessão 2026-05-05)

### PHP do servidor está em UTC
- `date_default_timezone_get()` = UTC, mas datas no banco são salvas em horário Brasília
- `strtotime($coluna_datetime)` errra +3h. `date('H:i:s', $ts)` formata em UTC
- **Solução**: usar helpers `timestampBrasilia()`, `formatarBrasilia()`, `dataBrasilia()` no `ApiProfessorController`
- Sintoma observado: cronômetro do app mostrava 03:40:52 em vez de 00:40
- Detalhes: [[Timezone PHP Servidor]]

### OPcache cheio impede deploys
- `cache_full: true`, `restart_pending: true` faz arquivos novos NÃO entrarem
- Sempre rodar `opcache_reset()` via curl HTTP após pscp
- Detalhes: [[OPcache Env Pitfalls]]

### .env quebra com valor não-quoteado contendo espaços
- `BRADESCO_RAZAO_SOCIAL = AG ESCOLA DE MUSICA LTDA` (sem aspas) → HTTP 500 em todas as rotas
- **Solução**: sempre `cp .env .env.bak.*` antes + citar valores com espaços

### AutoMigrate quebra com migration aplicada manualmente
- `Duplicate column name 'X'` derruba o boot
- Registrar entrada na tabela `migrations` quando aplicar via SQL puro

## Notas Relacionadas
- [[Comissoes]]
- [[Comissao Override]]
- [[Financeiro - Cards e Contas]]
- [[Financeiro Cartao Faturas]]
- [[WhatsApp Melhorias]]
- [[Deploy - Procedimento]]
- [[App Professor e Assinatura]]
- [[Aula Edicao Conflitos]]
- [[Dashboard Calendario]]
- [[Matricula Cancelar Trancar]]
- [[Recibo Pagamento Aluno]]
- [[Boleto Bradesco]]
- [[Permissoes RBAC]]
- [[Feriados Automacoes]]
- [[Analytics Modulo]]
- [[Monitoramento Aulas v2]]
- [[Timezone PHP Servidor]]
- [[OPcache Env Pitfalls]]