Instruction file imported from ClevertonCodev/fisioweb (
.cursor/rules/specify-rules.mdc). Copyright stays with the author.
Fisioweb — Spec Kit Context
Spec-Driven Development ativo. Regras de projeto em CLAUDE.md / AGENTS.md, skills em .claude/skills/ e .cursor/skills/ (ambas canônicas) e mapa em .cursor/rules/fisioweb-skills.mdc.
| Arquivo | Conteúdo |
|---|---|
CLAUDE.md / AGENTS.md |
Overview, stack, comandos, princípios não-negociáveis |
.cursor/rules/fisioweb-skills.mdc |
Skill map — consultar antes de implementar |
.claude/skills/ e .cursor/skills/ |
Skills detalhadas (mesmo conteúdo; atualizar as duas; bash bin/verificar-skills.sh) |
.specify/memory/constitution.md |
Princípios Spec Kit (local; template se ainda não ratificado) |
specs/_shared/ |
Artefatos compartilhados entre features (ex.: UI patterns) |
specs/*/ |
Spec, plan, tasks e contratos da feature ativa |
Comandos SDD
| Skill | Quando usar |
|---|---|
/speckit-constitution |
Atualizar princípios do projeto |
/speckit-specify |
Definir feature (o quê/por quê) |
/speckit-clarify |
Esclarecer ambiguidades na spec |
/speckit-checklist |
Validar qualidade da spec |
/speckit-plan |
Plano técnico fisioweb |
/speckit-tasks |
Tarefas acionáveis com paths |
/speckit-analyze |
Auditar consistência spec/plan/tasks |
/speckit-implement |
Implementar tarefas do tasks.md |
/speckit-agent-context-update |
Atualizar bloco SPECKIT neste arquivo com plano ativo |
Referência completa: .cursor/spec-kit-comandos.md
Skills — consultar sempre (conforme escopo)
Leia o SKILL.md relevante antes de codar. Cursor: .cursor/skills/<nome>/. Claude Code: .claude/skills/<nome>/. Ambas canônicas — mantenha iguais (bash bin/verificar-skills.sh).
Backend
| Tarefa | Skill |
|---|---|
| Fronteira entre módulos, CRUD no módulo, contrato público, eventos, ADR | architecture-paradigm-modular-monolith |
| Eloquent (Model, scopes, casts, observers, transações) | laravel-eloquent |
| Job async (WhatsApp, PDF, R2, e-mail) | laravel-queues |
| Enum, DTO readonly, Value Object, match | php-modern |
| Testes PHPUnit + Mockery | php-testing |
Frontend
| Tarefa | Skill |
|---|---|
| DDD (domain → application → infra → page → route) | frontend-ddd |
| Hooks, performance, React 19 | frontend-react |
| Testes Vitest + RTL | frontend-testing |
| Componentes, cores, sidebar, popover, cursor (telas v1) | frontend-ui-patterns |
Telas v2: design system @/components/ds (tokens --ds-*, dark mode) |
design-system |
| DataTable, Forms RHF+Zod, Dialog (telas v1) | forms-shadcn |
| apiClient, Repository, JWT multi-guard | api-client |
Cross-cutting
| Tarefa | Skill |
|---|---|
| Policies + permissions.ts + RequireClinicAdmin | security |
Regras inegociáveis (resumo)
- Multi-tenant: todo acesso filtrado por
clinic_id; global scopes (BelongsToClinic) nos models de clínica. - Monólito modular: backend em
modules/*(Admin, Clinic, Patient, Media, Pdf, Xlsx, Cloudflare, GoogleCalendar, WhatsApp) — não emapp/Modules. Não injetar Model/Repository interno de outro módulo. - Backend é fonte de verdade: autorização (Policies + middleware), validação de domínio e regras críticas no Laravel; frontend só esconde para UX.
- Camadas frontend: loader →
application/; página nunca importaapiClient; mapeamento snake_case ↔ camelCase só eminfrastructure/. - HTTP só via
apiClient: guards JWT inferidos pela URL (/admin/*→ admin,/clinic/*→ clinic). domain/puro: camelCase, sem_at, semApiXxx, sem WriteDto, sem constantes de UI.- Form com 2+ campos → RHF + Zod (não copiar pages legadas com
useState). - UI: telas v1 com tokens Tailwind/shadcn,
AdminLayout/ClinicLayout, cursor pointer em clicáveis — verfrontend-ui-patternsespecs/_shared/frontend-ui-patterns.md. Telas v2 usam@/components/ds— verdesign-system; nunca as duas bibliotecas na mesma tela. - PHP: Laravel Pint; sem
declare(strict_types=1)por convenção atual; Controller → Service → Repository → Model; null comis_null()/!is_null(); string vazia comempty()/!empty().
Stack
PHP 8.2+ · Laravel 12 · Eloquent · JWT multi-guard (admin + clinic) · MySQL/PostgreSQL · Laravel Queues · Cloudflare R2 · DomPDF · React 19 + TypeScript strict · Vite · TanStack Query v5 · react-router-dom v6 · RHF + Zod · shadcn/ui + Tailwind · Vitest 4 + RTL
Estrutura (alto nível)
modules/ # backend modular (ownership por módulo)
resources/js/
├── domain/ # entidades puras (camelCase)
├── application/ # hooks React Query + ports + use-cases
├── infrastructure/ # apiClient + repositories + mappers
├── pages/{admin,clinic}/ # EntityListPage / NewPage / EditPage
├── components/{ui,admin,clinic}/
└── routes/ # RouteObject[] por contexto
Path alias: @ → resources/js/
Comandos shell
composer run dev # Laravel + queue + Pail + Vite
composer run test # PHPUnit (backend)
npm run test # Vitest (frontend)
npm run build && npm run types && npm run lint
./vendor/bin/pint # PHP formatterTeste filtrado: vendor/bin/phpunit --filter=NomeDoTest
Plano ativo
Feature atual: specs/014-program-pdf-download/
| Artefato | Path |
|---|---|
| Spec | specs/014-program-pdf-download/spec.md |
| Plan | specs/014-program-pdf-download/plan.md |
| Research | specs/014-program-pdf-download/research.md |
| Data model | specs/014-program-pdf-download/data-model.md |
| Quickstart | specs/014-program-pdf-download/quickstart.md |
| Contracts | specs/014-program-pdf-download/contracts/ |
| Tasks | specs/014-program-pdf-download/tasks.md (gerar com /speckit-tasks) |
| Checklist | specs/014-program-pdf-download/checklists/requirements.md |
Antes de implementar: leia plan.md + tasks.md da feature ativa e a skill correspondente ao escopo.
