Luiz Silva
bf9be375e2
- 55 arquivos .md renomeados para sem extensão - Convenção: artefatos de conhecimento sem extensão, scripts (.sh) e dados (.json) mantêm extensão - Scripts atualizados: gerar-manifesto.sh, atualizar-agente.sh, atualizar-agente.global.sh, gerar-agent-json.sh, verificar-linhas.sh - Documentação reescrita: AGENTS, README, EXTEND para refletir uso como submodule .agent direto - manifesto.json regenerado v3.0.0 - Todas as referências internas entre artefatos atualizadas BREAKING CHANGE: arquivos não possuem mais extensão .md
123 lines
3.8 KiB
Text
123 lines
3.8 KiB
Text
---
|
|
type: rule
|
|
name: mensagens-usuario
|
|
description: Toda mensagem visível ao usuário final deve ser escrita em linguagem do domínio, sem termos técnicos de TI
|
|
scope: global
|
|
trigger: file_match
|
|
globs:
|
|
- "**/*.vue"
|
|
- "**/*.ts"
|
|
- "**/*.tsx"
|
|
updatedAt: "2026-06-01"
|
|
---
|
|
|
|
# Regra: Mensagens Orientadas ao Domínio
|
|
|
|
## Contexto
|
|
|
|
O usuário final dos módulos SaaS é profissional de **engenharia, ciência ou gestão ambiental**. Ele entende de legislação, processos técnicos e ciência aplicada — mas **não tem obrigação de entender tecnologia**.
|
|
|
|
Toda mensagem visível na interface — erro, validação, confirmação, tooltip, empty state, ajuda — deve ser escrita na linguagem do domínio do módulo.
|
|
|
|
## Regra
|
|
|
|
### 1. Erros de validação devem indicar O QUE preencher, não O QUE falhou
|
|
|
|
```typescript
|
|
// ❌ ERRADO — linguagem técnica
|
|
"Campo obrigatório"
|
|
"Erro de validação"
|
|
"Formato inválido"
|
|
"Payload inválido"
|
|
|
|
// ✅ CORRETO — linguagem do domínio
|
|
"Informe a Área do Empreendimento (em hectares)"
|
|
"Selecione o Tipo de Licença: LP, LI ou LO"
|
|
"A Data da Vistoria deve ser anterior à data atual"
|
|
"Informe o CNPJ no formato 00.000.000/0000-00"
|
|
```
|
|
|
|
### 2. Erros de sistema devem ser traduzidos para o usuário
|
|
|
|
```typescript
|
|
// ❌ ERRADO — erro técnico exposto
|
|
"Erro 500: Internal Server Error"
|
|
"Timeout na requisição"
|
|
"Network Error"
|
|
"ECONNREFUSED"
|
|
|
|
// ✅ CORRETO — mensagem humanizada
|
|
"Não foi possível salvar. Tente novamente em instantes."
|
|
"A operação demorou mais que o esperado. Tente novamente."
|
|
"Sem conexão com o servidor. Verifique sua internet."
|
|
```
|
|
|
|
### 3. Estados vazios devem explicar o contexto
|
|
|
|
Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário:
|
|
|
|
```typescript
|
|
// ❌ ERRADO — genérico
|
|
"Nenhum registro encontrado"
|
|
"Lista vazia"
|
|
|
|
// ✅ CORRETO — explica o domínio e orienta
|
|
"Nenhuma condicionante cadastrada para esta licença."
|
|
"Nenhum relatório de monitoramento registrado neste período."
|
|
"Nenhum empreendimento encontrado com os filtros aplicados. Tente ampliar a busca."
|
|
```
|
|
|
|
### 4. Confirmações devem descrever a consequência
|
|
|
|
```typescript
|
|
// ❌ ERRADO — genérico
|
|
"Tem certeza que deseja excluir?"
|
|
"Confirmar operação?"
|
|
|
|
// ✅ CORRETO — descreve o impacto
|
|
"Excluir esta condicionante? O prazo de cumprimento e os documentos vinculados serão removidos."
|
|
"Arquivar esta licença? Ela não aparecerá mais nas listagens ativas."
|
|
```
|
|
|
|
### 5. Labels e placeholders devem usar vocabulário do domínio
|
|
|
|
```typescript
|
|
// ❌ ERRADO — genérico
|
|
label: "Nome"
|
|
placeholder: "Digite aqui"
|
|
|
|
// ✅ CORRETO — específico do domínio
|
|
label: "Razão Social do Empreendedor"
|
|
placeholder: "Ex: Mineração Vale Verde Ltda."
|
|
|
|
label: "Área Total do Empreendimento"
|
|
placeholder: "Em hectares (ex: 150,5)"
|
|
```
|
|
|
|
### 6. Schemas Zod devem ter mensagens de domínio
|
|
|
|
```typescript
|
|
// ❌ ERRADO — mensagens padrão do Zod
|
|
const zEmpreendimento = z.object({
|
|
nome: z.string().min(1), // "String must contain at least 1 character(s)"
|
|
area: z.number().positive(), // "Number must be greater than 0"
|
|
})
|
|
|
|
// ✅ CORRETO — mensagens customizadas
|
|
const zEmpreendimento = z.object({
|
|
nome: z.string().min(1, "Informe o nome do empreendimento"),
|
|
area: z.number({ invalid_type_error: "A área deve ser um número" })
|
|
.positive("A área deve ser maior que zero"),
|
|
cnpj: z.string().regex(/^\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}$/,
|
|
"CNPJ inválido. Use o formato 00.000.000/0000-00"),
|
|
})
|
|
```
|
|
|
|
## Impacto
|
|
|
|
Sem esta regra, o agente gera mensagens técnicas que confundem gestores ambientais, consultores e técnicos de campo — forçando a equipe de suporte a traduzir erros de sistema para o vocabulário do cliente.
|
|
|
|
## Referências
|
|
|
|
- Rule: `global/rules/zod-validacao-padrao` (schemas com mensagens customizadas)
|
|
- Workflow: `global/workflows/ux` (design de interface)
|