尚未偵測到更新。GitHub 發布版本後會顯示在這裡。
依最近已完成的 8 小時觀測回合間的 GitHub 星號增量排序
ESP32-S3 N16R8 bench guide: live pinout, lessons, simulators and the bench log.
翻譯準備中
Bridge AI assistants with Canvas LMS using MCP. Up to 103 tools for students and educators.
翻譯準備中
個人 GitHub 帳號下公開儲存庫的擁有者可以登入並驗證所有權，自行管理介紹，無需管理員核准。
登入並產生驗證檔案，在 30 分鐘內將其提交至此儲存庫的預設分支。其他分支或分叉儲存庫中的檔案無效。然後在下方檢查檔案，即可無需管理員核准直接管理專案。請保留檔案以維持管理權限。
如需登入，將前往登入頁面。登入後請回到此處，再次點擊所選的驗證按鈕。
在專案資料夾中執行 /nomorevibe verify，即可驗證所有權並自行管理介紹。
一分鐘完成驗證Sistema de Gestão Acadêmica
翻譯準備中
取自儲存庫 README
正在載入完整 README。
檢視完整 README ↗Sistema de gestão acadêmica da Divisão de Administração Acadêmica (CIAARA-11) do Centro de Instrução e Adestramento Almirante Radler de Aquino, Marinha do Brasil.
A produção do CIAARA-11 é a v2.0, sobre Google Apps Script + Sheets, até o corte. Este repositório é a plataforma nova, no mesmo domínio. Nada aqui está em uso operacional ainda.
Este roteiro é completo e autossuficiente: se você precisar consultar qualquer outra fonte para chegar ao sistema no ar, isso é um defeito deste arquivo — abra uma questão em vez de contornar.
| Ferramenta | Versão mínima | Conferir com |
|---|---|---|
| Node.js | 22 | node --version |
| pnpm | 11 | corepack enable && pnpm --version |
| Docker | em execução | docker info |
| Supabase CLI | 2.x | supabase --version |
| Git | 2.40 | git --version |
pnpm, não npm. Decisão de 26/08/2026. pnpm-lock.yaml é o lockfile do projeto.
git clone https://github.com/villasboasbernardo-hub/Sistema-de-Gestao-Academica-V2.1.git
cd Sistema-de-Gestao-Academica-V2.1
pnpm install
cp .env.local.example .env.local
Abra o .env.local e preencha. Se esquecer, o sistema sobe assim mesmo e diz na tela qual
variável falta — não quebra com stack trace. Para trabalhar só contra o banco local, os valores
que interessam saem do passo 4.
O que cada variável faz está comentado no próprio arquivo de exemplo. Uma regra basta para não
errar: variável com prefixo NEXT_PUBLIC_ vai para o navegador; sem o prefixo, fica no
servidor. Se você precisou pôr NEXT_PUBLIC_ num segredo, o desenho está errado.
pnpm db:start
Imprime as URLs e chaves locais. Copie API_URL para NEXT_PUBLIC_SUPABASE_URL e ANON_KEY para
NEXT_PUBLIC_SUPABASE_ANON_KEY no .env.local.
O banco local é descartável por definição — pnpm db:reset reconstrói do zero, sem passo
manual. Use sem medo.
pnpm dev
http://localhost:3000. Uma faixa no topo diz em que ambiente você está — ela existe para que
ninguém registre aula de verdade achando que está em homologação.
São dois comandos, com promessas diferentes. Não são redundantes:
| Comando | Cobre | Docker? | Promete | Quando |
|---|---|---|---|---|
pnpm verificar | tipos, lint, formatação, unidade, build | não | rapidez — alvo de 5 min | a cada commit |
pnpm verificar:tudo | tudo acima + pgTAP, RLS e ponta a ponta | sim | coincidir com o CI | antes de abrir o PR |
Verde em verificar:tudo seguido de vermelho no CI é defeito da verificação, não azar — vira
tarefa de correção.
pnpm run lista os 28 scripts. O porquê de cada um está em scriptsComentarios, no
package.json — JSON não aceita comentário, então eles vivem na chave irmã.
Duas fronteiras são verificadas pelo lint e provadas por teste (pnpm test:unidade). Não são
estilo: são arquitetura.
lib/dominio/ é puro. Nada ali importa supabase, next ou react. É onde as regras de
negócio viram funções testáveis sem banco.service_role nunca chega ao navegador. lib/supabase/admin.ts ignora toda a RLS.
Importá-lo de um Client Component quebra o build.Se você desligar uma delas, tests/unidade/lint/fronteiras.test.ts fica vermelho. É de propósito.
lib/tipos/database.ts sai do banco por comando. Ninguém digita nome de coluna.
pnpm db:tipos # regenera a partir do banco LOCAL
pnpm db:tipos:conferir # regenera E falha se divergir do commitado — é o portão do CI
Rode pnpm db:tipos depois de TODA migration, sem exceção. O CI reprova quando o arquivo
commitado diverge das migrations, e é a única defesa que não depende de alguém lembrar.
Este arquivo substitui a aba _Meta_Colunas da v2.0: o contrato de coluna que o Sheets não tinha
passa a ser garantido pelo motor. Hoje ele é praticamente vazio — o schema é o Épico 1, e isso
está correto. O portão nasce funcionando antes de existir o que ele protege, para que o Épico 1
não precise construí-lo junto com a primeira migration.
Se o tsc reclamar de uma coluna que "deveria existir": quase sempre é coluna inventada. A
correção é a migration, não editar o tipo.
git push direto na main. Branch, PR, revisão.lib/tipos/database.ts à mão. É gerado..env.local. Está no .gitignore e precisa continuar lá.Rotacione a chave. Não apague o commit.
Este repositório é público desde 26/08/2026. Reescrever a história não desfaz exposição: quem
clonou continua com a cópia, e o GitHub serve o objeto antigo por um tempo mesmo depois do
force-push. Uma chave que saiu do cofre está comprometida — inclusive se saiu por conversa, por
captura de tela ou por mensagem, não só por commit.
O procedimento, na ordem:
anon e service_role..env.local e o escopo Preview da Vercel
(vercel env rm seguido de vercel env add). Não há escopo Production nesta fatia.Qual chave é qual, antes de colar em qualquer lugar:
| Chave | Formato | Pode circular? |
|---|---|---|
publicável / anon | sb_publishable_… ou JWT com "role":"anon" | Sim. Vai embutida no bundle do navegador por definição; quem protege o dado é a RLS |
secreta / service_role | sb_secret_… ou JWT com "role":"service_role" | Não. Nunca. Ignora a RLS inteira — as 27 tabelas e as 77 policies não valem nada diante dela |
Se você recebeu um JWT e não sabe qual é, procure role no trecho do meio: ele diz anon ou
service_role em texto quase legível dentro do base64.
A v2.1 nasceu como subpasta do repositório SIS11, que guarda também a v1.0 e a v2.0, e foi
replantada aqui em repositório próprio (FR-021). Os commits originais continuam intactos no
SIS11 — nada foi apagado nem reescrito (Princípio IV).
O git subtree split preserva mensagem, autor e data, mas gera commits novos. A correspondência,
para quem precisar seguir a trilha:
Original no SIS11 | Aqui | Commit |
|---|---|---|
d19ab10 | 0eb509c | chore(UE-1): versionar a v2.1 com UE-1 decidida e specs renumeradas |
d31bd56 | e64484d | docs(EPICO-0): especificar a fundacao e registrar o repo publico |
Os SHAs 27e977a e a693373, citados na pesquisa R-1 da spec 001, são de um teste seco feito em
27/08/2026 — ficaram no SIS11 e não são os do replantio real.
O 596d46e Initial commit, de 25/08/2026, é o commit que criou este repositório no GitHub e antecede
o replantio.
Esta pasta é a suíte de documentação da Versão 2.1 do sistema de gestão acadêmica do CIAARA-11 (Divisão de Administração Acadêmica do Centro de Instrução e Adestramento Almirante Radler de Aquino, Marinha do Brasil). A v2.1 é uma migração de plataforma, e nada além disso: o sistema da v2.0 — hoje em produção sobre Google Apps Script + Google Sheets, com 39 ciclos Spec Kit executados e a base já saneada — é reimplantado sobre Next.js 15 (App Router, React 19, TypeScript strict) + Supabase (PostgreSQL, Auth, RLS), hospedado na Vercel. Requisitos, regras de negócio e vocabulário institucional permanecem intactos; muda o substrato técnico. A decisão é de Bernardo Villas Bôas dos Santos, Primeiro-Tenente, arquiteto/desenvolvedor responsável, em 25/08/2026. Não há funcionalidade nova de negócio nesta versão: o valor entregue é a plataforma — integridade referencial, transações, segurança no dado (RLS), deep-link por tela, ambiente de teste por branch e tipos verificados em compilação.
Regra que governa tudo aqui: a v2.1 não reinventa o domínio. Todo RF-, RN- e RNF- da v2.0 tem destino explícito — preservado, preservado com nova implementação, absorvido pela plataforma ou revogado — e nenhum requisito é apagado.
Se você tem 15 minutos: leia docs/fase-1/00-Visao-Geral-e-Escopo.md, seções 5 (por que migrar, com as perdas declaradas) e 9 (os 12 critérios de aceite). Elas contêm o essencial da decisão.
Se você vai começar a implementar hoje, o primeiro comando prático é o do Épico 0 — Fundação. O projeto Supabase e o repositório GitHub já existem (ver Estado do projeto), então o passo real é conectar o repositório à base e gerar os tipos:
# 1. no repositório já criado no GitHub, inicializar o Next.js (Épico 0)
npx create-next-app@latest . --typescript --tailwind --app --eslint --import-alias "@/*"
# 2. inicializar o Supabase local e vincular ao projeto que o Bernardo já criou
npx supabase init
npx supabase link --project-ref <ref-do-projeto>
# 3. gerar os tipos a partir do schema real — este arquivo é o contrato de dados da v2.1,
# e substitui a aba `_Meta_Colunas` da v2.0 (ver Glossário, "tipos gerados")
npx supabase gen types typescript --linked > lib/tipos/database.ts
Antes de escrever a primeira migration, leia docs/fase-2/21-Schema-Fisico-PostgreSQL.md e os scripts de docs/sql-referencia/ na ordem numérica — ela é a ordem de execução.
| Ordem | Leia | Por quê |
|---|---|---|
| 1 | docs/vibe-coding/40-Constitution-v2.1.md | Os princípios que prevalecem sobre qualquer plano ou tarefa. Em especial o Princípio III, reescrito: deixa de proibir framework/banco externo/CI e passa a fixar a nova stack |
| 2 | docs/fase-2/20-Arquitetura-Alvo-Next-Supabase.md | O desenho de conjunto e as fronteiras de camada |
| 3 | docs/fase-2/24-Estrutura-do-Repositorio-e-Convencoes.md | Onde cada coisa mora e como se nomeia |
| 4 | docs/fase-1/04-Regras-de-Negocio-a-Preservar.md | O contrato. As ~40 regras RN-, que viram funções puras em lib/dominio/ |
| 5 | docs/fase-2/21-Schema-Fisico-PostgreSQL.md + docs/sql-referencia/ | O schema e os scripts, na ordem numérica |
| 6 | docs/vibe-coding/42-Prompts-por-Epico.md | O prompt de partida do épico em que você vai trabalhar |
| 7 | docs/fase-1/07-Glossario.md | Consulta permanente — sobretudo a coluna Equivalente na v2.0 |
As duas regras que mais economizam retrabalho: nada em
lib/dominio/importasupabase(regra pura ⇒ testável sem banco), e nenhuma regra de negócio vive só na UI.
| Ordem | Leia | Por quê |
|---|---|---|
| 1 | docs/fase-1/00-Visao-Geral-e-Escopo.md | Escopo, não-escopo e o que foi revogado em 25/08/2026 (seção 7.1) |
| 2 | docs/fase-1/01-Stakeholders-e-Perfis-de-Usuario.md | A fronteira organizacional (seção 0) e a matriz perfil × recurso × ação (seção 2.5) |
| 3 | docs/fase-1/02 e 03 | Requisitos funcionais e não-funcionais, com a coluna Destino na v2.1 |
| 4 | docs/fase-1/04-Regras-de-Negocio-a-Preservar.md | Classificação de risco e de conformidade de cada regra |
| 5 | docs/fase-1/08 e 09 (históricos) | A fundamentação: decisões D1–D7, achados A-1..A-12, propostas P-1..P-14 |
O teste de escopo, em uma frase (Princípio IX): este processo está atribuído à CIAARA-11 na Matriz de Responsabilidades? Se não, está fora — por mais simples que seja implementar. É o critério que sustenta
RNF-NORM-06(o sistema não calcula nota, média, aprovação ou documento escolar).
| Ordem | Leia | Por quê |
|---|---|---|
| 1 | docs/fase-3/30-Plano-de-Migracao-ETL.md | Ordem de carga, congelamento de escrita, corte, reconciliação, critério de aborto e rollback |
| 2 | docs/fase-3/31-Mapa-De-Para-Sheets-PostgreSQL.md | Aba por aba, coluna por coluna, com a transformação aplicada |
| 3 | docs/fase-1/05-Modelo-de-Dados-Conceitual.md | As entidades e as convenções (codigo, origem_migracao_v1, exclusão lógica, vigência) |
| 4 | docs/fase-1/00, seção 9 | Os critérios CA-02, CA-03, CA-10 e CA-11 — que são o portão do corte |
| 5 | docs/fase-1/07-Glossario.md, seção Termos de migração | Para que "reconciliação", "corte" e "rollback" signifiquem a mesma coisa para todos |
Duas decisões já tomadas, para não serem rediscutidas no meio do corte: dupla escrita foi considerada e rejeitada (o corte é único, com congelamento curto); e a CAHO 2026 não é padrão-ouro — validação é por invariante estrutural e matemático, nunca por diff com a saída histórica de um curso.
Cada .md tem uma versão .docx ao lado, para leitura e revisão fora do editor. O .md é a fonte de verdade; o .docx é derivado e nunca é editado diretamente.
v2.1/
├── README.md Este índice: mapa de leitura, árvore, estado e primeiro comando
├── CLAUDE.md Contexto operacional do repositório de código: convenções, gotchas, comandos
│
├── docs/fase-1/
│ ├── 00-Visao-Geral-e-Escopo Por que migrar, o que entra, o que não entra, e os 12 critérios de aceite
│ ├── 01-Stakeholders-e-Perfis Fronteira organizacional, os 9 perfis, matriz perfil × recurso × ação, ciclo de vida da conta
│ ├── 02-Requisitos-Funcionais O que o sistema faz, módulo a módulo, com o destino de cada RF-
│ ├── 03-Requisitos-Nao-Funcionais Desempenho, usabilidade, segurança, manutenibilidade — com RNF-PLAT-01..04 e RNF-SEG-01 revogados
│ ├── 04-Regras-de-Negocio As ~40 regras RN-, com risco, conformidade e destino em lib/dominio/, constraint, trigger ou policy
│ ├── 05-Modelo-de-Dados-Conceitual Entidades, relacionamentos e as convenções de dado da v2.1
│ ├── 06-Backlog-de-Epicos-V2.1 Os 14 épicos (0–13), sequenciamento e critérios de aceite de alto nível
│ ├── 07-Glossario Termos institucionais (invariáveis) + termos técnicos com equivalente na v2.0 + termos de migração
│ ├── 08-Relatorio-de-Triagem [histórico, preservado] Os 48 comentários e as decisões D1–D7 que geraram a v1.1
│ ├── 09-Relatorio-de-Auditoria [histórico, preservado] 12 achados, 7 recomendações, 14 propostas — a fundamentação normativa
│ └── 10-Plano-de-Execucao-Vibe Como os épicos viram ciclos Spec Kit, a Definition of Done e o portão de CI
│
├── docs/fase-2/
│ ├── 20-Arquitetura-Alvo App Router, Server/Client Components, Server Actions, o papel de lib/dominio/
│ ├── 21-Schema-Fisico-PostgreSQL DDL comentado tabela a tabela: tipos, ENUM, constraints, índices, colunas geradas
│ ├── 22-Seguranca-RLS-Autenticacao Sessão e autenticação, perfil_permissao, funções app.*, policies e os testes negativos obrigatórios
│ ├── 23-Design-System Tokens CIAARA sob @theme, tema claro/noturno, components/ciaara/, rotas /print/*
│ ├── 24-Estrutura-do-Repositorio Árvore de pastas, nomenclatura, Conventional Commits, organização de testes
│ └── 25-Camada-de-Dados-e-Estado @supabase/ssr, URL como fonte de verdade (nuqs), revalidate*, degradação segura
│
├── docs/fase-3/
│ ├── 30-Plano-de-Migracao-ETL Ordem de carga, congelamento de escrita, corte, reconciliação, aborto e rollback
│ └── 31-Mapa-De-Para Aba por aba e coluna por coluna: origem, destino, tipo, transformação, ID legado em `codigo`
│
├── docs/vibe-coding/
│ ├── 40-Constitution-v2.1 Os princípios reescritos — em especial o Princípio III, que muda de sentido
│ ├── 41-Guia-de-Vibe-Coding Como conduzir os ciclos Spec Kit nesta stack; a Definition of Done por fatia
│ └── 42-Prompts-por-Epico O prompt de partida de cada um dos 14 épicos
│
└── docs/sql-referencia/ Fonte de supabase/migrations/*.sql e seed.sql — a ordem numérica É a ordem de execução
├── 00-extensoes-e-tipos.sql Extensões, schema `app` e os ENUM normativos (perfil_usuario, escopo_curso, ...)
├── 01-tabelas-cadastro.sql cursos, turmas, disciplinas, instrutores, instrutor_disciplina, usuarios, usuario_curso
├── 02-tabelas-fato.sql registros_aula, avaliacoes, atividades_nao_letivas, planejamento_anual, migracao_log
├── 03-config-e-calendario.sql config_listas, config_parametros, feriados, janelas_curso, reservas_proens, horarios
├── 04-views-e-funcoes.sql Funções app.*, trigger set_auditoria() e as VIEWs de compatibilidade com as abas da v2.0
└── 05-policies-rls.sql RLS em toda tabela, policies por operação e o seed de perfil_permissao
⚠️ Emenda de 03/10/2026 à descrição do documento 22 (decisão de Bernardo Villas Boas, 03/10/2026, D-USR-1). O convite por e-mail foi permanentemente removido, e o sistema não envia e-mail nenhum. Quem cria conta é o Admin, na tela
/admin/usuarios/novo, com senha temporária gerada no servidor, mostrada uma vez e troca obrigatória no primeiro acesso (D-USR-2). Medido no repositório em 03/10/2026: não existem as rotas/convitenem/recuperar-senha,inviteUserByEmaileresetPasswordForEmailnão aparecem em lugar nenhum, etests/unidade/sem-convite-nem-envio-de-email.test.tsreprova se voltarem. ⚠️ (Registro anterior, vencido: a linha acima dizia "22-Seguranca-RLS-Autenticacao — Convite e sessão, perfil_permissao, …".) ⚠️ Esta emenda corrige apenas a descrição no índice: o documento 22 em si cita o convite em 14 lugares (medido em 03/10/2026) e é emendado à parte.
Se você vai ler a suíte inteira, esta é a sequência que faz cada documento ser entendido com o contexto que ele pressupõe:
00 — Visão Geral e Escopo. Estabelece por que a v2.1 existe e o que ela não é.01 — Stakeholders. A fronteira organizacional é pré-requisito para julgar qualquer escopo.07 — Glossário. Lido cedo, não no fim: sem ele, metade dos termos das seções seguintes é ruído.04 — Regras de Negócio. O contrato que a migração precisa honrar.05 — Modelo de Dados. As entidades sobre as quais as regras operam.02 e 03 — Requisitos funcionais e não-funcionais, com os destinos.06 — Backlog de Épicos. Como o trabalho é fatiado.20–25 — Arquitetura, na ordem numérica.30–31 — Migração de dados.40–42 — Vibe coding, imediatamente antes de começar a implementar.08 e 09 — históricos, por consulta: quando quiser saber por que uma decisão é como é.| Item | Estado |
|---|---|
| Sistema em produção | v2.0 — Apps Script + Sheets. Continua sendo a produção até o corte. Base viva: Banco de dados CIAARA-11 v2.0, 23 abas |
| Decisão de migrar | ✅ Tomada por Bernardo Villas Bôas dos Santos em 25/08/2026 |
| Projeto Supabase | ✅ Criado pelo Bernardo — vazio, aguardando o schema do Épico 1 |
| Repositório GitHub | ✅ Criado pelo Bernardo — aguardando o scaffold do Épico 0 |
| Stack | ✅ Decidida, não em aberto: Next.js 15 · React 19 · TypeScript strict · Tailwind v4 · shadcn/ui · Supabase · Vercel · Vitest/Playwright/pgTAP · ETL em Python |
| Documentação Fase 1 | 🟡 Em redação — 00, 01 e 07 escritos; 02–06 e 10 pendentes |
| Documentação Fases 2–3 e Vibe Coding | ⬜ Pendentes |
Schema PostgreSQL / docs/sql-referencia/ | ⬜ Pendente (Épico 1) |
| ETL e corte | ⬜ Pendentes (Épicos 2 e o plano do documento 30) |
| Ambiente de preview e CI | ⬜ Pendentes (Épico 0) |
Sequenciamento dos épicos: 0 → 1 → 2 → 3 → 4, depois por valor. O Épico 2 (ETL) vem antes do 3 (Auth): sem dado migrado não há o que proteger.
Volumes, para dimensionar — não para otimizar: 24 cursos · 29 turmas · 175 disciplinas · 177 instrutores · 798 vínculos instrutor↔disciplina · ~1.753 registros de aula · 663 atividades não letivas · 111 avaliações · dezenas de usuários simultâneos no máximo. É uma base pequena. Priorize clareza de schema e manutenibilidade sobre desempenho; desempenho não é um problema real deste sistema.
RN-DEG-02).migracao_log apenas-acrescenta, requisito revogado fica marcado e não some..md de fase: title, author, date: "25/08/2026", version: "2.1".[PRESERVADO] · [MIGRAÇÃO v2.1] · [REVOGADO — v2.1] · [ABSORVIDO PELA PLATAFORMA] · [NOVO — v2.1].RF-…, RN-…, RNF-…, achado, decisão, épico ou spec).specs/ — as 39 specs da v2.0, convertidas (acrescentado em 26/08/2026)| Item | O que é |
|---|---|
specs/00-Fundacao-Tecnica.md | Spec 00 — o documento mestre. Declara Next.js (App Router), Tailwind CSS e Supabase (banco + auth), fixa o Login como primeira tela e o RBAC via Supabase Auth. Prevalece sobre qualquer spec numerada. |
specs/README.md | Guia de leitura das specs, com o grau de confiabilidade de cada artefato |
specs/001-… a specs/039-… | As 39 specs executadas na v2.0, com a plataforma convertida — ~11.300 substituições, zero menção a Apps Script/Sheets |
⚠️ plan.md e tasks.md de cada spec foram traduzidos, não replanejados. Ao retomar uma
feature, regere os dois com /speckit.plan e /speckit.tasks a partir do spec.md.