commit aa1d925642575a3a0b08f3d7f22bd8817a37abb1 Author: camilafagundes Date: Sat Oct 3 00:36:29 2026 -0300 Implantação MVP diff --git a/.cursor/rules/elopro-gerador-contratos.mdc b/.cursor/rules/elopro-gerador-contratos.mdc new file mode 100644 index 0000000..a03fd95 --- /dev/null +++ b/.cursor/rules/elopro-gerador-contratos.mdc @@ -0,0 +1,32 @@ +--- +description: Regras obrigatórias do módulo EloPro Gerador de Contratos +globs: + - "app/**/contracts/**" + - "components/**/contracts/**" + - "lib/**/contracts/**" + - "utils/**/contracts/**" + - "**/*contract*" +alwaysApply: false +--- + +# EloPro Gerador de Contratos + +- Reuse arquitetura e helpers existentes do EloPro; não crie auth, RBAC, feature flag ou design system paralelos. +- Tenant técnico = `workspace_id`; nunca confie em workspace_id arbitrário do client. +- Feature flag = `contracts`, fail-closed. +- Auth = Supabase Auth/SSR. +- Gestão de templates = owner/admin somente. +- Gestor/agent = fluxo operacional. +- Use RLS + autorização server-side. +- Templates: .docx/.txt, até 5 MB, até 50 chaves únicas {{chave}}. +- data_* => date; valor_*/preco_* => number; demais => text. +- Todos os campos obrigatórios no MVP. +- Autosave ~15 s; draft TTL 24 h. +- 10 modelos-base ativos/workspace; versões não contam como novos modelos. +- Mesmo nome nunca sobrescreve; cria nova versão. +- Draft ativo bloqueia exclusão da versão. +- Preview e PDF devem usar o mesmo Contract Document Model. +- PDF via @react-pdf/renderer e não é repositório permanente no MVP. +- Design System EloPro V2.1 obrigatório; não usar os tokens antigos do protocolo. +- Sentry deve scrubbar conteúdo do contrato, formulário, tokens e cookies. +- Não adicionar dependências para parser/sanitização/storage sem resolver DT-CTR-001…004. diff --git a/docs/contracts/P00-discovery-audit.md b/docs/contracts/P00-discovery-audit.md new file mode 100644 index 0000000..4beaeae --- /dev/null +++ b/docs/contracts/P00-discovery-audit.md @@ -0,0 +1,185 @@ +# P00 — Discovery técnico e auditoria do módulo existente + +Data: 2026-10-02 +Escopo auditado: `c:\Users\Usuário\Documents\crm` (package `crm-2.0`, Next.js 16.0.10). +Workspace desta sessão: `gerador-contratos` (repositório Gitea vazio, sem código de produto). +Cópia irmã `Documents\CRM-2.0` existe e contém o mesmo módulo antigo de contratos, sem as migrations mais novas da calculadora. A fonte usada aqui é `crm`. + +Nenhum código de produto, banco ou UI foi alterado. + +## Achado de localização + +O Gerador de Contratos não pode nascer neste repositório. `gerador-contratos` só tem git e remote `https://gitea.fatorxtech.com/cferraz/gerador-contratos.git`. Auth, RLS, feature flag, AppShell, Sentry, Redis e Design System estão em `crm`. + +A spec e a regra do módulo proíbem arquitetura paralela. **DT-CTR-007 foi aprovado:** implementar dentro de `crm`, preservando `/dashboard/contracts`. + +## Arquitetura atual + +``` +Sidebar (lib/nav.ts, flag contracts) + | + v +app/dashboard/contracts/layout.tsx + requireFeature('contracts') --> fail-closed, redirect /dashboard + | + +-- page.tsx lista + +-- new/page.tsx ContractWizard (passos fixos) + +-- [id]/page.tsx ContractEditor + +-- actions.ts Server Actions (CRUD, PDF, deal) + | + v +Supabase Auth/SSR + getCurrentWorkspaceId() + cookie active_workspace_id validado por membership + | + v +Postgres + contracts + contract_commercial + contract_sla_items + + contract_modules + contract_clauses + + contract_sla_defaults + contract_clause_defaults + RLS: is_workspace_member (qualquer papel) + | + v +PDF @react-pdf/renderer (utils/contractPdf.tsx) + persistido no bucket privado Storage `contracts` + caminho {workspace_id}/{contract_id}.pdf + pdf_url gravado na linha + +API externa paralela (Bearer API key, service role): + POST/GET /api/v1/contracts + /api/v1/contracts/defaults + /api/v1/contracts/:id + POST /api/v1/contracts/:id/generate-pdf +``` + +Fora deste fluxo, e **não é o gerador**: + +- `calculator_contracts` (migration 156) confirma uma versão imutável de proposta da calculadora. Dono, time e hash. Não usar essas tabelas para templates. + +## Inventário + +| Caminho | Papel | Classe | +|---|---|---| +| `lib/nav.ts` | Item Contratos, flag `contracts` | REUTILIZAR | +| `utils/featureFlags.ts` | `isFeatureEnabled` / `requireFeature`, sem linha = desligado | REUTILIZAR | +| `app/dashboard/contracts/layout.tsx` | Guard da flag | REUTILIZAR | +| `utils/supabase/server.ts`, `utils/supabase/user.ts` | Auth SSR | REUTILIZAR | +| `utils/workspace.ts` | `getCurrentWorkspaceId`, `isWorkspaceAdmin`, `isWorkspaceManager`, `getManagedTeamIds` | REUTILIZAR | +| `utils/workspaceAdmin.ts` | Decisões puras de papel | REUTILIZAR | +| `migrations/038_contracts.sql` | Schema do contrato comercial Fly Apex | MANTER como legado; não é o gerador | +| `app/dashboard/contracts/actions.ts` | CRUD do contrato fixo | ADAPTAR só depois do DT-CTR-007; hoje qualquer membro edita | +| `components/Contracts/ContractWizard.tsx` | Wizard de campos fixos + hex antigo | ADAPTAR ou conviver; não é wizard de template | +| `components/Contracts/ContractEditor.tsx` | Editor de cláusulas/SLA/módulos | idem | +| `components/Contracts/DealContractsTab.tsx` | Contratos no card do deal | REUTILIZAR o gancho de deal; domínio novo é outro | +| `components/Contracts/ContractStatusBadge.tsx` | Badge de status comercial | REUTILIZAR se o status legado permanecer | +| `utils/contractPdf.tsx` | PDF do schema fixo + persistência | ADAPTAR o renderer; o modelo de documento é CRIAR | +| `app/api/v1/contracts/**` | API externa do schema antigo | MANTER para o legado; API nova só se DT-CTR-006 exigir | +| `utils/sanitize.ts` | `stripHtml` / `sanitizeText` (remove tags) | ADAPTAR; não é sanitizador HTML com allowlist | +| `utils/auditLog.ts` | Auditoria de plataforma (workspace/user/org) | ADAPTAR o padrão; eventos de contrato são CRIAR | +| `utils/rateLimit.ts`, `utils/cache.ts` | Redis/ioredis, rate limit fail-open | REUTILIZAR | +| `sentry.*.config.ts`, `instrumentation-client.ts` | Sentry, `sendDefaultPii: false`, replay em erro | ADAPTAR (falta scrub de conteúdo contratual) | +| `app/globals.css` tokens `--bc-*` | Traxion DS implementado no app | REUTILIZAR; ver conflito visual abaixo | +| `scripts/db/migrate.ts` + `migrations/*.sql` | Migrations numeradas, `npm run migrate` | REUTILIZAR | +| `.github/workflows/ci.yml` | npm ci, Node 20, tsc, build | REUTILIZAR | +| Famílias/versões de template, placeholders, drafts 24 h, Contract Document Model | inexistentes | CRIAR | + +Não há parser DOCX, upload de `.docx`/`.txt` de modelo, autosave de rascunho de formulário, nem cota de 10 modelos. + +## Schema encontrado + +Migration `038_contracts.sql`: + +- `contracts`: workspace, deal opcional, título, cliente, status `rascunho|enviado|assinado|ativo|expirado|cancelado`, `pdf_url`. +- `contract_commercial`: limites, setup, mensalidade, vencimento, pagamento. +- `contract_sla_items`, `contract_modules`, `contract_clauses`. +- `contract_sla_defaults` e `contract_clause_defaults`: seed global (`workspace_id` nulo) ou por workspace. Escrita de global exige `is_superadmin()`. +- Flag `contracts` inserida com `enabled_globally = false`. +- RLS de membro em todas as tabelas de contrato. Sem divisão owner/admin vs gestor/agent. +- Nenhuma migration posterior altera `public.contracts`. + +`calculator_contracts` é outro bounded context (proposta da calculadora). + +## Feature flag e guards + +- Flag `contracts`, default global desligado. Override por workspace vence o global (`utils/featureFlags.ts`). +- Ausência da linha retorna `false` (fail-closed). +- Layout chama `requireFeature('contracts')` e redireciona para `/dashboard`. +- Server Actions repetem `guardFeature()`. +- API v1 repete a checagem e devolve 403. +- Sidebar só mostra o item com a flag ligada. +- **Não há guard de papel** nas actions de contrato. `isWorkspaceAdmin()` não é usado em `app/dashboard/contracts`. + +Tenant: `getCurrentWorkspaceId()` lê o cookie `active_workspace_id` e confirma membership. As queries filtram `workspace_id` no servidor. A API v1 usa o workspace da API key, não um id solto do body. + +## Gaps contra o Gerador de Contratos + +| Requisito | Estado | +|---|---| +| Famílias e versões; mesmo nome cria versão; sem overwrite | Inexistente. Defaults globais são seed fixo. | +| Upload `.docx`/`.txt`, 5 MB, 50 `{{chave}}` | Inexistente. | +| Tipos `data_*` date, `valor_*`/`preco_*` number, resto text | Inexistente. Campos comerciais são colunas fixas. | +| Todos os campos obrigatórios | Wizard só exige título. | +| Máx. 10 modelos-base ativos; versões não contam | Inexistente. | +| Draft autosave ~15 s, TTL 24 h | Inexistente. Status `rascunho` é o contrato persistido. | +| Draft ativo bloqueia exclusão da versão | Delete bloqueia só status `assinado` e `ativo`. | +| Preview e PDF no mesmo Contract Document Model | PDF lê o schema relacional direto. Não há preview compartilhado. | +| PDF não é repositório permanente no MVP | O fluxo atual grava o PDF no Storage e `pdf_url`. | +| owner/admin gerenciam templates; gestor/agent operam | Qualquer membro do workspace faz CRUD. | +| Superadmin não edita documento privado no fluxo comum | Superadmin entra em `isWorkspaceAdmin` (plataforma). Defaults globais usam `is_superadmin()`. Não misturar com o fluxo operacional novo. | +| Sentry sem conteúdo contratual | `sendDefaultPii: false`. Sem `beforeSend` que raspe corpo de contrato, formulário, token ou cookie. Replay de erro está ligado no client (`replaysOnErrorSampleRate: 1`). | +| UI no Design System, sem tokens do protocolo antigo | Wizard/editor usam hex `#001A3B`, `#00478F`, `#00AEEF`. O app vivo usa `--bc-*` (Traxion). | + +Conflitos que não devem ser resolvidos em silêncio: + +1. O módulo em produção é um contrato comercial de plataforma (SLA, módulos, cláusulas markdown), ligado a deal e funil (`proposal_created` / `proposal_sent`). O gerador novo é template com placeholders. Substituir o schema atual quebra deal, API v1 e PDF armazenado. +2. A spec chama o visual de EloPro Design System V2.1. No `crm` o handoff implementado é Traxion DS, tokens `--bc-*` em `app/globals.css` e `docs/design/redesign-traxion-ds1.md`. Não há artefato nomeado V2.1 neste repo. Os hex do wizard são o visual antigo e não devem ser copiados. +3. `audit_log` da plataforma não tem ações de contrato e o `target_type` não inclui contrato. A calculadora tem `calculator_audit_log` próprio. O gerador precisa de trilha nova, no mesmo estilo, sem enfiar conteúdo do documento no `meta`. + +## Estratégia recomendada + +Não apagar o módulo atual nesta fase. + +1. Implementar o gerador **dentro de `crm`**, na flag `contracts` já existente. +2. Conviver com o contrato comercial legado até uma decisão de produto (aba, rota irmã ou substituição). Não reutilizar `contracts` / `contract_clauses` como tabela de template. +3. Criar tabelas novas de família, versão, campo, draft e auditoria do gerador, com RLS por `workspace_id` e checagem de papel no servidor (`isWorkspaceAdmin` para gestão). +4. Reusar Auth SSR, `getCurrentWorkspaceId`, feature flag, nav, Redis, `@react-pdf/renderer`, runner de migration e CI. +5. PDF novo: gerar sob demanda com o Contract Document Model e não gravar como acervo. O bucket `contracts` continua válido para o PDF legado. +6. UI nova com tokens `--bc-*` já presentes, até alguém apontar o arquivo V2.1 se ele for diferente do Traxion. + +## Decisões aprovadas em 2026-10-02 (encerram o P00) + +1. Implementar dentro de `Documents\crm`, ao lado do módulo antigo. Não substituir, migrar nem alterar o contrato comercial ligado ao deal. +2. Parser DOCX: Mammoth. Sanitização HTML: `sanitize-html` no servidor, obrigatória antes de persistir ou renderizar, preservando `{{chave}}`. Sem troca de biblioteca; Mammoth fica no Node (não no client e não no Edge). Cabeçalho, rodapé e caixa de texto seguem fora até a matriz DT-CTR-003. +3. Sem endpoint público `/api/v1` para o gerador. A API antiga permanece só no domínio legado. + +Os dez achados deste relatório continuam vinculantes. `workspace_id` não vem do browser. Tabela do módulo antigo não é reaproveitada por semelhança de nome. + +## Decision gates + +| Gate | Status | Evidência | +|---|---|---| +| DT-CTR-001 parser DOCX | RESOLVIDO | Mammoth 1.13 no `crm`. Conversão do upload fica no P03. Roda só no Node. | +| DT-CTR-002 sanitização HTML | RESOLVIDO | `sanitize-html` no servidor (`lib/gerador-contratos/sanitize.ts`), antes de persistir ou renderizar. `{{chave}}` é preservado fora de tag removida. | +| DT-CTR-003 matriz DOCX | PENDENTE | Cabeçalho, rodapé, caixa de texto e estilo não estão prometidos. | +| DT-CTR-004 Storage | RESOLVIDO POR EVIDÊNCIA | Supabase Storage. Bucket privado `contracts`, service role, URL assinada. Templates devem usar esse mecanismo; o path/bucket exato do arquivo-fonte fica para a implementação, sem trocar de produto. | +| DT-CTR-005 deploy/CI/package | RESOLVIDO POR EVIDÊNCIA | npm (`package-lock.json`), Node 20, `npm run migrate` via `postgres`+`tsx`, CI em `.github/workflows/ci.yml` (tsc + build; lint não bloqueia). | +| DT-CTR-006 API `/api/v1` | RESOLVIDO | Sem API pública nova no gerador. `/api/v1/contracts` permanece só no legado. | +| DT-CTR-007 migração de `/dashboard/contracts` | RESOLVIDO | Convive. Gerador em `/dashboard/gerador-contratos`. Contrato comercial do deal intocado. | + +## Plano P01–P12 (só depois do DT-CTR-007) + +Trabalho no repo `crm`, branch dedicada. Este repo `gerador-contratos` não recebe o app. + +1. **P01** Fundação: tipos de domínio, guards de flag e de admin, esqueleto de telas (lista, novo, modelos admin, histórico) sem parser nem PDF novo. +2. **P02** Migrations novas (próximo número após a última em `crm/migrations`), RLS por workspace e papel, índices. Não alterar o significado das tabelas da 038. +3. **P03** Upload e parser com Mammoth e `sanitizeContractHtml`. Validação 5 MB, 50 chaves, tipos por prefixo, cota de 10 bases, versão por nome. A matriz DT-CTR-003 continua em aberto. +4. **P04** Wizard operacional: escolha, revisão, formulário dinâmico, tudo obrigatório. +5. **P05** Draft autosave ~15 s, TTL 24 h. Redis só como apoio; Postgres é a fonte se o draft precisar sobreviver. Bloqueio de exclusão com draft ativo. +6. **P06** Contract Document Model único para preview e PDF. `@react-pdf/renderer`. Sem persistir o PDF novo. +7. **P07** Admin de templates, versões, exclusão protegida, auditoria sem conteúdo sensível no log. +8. **P08** Trocar hex do fluxo novo pelos tokens `--bc-*`. Não criar design system. +9. **P09** Hardening: papel no servidor, scrub Sentry (corpo, formulário, token, cookie, replay), upload, XSS, rate limit reusando `utils/rateLimit.ts`. +10. **P10** Vitest + critérios de aceite. E2E no Playwright já existente se o fluxo estiver estável. +11. **P11** Performance, WCAG AA, responsivo. +12. **P12** Rollout pela flag `contracts` (continua fail-closed, default desligada). + +P13 e P14 ficam para revisão e correção, fora deste plano de construção. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/CURSOR_MASTER_CONTEXT.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/CURSOR_MASTER_CONTEXT.md new file mode 100644 index 0000000..25373db --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/CURSOR_MASTER_CONTEXT.md @@ -0,0 +1,53 @@ +# Contexto mestre para Cursor — EloPro Gerador de Contratos + +Use este texto no início de uma sessão longa do Cursor Agent, ou converta-o em regra local do projeto se a equipe desejar. + +Você está implementando o **Gerador de Contratos** dentro do EloPro/CRO. Não é um produto isolado. + +## Prioridade das fontes + +1. Stack e decisões explícitas do projeto. +2. Documentação oficial EloPro/CRO do repositório. +3. EloPro Design System V2.1/handoff. +4. Especificação final `EloPro_Gerador_de_Contratos_Escopo_e_Especificacao_v1.0`. +5. Protocolo V3 como origem das regras de negócio já consolidadas. +6. Gerador de Propostas como referência de composição, nunca como fonte para copiar regra de negócio. + +Em conflito de arquitetura, prevalece EloPro. Em conflito visual, Design System. Em regra de negócio, prevalece a especificação final consolidada. + +## Não negociáveis + +- `workspace_id` é o tenant técnico. +- Supabase Auth/SSR; sem login próprio. +- feature flag `contracts`, fail-closed. +- RLS em Postgres + autorização server-side. +- owner/admin gerenciam templates; gestor/agent não. +- superadmin não é atalho para editar documento privado do cliente em fluxo operacional comum. +- Next.js 16 App Router, React 19, TS5, Tailwind v4. +- DS EloPro e Lucide; não inventar tokens/components globais. +- TanStack Query somente quando necessário. +- Redis é efêmero/cache/locks/rate limit, não banco primário. +- PDF via `@react-pdf/renderer`. +- preview e PDF do mesmo Contract Document Model. +- `.docx` e `.txt`, 5 MB, 50 campos únicos. +- placeholders `{{chave}}`. +- todos os campos obrigatórios no MVP. +- autosave ~15 s; draft 24 h. +- no máximo 10 modelos-base ativos por workspace. +- mesmo nome => nova versão; sem overwrite. +- template com draft ativo => delete bloqueado. +- PDF não persistido como repositório no MVP. +- Sentry sem conteúdo contratual sensível. +- IA/Claude não é requisito do MVP. + +## Modo de trabalho + +Antes de editar: +1. Leia arquivos reais relacionados. +2. Reuse padrões existentes. +3. Mostre plano curto. +4. Faça mudanças pequenas e coesas. +5. Rode testes/lint/typecheck relevantes. +6. Reporte o que mudou e o que ficou pendente. + +Nunca resolva silenciosamente um decision gate sem evidência no repo ou aprovação explícita. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/CURSOR_RULE_SUGGESTION.mdc b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/CURSOR_RULE_SUGGESTION.mdc new file mode 100644 index 0000000..a03fd95 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/CURSOR_RULE_SUGGESTION.mdc @@ -0,0 +1,32 @@ +--- +description: Regras obrigatórias do módulo EloPro Gerador de Contratos +globs: + - "app/**/contracts/**" + - "components/**/contracts/**" + - "lib/**/contracts/**" + - "utils/**/contracts/**" + - "**/*contract*" +alwaysApply: false +--- + +# EloPro Gerador de Contratos + +- Reuse arquitetura e helpers existentes do EloPro; não crie auth, RBAC, feature flag ou design system paralelos. +- Tenant técnico = `workspace_id`; nunca confie em workspace_id arbitrário do client. +- Feature flag = `contracts`, fail-closed. +- Auth = Supabase Auth/SSR. +- Gestão de templates = owner/admin somente. +- Gestor/agent = fluxo operacional. +- Use RLS + autorização server-side. +- Templates: .docx/.txt, até 5 MB, até 50 chaves únicas {{chave}}. +- data_* => date; valor_*/preco_* => number; demais => text. +- Todos os campos obrigatórios no MVP. +- Autosave ~15 s; draft TTL 24 h. +- 10 modelos-base ativos/workspace; versões não contam como novos modelos. +- Mesmo nome nunca sobrescreve; cria nova versão. +- Draft ativo bloqueia exclusão da versão. +- Preview e PDF devem usar o mesmo Contract Document Model. +- PDF via @react-pdf/renderer e não é repositório permanente no MVP. +- Design System EloPro V2.1 obrigatório; não usar os tokens antigos do protocolo. +- Sentry deve scrubbar conteúdo do contrato, formulário, tokens e cookies. +- Não adicionar dependências para parser/sanitização/storage sem resolver DT-CTR-001…004. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P00_DISCOVERY_AUDIT.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P00_DISCOVERY_AUDIT.md new file mode 100644 index 0000000..d82e703 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P00_DISCOVERY_AUDIT.md @@ -0,0 +1,71 @@ +# P00 — Discovery técnico e auditoria do módulo existente + +Você está trabalhando no repositório do **EloPro/CRO**. Antes de escrever qualquer código do Gerador de Contratos, faça uma auditoria completa do que já existe. + +## Contexto obrigatório + +A documentação oficial registra: +- rota existente `/dashboard/contracts`; +- feature flag `contracts`; +- arquitetura Next.js App Router + Supabase/Postgres; +- tenant por `workspace_id`; +- papéis reais em `workspace_members.role` (`owner`, `admin`, `gestor`, `agent`) e `profiles.is_superadmin`; +- helpers de permissão já existentes, como `isWorkspaceAdmin()`, `isWorkspaceManager()`, `getManagedTeamIds()` e equivalentes; +- superadmin usa arquitetura própria e não deve ser confundido com operações normais do workspace. + +## Objetivo + +Descobrir o estado real do módulo de contratos, impedir duplicação de arquitetura e produzir um plano de migração/reuso antes da implementação. + +## Tarefas + +1. Localize todas as ocorrências de: + - `contracts` + - `/dashboard/contracts` + - feature flag `contracts` + - tabelas/migrations relacionadas a contratos/templates/drafts + - APIs, Server Actions, componentes e hooks relacionados. +2. Mapeie: + - rotas e layouts; + - componentes server/client; + - schema atual; + - RLS/policies; + - helpers de autorização; + - feature flags e AppShell/sidebar; + - padrões de auditoria; + - padrões de Sentry; + - padrões de upload/Storage existentes; + - padrões de Server Actions vs Route Handlers; + - package manager, scripts, CI e convenções de migrations. +3. Compare o estado atual com estes requisitos do novo módulo: + - famílias e versões de templates; + - placeholders dinâmicos; + - drafts temporários; + - preview + PDF; + - auditoria; + - RBAC; + - isolamento por `workspace_id`. +4. NÃO implemente nada nesta fase. +5. Classifique cada parte encontrada como: + - REUTILIZAR + - ADAPTAR + - MIGRAR + - REMOVER/DEPRECAR + - CRIAR +6. Identifique conflitos com a especificação. Não escolha arbitrariamente. Registre-os como decisões necessárias. + +## Saída esperada + +Crie `docs/contracts/P00-discovery-audit.md` contendo: +- inventário de arquivos; +- diagrama textual da arquitetura atual; +- schema/migrations encontradas; +- feature flag e guards; +- gaps contra RF/RN/CA do Gerador de Contratos; +- estratégia recomendada de migração/reuso; +- lista dos decision gates DT-CTR-001…007 com status `RESOLVIDO POR EVIDÊNCIA`, `PENDENTE` ou `NÃO APLICÁVEL`; +- plano de execução para P01–P12. + +## Critério de conclusão + +Pare ao final da auditoria. Não altere produto, banco ou UI. Mostre um resumo com os 10 achados mais importantes e os bloqueios que precisam de decisão humana. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P01_FOUNDATION_ARCHITECTURE.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P01_FOUNDATION_ARCHITECTURE.md new file mode 100644 index 0000000..418928f --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P01_FOUNDATION_ARCHITECTURE.md @@ -0,0 +1,57 @@ +# P01 — Fundação e arquitetura do módulo + +Implemente somente a fundação do Gerador de Contratos com base no resultado aprovado do P00. + +## Regras + +- Next.js 16 App Router + React 19 + TypeScript 5. +- Não criar app separado; integrar ao AppShell EloPro. +- Rota principal deve seguir o padrão real do repo e preservar `/dashboard/contracts` quando aplicável. +- Feature flag `contracts` é obrigatória e fail-closed. +- Sessão vem de Supabase Auth/SSR; sem login próprio. +- Tenant vem do contexto autenticado/membership. Nunca confie em `workspace_id` arbitrário vindo do browser. +- Papéis: Superadmin / owner/admin / gestor / agent, reutilizando helpers existentes. +- Somente owner/admin gerenciam templates. +- Gestor e agent executam o fluxo operacional. +- Não criar novas libs ou abstrações globais sem necessidade comprovada. + +## Implementar + +1. Estrutura de pastas do módulo, separando apresentação, domínio e acesso a dados conforme padrões do repo. +2. Guard de feature flag e membership. +3. Guard server-side para gestão administrativa. +4. Navegação/entrada do módulo no AppShell conforme padrão existente. +5. Esqueleto das telas: + - Contratos + - Novo contrato + - Modelos de contrato (admin) + - Histórico (admin) +6. Tipos de domínio centrais: + - TemplateFamily + - ContractTemplate + - TemplateField + - ContractDraft + - ContractAuditEvent + - ContractDocumentModel +7. Catálogo de erros do módulo com códigos estáveis: + `TEMPLATE_INVALID_FORMAT`, `TEMPLATE_TOO_LARGE`, `TEMPLATE_NO_PLACEHOLDERS`, `TEMPLATE_TOO_MANY_FIELDS`, `TEMPLATE_LIMIT_REACHED`, `TEMPLATE_IN_USE`, `DRAFT_EXPIRED`, `DRAFT_SAVE_FAILED`, `PDF_GENERATION_FAILED`, `FEATURE_DISABLED`, `FORBIDDEN`, `RESOURCE_NOT_FOUND`. + +## Não fazer ainda + +- migrations definitivas; +- parser DOCX; +- PDF; +- autosave; +- telas finais; +- API pública v1. + +## Qualidade + +- TypeScript strict conforme repo. +- Reusar helpers do EloPro. +- Sem duplicação de auth/permissions/feature flags. +- Rodar lint/typecheck/testes mínimos disponíveis. + +## Entrega + +Ao final, relate arquivos criados/alterados, decisões herdadas do P00, riscos e o que ficou preparado para P02. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P02_DATABASE_RLS.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P02_DATABASE_RLS.md new file mode 100644 index 0000000..c2af87c --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P02_DATABASE_RLS.md @@ -0,0 +1,76 @@ +# P02 — Banco, migrations, índices e RLS + +Implemente a persistência do Gerador de Contratos usando os padrões reais de migration do EloPro. + +## Modelo alvo + +Crie/adapte estas entidades sem duplicar estruturas equivalentes já existentes: + +1. `contract_template_families` + - `id` + - `workspace_id` + - `name` + - `slug` + - `is_active` + - `created_by` + - `created_at` + +2. `contract_templates` + - `id` + - `workspace_id` + - `family_id` + - `version` + - `original_filename` + - `storage_path` ou referência equivalente aprovada no P00 + - `mime_type` + - `size_bytes` + - `checksum` + - `is_active` + - `created_by` + - `created_at` + +3. `contract_template_fields` + - `id`, `workspace_id`, `template_id`, `key`, `label`, `field_type`, `position`, `required`, `metadata` + +4. `contract_drafts` + - `id`, `workspace_id`, `user_id`, `template_id`, `values_json`, `status`, `last_saved_at`, `expires_at`, `created_at` + +5. `contract_audit_events` + - `id`, `workspace_id`, `actor_id`, `action`, `entity_type`, `entity_id`, `metadata`, `created_at` + +6. `app_connections` + - só criar se não existir estrutura equivalente no repo; caso exista, adaptar/reusar. + +## Regras obrigatórias + +- `workspace_id` em todas as entidades tenant-scoped. +- Máximo de 10 modelos-base ativos por workspace; versões da mesma família não contam como novos modelos-base. +- Versão de template é imutável após ativação, exceto estado permitido explicitamente. +- Unicidade coerente para `family_id + version`. +- Índices para listagem por workspace, família/versão, drafts por usuário/template e expiração. +- Draft expira 24 h após último save elegível. +- RLS deve ser a barreira principal, não apenas filtros da aplicação. + +## RLS mínima + +- SELECT templates: membro do workspace; fluxo operacional vê somente versões permitidas/ativas. +- INSERT/gestão templates: owner/admin. +- SELECT/UPSERT draft: próprio usuário no mesmo workspace. +- SELECT audit: owner/admin no próprio workspace; superadmin apenas via mecanismos globais já existentes. +- INSERT audit: somente caminho server/controlado; cliente não pode forjar actor/workspace. +- Nunca usar service role no fluxo normal do módulo. + +## Testes adversariais obrigatórios + +Inclua testes/SQL checks cobrindo: +- Tenant A não lê/escreve Tenant B. +- agent/gestor não cria ou exclui template. +- usuário não altera draft de outro usuário. +- actor/workspace do audit não pode ser falsificado pelo browser. + +## Entrega + +- migrations idempotentes no padrão do repo; +- documentação curta em `docs/contracts/P02-database-rls.md`; +- output dos testes de RLS; +- nenhuma API/UI além do mínimo necessário para compilar. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P03_TEMPLATES_UPLOAD_PARSER.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P03_TEMPLATES_UPLOAD_PARSER.md new file mode 100644 index 0000000..1fbd2d3 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P03_TEMPLATES_UPLOAD_PARSER.md @@ -0,0 +1,58 @@ +# P03 — Upload, validação, parsing e versionamento técnico de templates + +Implemente o pipeline de templates do MVP. + +## Regras de produto + +- Formatos MVP: `.docx` e `.txt`. +- Tamanho máximo: 5 MB. +- Placeholder: `{{chave}}`. +- Máximo: 50 chaves únicas. +- Tipos: + - prefixo `data_` => `date` + - prefixo `valor_` ou `preco_` => `number` + - demais => `text` +- Label: transformar underscore em espaço e humanizar. +- Mesma chave repetida no documento representa um único campo lógico e deve receber o mesmo valor em todas as ocorrências. +- Template sem placeholder válido deve ser rejeitado. +- Mesmo nome base não sobrescreve: deve entrar no fluxo de nova versão. +- Não editar in-place versão histórica. + +## Decision gates + +Antes de adicionar dependência: +1. Verifique P00 para DT-CTR-001 (parser DOCX) e DT-CTR-002 (sanitização). +2. Se o repo já tiver solução aprovada, reutilize. +3. Se continuarem pendentes, NÃO invente silenciosamente. Implemente a interface/adapter e registre o bloqueio exato para aprovação humana. +4. Respeite DT-CTR-003: não prometa fidelidade a recursos DOCX que a matriz aprovada não suporte. +5. Respeite DT-CTR-004 para Storage. + +## Pipeline + +Upload → validar extensão/MIME/tamanho → armazenar/ler de forma segura → extrair conteúdo → sanitizar → detectar placeholders → deduplicar chaves → preservar ordem da primeira ocorrência → inferir tipos/labels → validar limites → calcular checksum → resolver família/nova versão → persistir template + fields → auditar. + +## Segurança + +- Não confiar só na extensão. +- Não executar macros/scripts. +- Sanitizar HTML/markup antes de qualquer preview. +- Storage privado/URLs temporárias se esse for o padrão aprovado. +- Nomes de arquivo normalizados. +- Erros claros sem revelar stack trace. + +## Testes Vitest + +Cubra: +- regex/placeholders; +- chaves repetidas; +- tipos inferidos; +- label humanizado; +- 0, 1, 50 e 51 campos; +- 5 MB e acima; +- MIME/extensão inconsistente; +- mesmo nome => versão seguinte; +- checksum e não sobrescrita. + +## Entrega + +Implemente serviços puros de parsing/normalização com boa testabilidade. Não construa ainda o wizard operacional completo. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P04_USER_FLOW_WIZARD.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P04_USER_FLOW_WIZARD.md new file mode 100644 index 0000000..fd46d5f --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P04_USER_FLOW_WIZARD.md @@ -0,0 +1,54 @@ +# P04 — Fluxo operacional: seleção, review e formulário dinâmico + +Construa o fluxo principal do usuário usando o EloPro Design System e padrões reais do Gerador de Propostas. + +## Telas + +- CTR-UI-01 Contratos +- CTR-UI-02 Novo contrato — Selecionar modelo +- CTR-UI-03 Novo contrato — Revisar modelo +- CTR-UI-04 Novo contrato — Preencher informações + +## Fluxo + +Contratos → Novo contrato → listar templates ativos do workspace → selecionar um → carregar conteúdo e metadados → review read-only + campos detectados → “Preencher informações” → formulário dinâmico. + +## Regras + +- Um template por draft. +- Ordenação por nome/versão conforme especificação. +- Empty state: “Nenhum modelo disponível. Solicite ao administrador.” ou microcopy equivalente no padrão EloPro. +- Formulário respeita ordem da primeira ocorrência. +- Todos os campos obrigatórios. +- number: positivo, até 2 decimais, contexto BRL quando aplicável. +- date: controle de data acessível. +- voltar para seleção com dados preenchidos exige Dialog de confirmação quando houver risco real de perda. +- gestor/usuário não veem controles administrativos. +- feature flag e auth sempre revalidados no servidor para mutações. + +## Arquitetura frontend + +- Server Components por padrão para carga inicial quando apropriado. +- Client Components apenas para interação necessária. +- TanStack Query v5 somente onde cache/fetch client-side trouxer benefício real; não duplicar Server Components sem motivo. +- Evitar estado global novo sem necessidade. +- Lucide React para ícones. +- `@dnd-kit` NÃO é necessário neste fluxo; não use sem necessidade funcional. + +## UX + +Use componentes existentes do EloPro: Button, Card/OpenFramePanel, Input, Select, DateField, Badge/SemanticMarker, Dialog, Toast/Tooltip quando apropriado. + +Implemente estados loading, empty, error, disabled e blocked. Mensagens devem explicar o que ocorreu e qual o próximo passo. + +## Testes + +- somente templates do workspace; +- seleção única; +- review read-only; +- campos obrigatórios; +- tipos corretos; +- voltar com/sem dados; +- papéis sem acesso admin. + +Pare antes de implementar preview/PDF; isso vem em P06. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P05_DRAFTS_AUTOSAVE_RESTORE.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P05_DRAFTS_AUTOSAVE_RESTORE.md new file mode 100644 index 0000000..cab86c8 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P05_DRAFTS_AUTOSAVE_RESTORE.md @@ -0,0 +1,48 @@ +# P05 — Drafts, autosave e restauração + +Implemente a preservação de progresso do formulário. + +## Regras + +- Autosave aproximadamente a cada 15 segundos após alterações, com debounce adequado para evitar request por tecla. +- Draft identificado por `workspace_id + user_id + template_id` ou pela estratégia aprovada no P02. +- Cada draft fixa uma versão exata de template. +- TTL: 24 h desde o último save elegível. +- Ao retornar dentro do TTL: oferecer “Encontramos um progresso não salvo. Deseja restaurar?” com data/hora quando disponível. +- SIM: restaurar valores. +- NÃO: abandonar/excluir draft e iniciar limpo. +- Voltar do preview nunca apaga os valores. +- Logout/limpeza deve impedir exposição de dados via cache/histórico do app. + +## Redis + +Use Redis/ioredis apenas conforme arquitetura aprovada no P00: +- cache/coordenação/locks/TTL efêmero se necessário; +- não transforme Redis em banco primário do domínio; +- persistência mínima confiável continua em Postgres quando necessária para restauração do produto. + +## Concorrência + +- Não há edição colaborativa. +- Drafts são isolados por usuário. +- Se houver múltiplas abas, evite sobrescrita silenciosa quando possível; use `updated_at`/versionamento otimista se o padrão do repo permitir. +- Draft ativo deve bloquear exclusão da versão de template correspondente. + +## UI + +Exibir status discreto e acessível: +- Salvando… +- Salvo +- Não foi possível salvar. Seus dados continuam nesta tela. Tentar novamente / nova tentativa automática conforme padrão do repo. + +Não bloquear digitação por falha temporária de autosave. + +## Testes + +- autosave não dispara por tecla; +- salva após janela esperada; +- restaura dentro de 24 h; +- expira após TTL; +- recusa restauração remove/abandona; +- draft de outro usuário/workspace não é acessível; +- template com draft ativo fica protegido. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P06_PREVIEW_AND_PDF.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P06_PREVIEW_AND_PDF.md new file mode 100644 index 0000000..be27205 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P06_PREVIEW_AND_PDF.md @@ -0,0 +1,48 @@ +# P06 — Contract Document Model, preview, PDF e download + +Implemente o núcleo de renderização garantindo consistência entre tela e PDF. + +## Princípio obrigatório + +Não mantenha duas fontes de verdade. Crie/use um `ContractDocumentModel` intermediário derivado de: + +Template + campos detectados + valores normalizados → ContractDocumentModel → Web Preview Renderer + @react-pdf/renderer. + +## Regras + +- Nenhum `{{placeholder}}` pode permanecer no preview aprovado ou no PDF. +- Mesma chave repetida usa o mesmo valor em todas as ocorrências. +- Cláusulas fixas devem permanecer semanticamente inalteradas. +- Voltar do preview mantém 100% dos valores. +- Durante geração: botão desabilitado e feedback “Gerando seu contrato…” no tom EloPro. +- Sucesso: habilitar download. +- Meta de performance: PDF em até 5 s no cenário de referência. +- MVP não cria repositório permanente de PDFs. + +## Nome do arquivo + +`[NomeDoTemplate]_[NomeDoCliente].pdf` + +- Preferir valor de `razao_social` ou equivalente mapeado. +- Fallback: `[NomeDoTemplate]_contrato.pdf`. +- Normalizar caracteres inseguros e evitar path traversal. + +## Fidelidade + +A especificação exige equivalência de conteúdo/estrutura, não pixel-perfect entre DOM e React PDF. Documente diferenças inevitáveis de paginação/fontes dentro da matriz DOCX aprovada. + +## Segurança/privacidade + +- PDF deve ser gerado server-side ou no local apropriado do padrão do repo sem expor segredos. +- Não enviar conteúdo contratual integral ao Sentry. +- Não persistir o PDF após o ciclo necessário para download, salvo mecanismo temporário já aprovado. + +## Testes + +- placeholder residual = falha; +- cláusula fixa alterada = falha; +- valores repetidos consistentes; +- nome do arquivo normalizado; +- geração duplicada por double click impedida; +- falha de PDF retorna erro acionável e preserva dados; +- benchmark do cenário de referência. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P07_ADMIN_TEMPLATES_AUDIT.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P07_ADMIN_TEMPLATES_AUDIT.md new file mode 100644 index 0000000..3473094 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P07_ADMIN_TEMPLATES_AUDIT.md @@ -0,0 +1,54 @@ +# P07 — Administração de modelos, versões, exclusão protegida e histórico + +Implemente o fluxo administrativo, somente para owner/admin do workspace. + +## Telas + +- CTR-UI-07 Modelos de contrato +- CTR-UI-08 Subir modelo +- CTR-UI-09 Revisar campos identificados +- CTR-UI-10 Revisar e ativar modelo +- CTR-UI-11 Nova versão +- CTR-UI-12 Histórico + +## Regras + +- Máximo de 10 modelos-base ativos por workspace. +- Versões da mesma família não consomem nova cota. +- Mesmo nome base => modal confirmando nova versão; nunca sobrescrever. +- Versão nova recebe vN+1. +- Versão histórica permanece imutável. +- Versão com draft ativo não pode ser excluída. +- Exclusão é destrutiva: Dialog obrigatório com confirmação clara. +- Gestor/Usuário não podem acessar nem chamar mutações administrativas, mesmo por URL direta. +- Superadmin não deve modificar templates privados como rotina operacional; seguir mecanismos de plataforma para suporte. + +## Auditoria + +Registrar no mínimo: +- `contract.template_uploaded` +- `contract.template_version_created` +- `contract.template_delete_blocked` +- `contract.template_deleted` +- `contract.template_selected` +- `contract.draft_restored` +- `contract.previewed` +- `contract.pdf_generated` +- `contract.pdf_downloaded` +- `contract.integration_toggled` + +Cada evento deve incluir actor, workspace, timestamp, entidade e metadados mínimos. Não guardar conteúdo contratual completo no audit log. + +## Histórico + +Admin vê somente seu workspace. Use paginação/filtros conforme padrão existente. Se filtros avançados estiverem fora do MVP, implemente somente o necessário para leitura útil sem expandir escopo. + +## Testes + +- quota de 10 famílias; +- versão não aumenta quota; +- nova versão preserva anterior; +- draft ativo bloqueia delete; +- admin only; +- audit actor/workspace não falsificável; +- eventos mínimos emitidos. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P08_UX_DESIGN_SYSTEM.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P08_UX_DESIGN_SYSTEM.md new file mode 100644 index 0000000..cdbff11 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P08_UX_DESIGN_SYSTEM.md @@ -0,0 +1,57 @@ +# P08 — Conformidade UX/UI com EloPro Design System + +Faça uma revisão e implementação visual do módulo inteiro sem inventar um design system paralelo. + +## Fonte de verdade + +Use os componentes/tokens existentes do EloPro e a composição do Gerador de Propostas como referência de aplicação prática. Não copie telas cegamente; preserve a semântica específica de contratos. + +## Tokens essenciais + +- Midnight Ink `#071B45` +- Cloud White `#FBFBFE` +- Primary Blue `#1F6FFF` +- Blue 600 `#225EDB` +- Bright Blue `#2F8FFF` +- Soft Blue `#DCEBFF` +- Aqua Signal `#00C2A8` +- Warning `#F39A2D` +- Insight `#7C8CFF` +- Error `#E63946` +- Text Secondary `#69758A` +- Border `#D1D8E3` +- Fonte principal: Manrope + +Não recrie tokens antigos do protocolo (Montserrat/dark #323232/verde #004E32/lime #CCFF00). + +## Componentes preferenciais + +Button, IconButton, Card, OpenFramePanel, Input, Select, Checkbox, Radio, Switch, DateField, DateRangeField, Badge, SemanticMarker, Tag, Tabs, CapsuleTabs, ContextGroup, SectionPill, Toast, Tooltip, Dialog, JourneyTrail/ContextLayers somente quando a semântica justificar. + +## Revisar todas as telas CTR-UI-01…12 + +Para cada tela, validar: +- hierarquia visual; +- estados loading/empty/error/success/disabled/autosave/blocked; +- microcopy clara; +- foco visível; +- teclado; +- labels; +- contraste; +- responsividade; +- ações destrutivas com confirmação; +- consistência com AppShell. + +## Regras de UX + +- self-service; +- progressive disclosure; +- defaults seguros; +- feedback claro; +- preservação de progresso; +- baixo esforço cognitivo; +- nenhuma interação dependente só de cor. + +## Entrega + +Corrija divergências encontradas, sem alterar regras de negócio. Gere `docs/contracts/P08-ui-conformance.md` com checklist por tela e componentes reutilizados. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P09_SECURITY_OBSERVABILITY.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P09_SECURITY_OBSERVABILITY.md new file mode 100644 index 0000000..a8cdfe2 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P09_SECURITY_OBSERVABILITY.md @@ -0,0 +1,55 @@ +# P09 — Segurança, privacidade, observabilidade e hardening + +Faça hardening do módulo sem expandir escopo funcional. + +## Segurança obrigatória + +- RLS por `workspace_id`. +- Autorização server-side em toda mutação. +- Feature flag fail-closed. +- Proteção contra IDOR. +- Upload: tamanho/MIME/extensão, sanitização, nomes seguros. +- Preview sem XSS. +- Storage privado/URL temporária se aplicável. +- Sem service role no fluxo normal. +- Rate limit para upload/geração PDF se padrão/necessidade justificar; Redis é permitido. +- Após logout, voltar no browser não deve revelar dados anteriores. +- Sem secrets/tokens/cookies em logs. + +## Sentry + +Configurar/validar client/server/edge conforme padrão EloPro. + +Eventos técnicos relevantes: +- `template.upload.failed` +- `template.parse.failed` +- `pdf.generation.failed` +- `pdf.generation.timeout` +- `draft.save.failed` +- `tenant.access.denied` + +Aplicar scrubbing para remover: +- valores de formulário; +- conteúdo do template/contrato; +- PDF; +- tokens/cookies; +- credenciais; +- URLs assinadas sensíveis. + +Adicionar correlation/request id se o repo tiver padrão. + +## Testes adversariais + +- workspace A tenta IDs do B; +- agent chama mutação admin; +- MIME forjado; +- HTML/script malicioso; +- nome de arquivo com traversal; +- payload excessivo; +- Sentry não recebe PII/conteúdo contratual; +- feature flag desligada; +- logout + browser back. + +## Entrega + +Gere relatório `docs/contracts/P09-security-review.md` com achados, correções e riscos residuais. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P10_TESTS_ACCEPTANCE.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P10_TESTS_ACCEPTANCE.md new file mode 100644 index 0000000..4701bb8 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P10_TESTS_ACCEPTANCE.md @@ -0,0 +1,56 @@ +# P10 — Testes e critérios de aceite + +Construa a suíte de testes do módulo alinhada à especificação. + +## Unitários — Vitest + +Cobrir regras puras: +- placeholders; +- deduplicação; +- labels; +- inferência de tipos; +- validação de campos; +- quota de famílias; +- versionamento; +- nome de PDF; +- expiração de draft; +- Contract Document Model; +- normalização/sanitização onde testável. + +## Integração + +Cobrir: +- upload → parse → persistência; +- template → fields; +- draft → save/restore; +- preview → PDF; +- RBAC; +- RLS; +- audit events; +- feature flag. + +## Critérios CA-CTR obrigatórios + +- CA-CTR-001: Tenant A não acessa template/draft/audit do Tenant B. +- CA-CTR-002: PDF ≤ 5 s no cenário de referência. +- CA-CTR-003: interrupção + retorno dentro de 24 h oferece restauração. +- CA-CTR-004: upload sem tags é bloqueado. +- CA-CTR-005: logout + voltar não revela contrato anterior. +- CA-CTR-006: mesma chave repetida usa valor consistente. +- CA-CTR-007: nome existente oferece v2 e mantém v1. +- CA-CTR-008: template com draft ativo não exclui. +- CA-CTR-009: voltar do preview mantém 100% dos valores. +- CA-CTR-010: PDF sem placeholder residual e cláusulas fixas preservadas. +- CA-CTR-011: Gestor/Usuário não acessam gestão de templates. +- CA-CTR-012: feature `contracts` desligada impede acesso. + +## E2E + +Use o framework E2E já existente no repo. Se não houver, não adicione uma nova stack silenciosamente: registre a lacuna e implemente o máximo possível com o padrão aprovado. + +Fluxo mínimo E2E: +login → contracts → novo → selecionar template → review → preencher → autosave → preview → editar → gerar → baixar. + +## Saída + +Crie uma matriz `docs/contracts/P10-test-matrix.md` ligando teste → RF/RN/CA. Nenhum critério crítico pode ficar sem cobertura ou justificativa explícita. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P11_PERFORMANCE_ACCESSIBILITY.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P11_PERFORMANCE_ACCESSIBILITY.md new file mode 100644 index 0000000..19154bd --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P11_PERFORMANCE_ACCESSIBILITY.md @@ -0,0 +1,41 @@ +# P11 — Performance, acessibilidade e responsividade + +Otimize e valide o módulo sem alterar regras de negócio. + +## Metas + +- acesso ao módulo ≤ 3 s em condições de referência; +- PDF ≤ 5 s; +- autosave sem degradação de digitação; +- loading sem layout shift desnecessário. + +## Performance + +- revisar boundaries Server/Client Components; +- eliminar fetch duplicado; +- usar TanStack Query somente onde necessário; +- revisar payloads de template/preview; +- lazy load quando apropriado; +- evitar re-render excessivo do formulário dinâmico; +- medir geração de PDF; +- checar índices das queries críticas. + +## Acessibilidade — referência WCAG AA + +- foco visível; +- navegação por teclado; +- labels e descrições; +- erro associado ao campo; +- Dialog com focus trap/retorno de foco conforme componente DS; +- status de autosave com `aria-live` quando apropriado; +- loading acessível; +- nenhuma informação depende apenas de cor; +- contraste conforme DS. + +## Responsividade + +Desktop é principal, mas a UI web deve responder a larguras menores sem quebrar tarefas essenciais. Não criar app mobile nativo. + +## Entrega + +Crie `docs/contracts/P11-performance-a11y.md` com medições, gargalos, correções e pendências. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P12_RELEASE_FEATURE_FLAG.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P12_RELEASE_FEATURE_FLAG.md new file mode 100644 index 0000000..cdb252d --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P12_RELEASE_FEATURE_FLAG.md @@ -0,0 +1,45 @@ +# P12 — Homologação, rollout e release por feature flag + +Prepare o Gerador de Contratos para release controlado. + +## Antes do rollout + +1. Rodar lint, typecheck, unitários, integração e E2E existentes. +2. Validar migrations em ambiente seguro. +3. Validar RLS com usuários/tenants distintos. +4. Testar templates reais representativos da matriz DOCX aprovada. +5. Confirmar Sentry sem vazamento de conteúdo. +6. Confirmar feature flag `contracts` fail-closed. +7. Confirmar papéis: + - owner/admin: gestão + operação; + - gestor/agent: operação, sem gestão; + - superadmin: mecanismos de plataforma, sem edição operacional rotineira de documentos privados. +8. Confirmar que PDFs não estão sendo armazenados permanentemente no MVP. +9. Confirmar backup/restauração 24 h. +10. Medir metas de 3 s / 5 s no cenário acordado. + +## Rollout + +Use o mecanismo real de feature flags do EloPro. Não crie flag paralela. + +Sugestão de ordem, se compatível com a plataforma: +- workspace interno/teste; +- workspace piloto; +- pequena coorte; +- expansão gradual. + +Não habilite globalmente se CA críticos falharem. + +## Definition of Done + +Marcar cada item da seção 24 da especificação como `PASS`, `FAIL` ou `WAIVED COM JUSTIFICATIVA`. + +## Entrega + +Crie: +- `docs/contracts/P12-release-checklist.md` +- notas de rollback; +- lista de migrations; +- lista de variáveis/configurações necessárias; +- riscos residuais; +- recomendação objetiva de `READY` ou `NOT READY` baseada somente nos critérios técnicos, sem mascarar falhas. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P13_CODE_REVIEW_AUDIT.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P13_CODE_REVIEW_AUDIT.md new file mode 100644 index 0000000..9b72714 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P13_CODE_REVIEW_AUDIT.md @@ -0,0 +1,44 @@ +# P13 — Auditoria final de código independente + +Faça uma revisão crítica do Gerador de Contratos como se você NÃO tivesse escrito a implementação. + +## Não altere código no primeiro passe + +Primeiro produza achados classificados por severidade: +- P0 crítico +- P1 alto +- P2 médio +- P3 baixo + +## Revisar + +1. Tenant/RLS/IDOR. +2. RBAC real vs UI. +3. Feature flag fail-closed. +4. Imutabilidade/versionamento de templates. +5. Quota de 10 famílias. +6. Draft TTL 24 h e proteção de exclusão. +7. Consistência Contract Document Model → preview/PDF. +8. Conteúdo fixo e placeholders residuais. +9. Upload e XSS. +10. Sentry/privacidade. +11. App Router/Server Components/Actions conforme padrões do repo. +12. Uso indevido de client components/TanStack Query. +13. Design System EloPro; componentes ou tokens paralelos. +14. Acessibilidade. +15. Performance. +16. Cobertura de CA-CTR-001…012. +17. Débitos/pendências DT-CTR-001…007. +18. Duplicação com módulo `/dashboard/contracts` legado. + +## Depois da auditoria + +Apresente: +- tabela de achados com arquivo/linha quando possível; +- impacto; +- evidência; +- correção recomendada; +- risco de regressão; +- itens sem evidência suficiente. + +Somente após aprovação do relatório, aplique correções P0/P1 em uma segunda etapa. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P14_BUGFIX_REGRESSION.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P14_BUGFIX_REGRESSION.md new file mode 100644 index 0000000..2adcad5 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/P14_BUGFIX_REGRESSION.md @@ -0,0 +1,29 @@ +# P14 — Prompt reutilizável para bugfix sem regressão + +Corrija o bug descrito abaixo no módulo Gerador de Contratos sem alterar comportamentos não relacionados. + +## Bug + +[COLE AQUI O BUG, PASSOS PARA REPRODUZIR, RESULTADO ATUAL E RESULTADO ESPERADO] + +## Processo obrigatório + +1. Reproduza/identifique a causa raiz antes de alterar código. +2. Localize RF/RN/CA afetados. +3. Verifique se o problema envolve tenant, RLS, RBAC, feature flag, versionamento, draft, preview/PDF ou Design System. +4. Escreva teste de regressão que falha antes da correção, quando tecnicamente viável. +5. Faça a menor correção segura. +6. Execute testes relacionados + lint/typecheck. +7. Não adicione dependências sem necessidade e aprovação. +8. Não relaxe segurança/RLS para “fazer funcionar”. +9. Não use service role para contornar policy no fluxo normal. +10. Não envie conteúdo contratual ao Sentry. + +## Saída + +Informe: +- causa raiz; +- arquivos alterados; +- teste de regressão; +- comportamento após correção; +- riscos/efeitos colaterais verificados. diff --git a/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/README.md b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/README.md new file mode 100644 index 0000000..e511d64 --- /dev/null +++ b/docs/contracts/prompt-pack/cursor_prompt_pack_elopro_contracts/README.md @@ -0,0 +1,67 @@ +# Cursor Prompt Pack — EloPro Gerador de Contratos + +Versão: 1.0 +Base: `EloPro_Gerador_de_Contratos_Escopo_e_Especificacao_v1.0` +Objetivo: construir o módulo **Gerador de Contratos** dentro do ecossistema EloPro/CRO sem criar arquitetura, padrões visuais ou mecanismos paralelos aos já existentes. + +## Como usar + +1. Execute os prompts **na ordem** abaixo em uma branch dedicada. +2. Cole cada prompt no Cursor Agent/Composer com acesso ao repositório completo. +3. Não pule o **P00 — Discovery/Auditoria**. A documentação oficial já registra um módulo `/dashboard/contracts` protegido por feature flag `contracts`; o primeiro trabalho é descobrir o que existe e reaproveitar/migrar corretamente. +4. Em cada fase, exija que o Cursor: + - leia os arquivos reais antes de alterar código; + - apresente um plano curto; + - implemente apenas o escopo da fase; + - execute lint/testes aplicáveis; + - entregue um relatório final com arquivos alterados, decisões, pendências e riscos. +5. Não aprove automaticamente novas dependências não previstas. Para parser DOCX, sanitização, Storage, deploy/API externa e migração do módulo existente, siga os **decision gates** da especificação. + +## Ordem de execução + +- `P00_DISCOVERY_AUDIT.md` — auditoria obrigatória do módulo existente +- `P01_FOUNDATION_ARCHITECTURE.md` — fundação, feature flag, guards, estrutura de domínio +- `P02_DATABASE_RLS.md` — schema, migrations, índices e RLS +- `P03_TEMPLATES_UPLOAD_PARSER.md` — upload, validação, parsing, placeholders, famílias/versões +- `P04_USER_FLOW_WIZARD.md` — seleção, review, formulário dinâmico, validação +- `P05_DRAFTS_AUTOSAVE_RESTORE.md` — autosave 15 s, TTL 24 h, Redis/Postgres +- `P06_PREVIEW_AND_PDF.md` — Contract Document Model, preview, React PDF e download +- `P07_ADMIN_TEMPLATES_AUDIT.md` — gestão admin, versionamento, exclusão protegida, auditoria +- `P08_UX_DESIGN_SYSTEM.md` — conformidade com EloPro Design System e Gerador de Propostas +- `P09_SECURITY_OBSERVABILITY.md` — hardening, Sentry, upload seguro, XSS, rate limit +- `P10_TESTS_ACCEPTANCE.md` — Vitest + integração/E2E + critérios CA-CTR +- `P11_PERFORMANCE_ACCESSIBILITY.md` — performance, WCAG AA e responsividade +- `P12_RELEASE_FEATURE_FLAG.md` — homologação, rollout e Definition of Done +- `P13_CODE_REVIEW_AUDIT.md` — revisão final independente +- `P14_BUGFIX_REGRESSION.md` — prompt reutilizável para correções sem regressão + +## Regras imutáveis do produto + +- Tenant técnico: `workspace_id`. +- Auth: Supabase Auth/SSR; sem login próprio do módulo. +- Feature flag: `contracts`, comportamento fail-closed. +- Papéis EloPro: Superadmin, Administrador (`owner/admin`), Gestor (`gestor`), Usuário (`agent`). +- Apenas Administrador gerencia templates. +- UI deve reutilizar o **EloPro Design System V2.1**; não criar um design system paralelo. +- Stack oficial: Next.js 16 App Router, React 19, Tailwind CSS v4, Lucide React, TanStack Query v5, @react-pdf/renderer, Supabase, Redis/ioredis, Sentry, TypeScript 5, Vitest, ESLint 9, postgres+tsx. `@dnd-kit` está disponível, mas só deve ser usado quando houver necessidade funcional real. +- IA via Anthropic/Claude não é dependência do MVP. +- Templates MVP: `.docx` e `.txt`, até 5 MB, até 50 chaves únicas `{{chave}}`. +- Tipos: `data_` => date; `valor_`/`preco_` => number; demais => text. +- Todos os campos são obrigatórios no MVP. +- Draft: autosave aproximadamente a cada 15 s; TTL de 24 h após o último save elegível. +- Preview e PDF devem derivar do mesmo Contract Document Model. +- PDF final não deve persistir como repositório permanente no MVP. +- Mesmo nome de template nunca sobrescreve: cria fluxo de nova versão. +- Versão com draft ativo não pode ser excluída. +- Máximo de 10 **modelos-base ativos** por workspace; versões não consomem cota extra. +- Conteúdo contratual não deve vazar para Sentry/telemetria. + +## Decision gates que não podem ser inventados silenciosamente + +- DT-CTR-001 — parser DOCX (Mammoth.js ou equivalente JS): verificar dependências/padrão real do repo; se inexistente, registrar necessidade antes de adicionar. +- DT-CTR-002 — sanitização HTML: verificar solução existente; se inexistente, registrar decisão. +- DT-CTR-003 — matriz de recursos DOCX suportados: tabelas, imagens, headers/footers, listas, estilos etc. +- DT-CTR-004 — Storage de templates: confirmar Supabase Storage ou mecanismo existente. +- DT-CTR-005 — deploy/CI/package manager: seguir o repositório. +- DT-CTR-006 — API externa `/api/v1`: só expor se o padrão real do EloPro exigir. +- DT-CTR-007 — migração do módulo `/dashboard/contracts` existente: resolver após P00.