Categorize cli errors with fix suggestions (us01/us02)#12414
Open
arthur-wolff wants to merge 7 commits into
Open
Categorize cli errors with fix suggestions (us01/us02)#12414arthur-wolff wants to merge 7 commits into
arthur-wolff wants to merge 7 commits into
Conversation
…S02)` ### 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: <CATEGORIA>] <mensagem> SUGESTAO: <ação corretiva> (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 <comando com falha não mapeada> [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)
✅ Deploy Preview for inventree-web-pui-preview canceled.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
feat(cli): categorize CLI errors with fix suggestions (US01/US02)Problem solved
Today, when an InvenTree
invokecommand fails (e.g.,invoke migrate,invoke server), the only generic handling point (task_exception_handlerintasks.py) only handlesModuleNotFoundErrormanually and prints the raw Python traceback for everything else. This forces whoever is providing support (or a beginner dev setting up the environment) to read a stack trace to understand what actually broke — database down, port in use, file permission, missing dependency, etc. This PR introduces a small, isolated module (cli_error_handling.py) that categorizes the exception and prints standardized output:Relation to the JTBD
JTBD identified in Phase I: "When an error occurs in the CLI, the support analyst/developer wants to understand the root cause immediately, so they don't have to depend on a senior dev or waste time reading tracebacks." This PR directly addresses this job, without touching the application's business logic.
User stories addressed
SuggestionProvideris built alongside the categorizer from the start — see justification indocumentacao/priorizacao_mvp)What changes
Evidence
Automated tests (5/5 passing):
Simulated terminal output:
AI usage
See
documentacao/uso_de_ia— prompts and human refinement decisions documented per item 3.8 of the assignment.