diff --git a/.claude/README.md b/.claude/README.md new file mode 100644 index 0000000..d45b5a4 --- /dev/null +++ b/.claude/README.md @@ -0,0 +1,45 @@ +# .claude/ — Documentação do Projeto + +## Estrutura + +``` +.claude/ +├── padroes/ # Guias de desenvolvimento por camada +│ ├── backend.md # Arquitetura, SOLID, testes, import/export +│ ├── frontend.md # Layout, componentes, hooks, Tailwind v3 +│ └── ux-ui.md # 10 heurísticas de Nielsen, cores, tabelas +│ +├── skills/ # Specs de implementação +│ ├── README.md # Índice com fluxo entre USs +│ ├── us/ # Uma spec por User Story (US-00 a US-07) +│ ├── qualidade/ # Qualidade e segurança (OWASP, testes, monitoramento) +│ └── readme-gen.md # Geração de READMEs +│ +├── requisitos.md # Épico + User Stories originais +├── backlog.md # Tarefas futuras (fases 2-5 de qualidade) +└── README.md # Este arquivo +``` + +## Como contribuir + +Seguir rigorosamente o [CONTRIBUTING.md](../.github/CONTRIBUTING.md): + +- **Branch**: criar a partir de `dev` (`feature/*`, `fix/*`, `chore/*`) +- **Commits**: `tipo(escopo): descrição` — Conventional Commits +- **PR**: título no mesmo formato, corpo com `## Resumo` + `## Como testar` +- **Merge**: merge commit (não squash), deletar branch após merge +- **Nunca** push direto em `dev` ou `main` + +## Referência rápida + +| Preciso de... | Onde encontrar | +|---------------|----------------| +| Padrões de backend | [padroes/backend.md](padroes/backend.md) | +| Padrões de frontend | [padroes/frontend.md](padroes/frontend.md) | +| Padrões de UX/UI | [padroes/ux-ui.md](padroes/ux-ui.md) | +| Como fazer commits e PRs | [padroes/commits-e-prs.md](padroes/commits-e-prs.md) | +| Spec de uma US | [skills/us/](skills/us/) | +| Roadmap de qualidade | [skills/qualidade/quality-security.md](skills/qualidade/quality-security.md) | +| Backlog de tarefas | [backlog.md](backlog.md) | +| Requisitos originais | [requisitos.md](requisitos.md) | +| Como fazer PR | [../.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md) | diff --git a/.claude/backend.md b/.claude/padroes/backend.md similarity index 100% rename from .claude/backend.md rename to .claude/padroes/backend.md diff --git a/.claude/padroes/commits-e-prs.md b/.claude/padroes/commits-e-prs.md new file mode 100644 index 0000000..b278d31 --- /dev/null +++ b/.claude/padroes/commits-e-prs.md @@ -0,0 +1,100 @@ +# Padrão de Commits e PRs + +Referência rápida baseada no [CONTRIBUTING.md](../../.github/CONTRIBUTING.md). +Este arquivo deve ser lido **antes de criar qualquer commit ou PR**. + +--- + +## Commits + +### Formato + +``` +tipo(escopo): descrição curta no imperativo +``` + +### Tipos + +| Tipo | Quando usar | +|------|-------------| +| `feat` | Nova funcionalidade | +| `fix` | Correção de bug | +| `test` | Adição ou correção de testes | +| `docs` | Documentação apenas | +| `chore` | Build, CI, dependências, sem mudança de lógica | +| `refactor` | Refatoração sem mudança de comportamento | +| `style` | Formatação, espaços, ponto e vírgula | + +### Regras + +- **Separar commits por camada**: backend e frontend em commits distintos +- **Escopo obrigatório**: `feat(dashboard)`, `test(collect)`, `chore(ci)` +- **Descrição com corpo**: se houver mais de 3 mudanças, listar no corpo do commit +- **Co-Authored-By**: usar apenas `Co-Authored-By: Claude ` — sem nome de modelo, sem contexto +- **Nunca** usar `--no-verify` ou `--amend` em commits já pushados + +### Exemplo + +``` +feat(dashboard): adicionar endpoints e service da US-06 + +- 5 endpoints: /dashboard/global, /dashboard/video, /dashboard/user, + /dashboard/bots, /dashboard/criteria-effectiveness +- Schemas Pydantic para request/response +- Service com agregações SQL batch e gráficos Plotly + +Co-Authored-By: Claude +``` + +--- + +## PRs + +### Branch + +- Criar a partir de `dev` (nunca de `main`) +- Naming: `feature/*`, `fix/*`, `test/*`, `chore/*`, `quality/*` +- **Nunca** push direto em `dev` ou `main` — sempre branch → PR → merge + +### Título + +Mesmo formato do commit principal: + +``` +feat(dashboard): implementar US-06 — Dashboard de Análise +``` + +### Corpo (obrigatório, em português) + +```markdown +## Resumo + +- Descrição concisa das mudanças (bullets) + +## Como testar + +- [ ] Passo a passo para validar +- [ ] Cenários de erro ou edge cases + +## Screenshots + +(se houver mudanças visuais no frontend) +``` + +### Merge + +- Usar **merge commit** (não squash, não rebase) +- Deletar branch após merge +- Para PR `dev → main`: sincronizar dev com main antes (`git pull origin main`) + +--- + +## Checklist antes de abrir PR + +- [ ] Branch criada a partir de `dev` +- [ ] `ruff check . && ruff format --check .` passando (backend) +- [ ] `bandit -r . --exclude tests` sem issues (backend) +- [ ] `pytest` com cobertura ≥ 90% (backend) +- [ ] `eslint . && prettier --check . && tsc --noEmit` passando (frontend) +- [ ] Nenhum segredo ou API key commitada +- [ ] Commits separados por camada (backend / frontend / docs) diff --git a/.claude/frontend.md b/.claude/padroes/frontend.md similarity index 100% rename from .claude/frontend.md rename to .claude/padroes/frontend.md diff --git a/.claude/ux-ui.md b/.claude/padroes/ux-ui.md similarity index 100% rename from .claude/ux-ui.md rename to .claude/padroes/ux-ui.md diff --git a/.claude/skills/README.md b/.claude/skills/README.md index 970f2bd..079d773 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -1,34 +1,40 @@ -# Skills — Guias de Implementação por User Story +# Skills — Guias de Implementação -Cada arquivo detalha o contrato de API, schemas de banco, lógica de service, -componentes React sugeridos, casos de erro e dependências com outras USs. +## User Stories (`us/`) -| Arquivo | US | Escopo | -|-------------------------------|-------|-------------------------------------------------| -| [us-00-infra.md](us-00-infra.md) | US-00 | CI/CD, pre-commit hooks, Dependabot, proteção de branch | -| [us-01-auth.md](us-01-auth.md) | US-01 | Login, logout, gestão de usuários (admin/user) | -| [us-02-collect.md](us-02-collect.md) | US-02 | Coleta de comentários via YouTube Data API | -| [us-03-clean.md](us-03-clean.md) | US-03 | Seleção estatística/comportamental de usuários suspeitos | -| [us-04-annotate.md](us-04-annotate.md) | US-04 | Anotação de comentários por usuário do YouTube | -| [us-05-review.md](us-05-review.md) | US-05 | Desempate de conflitos e revisão de bots (admin)| -| [us-06-dashboard.md](us-06-dashboard.md) | US-06 | Dashboard global e individual com Plotly | +Cada arquivo detalha o contrato de API, schemas, lógica de service, componentes React e testes. -| [readme-gen.md](readme-gen.md) | — | Geração consistente de READMEs (raiz, backend, frontend) | +| Arquivo | US | Status | +|---------|-----|--------| +| [us-00-infra.md](us/us-00-infra.md) | US-00 · Infraestrutura e CI/CD | Concluída | +| [us-01-auth.md](us/us-01-auth.md) | US-01 · Autenticação e gestão de usuários | Concluída | +| [us-02-collect.md](us/us-02-collect.md) | US-02 · Coleta de comentários YouTube | Concluída | +| [us-03-clean.md](us/us-03-clean.md) | US-03 · Limpeza e seleção de dataset | Concluída | +| [us-04-annotate.md](us/us-04-annotate.md) | US-04 · Anotação de comentários | Concluída | +| [us-05-review.md](us/us-05-review.md) | US-05 · Revisão de conflitos | Concluída | +| [us-06-dashboard.md](us/us-06-dashboard.md) | US-06 · Dashboard de análise | Concluída | +| [us-07-data-catalog.md](us/us-07-data-catalog.md) | US-07 · Catálogo de dados | Concluída | -## Fluxo entre USs +## Qualidade e Segurança (`qualidade/`) -``` -US-00 (Infra) — base para todas as outras +| Arquivo | Escopo | +|---------|--------| +| [quality-security.md](qualidade/quality-security.md) | 5 fases: cobertura, OWASP, frontend, E2E, monitoramento | + +## Utilitários -US-01 (Auth) — JWT necessário em todas as outras +| Arquivo | Escopo | +|---------|--------| +| [readme-gen.md](readme-gen.md) | Geração de READMEs (raiz, backend, frontend) | + +## Fluxo entre USs -US-02 (Coleta) → US-03 (Limpeza) → US-04 (Anotação) → US-05 (Desempate) - └─────────────────────────→ US-06 (Dashboard) ``` +US-00 (Infra) — base para todas -## Papéis +US-01 (Auth) — JWT necessário em todas -| Role | Acesso | -|---------|---------------------------------------------------------------| -| `admin` | Tudo: gestão de usuários, coleta, limpeza, anotação, desempate, dashboard | -| `user` | Coleta, limpeza, anotação, dashboard | +US-02 (Coleta) → US-03 (Limpeza) → US-04 (Anotação) → US-05 (Revisão) + └──────────────────────→ US-06 (Dashboard) + US-07 (Catálogo) +``` diff --git a/.claude/skills/quality-security.md b/.claude/skills/qualidade/quality-security.md similarity index 100% rename from .claude/skills/quality-security.md rename to .claude/skills/qualidade/quality-security.md diff --git a/.claude/skills/us-00-infra.md b/.claude/skills/us/us-00-infra.md similarity index 100% rename from .claude/skills/us-00-infra.md rename to .claude/skills/us/us-00-infra.md diff --git a/.claude/skills/us-01-auth.md b/.claude/skills/us/us-01-auth.md similarity index 100% rename from .claude/skills/us-01-auth.md rename to .claude/skills/us/us-01-auth.md diff --git a/.claude/skills/us-02-collect.md b/.claude/skills/us/us-02-collect.md similarity index 100% rename from .claude/skills/us-02-collect.md rename to .claude/skills/us/us-02-collect.md diff --git a/.claude/skills/us-03-clean.md b/.claude/skills/us/us-03-clean.md similarity index 100% rename from .claude/skills/us-03-clean.md rename to .claude/skills/us/us-03-clean.md diff --git a/.claude/skills/us-04-annotate.md b/.claude/skills/us/us-04-annotate.md similarity index 100% rename from .claude/skills/us-04-annotate.md rename to .claude/skills/us/us-04-annotate.md diff --git a/.claude/skills/us-05-review.md b/.claude/skills/us/us-05-review.md similarity index 100% rename from .claude/skills/us-05-review.md rename to .claude/skills/us/us-05-review.md diff --git a/.claude/skills/us-06-dashboard.md b/.claude/skills/us/us-06-dashboard.md similarity index 100% rename from .claude/skills/us-06-dashboard.md rename to .claude/skills/us/us-06-dashboard.md diff --git a/.claude/skills/us-07-data-catalog.md b/.claude/skills/us/us-07-data-catalog.md similarity index 100% rename from .claude/skills/us-07-data-catalog.md rename to .claude/skills/us/us-07-data-catalog.md diff --git a/CLAUDE.md b/CLAUDE.md index 13eeab9..1da3420 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -224,7 +224,7 @@ Arquivo `.github/dependabot.yml` configurado para: - Canais não retornados pela YouTube API recebem epoch (1970-01-01) para evitar loop infinito - Refresh token (7 dias) no `localStorage`, access token (60min) no `sessionStorage` — interceptor transparente no `http.ts` - API keys pessoais e intransferíveis — avisos obrigatórios em CollectPage, UsersPage e CreateUserModal -- **Cards de instrução obrigatórios em páginas de US**: toda página de US deve orientar o usuário em cada etapa do fluxo — use `` no estado inicial, notice `bg-davint-50` durante processamento ativo, banner `bg-yellow-50` para estados interrompidos, CTA claro ao concluir. Ver `.claude/frontend.md` § "Cards de instrução por etapa" +- **Cards de instrução obrigatórios em páginas de US**: toda página de US deve orientar o usuário em cada etapa do fluxo — use `` no estado inicial, notice `bg-davint-50` durante processamento ativo, banner `bg-yellow-50` para estados interrompidos, CTA claro ao concluir. Ver `.claude/padroes/frontend.md` § "Cards de instrução por etapa" ## Import/Export de dados