IkkonAdmin

---

Visão geral

O IkkonAdmin é uma aplicação web criada para apoiar a operação do IKKON SPTD | Ikkon São Paulo Taiko Dojo, escola de taiko em São Paulo dedicada ao ensino de percussão japonesa, fue, teoria musical e apresentações culturais.

O sistema centraliza rotinas que antes dependiam de planilhas, Notion, WhatsApp e controles financeiros separados:

• cadastro e acompanhamento de alunos;
• turmas, aulas, frequência e instrutores;
• financeiro, mensalidades, pagamentos, atrasos e acordos;
• admissões, desligamentos e graduações;
• inventário de instrumentos e equipamentos;
• agenda operacional com Google Agenda;
• portal do aluno;
• comunicados, documentos, eventos e conquistas;
• blog público com versões por idioma;
• usuários, cargos, permissões e auditoria.

Este projeto nasceu como uma iniciativa voluntária para organizar processos internos da escola e criar uma base técnica evolutiva para os próximos anos.

Módulos

Site institucional

Rotas públicas:

• / - apresentação institucional.
• /escola - aulas, cursos e experiência do aluno.
• /eventos - grupo artístico, apresentações e eventos.
• /blog - publicações, novidades e bastidores.

O site possui suporte de interface para português, inglês e japonês nas áreas públicas definidas, com seletor de idioma por cookie.

Painel administrativo

O painel interno fica sob /admin e usa autenticação por cookie, roles e permissões granulares. Ele cobre:

• dashboard operacional;
• alunos, turmas, financeiro, admissões, desligamentos e graduações;
• inventário;
• agenda;
• blog;
• administração de usuários, cargos, permissões, sistema e auditoria;
• manutenção operacional da Área do Aluno.

Área do Aluno

O aluno acessa por /aluno/login e usa o portal em /area-do-aluno. O portal consulta dados pelo usuário autenticado, usando o vínculo UsuarioSistema.AlunoId, sem receber AlunoId sensível por rota.

Funcionalidades principais:

• dashboard do aluno;
• perfil;
• financeiro;
• turmas, aulas e horários;
• frequência;
• documentos;
• comunicados;
• eventos;
• conquistas.

Blog

O blog possui painel editorial em /admin/blog e área pública em /blog. Recursos atuais:

• editor rico com texto, imagem e vídeo do YouTube;
• imagem de capa;
• categorias e tags;
• rascunho, agendamento, publicação e arquivamento;
• destaque e blog da semana;
• versões por idioma: pt-BR, en-US e ja-JP;
• SEO básico por post.

Arquitetura

O projeto segue MVC server-side em uma solução ASP.NET Core:

IkkonAdmin
├── IkkonAdmin.Web
│   ├── Controllers
│   ├── Data
│   │   ├── Configurations
│   │   └── Migrations
│   ├── Enums
│   ├── Models
│   │   ├── Entities
│   │   └── ViewModels
│   ├── Infrastructure
│   ├── Security
│   ├── Services
│   ├── Views
│   └── wwwroot
├── IkkonAdmin.Tests
├── docs
├── DEPLOYMENT.md
├── GOOGLE_AGENDA_SETUP.md
├── USUARIOS_ACESSO.md
└── README.md

Stack principal:

• .NET 10 / ASP.NET Core MVC.
• Razor Views para renderização server-side.
• Entity Framework Core 10 com SQL Server.
• Bootstrap 5 e CSS customizado.
• Data Protection para tokens sensíveis.
• Google Calendar API via HttpClient.

Princípios usados:

• regras de negócio concentradas em services;
• services de consulta separados dos comandos nos módulos maiores;
• retornos de comandos padronizados com OperationResult;
• infraestrutura transversal para tempo, usuário atual, storage e auditoria;
• ViewModels por tela;
• Entity Framework Core com configurations por entidade;
• policies e claims para autorização granular, com registro centralizado;
• separação clara entre site público, painel administrativo e portal do aluno;
• migrations versionadas.

Rodando localmente

Pré-requisitos

• .NET SDK compatível com net10.0.
• SQL Server ou SQL Server Express LocalDB.
• Git.
• Opcional: dotnet-ef.

Restaurar pacotes

dotnet restore IkkonAdmin.Web/IkkonAdmin.Web.csproj

Configurar banco

Crie um arquivo local não versionado:

IkkonAdmin.Web/appsettings.Development.json

Exemplo:

"ConnectionStrings": {
  "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=IkkonAdminDb;Trusted_Connection=True;MultipleActiveResultSets=true;TrustServerCertificate=True"
}

Aplicar migrations

dotnet ef database update --project IkkonAdmin.Web/IkkonAdmin.Web.csproj --startup-project IkkonAdmin.Web/IkkonAdmin.Web.csproj

Rodar aplicação

dotnet run --project IkkonAdmin.Web/IkkonAdmin.Web.csproj

O log de desenvolvimento é enxuto de propósito, para a URL do servidor e os erros não ficarem soterrados. Para ver o detalhe completo — incluindo cada SQL executado pelo Entity Framework — use:

IKKON_LOGS=verbose dotnet run --project IkkonAdmin.Web/IkkonAdmin.Web.csproj

URL comum em desenvolvimento:

http://localhost:5037

Docker Compose

O projeto inclui compose.yaml para subir app e SQL Server local em containers:

docker compose up --build

Aplicação:

http://localhost:8080

SQL Server local:

localhost,14333

Credenciais padrão do container de desenvolvimento:

User ID: sa
Password: IkkonLocal!2026
Database: IkkonAdminDb

Usuários de demonstração

As credenciais de desenvolvimento estão em USUARIOS_ACESSO.md.

Resumo:

Perfil	Login	Senha	Destino
Admin	funcionario.admin	Ikkon@123	/admin/painel
Funcionário	funcionario.operacional	Func@123	/admin
Aluno	aluno.demo	Aluno@123	/area-do-aluno

Credenciais exclusivas de desenvolvimento e demonstração; elas não são criadas em produção.

O seed demonstrativo não roda em Production. O primeiro administrador de produção é criado somente pelo bootstrap secreto descrito no runbook.

Documentação

Documentação técnica e funcional separada:

• Índice da documentação
• Arquitetura e convenções
• Padrões de serviços e operações
• Área do Aluno
• Blog e idiomas
• Módulos administrativos e permissões
• Uploads e storage
• Deploy
• Runbook de produção
• Google Agenda
• Usuários de acesso

Deploy

O guia de demonstração fica em DEPLOYMENT.md; produção segue o runbook. Os principais health checks são:

/health/live
/health/ready

Para ambientes com uploads reais, leia também Uploads e storage.

Segurança

Cuidados já considerados:

• autenticação separada para administração e aluno;
• autorização por roles, claims e policies;
• validação server-side de ações protegidas;
• query filter para usuários excluídos;
• área do aluno sempre resolvida pelo usuário autenticado;
• dados financeiros e documentos protegidos por permissão e vínculo;
• tokens do Google protegidos com Data Protection;
• documentos de aluno armazenados fora de wwwroot;
• secrets e uploads ignorados no Git.

Licença e observação

Este projeto foi criado como uma iniciativa voluntária para apoiar a organização administrativa do IKKON SPTD.

O código e os assets institucionais devem respeitar a autorização da escola antes de qualquer uso externo, redistribuição ou publicação comercial.