From 2746b0f3963606db93b624efd8aecd0bb5f461b5 Mon Sep 17 00:00:00 2001 From: Kelvinmilagres Date: Fri, 26 Jun 2026 00:08:41 -0300 Subject: [PATCH 1/6] adding folders --- ai-usage/design_thinking_prompts.md | 0 discovery/design_thinking.md | 45 +++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 ai-usage/design_thinking_prompts.md create mode 100644 discovery/design_thinking.md diff --git a/ai-usage/design_thinking_prompts.md b/ai-usage/design_thinking_prompts.md new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/discovery/design_thinking.md b/discovery/design_thinking.md new file mode 100644 index 000000000000..74a74b5b2613 --- /dev/null +++ b/discovery/design_thinking.md @@ -0,0 +1,45 @@ +# Design Thinking com IA + +Este documento apresenta as personas e o mapa de empatia. + +## 1. Personas +### Persona 1: Lucas Rocha (O Desenvolvedor Iniciante) +* **Perfil:** Estudante de Sistemas de Informação, 21 anos, usuário de Linux (Ubuntu). +* **Comportamento:** Muito ativo em comunidades de tecnologia no Discord, prefere utilizar ferramentas via linha de comando (CLI) e busca fazer sua primeira contribuição em um projeto open-source para melhorar o currículo. +* **Frustrações/Dores:** Sente que o processo de setup inicial e a documentação do repositório são confusos. Perdeu mais de duas horas tentando rodar o projeto localmente devido a dependências desatualizadas e erros de ambiente não documentados no `README.md`. +* **Objetivos/Ganhos:** Encontrar um guia claro "passo a passo" ou uma automação (como um container Docker ou script de ambiente) que permita configurar o projeto em menos de 10 minutos, dando segurança para codificar. + +### Persona 2: Mariana Souza (A Analista de Suporte) +* **Perfil:** Analista de Suporte Técnico, 33 anos, focada em agilidade e cumprimento de prazos. +* **Comportamento:** Pragmática, utiliza o sistema diariamente em ambiente de produção para resolver problemas de clientes sob pressão. Não busca customizar o código, precisa apenas que a ferramenta funcione sem surpresas. +* **Frustrações/Dores:** O sistema gera logs de erro extremamente genéricos no terminal quando algo falha. Quando um processo trava, ela não consegue identificar rapidamente se o problema é de rede, permissão ou um bug interno, atrasando o atendimento. +* **Objetivos/Ganhos:** Obter um formato de logs de erro mais descritivo, limpo e estruturado, facilitando o diagnóstico rápido de falhas sem a necessidade de abrir o código-fonte para entender o problema. + +--- + +## 2. Mapa de Empatia (Persona Principal: Mariana Souza) + +| O que ela Pensa e Sente? | O que ela Vê? | +| :--- | :--- | +| * "Preciso resolver os chamados dos clientes rápido."
* Frustração com a falta de clareza do sistema.
* Insegurança ao tentar adivinhar a causa de um erro. | * Logs extensos e poluídos no terminal.
* Clientes cobrando soluções rápidas.
* Issues antigas no GitHub discutindo erros parecidos. | +| **O que ela Ouve?** | **O que ela Fala e Faz?** | +| * Os clientes reclamando da demora no suporte.
* A gerência cobrando agilidade nas métricas.
* Colegas dizendo que o sistema é "caixa preta". | * Reclama que os logs atuais não ajudam em nada.
* Abre o terminal e tenta reiniciar o sistema do zero.
* Documenta manualmente os erros que consegue decifrar. | +| **Dores (Frustrações)** | **Ganhos (Necessidades/Desejos)** | +| * Perda de tempo decifrando mensagens genéricas.
* Estresse com a pressão do tempo de atendimento.
* Dependência de desenvolvedores seniores para bugs simples. | * Diagnóstico visual imediato do problema através do log.
* Maior autonomia no trabalho diário de suporte.
* Redução do tempo de resolução de chamados (SLA). | + +--- + +## 3. Ideias de Solução Exploradas + +* **Ideia 1:** Criar um painel visual (Dashboard) para monitoramento de erros em tempo real. +* **Ideia 2:** Padronizar e reestruturar as saídas de erro do sistema de forma semântica (Ex: `[ERRO: BANCO_DE_DADOS] Falha de conexão na porta 5432`) acompanhadas de possíveis ações de correção (Foco selecionado para o MVP). + +# 3.3 Design Thinking com IA + +Este documento apresenta os resultados da fase de Discovery obtidos através da colaboração com Inteligência Artificial, conforme os requisitos de transparência e criticidade estabelecidos[cite: 1]. + +## 4. Reflexão Crítica + +O uso da inteligência artificial foi fundamental para acelerar o processo criativo e estruturar o mapeamento psicográfico das personas de forma rápida. O modelo foi capaz de simular com precisão dores reais de profissionais de suporte que lidam com ferramentas open-source. + +No entanto, exercemos a decisão humana final ao filtrar alucinações do modelo. A IA sugeriu inicialmente dores voltadas a interfaces mobile e relatórios em PDF, recursos que não condizem com a proposta puramente técnica via CLI do software analisado. Nós removemos esses excessos e refinamos os textos manualmente para garantir que o mapa de empatia estivesse perfeitamente conectado às issues e limitações reais encontradas no repositório do projeto. \ No newline at end of file From cd00728b68672c802ac29ee5afc1aca33b4df06f Mon Sep 17 00:00:00 2001 From: Kelvinmilagres Date: Thu, 9 Jul 2026 00:56:36 -0300 Subject: [PATCH 2/6] adding documentation --- documentacao/backlog.md | 13 +++++ documentacao/cenarios_de_teste | 51 +++++++++++++++++++ documentacao/definicao_do_mvp | 12 +++++ .../design_thinking.md | 20 +++++++- documentacao/priorizacao_mvp | 18 +++++++ documentacao/uso_de_ia | 34 +++++++++++++ 6 files changed, 146 insertions(+), 2 deletions(-) create mode 100644 documentacao/backlog.md create mode 100644 documentacao/cenarios_de_teste create mode 100644 documentacao/definicao_do_mvp rename {discovery => documentacao}/design_thinking.md (72%) create mode 100644 documentacao/priorizacao_mvp create mode 100644 documentacao/uso_de_ia diff --git a/documentacao/backlog.md b/documentacao/backlog.md new file mode 100644 index 000000000000..dc9585dd452f --- /dev/null +++ b/documentacao/backlog.md @@ -0,0 +1,13 @@ +## 3.5 Backlog + Priorização (Escopo do MVP) + +A tabela abaixo consolida as 5 histórias de usuário necessárias para compor o MVP, priorizadas com base no valor de entrega para a resolução das dores das nossas personas operacionais. + +| ID | História de Usuário | Prioridade | Estado no MVP | +| :--- | :--- | :--- | :--- | +| **US01** | Como Analista de Suporte, quero visualizar os erros estruturados por categoria, para que eu possa identificar a origem do problema instantaneamente. | Alta | **IMPLEMENTADA NO PR** | +| **US02** | Como Analista de Suporte, quero receber uma sugestão de comando ou ação de correção junto ao log de erro, para que eu consiga resolver o incidente de forma autônoma. | Alta | Integrada ao MVP | +| **US03** | Como Desenvolvedor Iniciante, quero que os erros de setup de ambiente gerem saídas semânticas detalhadas, para que eu não perca tempo com configurações incorretas. | Média | Integrada ao MVP | +| **US04** | Como Analista de Suporte, quero poder exportar os erros estruturados em formato JSON usando uma flag `--json`, para que seja possível integrá-los a outras ferramentas de automação. | Baixa | Integrada ao MVP | +| **US05** | Como Analista de Suporte, quero que as categorias de erros críticos possuam cores distintas no terminal, para que o diagnóstico sob pressão seja facilitado. | Baixa | Integrada ao MVP | + +--- diff --git a/documentacao/cenarios_de_teste b/documentacao/cenarios_de_teste new file mode 100644 index 000000000000..062d6c2b547e --- /dev/null +++ b/documentacao/cenarios_de_teste @@ -0,0 +1,51 @@ +## 3.6 Cenários de Teste + +### US01: Categorização e Estruturação Semântica de Erros +* **História:** Como Analista de Suporte, quero visualizar os erros estruturados por categoria, para que eu possa identificar a origem do problema instantaneamente. +* **Critério:** + Dado que o sistema sofra uma falha interna de comunicação com a base de dados + Quando o comando CLI for executado + Então o terminal deve exibir a saída no padrão rigoroso `[ERRO: ] ` +* **Cenários de teste:** + - Dados válidos → sucesso: Queda do banco simulada gera `[ERRO: BANCO_DE_DADOS] Falha de conexão na porta 5432` + - Dados inválidos/Exceção não mapeada → validação falha: Erro desconhecido gera `[ERRO: SISTEMA_DESCONHECIDO] Ocorreu uma falha interna inesperada` + +### US02: Exibição de Ações Corretivas Sugeridas +* **História:** Como Analista de Suporte, quero receber uma sugestão de comando ou ação de correção junto ao log de erro, para que eu consiga resolver o incidente de forma autônoma. +* **Critério:** + Dado que um log de erro padronizado seja gerado na CLI + Quando a categoria possuir uma solução conhecida pré-documentada + Então o sistema deve exibir uma linha adicional contendo `SUGESTÃO: ` +* **Cenários de teste:** + - Dados válidos → sucesso: Erro de escrita gera `[ERRO: PERMISSAO] Arquivo de config ilegível` seguido de `SUGESTÃO: Execute 'chmod +w '` + - Campo vazio/Solução indisponível → erro: Erro sem tratativa cadastrada omite a linha de sugestão + +### US03: Tratamento de Erros Semânticos no Setup de Ambiente +* **História:** Como Desenvolvedor Iniciante, quero que os erros de setup de ambiente gerem saídas semânticas detalhadas, para que eu não perca tempo com configurações incorretas. +* **Critério:** + Dado que o desenvolvedor execute o script de inicialização do projeto + Quando houver uma dependência ou versão de software desatualizada na máquina hospedeira + Então o script deve interromper a execução e apontar qual dependência causou o problema e a versão mínima exigida +* **Cenários de teste:** + - Dados inválidos/Ambiente defasado → validação falha: Versão do Node antiga interrompe o fluxo e exibe `[ERRO: AMBIENTE] Versão do Node.js incompatível. Encontrada: v14. Requerida: >= v18` + - Dados válidos → sucesso: Todas as dependências corretas permitem que o setup finalize com sucesso + +### US04: Flag de Saída em Formato Estruturado JSON +* **História:** Como Analista de Suporte, quero poder exportar os erros estruturados em formato JSON usando uma flag `--json`, para que seja possível integrá-los a outras ferramentas de automação. +* **Critério:** + Dado que qualquer comando da ferramenta CLI resulte em um erro + Quando o usuário adicionar o parâmetro `--json` ao final da linha de comando + Então o erro não deve ser impresso em texto comum, mas sim como um objeto JSON válido contendo as chaves `"error"`, `"category"`, `"message"` e `"suggestion"` +* **Cenários de teste:** + - Dados válidos → sucesso: Comando com erro executado com `--json` retorna estritamente o objeto `{"error": true, "category": "REDE", "message": "Timeout ao conectar na API"}` + - Campo vazio/Parâmetro ausente → erro: Comando com erro executado sem a flag retorna o log em texto legível padrão da CLI + +### US05: Identificação Visual de Erros por Cores no Terminal +* **História:** Como Analista de Suporte, quero que as categorias de erros críticos possuam cores distintas no terminal, para que o diagnóstico sob pressão seja facilitado. +* **Critério:** + Dado que a CLI esteja rodando em um emulador de terminal compatível com caracteres ANSI + Quando um erro crítico de infraestrutura for disparado + Então o prefixo `[ERRO: CATEGORIA]` deve ser renderizado utilizando a cor correspondente ao nível de severidade estabelecido +* **Cenários de teste:** + - Dados válidos → sucesso: Erro de banco de dados renderiza a tag com o código ANSI para a cor vermelha + - Dados inválidos/Terminal sem suporte → validação falha: Execução em ambiente sem suporte TTY identifica a limitação e remove os caracteres ANSI, exibindo o texto limpo \ No newline at end of file diff --git a/documentacao/definicao_do_mvp b/documentacao/definicao_do_mvp new file mode 100644 index 000000000000..8ccf8d69ca14 --- /dev/null +++ b/documentacao/definicao_do_mvp @@ -0,0 +1,12 @@ +## 3.4 Definição do MVP + +### Proposta de Solução Mínima Viável (MVP) +O MVP consiste na Padronização e Semântica de Saídas de Erro via CLI com Guia de Resolução Acoplado. A solução modifica a engine de tratamento de exceções da ferramenta de linha de comando para interceptar falhas genéricas e envelopá-las em um formato padronizado, estruturado em três blocos legíveis: Identificador do Subsistema, Mensagem Descritiva da Causa e Ação Corretiva Sugerida. + +### Justificativa de Valor e Viabilidade + +Valor: Reduz drasticamente o tempo médio de atendimento (SLA) da equipe de suporte técnico (representada por Mariana). Ao prover diagnósticos imediatos e inteligíveis diretamente no terminal, elimina-se a dependência de desenvolvedores seniores para investigar erros operacionais corriqueiros (como falhas de permissão de arquivos ou portas de rede ocupadas). + +Viabilidade: A implementação possui altíssima viabilidade técnica, pois atua exclusivamente no fluxo de tratamento de erros global do software. Não demanda refatorações na lógica central de negócios e dispensa a construção ou manutenção de infraestruturas externas complexas, como servidores de banco de dados ou painéis visuais web (Dashboards) + +--- \ No newline at end of file diff --git a/discovery/design_thinking.md b/documentacao/design_thinking.md similarity index 72% rename from discovery/design_thinking.md rename to documentacao/design_thinking.md index 74a74b5b2613..d787202ba6be 100644 --- a/discovery/design_thinking.md +++ b/documentacao/design_thinking.md @@ -34,9 +34,25 @@ Este documento apresenta as personas e o mapa de empatia. * **Ideia 1:** Criar um painel visual (Dashboard) para monitoramento de erros em tempo real. * **Ideia 2:** Padronizar e reestruturar as saídas de erro do sistema de forma semântica (Ex: `[ERRO: BANCO_DE_DADOS] Falha de conexão na porta 5432`) acompanhadas de possíveis ações de correção (Foco selecionado para o MVP). -# 3.3 Design Thinking com IA +## 3.3 Prompts Utilizados para a IA -Este documento apresenta os resultados da fase de Discovery obtidos através da colaboração com Inteligência Artificial, conforme os requisitos de transparência e criticidade estabelecidos[cite: 1]. +#### Prompt 1: Criação de Personas e Mapa de Empatia + +Atue como um especialista em Product Discovery e Design Thinking aplicado à Engenharia de Software. Estou trabalhando em um projeto prático de reformulação e melhoria de uma ferramenta de software livre puramente técnica, baseada em CLI (Interface de Linha de Comando). + +Preciso que você crie 2 personas distintas que representem os usuários desse ecossistema: +1. Um usuário extremo focado no desenvolvimento (ex: um desenvolvedor iniciante ou adotante inicial tentando configurar o ambiente). +2. Um usuário de ponta focado na operação/suporte diário (ex: um analista de suporte sob pressão). + +Para cada persona, forneça: Perfil, Comportamento, Frustrações/Dores e Objetivos/Ganhos. + +Em seguida, monte um Mapa de Empatia em formato de tabela Markdown focado na segunda persona (Analista de Suporte), dividindo em: O que ela Pensa e Sente?, O que ela Vê?, O que ela Ouve?, O que ela Fala e Faz?, Dores (Frustrações) e Ganhos (Necessidades/Desejos). + +#### Prompt 2: Brainstorming e Ideação de Soluções + +Com base nas dores apresentadas pela persona Mariana Souza (Analista de Suporte), especificamente sobre a dificuldade de diagnosticar falhas operacionais devido a logs extensos, poluídos e extremamente genéricos no terminal, sugira ideias de soluções. + +Gere duas propostas distintas: uma que envolva uma quebra de paradigma visual (Dashboard) e outra focada em reestruturação semântica diretamente na linha de comando (CLI) que traga ações de correção acopladas ao erro. ## 4. Reflexão Crítica diff --git a/documentacao/priorizacao_mvp b/documentacao/priorizacao_mvp new file mode 100644 index 000000000000..014881b171b6 --- /dev/null +++ b/documentacao/priorizacao_mvp @@ -0,0 +1,18 @@ +## 3.7 Priorização do MVP + +As histórias de usuário mapeadas para o escopo do produto foram ordenadas de maneira decrescente com base no valor operacional agregado para as dores da persona principal e nos pilares de dependência técnica: + +1. **[US01] Categorização e Estruturação Semântica de Erros (IMPLEMENTADA NO PR)** +2. **[US02] Exibição de Ações Corretivas Sugeridas** +3. **[US03] Tratamento de Erros Semânticos no Setup de Ambiente** +4. **[US04] Flag de Saída em Formato Estruturado JSON** +5. **[US05] Identificação Visual de Erros por Cores no Terminal** +--- + +### Justificativa da Escolha da História para o Pull Request (PR) + +A história **US01 (Categorização e Estruturação Semântica de Erros)** foi selecionada de forma estratégica pela dupla para compor a entrega prática do Pull Request do projeto pelas seguintes razões: + +**Núcleo Estrutural:** Esta história atua diretamente no motor central de tratamento de exceções global da ferramenta de linha de comando (CLI). Ela cria a infraestrutura básica necessária para capturar falhas genéricas do sistema operacional e encapsulá-las nas categorias normalizadas. +**Bloqueio de Dependência:** As demais histórias de alta e média prioridade dependem estritamente da existência da US01. Não é semanticamente viável sugerir um comando de correção (US02) ou injetar códigos de escape ANSI de cores (US05) sem que a inteligência de categorização de erros e a separação por subsistemas já estejam consolidadas e operando no fluxo do software. +**Minimização Imediata de Risco:** A implementação da US01 ataca imediatamente a principal causa raiz da frustração e "caixa preta" apontada no mapa de empatia, que é a poluição visual e a falta de clareza das mensagens brutas no terminal. \ No newline at end of file diff --git a/documentacao/uso_de_ia b/documentacao/uso_de_ia new file mode 100644 index 000000000000..dec931253501 --- /dev/null +++ b/documentacao/uso_de_ia @@ -0,0 +1,34 @@ +## 3.8 Uso de IA + +### Prompts Utilizados + +#### Prompt 1: Refinamento Gramatical do Backlog (Fase II) + +**Contexto:** Engenharia de Requisitos para CLI com foco na Persona Mariana Souza. + +Atue como Engenheiro de Requisitos Sênior. Com base no MVP selecionado ("Padronização e Semântica de Saídas de Erro via CLI com Guia de Resolução Acoplado") , refine as 5 histórias de usuário mapeadas para o escopo. + +Certifique-se de aplicar de forma estrita o template tradicional de histórias de usuário: **Como [usuário], quero [ação], para que [benefício]**. Garanta que o benefício esteja conectado diretamente com o ganho de autonomia de Mariana (equipe de suporte) e com o setup rápido de Lucas (desenvolvedor iniciante). + +#### Prompt 2: Detalhamento de Comportamento e Cenários de Teste (Fase II) + +**Contexto:** Mapeamento de critérios normativos baseados no comportamento esperado. + +Para as 5 histórias de usuário refinadas no prompt anterior, desdobre os critérios de aceite obrigatoriamente utilizando a sintaxe BDD: **Dado que... Quando... Então...**. + +Logo após cada critério, mapeie cenários de teste objetivos seguindo estritamente a classificação do roteiro da disciplina: +* Dados válidos $\rightarrow$ sucesso * Campo vazio / Fluxo alternativo $\rightarrow$ erro * Dados inválidos / Exceção $\rightarrow$ validação falha + +Mantenha os cenários de teste focados no contexto técnico e operacional de uma interface de linha de comando (CLI). + +--- + +### Decisões Justificadas e Avaliação Crítica + +A colaboração com o modelo de inteligência artificial na Fase II atuou como um acelerador criativo no desdobramento das histórias e na estruturação dos cenários executáveis. Contudo, a revisão humana final foi aplicada de maneira rigorosa para corrigir falhas conceituais e garantir a aderência ao ecossistema técnico do repositório: + +**Adequação Ortográfica e Sintática do Template:** O modelo de IA gerou inicialmente os benefícios das histórias utilizando a conjunção explicativa simplificada "para". Realizamos a adequação manual em todas as sentenças para o termo exato **"para que"**, cumprindo com precisão a checklist gramatical exigida nos critérios de avaliação do trabalho. + +**Tradução de Conceitos Web (GUI) para Linha de Comando (CLI):** Ao mapear os cenários de "campo vazio" e "dados inválidos" para as histórias US04 (Formato JSON) e US05 (Coloração do terminal), a IA alucinou propondo fluxos como "deixar caixas de texto vazias" ou "clicar em botões na interface gráfica". Exercemos o papel de revisores técnicos para traduzir essas validações para a realidade de uma CLI, substituindo-as por "ausência de parâmetros/flags obrigatórias na linha de comando" e "execução do comando em emuladores de terminal sem suporte a caracteres ANSI". + +**Simplificação e Testabilidade dos Critérios:** O modelo de IA sugeriu blocos extensos e narrativos de pós-condições para os testes. Nós simplificamos as respostas brutas mantendo apenas os comportamentos diretamente observáveis no terminal através de código ou saídas textuais (`stdout`/`stderr`), tornando as asserções objetivas para a fase de implementação prática no Pull Request. \ No newline at end of file From 5b923317837242598bf5c27a4e53c9c64db440eb Mon Sep 17 00:00:00 2001 From: Kelvinmilagres Date: Thu, 16 Jul 2026 16:39:51 -0300 Subject: [PATCH 3/6] adding --- documentacao/diagrams/classDiagram.md | 65 ++++++++++++++++++++++ documentacao/diagrams/componentsDiagram.md | 37 ++++++++++++ documentacao/diagrams/sequenceDiagram.md | 40 +++++++++++++ documentacao/discovery/JTBD.md | 35 ++++++++++++ documentacao/requirements/MVP.md | 48 ++++++++++++++++ 5 files changed, 225 insertions(+) create mode 100644 documentacao/diagrams/classDiagram.md create mode 100644 documentacao/diagrams/componentsDiagram.md create mode 100644 documentacao/diagrams/sequenceDiagram.md create mode 100644 documentacao/discovery/JTBD.md create mode 100644 documentacao/requirements/MVP.md diff --git a/documentacao/diagrams/classDiagram.md b/documentacao/diagrams/classDiagram.md new file mode 100644 index 000000000000..43cb8118f37a --- /dev/null +++ b/documentacao/diagrams/classDiagram.md @@ -0,0 +1,65 @@ +# Diagrama de Classes +Baseando-se no MVP proposto para a issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) obtemos o seguinte diagrama de classe: + +```mermaid + classDiagram + class Part { + +int id + +string name + +string description + +bool active + +bool virtual + +bool purchaseable + +int category_id + +create(data) Part + } + + class StockItem { + +int id + +int part_id + +int location_id + +decimal quantity + +datetime creation_date + +create(part, quantity, location) StockItem + } + + class StockLocation { + +int id + +string name + +int parent_id + } + + class PartCategory { + +int id + +string name + +int parent_id + } + + class InitialStockSerializer { + +decimal quantity + +int location + +validate(data) bool + } + + class PartSerializer { + +InitialStockSerializer initial_stock + +create(validated_data) Part + } + + class GlobalSetting { + +string key + +string value + +isSet(key) bool + } + + Part "1" --> "0..*" StockItem : possui + StockItem "0..*" --> "1" StockLocation : armazenado em + Part "0..*" --> "1" PartCategory : pertence a + PartSerializer "1" --> "0..1" InitialStockSerializer : contém + PartSerializer ..> Part : cria + PartSerializer ..> StockItem : cria (se initial_stock informado) + GlobalSetting <.. PartSerializer : consulta PART_CREATE_INITIAL + + + +``` \ No newline at end of file diff --git a/documentacao/diagrams/componentsDiagram.md b/documentacao/diagrams/componentsDiagram.md new file mode 100644 index 000000000000..1fd2df5831d0 --- /dev/null +++ b/documentacao/diagrams/componentsDiagram.md @@ -0,0 +1,37 @@ +# Diagrama de Componentes +aseando-se no MVP proposto para a issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) obtemos o seguinte diagrama de componentes: + +```mermaid + graph TB + subgraph Frontend["Frontend (React)"] + PartForm["PartForm.tsx
(formulário Add Part)"] + GlobalSettingsHook["useGlobalSettingsState
(hook de configurações)"] + end + + subgraph Backend["Backend (Django REST Framework)"] + PartAPI["PartList / PartDetail
(API View)"] + PartSerializerC["PartSerializer"] + InitialStockSerializerC["InitialStockSerializer"] + SettingsAPI["InvenTreeSetting
(PART_CREATE_INITIAL)"] + end + + subgraph Data["Camada de Dados"] + PartTable[("Tabela: part_part")] + StockItemTable[("Tabela: stock_stockitem")] + SettingsTable[("Tabela: common_inventreesetting")] + end + + PartForm -->|consulta configuração| GlobalSettingsHook + GlobalSettingsHook -->|GET /api/settings/global/| SettingsAPI + SettingsAPI --> SettingsTable + + PartForm -->|POST /api/part/| PartAPI + PartAPI --> PartSerializerC + PartSerializerC --> InitialStockSerializerC + PartSerializerC -->|cria| PartTable + InitialStockSerializerC -->|cria| StockItemTable + + style PartForm fill:#ffd6d6,stroke:#c0392b,stroke-width:2px + style GlobalSettingsHook fill:#ffd6d6,stroke:#c0392b,stroke-width:2px + +``` \ No newline at end of file diff --git a/documentacao/diagrams/sequenceDiagram.md b/documentacao/diagrams/sequenceDiagram.md new file mode 100644 index 000000000000..e8f5158477f3 --- /dev/null +++ b/documentacao/diagrams/sequenceDiagram.md @@ -0,0 +1,40 @@ +# Diagrama de Sequencia +Baseando-se no MVP proposto para a issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) obtemos o seguinte diagrama de sequencia: + +```mermaid + sequenceDiagram + actor Usuário + participant Form as PartForm (Frontend) + participant Settings as GlobalSettings + participant API as API (/api/part/) + participant Serializer as PartSerializer (Backend) + participant DB as Banco de Dados + + Usuário->>Form: Abre formulário "Add Part" + Form->>Settings: Verifica PART_CREATE_INITIAL + Settings-->>Form: Retorna valor da configuração + + alt PART_CREATE_INITIAL habilitado + Form->>Form: Renderiza campos initial_stock (quantity, location) + else PART_CREATE_INITIAL desabilitado + Form->>Form: Oculta campos initial_stock + end + + Usuário->>Form: Preenche dados da Part + estoque inicial + Usuário->>Form: Confirma envio (Salvar) + + Form->>API: POST /api/part/ (payload com initial_stock) + API->>Serializer: Valida dados recebidos + Serializer->>DB: Cria registro Part + DB-->>Serializer: Part criada (id) + + alt initial_stock informado + Serializer->>DB: Cria StockItem (quantity, location, part) + DB-->>Serializer: StockItem criado + end + + Serializer-->>API: Retorna Part criada (com stock vinculado) + API-->>Form: Resposta 201 Created + Form-->>Usuário: Exibe confirmação de sucesso +``` + diff --git a/documentacao/discovery/JTBD.md b/documentacao/discovery/JTBD.md new file mode 100644 index 000000000000..e4f80d01974c --- /dev/null +++ b/documentacao/discovery/JTBD.md @@ -0,0 +1,35 @@ + # Descrição do Sistema + +O Inventree é um sistema de gerenciamento de inventario de código aberto, planejado para auxiliar na gestão de estoques. Buscando ser uma alternativa leve e de fácil uso, visando aplicações de pequenas e médias empresas ou para hobby. Utiliza de uma forte logica de negócios para manter o histórico de rastreamento do estoque, para que o usuário tem acesso rápido as informações. + +O sistema é desenvolvido em python e django, armazenando dados em um banco de dados relacional e os disponibiliza através de uma aplicação WEB. Tendo como opção também a integração com outra aplicação através de uma API. + +O sistema possui algumas funcionalidades principais, são elas: + +- Parts: É o componente principal do sistema, representam os itens que serão estocados e organizados pelo sistema; +- Suppliers: É uma funcionalidade que tem como função gerenciar fornecedores, podendo realizar operações sobre os fornecedores do usuário; +- Instant Stock Knowledge: Visualizar informações sobre o estoque e as parts, de forma rápida e direta, permitindo filtrar dados e organizar informações; +- Bill of Materials: Gerencia a lista de materiais que uma part precisa para ser criada, assim permitindo criar pedidos para essas; +- Build Parts: É a funcionalidade responsável por rastrear o progresso de construção de novas parts e estoques da mesma; +- Report: É capaz de gerar relatórios baseados nas movimentações realizadas no estoque; + +## Qual o problema o sistema resolve ? + +O InvenTree busca atender a demanda sobre um sistema de gerenciamento de estoques de acesso livre que possa ser integrado a outros sistemas de maneira fácil, facilitando assim que pequenas e médias empresas possam gerenciar seus estoques. + +## Qual "trabalho" o usuário deseja realizar ? + +Quando um usuário precisa gerenciar um estoque com multiplos fornecedores, locais de deposito, peças e sub-peças, ele busca visuabilidade rápida e clara sobre o que está disponivel no estoque e o que precisa ser reposto, caso contrario os processos não sejam interrompidos nem sofram com a falta de algum material que por engano não está disponivel para a tarefa em que ele é necessário + +## Onde há falhas ou oportunidades ? + +O Projeto possui uma label no github, chamada roadmap, onde são categorizados issues que estão no caminho de serem implementadas e priorizadas, além de mais algumas que são adicionadas pela propria comunidade, que revelam pontos a serem resolvidos/aprimorados, podemos citar: + +- **Initial Stock Data fields are missing in Add Part form when enabled** +([#12266](https://github.com/inventree/InvenTree/issues/12266)) Mesmo com a opção "Initial stock data" habilitada no painel admin, o formulario de criação de peça não exibe campos para informar o estoque inicial. + +- **Adding/pulling custom status text in printable labels/reports** +([#11973](https://github.com/inventree/InvenTree/issues/11973)) Quando o usuário utiliza status costumizados de estoque, não conseguem "imprimir" o texto descritivo desse status nas tags. + +- **Decrementing Non-Tracked Stock When Completing Build Output** +([#11228](https://github.com/inventree/InvenTree/issues/11228)) Em uma ordem de produção de longa duração, o estoque "disponivel" de materia-prima não rastreada não é atualizado corretamente conforme os build outputs, gerando informação impresisa. diff --git a/documentacao/requirements/MVP.md b/documentacao/requirements/MVP.md new file mode 100644 index 000000000000..a306533a3e64 --- /dev/null +++ b/documentacao/requirements/MVP.md @@ -0,0 +1,48 @@ +# Definição do MVP + +## Problema +Issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) Mesmo com a opção "Initial stock data" habilitada no painel admin, o formulario de criação de peça não exibe campos para informar o estoque inicial. + +## Solução do Problema (MVP) +Exibir o campo de estoque inicial no formulário de criação de Part quando a opção "Initial stock data" estiver habilitada, eliminando a necessidade do lançamento de estoque manual e separado. + +## Descrição do Problema +Ao analizar a branch: `master` encontramos as seguintes informações sobre o problema: +- **Backend:** No backend o campo `initial_stock` já foi criado e implementado, recebendo `quantity` e `location` e criando o `StockItem` junto com a peça. +- **Frontend:** No frontend, o formulário de criação de uma `Part` decide se exibe os campos através o do seguinte trecho de codigo: + +```tsx + // Additional fields for creation + if (create && !virtual) { + fields.copy_category_parameters = {}; + + if (virtual != false) { + fields.initial_stock = { + icon: , + children: { + quantity: { + value: 0 + }, + location: {} + } + }; + } +``` +Assim a condição `!virtual` checa se a peça é **virtual**, mas deveria checar se a configuração global `PART_CREATE_INITIAL` está habilitada, como uma peça que não é virtual nunca satisfaz, logo o `initial_stock` nunca é adicionado ao formulário. + + +## Justificativa de Valor +- Resolver um problema já indicado pela comunidade. +- Escopo pequeno e isolado. +- Impacto direto na experiencia do usuário no fluxo mais básico do sistema + +## Justificativa de Viabilidade +- Área do codigo já mapeada +- Não exige mudança de schema de banco de dados +- Testavel de forma isolada + +## Relação com o JTBD +Esse MVP atende a necessidade de visibilidade clara e confiança que um gerenciador de estoque precisa ter, reduzindo riscos para que aconteça erros na hora de registrar etoque inicial dado a ação de criar uma nova peça. + + + From 1b46e339c3baa20b747ee9a83d4e6b57bd32b34e Mon Sep 17 00:00:00 2001 From: arthur-wolff Date: Thu, 16 Jul 2026 23:31:29 -0300 Subject: [PATCH 4/6] =?UTF-8?q?`feat(cli):=20categorizar=20erros=20da=20CL?= =?UTF-8?q?I=20com=20sugest=C3=A3o=20de=20corre=C3=A7=C3=A3o=20(US01/US02)?= =?UTF-8?q?`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Problema resolvido Hoje, quando um comando `invoke` da InvenTree falha (ex.: `invoke migrate`, `invoke server`), o único ponto de tratamento genérico (`task_exception_handler` em `tasks.py`) só trata `ModuleNotFoundError` de forma manual e imprime o traceback Python cru para todo o resto. Isso obriga quem está dando suporte (ou um dev iniciante configurando o ambiente) a ler stack trace para entender o que de fato quebrou — banco fora do ar, porta ocupada, permissão de arquivo, dependência faltando, etc. Este PR introduz um módulo pequeno e isolado (`cli_error_handling.py`) que categoriza a exceção e imprime uma saída padronizada: ``` [ERRO: ] SUGESTAO: (quando conhecida) ``` ### Relação com o JTBD JTBD identificado na Fase I: *"Quando um erro ocorre na CLI, o analista de suporte/desenvolvedor quer entender a causa raiz imediatamente, para não depender de um dev sênior nem perder tempo lendo tracebacks."* Este PR ataca diretamente esse job, sem tocar na lógica de negócio da aplicação. ### Histórias de usuário atendidas - **US01** — Categorização e estruturação semântica de erros *(implementada neste PR)* - **US02** — Sugestão de ação corretiva *(implementada neste PR, pois o `SuggestionProvider` já nasce junto do categorizador — ver justificativa em `documentacao/priorizacao_mvp`)* - US03, US04, US05 — não implementadas neste PR; ficam para incrementos futuros (documentado no backlog). ### O que muda | Arquivo | Tipo | Descrição | |---|---|---| | `cli_error_handling.py` | novo | `ErrorCategory`, `ExceptionCategorizer`, `SuggestionProvider`, `StructuredError`, `build_structured_error`, `format_structured_error` | | `test_cli_error_handling.py` | novo | 5 testes cobrindo os cenários de `documentacao/cenarios_de_teste` | | `tasks.py` | editado | `task_exception_handler` passa a delegar para o novo módulo (ver `INTEGRACAO_tasks_py.md`) | ### Evidências **Testes automatizados (5/5 passando):** ``` test_cli_error_handling.py::test_us01_dados_validos_categoriza_erro_de_banco PASSED test_cli_error_handling.py::test_us01_excecao_nao_mapeada_cai_em_sistema_desconhecido PASSED test_cli_error_handling.py::test_us02_categoria_com_solucao_conhecida_exibe_sugestao PASSED test_cli_error_handling.py::test_us02_categoria_sem_solucao_omite_linha_de_sugestao PASSED test_cli_error_handling.py::test_ambiente_reaproveita_categoria_ja_tratada_pelo_task_exception_handler PASSED ``` **Saída simulada no terminal:** ``` $ invoke migrate [ERRO: BANCO_DE_DADOS] Falha de conexao na porta 5432 SUGESTAO: Verifique se o servico de banco de dados esta ativo e acessivel $ invoke server (dependência ausente) [ERRO: AMBIENTE] No module named 'invoke' SUGESTAO: Execute 'invoke install' para reinstalar as dependencias corretas $ invoke [ERRO: SISTEMA_DESCONHECIDO] Ocorreu uma falha interna inesperada ``` *(Substituir por prints reais do terminal de vocês antes de submeter — rodem os comandos de fato no fork local e capturem a tela.)* ### Uso de IA Ver `documentacao/uso_de_ia` — prompts e decisões humanas de refino documentados conforme item 3.8 do enunciado. ### Checklist antes de abrir o PR - [ ] Rodar `pytest test_cli_error_handling.py` localmente no fork - [ ] Aplicar as duas edições em `tasks.py` (ver `INTEGRACAO_tasks_py.md`) - [ ] Testar manualmente pelo menos 1 comando `invoke` real falhando - [ ] Capturar print real do terminal para substituir a evidência simulada - [ ] Um dos dois revisa o código do outro e deixa comentários no PR (item 3.12) --- cli_error_handling.py | 111 ++++++++++++++++++ .../ai-usage}/design_thinking_prompts.md | 0 .../{uso_de_ia => ai-usage/uso_de_ia.md} | 0 documentacao/diagrams/classDiagram.md | 65 ---------- documentacao/diagrams/componentsDiagram.md | 37 ------ documentacao/diagrams/sequenceDiagram.md | 40 ------- .../definicao_do_mvp.md} | 0 .../{ => discovery}/design_thinking.md | 0 .../priorizacao_mvp.md} | 0 documentacao/{ => requirements}/backlog.md | 0 .../cenarios_de_teste.md} | 0 tasks.py | 17 +-- test_cli_error_handling.py | 70 +++++++++++ 13 files changed, 186 insertions(+), 154 deletions(-) create mode 100644 cli_error_handling.py rename {ai-usage => documentacao/ai-usage}/design_thinking_prompts.md (100%) rename documentacao/{uso_de_ia => ai-usage/uso_de_ia.md} (100%) delete mode 100644 documentacao/diagrams/classDiagram.md delete mode 100644 documentacao/diagrams/componentsDiagram.md delete mode 100644 documentacao/diagrams/sequenceDiagram.md rename documentacao/{definicao_do_mvp => discovery/definicao_do_mvp.md} (100%) rename documentacao/{ => discovery}/design_thinking.md (100%) rename documentacao/{priorizacao_mvp => discovery/priorizacao_mvp.md} (100%) rename documentacao/{ => requirements}/backlog.md (100%) rename documentacao/{cenarios_de_teste => requirements/cenarios_de_teste.md} (100%) create mode 100644 test_cli_error_handling.py diff --git a/cli_error_handling.py b/cli_error_handling.py new file mode 100644 index 000000000000..de0d1616fd11 --- /dev/null +++ b/cli_error_handling.py @@ -0,0 +1,111 @@ +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +from typing import Optional + + +class ErrorCategory(str, Enum): + + + BANCO_DE_DADOS = 'BANCO_DE_DADOS' + REDE = 'REDE' + PERMISSAO = 'PERMISSAO' + AMBIENTE = 'AMBIENTE' + SISTEMA_DESCONHECIDO = 'SISTEMA_DESCONHECIDO' + + + +_DEFAULT_MESSAGES = { + ErrorCategory.SISTEMA_DESCONHECIDO: 'Ocorreu uma falha interna inesperada', +} + + +_SUGGESTIONS = { + ErrorCategory.PERMISSAO: "Execute 'chmod +w ' ou ajuste as permissoes do diretorio", + ErrorCategory.AMBIENTE: "Execute 'invoke install' para reinstalar as dependencias corretas", + ErrorCategory.BANCO_DE_DADOS: 'Verifique se o servico de banco de dados esta ativo e acessivel', + ErrorCategory.REDE: 'Verifique a conectividade de rede e as credenciais do endpoint remoto', +} + + +@dataclass +class StructuredError: + + + category: ErrorCategory + message: str + suggestion: Optional[str] = None + + +class ExceptionCategorizer: + + _TYPE_NAME_MAP = { + 'OperationalError': ErrorCategory.BANCO_DE_DADOS, + 'InterfaceError': ErrorCategory.BANCO_DE_DADOS, + 'DatabaseError': ErrorCategory.BANCO_DE_DADOS, + 'PermissionError': ErrorCategory.PERMISSAO, + 'ModuleNotFoundError': ErrorCategory.AMBIENTE, + 'ImportError': ErrorCategory.AMBIENTE, + 'ConnectionError': ErrorCategory.REDE, + 'ConnectionRefusedError': ErrorCategory.REDE, + 'TimeoutError': ErrorCategory.REDE, + 'URLError': ErrorCategory.REDE, + } + + + _KEYWORD_MAP = ( + (('porta', 'connection refused', 'database', 'banco de dados'), ErrorCategory.BANCO_DE_DADOS), + (('network', 'rede', 'timeout', 'dns'), ErrorCategory.REDE), + (('permission', 'permissao', 'read-only', 'access is denied'), ErrorCategory.PERMISSAO), + ) + + def classify(self, exc: BaseException) -> ErrorCategory: + + type_name = type(exc).__name__ + if type_name in self._TYPE_NAME_MAP: + return self._TYPE_NAME_MAP[type_name] + + message = str(exc).lower() + for keywords, category in self._KEYWORD_MAP: + if any(keyword in message for keyword in keywords): + return category + + return ErrorCategory.SISTEMA_DESCONHECIDO + + +class SuggestionProvider: + + + def get_suggestion(self, category: ErrorCategory) -> Optional[str]: + + return _SUGGESTIONS.get(category) + + +def build_structured_error( + exc: BaseException, + categorizer: Optional[ExceptionCategorizer] = None, + suggestion_provider: Optional[SuggestionProvider] = None, +) -> StructuredError: + + categorizer = categorizer or ExceptionCategorizer() + suggestion_provider = suggestion_provider or SuggestionProvider() + + category = categorizer.classify(exc) + message = str(exc).strip() or _DEFAULT_MESSAGES.get( + category, 'Ocorreu uma falha inesperada' + ) + + return StructuredError( + category=category, + message=message, + suggestion=suggestion_provider.get_suggestion(category), + ) + + +def format_structured_error(error: StructuredError) -> str: + + lines = [f'[ERRO: {error.category.value}] {error.message}'] + if error.suggestion: + lines.append(f'SUGESTAO: {error.suggestion}') + return '\n'.join(lines) \ No newline at end of file diff --git a/ai-usage/design_thinking_prompts.md b/documentacao/ai-usage/design_thinking_prompts.md similarity index 100% rename from ai-usage/design_thinking_prompts.md rename to documentacao/ai-usage/design_thinking_prompts.md diff --git a/documentacao/uso_de_ia b/documentacao/ai-usage/uso_de_ia.md similarity index 100% rename from documentacao/uso_de_ia rename to documentacao/ai-usage/uso_de_ia.md diff --git a/documentacao/diagrams/classDiagram.md b/documentacao/diagrams/classDiagram.md deleted file mode 100644 index 43cb8118f37a..000000000000 --- a/documentacao/diagrams/classDiagram.md +++ /dev/null @@ -1,65 +0,0 @@ -# Diagrama de Classes -Baseando-se no MVP proposto para a issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) obtemos o seguinte diagrama de classe: - -```mermaid - classDiagram - class Part { - +int id - +string name - +string description - +bool active - +bool virtual - +bool purchaseable - +int category_id - +create(data) Part - } - - class StockItem { - +int id - +int part_id - +int location_id - +decimal quantity - +datetime creation_date - +create(part, quantity, location) StockItem - } - - class StockLocation { - +int id - +string name - +int parent_id - } - - class PartCategory { - +int id - +string name - +int parent_id - } - - class InitialStockSerializer { - +decimal quantity - +int location - +validate(data) bool - } - - class PartSerializer { - +InitialStockSerializer initial_stock - +create(validated_data) Part - } - - class GlobalSetting { - +string key - +string value - +isSet(key) bool - } - - Part "1" --> "0..*" StockItem : possui - StockItem "0..*" --> "1" StockLocation : armazenado em - Part "0..*" --> "1" PartCategory : pertence a - PartSerializer "1" --> "0..1" InitialStockSerializer : contém - PartSerializer ..> Part : cria - PartSerializer ..> StockItem : cria (se initial_stock informado) - GlobalSetting <.. PartSerializer : consulta PART_CREATE_INITIAL - - - -``` \ No newline at end of file diff --git a/documentacao/diagrams/componentsDiagram.md b/documentacao/diagrams/componentsDiagram.md deleted file mode 100644 index 1fd2df5831d0..000000000000 --- a/documentacao/diagrams/componentsDiagram.md +++ /dev/null @@ -1,37 +0,0 @@ -# Diagrama de Componentes -aseando-se no MVP proposto para a issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) obtemos o seguinte diagrama de componentes: - -```mermaid - graph TB - subgraph Frontend["Frontend (React)"] - PartForm["PartForm.tsx
(formulário Add Part)"] - GlobalSettingsHook["useGlobalSettingsState
(hook de configurações)"] - end - - subgraph Backend["Backend (Django REST Framework)"] - PartAPI["PartList / PartDetail
(API View)"] - PartSerializerC["PartSerializer"] - InitialStockSerializerC["InitialStockSerializer"] - SettingsAPI["InvenTreeSetting
(PART_CREATE_INITIAL)"] - end - - subgraph Data["Camada de Dados"] - PartTable[("Tabela: part_part")] - StockItemTable[("Tabela: stock_stockitem")] - SettingsTable[("Tabela: common_inventreesetting")] - end - - PartForm -->|consulta configuração| GlobalSettingsHook - GlobalSettingsHook -->|GET /api/settings/global/| SettingsAPI - SettingsAPI --> SettingsTable - - PartForm -->|POST /api/part/| PartAPI - PartAPI --> PartSerializerC - PartSerializerC --> InitialStockSerializerC - PartSerializerC -->|cria| PartTable - InitialStockSerializerC -->|cria| StockItemTable - - style PartForm fill:#ffd6d6,stroke:#c0392b,stroke-width:2px - style GlobalSettingsHook fill:#ffd6d6,stroke:#c0392b,stroke-width:2px - -``` \ No newline at end of file diff --git a/documentacao/diagrams/sequenceDiagram.md b/documentacao/diagrams/sequenceDiagram.md deleted file mode 100644 index e8f5158477f3..000000000000 --- a/documentacao/diagrams/sequenceDiagram.md +++ /dev/null @@ -1,40 +0,0 @@ -# Diagrama de Sequencia -Baseando-se no MVP proposto para a issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) obtemos o seguinte diagrama de sequencia: - -```mermaid - sequenceDiagram - actor Usuário - participant Form as PartForm (Frontend) - participant Settings as GlobalSettings - participant API as API (/api/part/) - participant Serializer as PartSerializer (Backend) - participant DB as Banco de Dados - - Usuário->>Form: Abre formulário "Add Part" - Form->>Settings: Verifica PART_CREATE_INITIAL - Settings-->>Form: Retorna valor da configuração - - alt PART_CREATE_INITIAL habilitado - Form->>Form: Renderiza campos initial_stock (quantity, location) - else PART_CREATE_INITIAL desabilitado - Form->>Form: Oculta campos initial_stock - end - - Usuário->>Form: Preenche dados da Part + estoque inicial - Usuário->>Form: Confirma envio (Salvar) - - Form->>API: POST /api/part/ (payload com initial_stock) - API->>Serializer: Valida dados recebidos - Serializer->>DB: Cria registro Part - DB-->>Serializer: Part criada (id) - - alt initial_stock informado - Serializer->>DB: Cria StockItem (quantity, location, part) - DB-->>Serializer: StockItem criado - end - - Serializer-->>API: Retorna Part criada (com stock vinculado) - API-->>Form: Resposta 201 Created - Form-->>Usuário: Exibe confirmação de sucesso -``` - diff --git a/documentacao/definicao_do_mvp b/documentacao/discovery/definicao_do_mvp.md similarity index 100% rename from documentacao/definicao_do_mvp rename to documentacao/discovery/definicao_do_mvp.md diff --git a/documentacao/design_thinking.md b/documentacao/discovery/design_thinking.md similarity index 100% rename from documentacao/design_thinking.md rename to documentacao/discovery/design_thinking.md diff --git a/documentacao/priorizacao_mvp b/documentacao/discovery/priorizacao_mvp.md similarity index 100% rename from documentacao/priorizacao_mvp rename to documentacao/discovery/priorizacao_mvp.md diff --git a/documentacao/backlog.md b/documentacao/requirements/backlog.md similarity index 100% rename from documentacao/backlog.md rename to documentacao/requirements/backlog.md diff --git a/documentacao/cenarios_de_teste b/documentacao/requirements/cenarios_de_teste.md similarity index 100% rename from documentacao/cenarios_de_teste rename to documentacao/requirements/cenarios_de_teste.md diff --git a/tasks.py b/tasks.py index 6e086e2c3007..d82d5d849c5f 100644 --- a/tasks.py +++ b/tasks.py @@ -143,21 +143,14 @@ def task_exception_handler(t, v, tb): """Handle exceptions raised by tasks. The intent here is to provide more 'useful' error messages when tasks fail. + Errors are categorized and rendered in the standard + `[ERRO: CATEGORIA] mensagem` format (US01), with an optional corrective + action suggestion appended when one is known (US02). """ sys.__excepthook__(t, v, tb) - if t is ModuleNotFoundError: - mod_name = str(v).split(' ')[-1].strip("'") - - error(f'Error importing required module: {mod_name}') - warning('- Ensure the correct Python virtual environment is active') - warning( - '- Ensure that the invoke tool is installed in the active Python environment' - ) - warning( - "- Ensure all required packages are installed by running 'invoke install'" - ) - + structured = build_structured_error(v) + error(format_structured_error(structured)) sys.excepthook = task_exception_handler diff --git a/test_cli_error_handling.py b/test_cli_error_handling.py new file mode 100644 index 000000000000..fa7fd76371db --- /dev/null +++ b/test_cli_error_handling.py @@ -0,0 +1,70 @@ +"""Tests for cli_error_handling.py (US01 / US02). + +These mirror the test scenarios documented in +documentacao/cenarios_de_teste. +""" + +from cli_error_handling import ( + ErrorCategory, + build_structured_error, + format_structured_error, +) + + +class FakeOperationalError(Exception): + """Stand-in for a DB driver's OperationalError (avoids a psycopg2 dependency in tests).""" + + +FakeOperationalError.__name__ = 'OperationalError' + + +def test_us01_dados_validos_categoriza_erro_de_banco(): + """Cenario: queda do banco simulada -> [ERRO: BANCO_DE_DADOS] ...""" + exc = FakeOperationalError('Falha de conexao na porta 5432') + result = build_structured_error(exc) + + assert result.category == ErrorCategory.BANCO_DE_DADOS + output = format_structured_error(result) + assert output.startswith('[ERRO: BANCO_DE_DADOS] Falha de conexao na porta 5432') + + +def test_us01_excecao_nao_mapeada_cai_em_sistema_desconhecido(): + """Cenario: erro desconhecido -> [ERRO: SISTEMA_DESCONHECIDO] ...""" + exc = RuntimeError('') # sem mensagem, tipo nao mapeado + result = build_structured_error(exc) + + assert result.category == ErrorCategory.SISTEMA_DESCONHECIDO + assert format_structured_error(result) == ( + '[ERRO: SISTEMA_DESCONHECIDO] Ocorreu uma falha interna inesperada' + ) + + +def test_us02_categoria_com_solucao_conhecida_exibe_sugestao(): + """Cenario: erro de escrita -> linha SUGESTAO: ... e' anexada.""" + exc = PermissionError('Arquivo de config ilegivel') + result = build_structured_error(exc) + output = format_structured_error(result) + + assert output == ( + '[ERRO: PERMISSAO] Arquivo de config ilegivel\n' + "SUGESTAO: Execute 'chmod +w ' ou ajuste as permissoes do diretorio" + ) + + +def test_us02_categoria_sem_solucao_omite_linha_de_sugestao(): + """Cenario: erro sem tratativa cadastrada -> omite a linha de sugestao.""" + exc = RuntimeError('falha nao mapeada qualquer') + result = build_structured_error(exc) + output = format_structured_error(result) + + assert 'SUGESTAO' not in output + + +def test_ambiente_reaproveita_categoria_ja_tratada_pelo_task_exception_handler(): + """ModuleNotFoundError ja era tratado manualmente em tasks.py; garante + que a nova categorizacao cobre o mesmo caso sem duplicar logica. + """ + exc = ModuleNotFoundError("No module named 'invoke'") + result = build_structured_error(exc) + + assert result.category == ErrorCategory.AMBIENTE \ No newline at end of file From 29de1162de1be1aa7c352be7d91db0013778b7df Mon Sep 17 00:00:00 2001 From: arthur-wolff Date: Thu, 16 Jul 2026 23:34:35 -0300 Subject: [PATCH 5/6] Update tasks.py --- tasks.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tasks.py b/tasks.py index d82d5d849c5f..bac3eff231ed 100644 --- a/tasks.py +++ b/tasks.py @@ -19,6 +19,7 @@ import invoke from invoke import Collection, task from invoke.exceptions import Exit, UnexpectedExit +from cli_error_handling import build_structured_error, format_structured_error def safe_value(fnc): From 0313d0a869d953460748c038213feb5155747ccc Mon Sep 17 00:00:00 2001 From: Arthur <106398646+arthur-wolff@users.noreply.github.com> Date: Fri, 17 Jul 2026 06:52:57 -0300 Subject: [PATCH 6/6] Delete documentacao directory --- .../ai-usage/design_thinking_prompts.md | 0 documentacao/ai-usage/uso_de_ia.md | 34 ----------- documentacao/discovery/JTBD.md | 35 ----------- documentacao/discovery/definicao_do_mvp.md | 12 ---- documentacao/discovery/design_thinking.md | 61 ------------------- documentacao/discovery/priorizacao_mvp.md | 18 ------ documentacao/requirements/MVP.md | 48 --------------- documentacao/requirements/backlog.md | 13 ---- .../requirements/cenarios_de_teste.md | 51 ---------------- 9 files changed, 272 deletions(-) delete mode 100644 documentacao/ai-usage/design_thinking_prompts.md delete mode 100644 documentacao/ai-usage/uso_de_ia.md delete mode 100644 documentacao/discovery/JTBD.md delete mode 100644 documentacao/discovery/definicao_do_mvp.md delete mode 100644 documentacao/discovery/design_thinking.md delete mode 100644 documentacao/discovery/priorizacao_mvp.md delete mode 100644 documentacao/requirements/MVP.md delete mode 100644 documentacao/requirements/backlog.md delete mode 100644 documentacao/requirements/cenarios_de_teste.md diff --git a/documentacao/ai-usage/design_thinking_prompts.md b/documentacao/ai-usage/design_thinking_prompts.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/documentacao/ai-usage/uso_de_ia.md b/documentacao/ai-usage/uso_de_ia.md deleted file mode 100644 index dec931253501..000000000000 --- a/documentacao/ai-usage/uso_de_ia.md +++ /dev/null @@ -1,34 +0,0 @@ -## 3.8 Uso de IA - -### Prompts Utilizados - -#### Prompt 1: Refinamento Gramatical do Backlog (Fase II) - -**Contexto:** Engenharia de Requisitos para CLI com foco na Persona Mariana Souza. - -Atue como Engenheiro de Requisitos Sênior. Com base no MVP selecionado ("Padronização e Semântica de Saídas de Erro via CLI com Guia de Resolução Acoplado") , refine as 5 histórias de usuário mapeadas para o escopo. - -Certifique-se de aplicar de forma estrita o template tradicional de histórias de usuário: **Como [usuário], quero [ação], para que [benefício]**. Garanta que o benefício esteja conectado diretamente com o ganho de autonomia de Mariana (equipe de suporte) e com o setup rápido de Lucas (desenvolvedor iniciante). - -#### Prompt 2: Detalhamento de Comportamento e Cenários de Teste (Fase II) - -**Contexto:** Mapeamento de critérios normativos baseados no comportamento esperado. - -Para as 5 histórias de usuário refinadas no prompt anterior, desdobre os critérios de aceite obrigatoriamente utilizando a sintaxe BDD: **Dado que... Quando... Então...**. - -Logo após cada critério, mapeie cenários de teste objetivos seguindo estritamente a classificação do roteiro da disciplina: -* Dados válidos $\rightarrow$ sucesso * Campo vazio / Fluxo alternativo $\rightarrow$ erro * Dados inválidos / Exceção $\rightarrow$ validação falha - -Mantenha os cenários de teste focados no contexto técnico e operacional de uma interface de linha de comando (CLI). - ---- - -### Decisões Justificadas e Avaliação Crítica - -A colaboração com o modelo de inteligência artificial na Fase II atuou como um acelerador criativo no desdobramento das histórias e na estruturação dos cenários executáveis. Contudo, a revisão humana final foi aplicada de maneira rigorosa para corrigir falhas conceituais e garantir a aderência ao ecossistema técnico do repositório: - -**Adequação Ortográfica e Sintática do Template:** O modelo de IA gerou inicialmente os benefícios das histórias utilizando a conjunção explicativa simplificada "para". Realizamos a adequação manual em todas as sentenças para o termo exato **"para que"**, cumprindo com precisão a checklist gramatical exigida nos critérios de avaliação do trabalho. - -**Tradução de Conceitos Web (GUI) para Linha de Comando (CLI):** Ao mapear os cenários de "campo vazio" e "dados inválidos" para as histórias US04 (Formato JSON) e US05 (Coloração do terminal), a IA alucinou propondo fluxos como "deixar caixas de texto vazias" ou "clicar em botões na interface gráfica". Exercemos o papel de revisores técnicos para traduzir essas validações para a realidade de uma CLI, substituindo-as por "ausência de parâmetros/flags obrigatórias na linha de comando" e "execução do comando em emuladores de terminal sem suporte a caracteres ANSI". - -**Simplificação e Testabilidade dos Critérios:** O modelo de IA sugeriu blocos extensos e narrativos de pós-condições para os testes. Nós simplificamos as respostas brutas mantendo apenas os comportamentos diretamente observáveis no terminal através de código ou saídas textuais (`stdout`/`stderr`), tornando as asserções objetivas para a fase de implementação prática no Pull Request. \ No newline at end of file diff --git a/documentacao/discovery/JTBD.md b/documentacao/discovery/JTBD.md deleted file mode 100644 index e4f80d01974c..000000000000 --- a/documentacao/discovery/JTBD.md +++ /dev/null @@ -1,35 +0,0 @@ - # Descrição do Sistema - -O Inventree é um sistema de gerenciamento de inventario de código aberto, planejado para auxiliar na gestão de estoques. Buscando ser uma alternativa leve e de fácil uso, visando aplicações de pequenas e médias empresas ou para hobby. Utiliza de uma forte logica de negócios para manter o histórico de rastreamento do estoque, para que o usuário tem acesso rápido as informações. - -O sistema é desenvolvido em python e django, armazenando dados em um banco de dados relacional e os disponibiliza através de uma aplicação WEB. Tendo como opção também a integração com outra aplicação através de uma API. - -O sistema possui algumas funcionalidades principais, são elas: - -- Parts: É o componente principal do sistema, representam os itens que serão estocados e organizados pelo sistema; -- Suppliers: É uma funcionalidade que tem como função gerenciar fornecedores, podendo realizar operações sobre os fornecedores do usuário; -- Instant Stock Knowledge: Visualizar informações sobre o estoque e as parts, de forma rápida e direta, permitindo filtrar dados e organizar informações; -- Bill of Materials: Gerencia a lista de materiais que uma part precisa para ser criada, assim permitindo criar pedidos para essas; -- Build Parts: É a funcionalidade responsável por rastrear o progresso de construção de novas parts e estoques da mesma; -- Report: É capaz de gerar relatórios baseados nas movimentações realizadas no estoque; - -## Qual o problema o sistema resolve ? - -O InvenTree busca atender a demanda sobre um sistema de gerenciamento de estoques de acesso livre que possa ser integrado a outros sistemas de maneira fácil, facilitando assim que pequenas e médias empresas possam gerenciar seus estoques. - -## Qual "trabalho" o usuário deseja realizar ? - -Quando um usuário precisa gerenciar um estoque com multiplos fornecedores, locais de deposito, peças e sub-peças, ele busca visuabilidade rápida e clara sobre o que está disponivel no estoque e o que precisa ser reposto, caso contrario os processos não sejam interrompidos nem sofram com a falta de algum material que por engano não está disponivel para a tarefa em que ele é necessário - -## Onde há falhas ou oportunidades ? - -O Projeto possui uma label no github, chamada roadmap, onde são categorizados issues que estão no caminho de serem implementadas e priorizadas, além de mais algumas que são adicionadas pela propria comunidade, que revelam pontos a serem resolvidos/aprimorados, podemos citar: - -- **Initial Stock Data fields are missing in Add Part form when enabled** -([#12266](https://github.com/inventree/InvenTree/issues/12266)) Mesmo com a opção "Initial stock data" habilitada no painel admin, o formulario de criação de peça não exibe campos para informar o estoque inicial. - -- **Adding/pulling custom status text in printable labels/reports** -([#11973](https://github.com/inventree/InvenTree/issues/11973)) Quando o usuário utiliza status costumizados de estoque, não conseguem "imprimir" o texto descritivo desse status nas tags. - -- **Decrementing Non-Tracked Stock When Completing Build Output** -([#11228](https://github.com/inventree/InvenTree/issues/11228)) Em uma ordem de produção de longa duração, o estoque "disponivel" de materia-prima não rastreada não é atualizado corretamente conforme os build outputs, gerando informação impresisa. diff --git a/documentacao/discovery/definicao_do_mvp.md b/documentacao/discovery/definicao_do_mvp.md deleted file mode 100644 index 8ccf8d69ca14..000000000000 --- a/documentacao/discovery/definicao_do_mvp.md +++ /dev/null @@ -1,12 +0,0 @@ -## 3.4 Definição do MVP - -### Proposta de Solução Mínima Viável (MVP) -O MVP consiste na Padronização e Semântica de Saídas de Erro via CLI com Guia de Resolução Acoplado. A solução modifica a engine de tratamento de exceções da ferramenta de linha de comando para interceptar falhas genéricas e envelopá-las em um formato padronizado, estruturado em três blocos legíveis: Identificador do Subsistema, Mensagem Descritiva da Causa e Ação Corretiva Sugerida. - -### Justificativa de Valor e Viabilidade - -Valor: Reduz drasticamente o tempo médio de atendimento (SLA) da equipe de suporte técnico (representada por Mariana). Ao prover diagnósticos imediatos e inteligíveis diretamente no terminal, elimina-se a dependência de desenvolvedores seniores para investigar erros operacionais corriqueiros (como falhas de permissão de arquivos ou portas de rede ocupadas). - -Viabilidade: A implementação possui altíssima viabilidade técnica, pois atua exclusivamente no fluxo de tratamento de erros global do software. Não demanda refatorações na lógica central de negócios e dispensa a construção ou manutenção de infraestruturas externas complexas, como servidores de banco de dados ou painéis visuais web (Dashboards) - ---- \ No newline at end of file diff --git a/documentacao/discovery/design_thinking.md b/documentacao/discovery/design_thinking.md deleted file mode 100644 index d787202ba6be..000000000000 --- a/documentacao/discovery/design_thinking.md +++ /dev/null @@ -1,61 +0,0 @@ -# Design Thinking com IA - -Este documento apresenta as personas e o mapa de empatia. - -## 1. Personas -### Persona 1: Lucas Rocha (O Desenvolvedor Iniciante) -* **Perfil:** Estudante de Sistemas de Informação, 21 anos, usuário de Linux (Ubuntu). -* **Comportamento:** Muito ativo em comunidades de tecnologia no Discord, prefere utilizar ferramentas via linha de comando (CLI) e busca fazer sua primeira contribuição em um projeto open-source para melhorar o currículo. -* **Frustrações/Dores:** Sente que o processo de setup inicial e a documentação do repositório são confusos. Perdeu mais de duas horas tentando rodar o projeto localmente devido a dependências desatualizadas e erros de ambiente não documentados no `README.md`. -* **Objetivos/Ganhos:** Encontrar um guia claro "passo a passo" ou uma automação (como um container Docker ou script de ambiente) que permita configurar o projeto em menos de 10 minutos, dando segurança para codificar. - -### Persona 2: Mariana Souza (A Analista de Suporte) -* **Perfil:** Analista de Suporte Técnico, 33 anos, focada em agilidade e cumprimento de prazos. -* **Comportamento:** Pragmática, utiliza o sistema diariamente em ambiente de produção para resolver problemas de clientes sob pressão. Não busca customizar o código, precisa apenas que a ferramenta funcione sem surpresas. -* **Frustrações/Dores:** O sistema gera logs de erro extremamente genéricos no terminal quando algo falha. Quando um processo trava, ela não consegue identificar rapidamente se o problema é de rede, permissão ou um bug interno, atrasando o atendimento. -* **Objetivos/Ganhos:** Obter um formato de logs de erro mais descritivo, limpo e estruturado, facilitando o diagnóstico rápido de falhas sem a necessidade de abrir o código-fonte para entender o problema. - ---- - -## 2. Mapa de Empatia (Persona Principal: Mariana Souza) - -| O que ela Pensa e Sente? | O que ela Vê? | -| :--- | :--- | -| * "Preciso resolver os chamados dos clientes rápido."
* Frustração com a falta de clareza do sistema.
* Insegurança ao tentar adivinhar a causa de um erro. | * Logs extensos e poluídos no terminal.
* Clientes cobrando soluções rápidas.
* Issues antigas no GitHub discutindo erros parecidos. | -| **O que ela Ouve?** | **O que ela Fala e Faz?** | -| * Os clientes reclamando da demora no suporte.
* A gerência cobrando agilidade nas métricas.
* Colegas dizendo que o sistema é "caixa preta". | * Reclama que os logs atuais não ajudam em nada.
* Abre o terminal e tenta reiniciar o sistema do zero.
* Documenta manualmente os erros que consegue decifrar. | -| **Dores (Frustrações)** | **Ganhos (Necessidades/Desejos)** | -| * Perda de tempo decifrando mensagens genéricas.
* Estresse com a pressão do tempo de atendimento.
* Dependência de desenvolvedores seniores para bugs simples. | * Diagnóstico visual imediato do problema através do log.
* Maior autonomia no trabalho diário de suporte.
* Redução do tempo de resolução de chamados (SLA). | - ---- - -## 3. Ideias de Solução Exploradas - -* **Ideia 1:** Criar um painel visual (Dashboard) para monitoramento de erros em tempo real. -* **Ideia 2:** Padronizar e reestruturar as saídas de erro do sistema de forma semântica (Ex: `[ERRO: BANCO_DE_DADOS] Falha de conexão na porta 5432`) acompanhadas de possíveis ações de correção (Foco selecionado para o MVP). - -## 3.3 Prompts Utilizados para a IA - -#### Prompt 1: Criação de Personas e Mapa de Empatia - -Atue como um especialista em Product Discovery e Design Thinking aplicado à Engenharia de Software. Estou trabalhando em um projeto prático de reformulação e melhoria de uma ferramenta de software livre puramente técnica, baseada em CLI (Interface de Linha de Comando). - -Preciso que você crie 2 personas distintas que representem os usuários desse ecossistema: -1. Um usuário extremo focado no desenvolvimento (ex: um desenvolvedor iniciante ou adotante inicial tentando configurar o ambiente). -2. Um usuário de ponta focado na operação/suporte diário (ex: um analista de suporte sob pressão). - -Para cada persona, forneça: Perfil, Comportamento, Frustrações/Dores e Objetivos/Ganhos. - -Em seguida, monte um Mapa de Empatia em formato de tabela Markdown focado na segunda persona (Analista de Suporte), dividindo em: O que ela Pensa e Sente?, O que ela Vê?, O que ela Ouve?, O que ela Fala e Faz?, Dores (Frustrações) e Ganhos (Necessidades/Desejos). - -#### Prompt 2: Brainstorming e Ideação de Soluções - -Com base nas dores apresentadas pela persona Mariana Souza (Analista de Suporte), especificamente sobre a dificuldade de diagnosticar falhas operacionais devido a logs extensos, poluídos e extremamente genéricos no terminal, sugira ideias de soluções. - -Gere duas propostas distintas: uma que envolva uma quebra de paradigma visual (Dashboard) e outra focada em reestruturação semântica diretamente na linha de comando (CLI) que traga ações de correção acopladas ao erro. - -## 4. Reflexão Crítica - -O uso da inteligência artificial foi fundamental para acelerar o processo criativo e estruturar o mapeamento psicográfico das personas de forma rápida. O modelo foi capaz de simular com precisão dores reais de profissionais de suporte que lidam com ferramentas open-source. - -No entanto, exercemos a decisão humana final ao filtrar alucinações do modelo. A IA sugeriu inicialmente dores voltadas a interfaces mobile e relatórios em PDF, recursos que não condizem com a proposta puramente técnica via CLI do software analisado. Nós removemos esses excessos e refinamos os textos manualmente para garantir que o mapa de empatia estivesse perfeitamente conectado às issues e limitações reais encontradas no repositório do projeto. \ No newline at end of file diff --git a/documentacao/discovery/priorizacao_mvp.md b/documentacao/discovery/priorizacao_mvp.md deleted file mode 100644 index 014881b171b6..000000000000 --- a/documentacao/discovery/priorizacao_mvp.md +++ /dev/null @@ -1,18 +0,0 @@ -## 3.7 Priorização do MVP - -As histórias de usuário mapeadas para o escopo do produto foram ordenadas de maneira decrescente com base no valor operacional agregado para as dores da persona principal e nos pilares de dependência técnica: - -1. **[US01] Categorização e Estruturação Semântica de Erros (IMPLEMENTADA NO PR)** -2. **[US02] Exibição de Ações Corretivas Sugeridas** -3. **[US03] Tratamento de Erros Semânticos no Setup de Ambiente** -4. **[US04] Flag de Saída em Formato Estruturado JSON** -5. **[US05] Identificação Visual de Erros por Cores no Terminal** ---- - -### Justificativa da Escolha da História para o Pull Request (PR) - -A história **US01 (Categorização e Estruturação Semântica de Erros)** foi selecionada de forma estratégica pela dupla para compor a entrega prática do Pull Request do projeto pelas seguintes razões: - -**Núcleo Estrutural:** Esta história atua diretamente no motor central de tratamento de exceções global da ferramenta de linha de comando (CLI). Ela cria a infraestrutura básica necessária para capturar falhas genéricas do sistema operacional e encapsulá-las nas categorias normalizadas. -**Bloqueio de Dependência:** As demais histórias de alta e média prioridade dependem estritamente da existência da US01. Não é semanticamente viável sugerir um comando de correção (US02) ou injetar códigos de escape ANSI de cores (US05) sem que a inteligência de categorização de erros e a separação por subsistemas já estejam consolidadas e operando no fluxo do software. -**Minimização Imediata de Risco:** A implementação da US01 ataca imediatamente a principal causa raiz da frustração e "caixa preta" apontada no mapa de empatia, que é a poluição visual e a falta de clareza das mensagens brutas no terminal. \ No newline at end of file diff --git a/documentacao/requirements/MVP.md b/documentacao/requirements/MVP.md deleted file mode 100644 index a306533a3e64..000000000000 --- a/documentacao/requirements/MVP.md +++ /dev/null @@ -1,48 +0,0 @@ -# Definição do MVP - -## Problema -Issue ([#12266](https://github.com/inventree/InvenTree/issues/12266)) Mesmo com a opção "Initial stock data" habilitada no painel admin, o formulario de criação de peça não exibe campos para informar o estoque inicial. - -## Solução do Problema (MVP) -Exibir o campo de estoque inicial no formulário de criação de Part quando a opção "Initial stock data" estiver habilitada, eliminando a necessidade do lançamento de estoque manual e separado. - -## Descrição do Problema -Ao analizar a branch: `master` encontramos as seguintes informações sobre o problema: -- **Backend:** No backend o campo `initial_stock` já foi criado e implementado, recebendo `quantity` e `location` e criando o `StockItem` junto com a peça. -- **Frontend:** No frontend, o formulário de criação de uma `Part` decide se exibe os campos através o do seguinte trecho de codigo: - -```tsx - // Additional fields for creation - if (create && !virtual) { - fields.copy_category_parameters = {}; - - if (virtual != false) { - fields.initial_stock = { - icon: , - children: { - quantity: { - value: 0 - }, - location: {} - } - }; - } -``` -Assim a condição `!virtual` checa se a peça é **virtual**, mas deveria checar se a configuração global `PART_CREATE_INITIAL` está habilitada, como uma peça que não é virtual nunca satisfaz, logo o `initial_stock` nunca é adicionado ao formulário. - - -## Justificativa de Valor -- Resolver um problema já indicado pela comunidade. -- Escopo pequeno e isolado. -- Impacto direto na experiencia do usuário no fluxo mais básico do sistema - -## Justificativa de Viabilidade -- Área do codigo já mapeada -- Não exige mudança de schema de banco de dados -- Testavel de forma isolada - -## Relação com o JTBD -Esse MVP atende a necessidade de visibilidade clara e confiança que um gerenciador de estoque precisa ter, reduzindo riscos para que aconteça erros na hora de registrar etoque inicial dado a ação de criar uma nova peça. - - - diff --git a/documentacao/requirements/backlog.md b/documentacao/requirements/backlog.md deleted file mode 100644 index dc9585dd452f..000000000000 --- a/documentacao/requirements/backlog.md +++ /dev/null @@ -1,13 +0,0 @@ -## 3.5 Backlog + Priorização (Escopo do MVP) - -A tabela abaixo consolida as 5 histórias de usuário necessárias para compor o MVP, priorizadas com base no valor de entrega para a resolução das dores das nossas personas operacionais. - -| ID | História de Usuário | Prioridade | Estado no MVP | -| :--- | :--- | :--- | :--- | -| **US01** | Como Analista de Suporte, quero visualizar os erros estruturados por categoria, para que eu possa identificar a origem do problema instantaneamente. | Alta | **IMPLEMENTADA NO PR** | -| **US02** | Como Analista de Suporte, quero receber uma sugestão de comando ou ação de correção junto ao log de erro, para que eu consiga resolver o incidente de forma autônoma. | Alta | Integrada ao MVP | -| **US03** | Como Desenvolvedor Iniciante, quero que os erros de setup de ambiente gerem saídas semânticas detalhadas, para que eu não perca tempo com configurações incorretas. | Média | Integrada ao MVP | -| **US04** | Como Analista de Suporte, quero poder exportar os erros estruturados em formato JSON usando uma flag `--json`, para que seja possível integrá-los a outras ferramentas de automação. | Baixa | Integrada ao MVP | -| **US05** | Como Analista de Suporte, quero que as categorias de erros críticos possuam cores distintas no terminal, para que o diagnóstico sob pressão seja facilitado. | Baixa | Integrada ao MVP | - ---- diff --git a/documentacao/requirements/cenarios_de_teste.md b/documentacao/requirements/cenarios_de_teste.md deleted file mode 100644 index 062d6c2b547e..000000000000 --- a/documentacao/requirements/cenarios_de_teste.md +++ /dev/null @@ -1,51 +0,0 @@ -## 3.6 Cenários de Teste - -### US01: Categorização e Estruturação Semântica de Erros -* **História:** Como Analista de Suporte, quero visualizar os erros estruturados por categoria, para que eu possa identificar a origem do problema instantaneamente. -* **Critério:** - Dado que o sistema sofra uma falha interna de comunicação com a base de dados - Quando o comando CLI for executado - Então o terminal deve exibir a saída no padrão rigoroso `[ERRO: ] ` -* **Cenários de teste:** - - Dados válidos → sucesso: Queda do banco simulada gera `[ERRO: BANCO_DE_DADOS] Falha de conexão na porta 5432` - - Dados inválidos/Exceção não mapeada → validação falha: Erro desconhecido gera `[ERRO: SISTEMA_DESCONHECIDO] Ocorreu uma falha interna inesperada` - -### US02: Exibição de Ações Corretivas Sugeridas -* **História:** Como Analista de Suporte, quero receber uma sugestão de comando ou ação de correção junto ao log de erro, para que eu consiga resolver o incidente de forma autônoma. -* **Critério:** - Dado que um log de erro padronizado seja gerado na CLI - Quando a categoria possuir uma solução conhecida pré-documentada - Então o sistema deve exibir uma linha adicional contendo `SUGESTÃO: ` -* **Cenários de teste:** - - Dados válidos → sucesso: Erro de escrita gera `[ERRO: PERMISSAO] Arquivo de config ilegível` seguido de `SUGESTÃO: Execute 'chmod +w '` - - Campo vazio/Solução indisponível → erro: Erro sem tratativa cadastrada omite a linha de sugestão - -### US03: Tratamento de Erros Semânticos no Setup de Ambiente -* **História:** Como Desenvolvedor Iniciante, quero que os erros de setup de ambiente gerem saídas semânticas detalhadas, para que eu não perca tempo com configurações incorretas. -* **Critério:** - Dado que o desenvolvedor execute o script de inicialização do projeto - Quando houver uma dependência ou versão de software desatualizada na máquina hospedeira - Então o script deve interromper a execução e apontar qual dependência causou o problema e a versão mínima exigida -* **Cenários de teste:** - - Dados inválidos/Ambiente defasado → validação falha: Versão do Node antiga interrompe o fluxo e exibe `[ERRO: AMBIENTE] Versão do Node.js incompatível. Encontrada: v14. Requerida: >= v18` - - Dados válidos → sucesso: Todas as dependências corretas permitem que o setup finalize com sucesso - -### US04: Flag de Saída em Formato Estruturado JSON -* **História:** Como Analista de Suporte, quero poder exportar os erros estruturados em formato JSON usando uma flag `--json`, para que seja possível integrá-los a outras ferramentas de automação. -* **Critério:** - Dado que qualquer comando da ferramenta CLI resulte em um erro - Quando o usuário adicionar o parâmetro `--json` ao final da linha de comando - Então o erro não deve ser impresso em texto comum, mas sim como um objeto JSON válido contendo as chaves `"error"`, `"category"`, `"message"` e `"suggestion"` -* **Cenários de teste:** - - Dados válidos → sucesso: Comando com erro executado com `--json` retorna estritamente o objeto `{"error": true, "category": "REDE", "message": "Timeout ao conectar na API"}` - - Campo vazio/Parâmetro ausente → erro: Comando com erro executado sem a flag retorna o log em texto legível padrão da CLI - -### US05: Identificação Visual de Erros por Cores no Terminal -* **História:** Como Analista de Suporte, quero que as categorias de erros críticos possuam cores distintas no terminal, para que o diagnóstico sob pressão seja facilitado. -* **Critério:** - Dado que a CLI esteja rodando em um emulador de terminal compatível com caracteres ANSI - Quando um erro crítico de infraestrutura for disparado - Então o prefixo `[ERRO: CATEGORIA]` deve ser renderizado utilizando a cor correspondente ao nível de severidade estabelecido -* **Cenários de teste:** - - Dados válidos → sucesso: Erro de banco de dados renderiza a tag com o código ANSI para a cor vermelha - - Dados inválidos/Terminal sem suporte → validação falha: Execução em ambiente sem suporte TTY identifica a limitação e remove os caracteres ANSI, exibindo o texto limpo \ No newline at end of file