From 9990259477584ae14bf87fa7d9f285f230029667 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 1 Sep 2026 16:25:37 -0300 Subject: [PATCH] =?UTF-8?q?refactor:=20poda=20e=20progressao=20=E2=80=94?= =?UTF-8?q?=20/utf-design=20no=20lugar=20do=20/utf-flows,=20json-server=20?= =?UTF-8?q?->=20BaaS,=20equipe=20e=20portoes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - /utf-flows vira /utf-design: a jornada vive no prototipo navegavel (ID1); o comando fecha framework CSS, tokens, breakpoints Mobile-First, identidade PWA e os pontos de desistencia (que viram regra no prd.md). docs/user-flows.md removido; guia §3.4 reescrito ('o prototipo e a jornada') - Progressao de dados da disciplina: json-server no MVP (E2) -> BaaS na E3, na ficha, no esqueleto do architecture (a troca atinge so os Services) e no setup (db.json vazio + script; ng add @angular/pwa) - Equipe: required_approving_review_count 1 (ID27), convencao 'quem abre nao mergeia' no CONTRIBUTING; portoes atualizados (cinco no CONTRIBUTING, guia sem ordinais e com o portao do commit) - Ficha e design-tokens nos inventarios; contagens corrigidas; apps/ -> src/; MCPs recomendados (Figma, Supabase, Context7) no README (ID32) Co-Authored-By: Claude Fable 5 --- .agents/workflows/architecture.md | 4 +- .agents/workflows/backlog.md | 2 +- .agents/workflows/design.md | 69 ++++++++++++++ .agents/workflows/prd.md | 4 +- .agents/workflows/setup.md | 21 +++-- .agents/workflows/user-flows.md | 127 -------------------------- .claude/commands/utf-architecture.md | 2 +- .claude/commands/utf-design.md | 5 + .claude/commands/utf-flows.md | 5 - .cursor/commands/utf-architecture.md | 2 +- .cursor/commands/utf-design.md | 5 + .cursor/commands/utf-flows.md | 5 - .cursor/commands/utf-prd.md | 2 +- .opencode/command/utf-architecture.md | 2 +- .opencode/command/utf-design.md | 5 + .opencode/command/utf-flows.md | 5 - .opencode/command/utf-prd.md | 2 +- CONTRIBUTING.md | 5 +- README.md | 9 +- docs/architecture.md | 18 ++-- docs/checklist.md | 13 ++- docs/design-tokens.md | 4 +- docs/guia-sdd.md | 125 ++++--------------------- docs/tutorial-sdd.md | 4 +- docs/user-flows.md | 45 --------- 25 files changed, 157 insertions(+), 333 deletions(-) create mode 100644 .agents/workflows/design.md delete mode 100644 .agents/workflows/user-flows.md create mode 100644 .claude/commands/utf-design.md delete mode 100644 .claude/commands/utf-flows.md create mode 100644 .cursor/commands/utf-design.md delete mode 100644 .cursor/commands/utf-flows.md create mode 100644 .opencode/command/utf-design.md delete mode 100644 .opencode/command/utf-flows.md delete mode 100644 docs/user-flows.md diff --git a/.agents/workflows/architecture.md b/.agents/workflows/architecture.md index 1209ca6..e015835 100644 --- a/.agents/workflows/architecture.md +++ b/.agents/workflows/architecture.md @@ -1,5 +1,5 @@ --- -description: Conduz a entrevista que produz o docs/architecture.md a partir do prd.md — stack, estrutura do monorepo, testes, glossário técnico, diagrama ER e os padrões estruturais cobrados pelos IDs. Garante as quatro declarações que o /utf-setup exige. Roda depois do /utf-prd e do /utf-flows. +description: Conduz a entrevista que produz o docs/architecture.md a partir do prd.md — stack, estrutura do projeto, testes, glossário técnico, diagrama ER e os padrões estruturais cobrados pelos IDs. Garante as quatro declarações que o /utf-setup exige. Roda depois do /utf-prd e do /utf-design. --- # Gerar o architecture.md @@ -15,7 +15,7 @@ Você é o entrevistador técnico. O aluno é o Arquiteto: **ele decide; você a ## Passo 0 — Pré-condições -0. `docs/user-flows.md` tem pelo menos uma jornada desenhada, com o parágrafo de decisão sobre o nó vermelho. Se não tiver, **PARE** e mande rodar `/utf-flows`: é lá que aparecem os estados que faltam ("o pedido fica AGUARDANDO para sempre?"), e estado esquecido aqui vira retrabalho na primeira spec. +0. `docs/design-tokens.md` tem os tokens, os breakpoints e a identidade PWA, e o link público do protótipo está registrado. Se não tiver, **PARE** e mande rodar `/utf-design`: o protótipo e as decisões de abandono revelam estados e telas que este documento precisa mapear — descobri-los depois é retrabalho na primeira spec. 1. `docs/prd.md` existe, com glossário, atores e stories. Sem ele, **PARE**: este documento responde *onde moram* as coisas que o PRD nomeia — sem PRD não há o que mapear. Mande rodar `/utf-prd` antes. 2. Leia `docs/checklist.md` **inteiro** — a seção *Regras da disciplina* diz o que é stack fixa e o que é escolha do aluno, e vários IDs são padrões estruturais que este documento precisa declarar. diff --git a/.agents/workflows/backlog.md b/.agents/workflows/backlog.md index 5a50aaa..b1e125f 100644 --- a/.agents/workflows/backlog.md +++ b/.agents/workflows/backlog.md @@ -53,7 +53,7 @@ fazer isso; se não conseguir, não é erro — siga com a orientação manual. ## Passo 4 — Entrega Relate: Issues criadas (número e título), stories puladas (e por quê), e o -estado do Kanban. Lembre o fluxo: se `/utf-flows`, `/utf-architecture` e `/utf-setup` ainda +estado do Kanban. Lembre o fluxo: se `/utf-design`, `/utf-architecture` e `/utf-setup` ainda não rodaram, eles vêm antes; então a implementação de cada Issue começa por `/utf-issue `, **uma por vez**, começando pelos `Must Have`. diff --git a/.agents/workflows/design.md b/.agents/workflows/design.md new file mode 100644 index 0000000..f4ea12c --- /dev/null +++ b/.agents/workflows/design.md @@ -0,0 +1,69 @@ +--- +description: Conduz as decisões de design da Fase 0 — framework CSS, Design System (docs/design-tokens.md), protótipo navegável (Stitch/Figma), Mobile-First e identidade PWA. A jornada vive no protótipo; aqui ela vira decisão registrada. Roda depois do /utf-prd e antes do /utf-architecture. +--- + +# Design: tokens, protótipo e identidade + +Você conduz as decisões visuais do projeto. O aluno decide; você pergunta, organiza +e escreve. **Nesta disciplina a jornada do usuário vive no protótipo navegável** +(Stitch/Figma — ID1), não num documento: o que se documenta aqui é o que o protótipo +não consegue guardar — os tokens, os breakpoints e as decisões de abandono. + +## Regras da conversa + +- **Uma pergunta por vez.** Espere a resposta antes da próxima. +- **Proibido implementação.** Nada de componente, service ou rota — isso é do + `/utf-architecture` em diante. Aqui é aparência, identidade e comportamento visual. +- Decisão sem dono não existe: cada escolha registrada é da equipe, e alguém da + equipe vai explicá-la na apresentação. + +## Passo 0 — Pré-condições + +1. `docs/prd.md` preenchido, com stories e critérios. Sem ele, **PARE** e mande + rodar `/utf-prd` — design sem requisito é decoração. +2. Se `docs/design-tokens.md` já tem conteúdo real, **PARE** e pergunte: revisar ou + recomeçar? + +## Passo 1 — Framework CSS e Design System (IDs 1 e 5) + +1. **Framework CSS** — apresente as opções que a ficha permite (ex.: Tailwind, + PrimeNG), com o custo de cada uma. A escolha é única para o semestre. +2. **Tokens** — grave em `docs/design-tokens.md`: paleta (com os papéis: primária, + superfície, erro…), escala de espaçamento, tipografia, estados de botão. Não é + design system completo — é o mínimo para a IA não inventar um botão por tela. +3. **Protótipo** — registre o **link público** do Stitch/Figma no + `docs/design-tokens.md` e no README. O protótipo é a jornada navegável: telas + das stories principais, no fluxo real. + +## Passo 2 — Mobile-First (ID2) + +Pergunte e registre nos tokens: os **breakpoints** e a regra de layout — o design +nasce para a menor tela e cresce. Toda tela do protótipo tem versão mobile antes da +versão desktop. + +## Passo 3 — Identidade PWA (ID3) + +Decida e registre (os valores alimentam o `manifest.webmanifest` no setup): nome +curto do app, cores de tema e de fundo, ícone, modo de exibição (standalone) e o +**comportamento visual offline** — o que a pessoa vê sem rede. + +## Passo 4 — O ponto de desistência + +Para cada story crítica do PRD (na dúvida, a mais central do tema), **uma** pergunta: +*"onde a pessoa desiste nesse fluxo, e o que fazemos a respeito?"*. A resposta não +vira documento novo — vira **regra de negócio ou critério de aceite no `prd.md`** +(registre lá, com o OK do aluno). O caminho ruim precisa aparecer antes de virar spec. + +## Passo 5 — Portão + +1. Grave `docs/design-tokens.md` completo (tokens + breakpoints + identidade PWA + + link do protótipo). +2. **PARE.** A equipe revisa fora do chat; o commit é dela. Próximo passo: + `/utf-architecture`. + +## Proibições + +- Gerar CSS, componente ou código de qualquer tipo — aqui nascem decisões, não telas. +- Inventar valores de marca (cores, nomes) sem o aluno escolher. +- Criar documento de jornadas separado — a jornada vive no protótipo, e a decisão de + abandono vive no `prd.md`. diff --git a/.agents/workflows/prd.md b/.agents/workflows/prd.md index df92b4b..b5ab4b5 100644 --- a/.agents/workflows/prd.md +++ b/.agents/workflows/prd.md @@ -1,5 +1,5 @@ --- -description: Conduz a entrevista que produz o docs/prd.md — tema, glossário, atores, user stories com critérios verificáveis, regras de negócio, fora de escopo e NFRs. Uma pergunta por vez; o aluno decide, o agente escreve. Roda antes do /utf-flows e do /utf-architecture. +description: Conduz a entrevista que produz o docs/prd.md — tema, glossário, atores, user stories com critérios verificáveis, regras de negócio, fora de escopo e NFRs. Uma pergunta por vez; o aluno decide, o agente escreve. Roda antes do /utf-design e do /utf-architecture. --- # Gerar o PRD @@ -48,7 +48,7 @@ Percorra o `docs/checklist.md` e confira o rascunho contra **todo ID cuja sement 1. Grave `docs/prd.md` completo. 2. **PARE.** O aluno lê o documento inteiro, fora do chat. Ajuste agora custa uma conversa; depois, custa uma spec. -3. O commit do `prd.md` é **dele**. Próximos passos, nesta ordem: com o **aceite do professor** e stories `Ready`, `/utf-backlog` leva as stories para o GitHub (Issues + Kanban); depois `/utf-flows`, que desenha as jornadas e acha os pontos de desistência; e só então `/utf-architecture`. +3. O commit do `prd.md` é **dele**. Próximos passos, nesta ordem: com o **aceite do professor** e stories `Ready`, `/utf-backlog` leva as stories para o GitHub (Issues + Kanban); depois `/utf-design`, que fecha tokens, protótipo e os pontos de desistência; e só então `/utf-architecture`. ## Proibições diff --git a/.agents/workflows/setup.md b/.agents/workflows/setup.md index ac68fcf..4f6149c 100644 --- a/.agents/workflows/setup.md +++ b/.agents/workflows/setup.md @@ -71,9 +71,15 @@ dentro da estrutura de pastas que o documento descreve. Sem isso, um repositório tocado em Windows e Linux reescreve todos os arquivos a cada troca de máquina, e o diff de qualquer PR vira ruído. -3. `package.json` da raiz com os scripts de orquestração descritos no - `architecture.md` (ex.: `start`, `api`, `test`). Se o documento traz os scripts - prontos, copie-os literalmente. +3. `package.json` com os scripts descritos no `architecture.md` (ex.: `start`, + `api`, `test`). Se o documento traz os scripts prontos, copie-os literalmente. + Dois casos desta disciplina: + - **json-server declarado para o MVP:** adicione a dependência, o script + (`"api": "json-server db.json"` ou equivalente) e um `db.json` **vazio de + negócio** (`{}`) — as entidades chegam pelas histórias, nunca pelo setup. + - **PWA declarado:** rode `ng add @angular/pwa` e preencha o + `manifest.webmanifest` com a identidade decidida no `/utf-design` + (nome curto, cores, ícones) — sem inventar valores. ## Passo 4 — As ferramentas do método @@ -103,7 +109,7 @@ do guia é exatamente como o Portão nasce parafraseado e sem efeito. { "required_status_checks": null, "enforce_admins": true, - "required_pull_request_reviews": { "required_approving_review_count": 0 }, + "required_pull_request_reviews": { "required_approving_review_count": 1 }, "restrictions": null, "allow_force_pushes": false, "allow_deletions": false @@ -111,9 +117,10 @@ do guia é exatamente como o Portão nasce parafraseado e sem efeito. JSON ``` - `required_approving_review_count: 0` exige **Pull Request** para entrar na - `main`, sem exigir aprovação de terceiro — funciona igual para quem faz - sozinho e para dupla. `enforce_admins: true` faz a regra valer também para o + `required_approving_review_count: 1` exige **Pull Request aprovado por um + colega** — nesta disciplina o projeto é em equipe (2–3), e a revisão entre + colegas com resolução de conflitos é cobrada pelo ID27: quem abre a story + não mergeia o próprio PR. `enforce_admins: true` faz a regra valer também para o dono do repositório: sem isso, o aluno é justamente quem fura a regra sem perceber. Para destravar uma emergência ele desliga a proteção conscientemente, e isso fica registrado no log do repositório. diff --git a/.agents/workflows/user-flows.md b/.agents/workflows/user-flows.md deleted file mode 100644 index 75ca635..0000000 --- a/.agents/workflows/user-flows.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -description: Conduz o desenho das jornadas de usuário (docs/user-flows.md) e dos tokens de design (docs/design-tokens.md) a partir do prd.md. Obriga pelo menos uma jornada com ponto de desistência declarado. Roda depois do /utf-prd e antes do /utf-architecture. ---- - -# Gerar as jornadas e os tokens - -Você conduz o desenho do **caminho que a pessoa percorre na tela** — e, principalmente, -dos pontos onde ela trava, espera ou desiste. O aluno decide; você pergunta, desenha e -escreve. - -Este fluxo existe porque **o caminho feliz é óbvio e os caminhos ruins não são**. Teste -automatizado não cobre esse buraco: o aluno escreve teste para o que imaginou, e o -problema é justamente o que ele não imaginou. A jornada é o único artefato da Fase 0 -que força o "e se der errado" a aparecer **antes** de virar spec. - -Ele roda **antes do `/utf-architecture`** de propósito: um nó vermelho quase sempre -revela um estado que faltava (*"o pedido fica AGUARDANDO para sempre?"*), e estado é -matéria do `architecture.md`. Desenhar depois é descobrir o estado com o documento já -fechado. - -## Regras da conversa - -- **Uma pergunta por vez.** Espere a resposta antes da próxima. -- **Proibido tecnologia.** Nada de endpoint, tabela ou componente: jornada é o que a - pessoa vive, não como o sistema atende. -- Uma jornada bem feita vale mais que três superficiais. **Não produza volume.** - -## Passo 0 — Pré-condições - -1. `docs/prd.md` preenchido, com stories e critérios de aceite. Sem ele, **PARE** e - mande rodar `/utf-prd` — jornada sem história é desenho decorativo. -2. Se `docs/user-flows.md` já tem jornada real (não é esqueleto), **PARE** e pergunte: - acrescentar uma nova ou revisar a existente? - -## Passo 1 — Escolher a história que merece jornada - -Nem todo fluxo precisa de diagrama: um CRUD de listagem não precisa de nenhum. -Percorra as stories do `docs/prd.md` e marque quais batem em cada um dos quatro -critérios: - -| # | Critério | Exemplo | -| --- | --- | --- | -| 1 | **Sai do site e volta** | checkout, login social, confirmação por e-mail | -| 2 | **Depende do tempo** | algo pode demorar, expirar ou chegar fora de ordem | -| 3 | **Depende de outra pessoa agir** | uma aprovação, uma moderação, um parceiro aceitar | -| 4 | **Pode ser abandonado no meio** | formulário longo, cadastro em etapas | - -Apresente a tabela ao aluno com as marcações e **peça que ele escolha**. Quanto mais -critérios uma história marca, mais ela merece o desenho — pagamento marca os quatro, e -é por isso que é o exemplo canônico. - -**Pelo menos uma jornada é obrigatória.** Se nenhuma story marcar critério nenhum, -não invente: desenhe a mais crítica do projeto e registre, no documento, que ela não -marca os quatro — isso é informação honesta, não falha. - -## Passo 2 — Desenhar - -Três convenções, e só três: - -- **Losango** — decisão do sistema (validação, guard, verificação de estado) -- **Retângulo com `«pessoa»`** — ação de quem está na tela -- **Nó vermelho** — onde a pessoa some - -Mermaid `flowchart TD`, versionado no repositório. Diagrama em imagem colada -desatualiza em silêncio; o do repo muda no mesmo commit do comportamento. - -```mermaid -flowchart TD - A(["Escolheu o produto"]) --> B{"Está logado?"} - B -->|"não"| C["/login"] --> D - B -->|"sim"| D["«pessoa» confirma o pedido"] - D --> E["API cria o Pedido
status AGUARDANDO"] - E --> F(["Checkout do gateway
fora do site"]) - F --> G{"O que aconteceu?"} - G -->|"pagou"| H["Volta para /pagamento/sucesso"] - G -->|"fechou a aba"| X1[["Some — e o pedido fica
AGUARDANDO para sempre?"]] - H --> I{"Status real do pedido"} - I -->|"webhook confirmou"| J(["PAGO"]) - I -->|"ainda não chegou"| K["«pessoa» vê 'processando'
e acompanha no painel"] - - style X1 fill:#ffe0e0,stroke:#c62828 -``` - -**Toda jornada precisa de pelo menos um nó vermelho.** Jornada sem ponto de -desistência é caminho feliz redesenhado — se você não achou nenhum, você não procurou. -Pergunte ao aluno, nesta ordem: o que acontece se ele fechar a aba aqui? se a conexão -cair? se a sessão expirar no meio? se a resposta do outro sistema nunca chegar? - -## Passo 3 — O parágrafo que vale a nota - -Abaixo de cada diagrama, **um parágrafo** dizendo o que foi decidido a respeito do nó -vermelho. É esse parágrafo que transforma o desenho em decisão de projeto, e é ele que -o professor vai pedir para o aluno explicar na defesa. - -O texto é **do aluno**. Você pergunta *"e aí, o que o sistema faz nesse caso?"* e -organiza a resposta dele. Se ele não souber, isso não vira invenção sua: vira uma linha -em **Dúvidas em aberto**, e o `/utf-architecture` a resolve. - -## Passo 4 — Tokens de design - -Não se espera design system: o que resolve o problema real — a IA inventando um botão -diferente a cada tela — é bem menor. Grave em `docs/design-tokens.md`: - -1. **Paleta** — as cores, com nome semântico (`primaria`, `perigo`, `superficie`, - `texto`), não `azul-2`. Inclua os estados de erro e de desabilitado. -2. **Escala de espaçamento** — uma progressão só (ex.: 4, 8, 16, 24, 32). -3. **Tipografia** — família, tamanhos e pesos, com o papel de cada um. -4. **Estados de botão** — normal, hover, foco, desabilitado, carregando. - -Pergunte também pelo link do protótipo (Figma, Stitch ou equivalente) com **3 a 5 -telas** das jornadas principais, e registre-o no documento. Se ainda não existir, -registre como pendência — não invente cor nem link. - -## Passo 5 — Portão - -1. Grave `docs/user-flows.md` e `docs/design-tokens.md`. -2. **PARE.** O aluno lê fora do chat. O commit é dele. -3. Próximo passo: `/utf-architecture` — que vai ler as jornadas para encontrar os - estados e os pontos de decisão que o `architecture.md` precisa declarar. - -## Proibições - -- Desenhar jornada de story que não existe no `docs/prd.md`. -- Entregar diagrama **sem** nó vermelho, ou nó vermelho **sem** o parágrafo do Passo 3. -- Escrever o parágrafo de decisão no lugar do aluno. -- Falar de endpoint, tabela, componente ou biblioteca — é `/utf-architecture`. -- Inventar cor, fonte ou link de protótipo que o aluno não deu. diff --git a/.claude/commands/utf-architecture.md b/.claude/commands/utf-architecture.md index f91e01f..821a298 100644 --- a/.claude/commands/utf-architecture.md +++ b/.claude/commands/utf-architecture.md @@ -1,5 +1,5 @@ --- -description: Gera o docs/architecture.md por entrevista guiada a partir do prd.md — stack, monorepo, testes, glossário técnico, diagrama ER e os padrões cobrados pelos IDs. Garante o que o /utf-setup exige. Roda depois do /utf-prd. +description: Gera o docs/architecture.md por entrevista guiada a partir do prd.md — stack, projeto, testes, glossário técnico, diagrama ER e os padrões cobrados pelos IDs. Garante o que o /utf-setup exige. Roda depois do /utf-prd. --- Leia `.agents/workflows/architecture.md` e execute-o integralmente. diff --git a/.claude/commands/utf-design.md b/.claude/commands/utf-design.md new file mode 100644 index 0000000..173db2e --- /dev/null +++ b/.claude/commands/utf-design.md @@ -0,0 +1,5 @@ +--- +description: Conduz as decisões de design da Fase 0 — framework CSS, tokens (docs/design-tokens.md), protótipo navegável, Mobile-First e identidade PWA. Roda depois do /utf-prd e antes do /utf-architecture. +--- + +Leia `.agents/workflows/design.md` e execute-o integralmente. diff --git a/.claude/commands/utf-flows.md b/.claude/commands/utf-flows.md deleted file mode 100644 index e52f095..0000000 --- a/.claude/commands/utf-flows.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Desenha as jornadas de usuário (docs/user-flows.md) e os tokens de design (docs/design-tokens.md) a partir do prd.md. Obriga pelo menos uma jornada com ponto de desistência. Roda antes do /utf-architecture. ---- - -Leia `.agents/workflows/user-flows.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-architecture.md b/.cursor/commands/utf-architecture.md index 34de834..c0a1f36 100644 --- a/.cursor/commands/utf-architecture.md +++ b/.cursor/commands/utf-architecture.md @@ -1,5 +1,5 @@ --- -description: Gera o docs/architecture.md por entrevista guiada — stack, monorepo, testes, glossário técnico e diagrama ER. Roda depois do /utf-flows. +description: Gera o docs/architecture.md por entrevista guiada — stack, projeto, testes, glossário técnico e diagrama ER. Roda depois do /utf-design. --- Leia `.agents/workflows/architecture.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-design.md b/.cursor/commands/utf-design.md new file mode 100644 index 0000000..173db2e --- /dev/null +++ b/.cursor/commands/utf-design.md @@ -0,0 +1,5 @@ +--- +description: Conduz as decisões de design da Fase 0 — framework CSS, tokens (docs/design-tokens.md), protótipo navegável, Mobile-First e identidade PWA. Roda depois do /utf-prd e antes do /utf-architecture. +--- + +Leia `.agents/workflows/design.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-flows.md b/.cursor/commands/utf-flows.md deleted file mode 100644 index d6535ab..0000000 --- a/.cursor/commands/utf-flows.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Desenha as jornadas de usuário e os tokens de design. Obriga pelo menos uma jornada com ponto de desistência. Roda antes do /utf-architecture. ---- - -Leia `.agents/workflows/user-flows.md` e execute-o integralmente. diff --git a/.cursor/commands/utf-prd.md b/.cursor/commands/utf-prd.md index f1bd539..779bd62 100644 --- a/.cursor/commands/utf-prd.md +++ b/.cursor/commands/utf-prd.md @@ -1,5 +1,5 @@ --- -description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories, regras de negócio e NFRs. Roda antes do /utf-flows. +description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories, regras de negócio e NFRs. Roda antes do /utf-design. --- Leia `.agents/workflows/prd.md` e execute-o integralmente. diff --git a/.opencode/command/utf-architecture.md b/.opencode/command/utf-architecture.md index 34de834..c0a1f36 100644 --- a/.opencode/command/utf-architecture.md +++ b/.opencode/command/utf-architecture.md @@ -1,5 +1,5 @@ --- -description: Gera o docs/architecture.md por entrevista guiada — stack, monorepo, testes, glossário técnico e diagrama ER. Roda depois do /utf-flows. +description: Gera o docs/architecture.md por entrevista guiada — stack, projeto, testes, glossário técnico e diagrama ER. Roda depois do /utf-design. --- Leia `.agents/workflows/architecture.md` e execute-o integralmente. diff --git a/.opencode/command/utf-design.md b/.opencode/command/utf-design.md new file mode 100644 index 0000000..173db2e --- /dev/null +++ b/.opencode/command/utf-design.md @@ -0,0 +1,5 @@ +--- +description: Conduz as decisões de design da Fase 0 — framework CSS, tokens (docs/design-tokens.md), protótipo navegável, Mobile-First e identidade PWA. Roda depois do /utf-prd e antes do /utf-architecture. +--- + +Leia `.agents/workflows/design.md` e execute-o integralmente. diff --git a/.opencode/command/utf-flows.md b/.opencode/command/utf-flows.md deleted file mode 100644 index d6535ab..0000000 --- a/.opencode/command/utf-flows.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Desenha as jornadas de usuário e os tokens de design. Obriga pelo menos uma jornada com ponto de desistência. Roda antes do /utf-architecture. ---- - -Leia `.agents/workflows/user-flows.md` e execute-o integralmente. diff --git a/.opencode/command/utf-prd.md b/.opencode/command/utf-prd.md index f1bd539..779bd62 100644 --- a/.opencode/command/utf-prd.md +++ b/.opencode/command/utf-prd.md @@ -1,5 +1,5 @@ --- -description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories, regras de negócio e NFRs. Roda antes do /utf-flows. +description: Gera o docs/prd.md por entrevista guiada — tema, glossário, atores, user stories, regras de negócio e NFRs. Roda antes do /utf-design. --- Leia `.agents/workflows/prd.md` e execute-o integralmente. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3223f3f..c0bea89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,7 @@ Você é o Engenheiro e o Arquiteto; a IA é a sua equipe de execução. - **Trabalho:** Crie uma feature branch curta **a partir da `develop`** para cada Issue. - **Integração:** Ao finalizar, abra um Pull Request **para a `develop`** com `Closes #`. O CI (testes + lint) precisa passar antes do merge. - **Release:** quando a `develop` está estável, um PR de `develop` → `main` publica a versão (é o que o deploy em produção acompanha). +- **Em equipe (ID27):** todo PR precisa da aprovação de **um colega** antes do merge — quem abre a story não mergeia o próprio PR. Os portões da história (spec, triagem, commit) são do **dono da história**; a revisão do PR é do colega. --- @@ -32,8 +33,8 @@ Nada é duplicado neste projeto. Informação repetida diverge. | **Vitrine** | `README.md` na raiz | O que é o projeto e como rodar. | | **Produto** | `docs/prd.md` | O que o sistema faz (Glossário, Atores, Histórias). | | **Arquitetura** | `docs/architecture.md` | Onde as coisas estão (estrutura, entidades, contratos). | -| **Jornadas** | `docs/user-flows.md` | O caminho do usuário e onde ele desiste. | | **Ficha** | `docs/checklist.md` | As regras da disciplina, os IDs e as entregas — a régua dos workflows. | +| **Design** | `docs/design-tokens.md` | Tokens, breakpoints, identidade PWA e o link do protótipo navegável. | | **Especificação** | `specs/-/` | O `spec.md` (o que fazer), o `plan.md` (tarefas técnicas) e `reviews/` (pareceres e triagem). | | **Leis da IA** | `.agents/` | `rules/utf-rules.md` (constituição, carregada via `CLAUDE.md`), `workflows/` (ciclos) e `agents/` (prompts dos subagentes). | @@ -52,7 +53,7 @@ O que é **norma inegociável** deste repositório são os cinco portões humano 2. **🚪 Explicação do tutor:** cada tarefa só é implementada depois do seu "pode implementar" — dúvida agora custa cinco minutos; depois do diff, custa uma rodada. 3. **🚪 Triagem:** só você aceita ou recusa apontamentos de revisão (recusa exige justificativa, registrada em `specs/-/reviews/tarefa-NN-decisoes-rN.md`). 4. **🚪 Commit:** revisores aprovarem não basta — o orquestrador apresenta o diff e os pareceres e só commita com o seu "pode commitar". -5. **🚪 Pull Request:** só você escreve a explicação, com as suas palavras, listando os apontamentos aceitos e recusados. +5. **🚪 Pull Request:** só você escreve a explicação, com as suas palavras, listando os apontamentos aceitos e recusados — e um **colega** aprova antes do merge. --- diff --git a/README.md b/README.md index 956ab5d..37188a5 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ apresentação final. | --- | --- | --- | | Requisitos | `/utf-prd` | `docs/prd.md` — o QUE o produto faz | | Backlog | `/utf-backlog` | Issues no GitHub + Kanban no Projects | -| Jornadas e tokens | `/utf-flows` | `docs/user-flows.md` e `docs/design-tokens.md` — o que a pessoa vive na tela | +| Design | `/utf-design` | `docs/design-tokens.md` + protótipo navegável — tokens, Mobile-First e identidade PWA | | Arquitetura | `/utf-architecture` | `docs/architecture.md` — onde as coisas moram | | Scaffold | `/utf-setup` | o app Angular, nascendo verde | | Cada história | `/utf-issue ` → `/utf-task` | spec, plano e código, tarefa a tarefa | @@ -65,8 +65,9 @@ o porquê de cada regra, em [`docs/guia-sdd.md`](docs/guia-sdd.md). Pré-requisitos das integrações: **`gh` autenticado (`gh auth login`, escopos `repo`, `workflow` e `project`) ou MCP do GitHub** — sem isso, backlog, etiquetas -e PRs não saem. Com MCP Context7 disponível, os fluxos conferem versões de -ferramentas na documentação atual antes de decidir. +e PRs não saem. **MCPs recomendados** (ID32 — configure na sua IDE): **Figma** +(o protótipo vira contexto do agente), **Supabase** (na E3) e **Context7** +(versões atuais de ferramentas antes de decidir). --- @@ -96,7 +97,7 @@ erDiagram - **Frontend:** Angular [versão] - **Framework CSS:** [Tailwind, PrimeNG, …] -- **BaaS:** [Supabase, PocketBase, …] +- **Dados:** json-server (MVP/E2) → [Supabase, PocketBase, …] (E3) - **Bibliotecas:** [lista] ## Em produção diff --git a/docs/architecture.md b/docs/architecture.md index ee82270..29b63c1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -45,17 +45,18 @@ fonte de estado, `model()` para two-way, `effect()` para efeitos colaterais, `input()`/`output()`, `inject()`, Pipes para formatação. - **Framework CSS:** [Tailwind, PrimeNG, …] (ID5) -- **BaaS:** [Supabase, PocketBase, …] — dados, autenticação (JWT) e CRUD (IDs 21–22) +- **Dados (em duas fases):** **json-server** no MVP (E2) → **[Supabase, PocketBase, …]** na E3, com autenticação (JWT) e CRUD reais (IDs 21–22). A troca atinge só os Services (§2.1). - **PWA:** `manifest.webmanifest` — ícones, cores de tema, splash, standalone, offline (ID3) - **Testes:** [ferramenta do gerador] + comandos exatos de suíte e lint (ID33) -### 🌐 2.1. Integração com o BaaS — regras estruturais +### 🌐 2.1. Camada de dados — regras estruturais > Declaradas uma a uma na entrevista, percorrendo os IDs da ficha. -- **Componente não fala com o servidor:** todo acesso ao BaaS passa por +- **Componente não fala com o servidor:** todo acesso a dados passa por **Services** injetados via `inject()` (ID15) — mudança de contrato mexe só - neles, nunca nas telas. + neles, nunca nas telas. **É esta regra que paga a migração da E3:** trocar o + json-server pelo BaaS reescreve os Services, e nenhuma tela. - **Autenticação e sessão (JWT):** [fluxo com o serviço de identidade do BaaS — ID21] - **Interceptors funcionais:** token injetado globalmente + tratamento centralizado de erros (ID23). @@ -73,7 +74,7 @@ ├── .agents/ # constituição, workflows e prompts dos agentes (§1) ├── CLAUDE.md / AGENTS.md # cascas por ferramenta (.claude/, .cursor/, .opencode/) ├── README.md # a vitrine, na estrutura exigida pela ficha -├── docs/ # prd.md, este arquivo, user-flows.md, design-tokens.md, checklist.md e guias +├── docs/ # prd.md, este arquivo, design-tokens.md, checklist.md e guias ├── specs/ # uma pasta por história implementada └── src/ # o app Angular ([preencher no /utf-setup]) ``` @@ -122,10 +123,11 @@ erDiagram > design — a segurança vem das regras de acesso do BaaS, ex.: RLS no Supabase); > **service keys e segredos nunca entram no repositório**. -| Ambiente | App roda em | BaaS | +| Fase | App roda em | Dados | | :--- | :--- | :--- | -| **Local** | `ng serve` | [projeto de dev] | -| **Produção** | [Vercel/Render] | [projeto de produção] | +| **Local (E2/MVP)** | `ng serve` | json-server (`db.json` local) | +| **Local (E3)** | `ng serve` | [BaaS — projeto de dev] | +| **Produção (E3)** | [Vercel/Render] | [BaaS — projeto de produção] | --- diff --git a/docs/checklist.md b/docs/checklist.md index e75ccbb..d1b6de0 100644 --- a/docs/checklist.md +++ b/docs/checklist.md @@ -23,9 +23,12 @@ - **Stack fixa:** **Angular 20+** — arquitetura **standalone** (sem NgModules), **Signals** para estado, sintaxe moderna (`@if`/`@for`/`@switch`/`@defer`, `input()`/`output()`/`model()`, `inject()`). -- **Sem backend próprio:** dados, autenticação (JWT) e CRUD via **BaaS** - (ex.: Supabase, PocketBase) — a escolha é da equipe, registrada no - documento técnico. +- **Sem backend próprio — e em duas fases:** no MVP (Entrega 2) os dados vêm + de um **json-server** (API fake local); na Entrega 3 a aplicação troca para + um **BaaS** (ex.: Supabase, PocketBase) com autenticação (JWT) e CRUD reais. + A escolha do BaaS é da equipe, registrada no documento técnico — e a troca + deve atingir **só os Services**: planeje a camada de dados para isso desde o + início (é a regra "componente não fala com o servidor" valendo dinheiro). - **Framework CSS moderno** à escolha (ex.: Tailwind CSS, PrimeNG), com **Design System** próprio da equipe (tokens em `docs/design-tokens.md`). - **UI/UX:** protótipo navegável (Stitch/Figma) com link público no @@ -110,8 +113,8 @@ | Entrega | O quê | Data | | --- | --- | --- | | **E1 — Concepção e Planejamento** | Escopo da equipe sobre o tema do semestre, repositório com Gitflow, README com o checklist, Design System, framework CSS, protótipo navegável no Figma | **20 de setembro** | -| **E2 — Estrutura Funcional (MVP)** | Aplicação com a estrutura funcional mínima, alimentada pelas atividades semanais | **25 de outubro** | -| **E3 — Aplicação Completa e Apresentação** | App completo em produção (Vercel/Render) + **vídeo** apresentando inspiração, design system, protótipo e o projeto contra o checklist | **06 de dezembro** | +| **E2 — Estrutura Funcional (MVP)** | Aplicação com a estrutura funcional mínima, consumindo dados do **json-server** | **25 de outubro** | +| **E3 — Aplicação Completa e Apresentação** | Dados e autenticação migrados para o **BaaS** (ex.: Supabase), app completo em produção (Vercel/Render) + **vídeo** apresentando inspiração, design system, protótipo e o projeto contra o checklist | **06 de dezembro** | > 🎥 Se o vídeo for insuficiente, a apresentação é síncrona ao Professor > (presencial ou remota). O detalhamento de cada entrega está no Guia do diff --git a/docs/design-tokens.md b/docs/design-tokens.md index 785e617..10c4045 100644 --- a/docs/design-tokens.md +++ b/docs/design-tokens.md @@ -1,14 +1,14 @@ # 🎨 Tokens de Design **Projeto:** [nome] -**Versão:** 0.0.0 · esqueleto — preencha via `/utf-flows` +**Versão:** 0.0.0 · esqueleto — preencha via `/utf-design` **Última atualização:** [data] > 🤖 **Este documento existe para a IA parar de inventar um botão diferente a cada > tela.** Não é um design system — é o mínimo que dá à prototipagem assistida algo a > que obedecer. > -> ✍️ **Não preencha na mão:** rode `/utf-flows`. +> ✍️ **Não preencha na mão:** rode `/utf-design`. --- diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index fbd1792..e0815d4 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -60,7 +60,7 @@ por isso que existe o `docs/architecture.md`: para escrever, uma vez, quais são ## 2. Os artefatos -Todo trabalho gira em torno de doze artefatos. Eles são a matéria-prima da sua nota. +Todo trabalho gira em torno de onze artefatos. Eles são a matéria-prima da sua nota. | Artefato | Onde fica | Para que serve | | --- | --- | --- | @@ -68,19 +68,18 @@ Todo trabalho gira em torno de doze artefatos. Eles são a matéria-prima da sua | **`prd.md`** | `docs/` | O que o produto faz: glossário, atores, histórias. | | **`architecture.md`** | `docs/` | Onde as coisas estão: estrutura, entidades, estados, contratos. | | **`checklist.md`** | `docs/` | A ficha da disciplina: regras do projeto, IDs e entregas — a régua dos workflows. | -| **`user-flows.md`** | `docs/` | O que a pessoa vive na tela, e onde ela desiste. | | **`design-tokens.md`** | `docs/` | Cores, espaçamento, tipografia — para a IA não inventar um botão por tela. | | **Issue** | GitHub Projects | A unidade de trabalho. Uma história de usuário. | | **`spec.md`** | `specs/-/` | O que precisa existir e como saber que ficou pronto. | | **`plan.md`** | `specs/-/` | Como será construído, em tarefas pequenas. | | **Pareceres de revisão** | `specs/-/reviews/` | O que cada revisor apontou, sem edição. É a prova de que a revisão aconteceu. | -| **Código** | `apps/api`, `apps/web` | O que a IA escreve seguindo o plano. | +| **Código** | `src/` | O que a IA escreve seguindo o plano. | | **Pull Request** | GitHub | Onde você explica, com suas palavras, o que foi feito. | -Desses doze itens, a IA produz sozinha apenas **o código, o plano e os pareceres**. +Desses onze itens, a IA produz sozinha apenas **o código, o plano e os pareceres**. A ficha vem pronta com o template; todo o resto precisa da sua direção. -E existe um décimo-terceiro, que é um índice e não um artefato: o `specs/README.md`, +E existe um décimo-segundo, que é um índice e não um artefato: o `specs/README.md`, descrito no fim do §4. --- @@ -98,9 +97,9 @@ fecha: | --- | --- | --- | --- | | 1 | Requisitos (`docs/prd.md`) | `/utf-prd` | Você lê, ajusta e **commita**; o professor aceita o tema | | 2 | Backlog (Issues + Kanban no Projects) | `/utf-backlog` | Você aprova a lista de Issues **antes** de elas serem criadas | -| 3 | Jornadas e tokens (`docs/user-flows.md`, `docs/design-tokens.md`) | `/utf-flows` | Você decide o que acontece em cada ponto de desistência e **commita** | +| 3 | Design (`docs/design-tokens.md` + protótipo navegável) | `/utf-design` | Você fecha tokens, Mobile-First e identidade PWA, decide os pontos de desistência (→ PRD) e **commita** | | 4 | Arquitetura (`docs/architecture.md`) | `/utf-architecture` | Você lê e **commita** | -| 5 | Scaffold (`apps/`, verde) | `/utf-setup` | Ratificações + o primeiro PR (`manutencao`) | +| 5 | Scaffold (o app Angular, verde) | `/utf-setup` | Ratificações + o primeiro PR (`manutencao`) | A etapa 3 vem **antes** da arquitetura de propósito: um nó vermelho quase sempre revela um estado que faltava (*"o pedido fica AGUARDANDO para sempre?"*), e estado é matéria do @@ -177,8 +176,8 @@ Contém: - **Stack tecnológica e ambiente.** Os frameworks e paradigmas. *Declare a tecnologia aqui, mas deixe a versão exata do ambiente viver no `.tool-versions` e as bibliotecas no `package.json`.* -- **Estrutura do monorepo.** Que pasta guarda o quê — `apps/api` em NestJS, - `apps/web` no framework que você escolheu. +- **Estrutura do projeto.** Que pasta guarda o quê dentro do app Angular — + `core/`, `shared/`, `features/` — e a regra de dependência entre elas. - **Diagrama de contexto (opcional).** Quem é o front, quem é o back, banco e integrações externas. Trata o seu sistema como caixa preta e ilustra quem o usa e com que sistemas externos ele conversa (Google OAuth, gateway de pagamento, sistema @@ -225,101 +224,15 @@ direto e a outra metade não. cada história. Colocar aqui polui o documento e estoura a janela de contexto da IA à toa. -### 3.4 `docs/user-flows.md` — o que a pessoa vive na tela +### 3.4 O protótipo é a jornada -**O que é:** o desenho do caminho que o usuário percorre, do primeiro clique até o -objetivo — **incluindo os pontos onde ele trava, espera ou desiste**. - -#### Por que isso não aparece sozinho - -Em todo fluxo, **o caminho feliz é óbvio e os caminhos ruins não são**. E os testes -automatizados não salvam: você escreve teste para o que imaginou, e o problema é -justamente o que não imaginou. - -Cinco situações que acontecem de verdade em projetos como o seu: - -**O Pix que demora.** Você testa com cartão, que aprova na hora, e está tudo certo. Na -apresentação, alguém paga com Pix. O usuário volta ao site e vê "aguardando -pagamento", espera cinco segundos, acha que falhou e **paga de novo**. Agora há dois -pagamentos para um pedido. - -**O cadastro que prende o usuário.** Cadastro em duas etapas: informa o e-mail, recebe -o link, completa o perfil. A pessoa fecha o navegador antes de confirmar. Uma semana -depois tenta se cadastrar: "e-mail já cadastrado". Tenta entrar: "usuário não -confirmado". Ela está presa, e não existe nenhum botão na tela que a tire dali. - -**A sessão que expira no formulário longo.** O usuário preenche vinte campos durante -quinze minutos, clica em salvar, o token já expirou, a API devolve 401, o interceptor -manda para o login — e **o formulário inteiro se perde**. A pergunta que a jornada -força: a sessão é verificada ao abrir o formulário ou só ao enviar? - -**A regra que só aparece no fim.** O usuário escolhe o serviço, preenche tudo, e só ao -enviar o servidor responde "você precisa ter um item cadastrado antes". A checagem -tinha que estar na porta, não na saída. - -**O login que perde o contexto.** A pessoa está navegando anônima, encontra um item, -clica em "favoritar", é mandada ao login, entra — e cai na home. Perdeu o que estava -fazendo e provavelmente desiste. - -#### Quando vale a pena escrever a jornada - -Não é para todo fluxo. Um CRUD de listagem não precisa de diagrama nenhum. **Vale -escrever quando o fluxo tem pelo menos uma destas quatro características:** - -1. **Sai do seu site e volta** — checkout, login social, confirmação por e-mail -2. **Depende do tempo** — algo pode demorar, expirar ou chegar fora de ordem -3. **Depende de outra pessoa agir** — uma aprovação, uma moderação, um parceiro aceitar -4. **Pode ser abandonado no meio** — formulário longo, cadastro em etapas - -Repare que o **pagamento marca as quatro ao mesmo tempo**. É por isso que ele é o -exemplo canônico. - -#### O que se exige nesta disciplina - -**Pelo menos uma jornada**, da história que você julgar mais crítica no seu projeto. -Se estiver em dúvida sobre qual escolher, use a **jornada de pagamento** — todo projeto -tem uma, e ela marca os quatro critérios. - -Uma jornada bem feita vale mais que três superficiais. O objetivo aqui é aprender a -enxergar o caminho ruim, não produzir documentação por volume. - -#### Como desenhar - -Três convenções, só: - -- **Losango** — decisão do sistema (validação, guard, verificação de estado) -- **Retângulo com `«pessoa»`** — ação de quem está na tela -- **Nó vermelho** — onde a pessoa some - -```mermaid -flowchart TD - A(["Escolheu o produto"]) --> B{"Está logado?"} - B -->|"não"| C["/login"] --> D - B -->|"sim"| D["«pessoa» confirma o pedido"] - D --> E["API cria o Pedido
status AGUARDANDO"] - E --> F(["Checkout do gateway
fora do site"]) - F --> G{"O que aconteceu?"} - G -->|"pagou"| H["Volta para /pagamento/sucesso"] - G -->|"fechou a aba"| X1[["Some — e o pedido fica
AGUARDANDO para sempre?"]] - H --> I{"Status real do pedido"} - I -->|"webhook confirmou"| J(["PAGO"]) - I -->|"ainda não chegou"| K["«pessoa» vê 'processando'
e acompanha no painel"] - - style X1 fill:#ffe0e0,stroke:#c62828 -``` - -Abaixo do diagrama, escreva **um parágrafo** dizendo o que você fez a respeito do nó -vermelho. Esse parágrafo é o que transforma o desenho em decisão de projeto — e é o que -o professor vai pedir para você explicar na defesa. - -Desenhe a jornada **antes** de implementar. Olhe para o nó vermelho: é ele que responde -as duas perguntas que quebram a maioria das integrações de pagamento — o que acontece -quando o usuário fecha a aba, e quem realmente decide que o pedido foi pago. - -> ⚠️ **A jornada só vira software se virar critério de aceite.** O nó vermelho que você -> desenhou aqui precisa reaparecer, mais tarde, como uma linha verificável no `spec.md` -> da história correspondente. Se ele ficar só no diagrama, ninguém escreve teste para -> ele e ele volta no dia da apresentação. Veja o Passo 2 do §4. +Nesta disciplina não existe documento de jornadas: **o protótipo navegável +(Stitch/Figma) é a jornada** — clicável, tela a tela, exigido pelo ID1. O que o +protótipo não guarda são as **decisões**: onde a pessoa trava, espera ou desiste, e o +que o sistema faz a respeito. Essas decisões o `/utf-design` pergunta uma a uma, e a +resposta vira **regra de negócio ou critério de aceite no `prd.md`** — nunca um +documento novo. Desenho bonito sem decisão registrada é decoração; é a decisão que o +professor pede para explicar na apresentação. ### 3.5 Tokens de design e protótipo @@ -333,7 +246,7 @@ problema real, que é a IA inventar um botão diferente a cada tela, é bem meno Com isso no repositório, a prototipagem assistida por IA tem a que obedecer. Sem isso, cada tela nasce de um gosto diferente. -Os dois artefatos desta seção e da anterior saem do mesmo comando, o `/utf-flows`. +Os tokens, os breakpoints, a identidade PWA e o link do protótipo saem do mesmo comando, o `/utf-design`. ### 3.6 A regra de ouro dos documentos @@ -348,8 +261,8 @@ confiar. | `README.md` | **como rodar** — instalação, execução, link em produção | | `docs/prd.md` | **o que o produto faz** — histórias, critérios e o que já está pronto | | `docs/architecture.md` | **onde as coisas estão** — estrutura, entidades, contratos, estados | -| `docs/user-flows.md` | **o que a pessoa vive** — jornadas e pontos de desistência | -| `docs/design-tokens.md` | **como o produto se parece** — paleta, espaçamento, tipografia | +| `docs/design-tokens.md` | **como o produto se parece** — tokens, breakpoints, identidade PWA, protótipo | +| `docs/checklist.md` | **o que a disciplina exige** — regras, IDs e entregas | | `docs/checklist.md` | **o que a disciplina exige** — regras, IDs e entregas | | `specs/` | **o que está sendo construído agora** — uma pasta por história | diff --git a/docs/tutorial-sdd.md b/docs/tutorial-sdd.md index aff4ebb..1c6e1d2 100644 --- a/docs/tutorial-sdd.md +++ b/docs/tutorial-sdd.md @@ -20,7 +20,7 @@ Quatro comandos, nesta ordem, cada um fechando num portão seu: | --- | --- | --- | --- | | 1 | `/utf-prd` | `docs/prd.md` — entrevista de requisitos | Lê o documento inteiro, ajusta e **commita**; leva o tema ao professor | | 2 | `/utf-backlog` | Issues (uma por story `Ready`) + Kanban no Projects | **Aprova a lista** antes de as Issues serem criadas | -| 3 | `/utf-flows` | `docs/user-flows.md` e `docs/design-tokens.md` — jornadas e tokens | Decide o que acontece em cada ponto de desistência e **commita** | +| 3 | `/utf-design` | `docs/design-tokens.md` + protótipo navegável — tokens, Mobile-First, identidade PWA | Decide o que acontece em cada ponto de desistência (vai para o PRD) e **commita** | | 4 | `/utf-architecture` | `docs/architecture.md` — entrevista técnica | Lê e **commita** | | 5 | `/utf-setup` | o app Angular nascendo com testes verdes | Ratifica as decisões relatadas e abre o **1º PR** (`manutencao`) | @@ -111,7 +111,7 @@ palavras, lista os apontamentos aceitos e recusados (saem dos arquivos | --- | --- | | `/utf-prd` | Fase 0, etapa 1 — a entrevista que gera o `docs/prd.md` | | `/utf-backlog` | Fase 0, etapa 2 — PRD aprovado vira Issues + Kanban (e roda de novo a cada leva de stories `Ready`) | -| `/utf-flows` | Fase 0, etapa 3 — desenha as jornadas e os tokens de design | +| `/utf-design` | Fase 0, etapa 3 — framework CSS, tokens, protótipo, Mobile-First e PWA | | `/utf-architecture` | Fase 0, etapa 4 — a entrevista que gera o `docs/architecture.md` | | `/utf-setup` | Fase 0, etapa 5 — gera o scaffold do projeto | | `/utf-issue ` | Uma vez, para iniciar o ciclo da Issue (spec → plano) | diff --git a/docs/user-flows.md b/docs/user-flows.md deleted file mode 100644 index 172cfbb..0000000 --- a/docs/user-flows.md +++ /dev/null @@ -1,45 +0,0 @@ -# 🗺️ Jornadas de Usuário - -**Projeto:** [nome] -**Versão:** 0.0.0 · esqueleto — preencha via `/utf-flows` -**Última atualização:** [data] - -> 🤖 **Este documento é a fonte da verdade sobre O QUE A PESSOA VIVE na tela** — -> o caminho do primeiro clique até o objetivo, e principalmente os pontos onde ela -> trava, espera ou desiste. -> -> ✍️ **Não preencha na mão:** rode `/utf-flows`. A entrevista escolhe a história que -> merece o desenho, obriga o ponto de desistência a aparecer e cobra a decisão sobre -> ele. -> -> 🚫 **Não duplique:** regra de negócio mora no `prd.md`; estado, entidade e contrato -> moram no `architecture.md`. Aqui mora o caminho. - ---- - -## Jornada 1 — [nome da história] - -**Story:** USnn -**Critérios que ela marca:** [sai do site e volta · depende do tempo · depende de outra pessoa · pode ser abandonada] - -```mermaid -flowchart TD - A(["início"]) --> B{"decisão do sistema"} - B -->|"sim"| C["«pessoa» faz algo"] - B -->|"não"| X1[["Some — e daí?"]] - - style X1 fill:#ffe0e0,stroke:#c62828 -``` - -**O que decidimos sobre o nó vermelho:** - -[Um parágrafo, com as palavras do aluno. O que o sistema faz quando a pessoa some ali? -É este parágrafo que transforma o desenho em decisão de projeto — e é ele que o -professor pede para explicar na defesa.] - ---- - -## Dúvidas em aberto - -| # | Dúvida | Onde ela precisa ser resolvida | -| --- | --- | --- |