---
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: glob
globs: "**/*.vue, **/*.ts, **/*.tsx"
updatedAt: "2026-09-28"
---

# 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)