{
  "id": "helper-currencyhelper",
  "title": "Helper — CurrencyHelper",
  "description": "Formatação de valores monetários usando locale e moeda configurados.",
  "type": "technical-reference",
  "status": "implemented",
  "visibility": "public",
  "tags": [
    "sge/helpers",
    "sge/formatacao"
  ],
  "related": [
    "helper-funcoes-globais",
    "providers",
    "helpers"
  ],
  "sourceRefs": [
    "https://github.com/sge-suite/sge/blob/master/app/Helpers/CurrencyHelper.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Responsabilidade\n\nClasse final com um método estático para formatar moeda usando `Illuminate\\Support\\Number::currency`.\n\n| Método      | Entrada | Saída                                                              |\n| ----------- | ------- | ------------------------------------------------------------------ |\n| `format(int | float   | null $value, string $currency = 'BRL', ?string $locale = 'pt_BR')` | número, `null`, código ISO e locale | string formatada; `null` vira zero e falha do formatter vira string vazia. |\n\nExemplo esperado em `pt_BR`: `formatCurrency(1234.5)` → `R$ 1.234,50`, conforme o formatter do Laravel.\n\n## Decisões\n\n- O padrão é BRL/`pt_BR`.\n- O locale pode ser sobrescrito por chamada.\n- O `AppServiceProvider` também configura locale e moeda globais.\n- O helper é apenas de apresentação; não deve converter valor para centavos nem persistir dinheiro.\n\n## Checklist\n\n- [x] Implementar `format()` com `Number::currency`.\n- [x] Tratar `null` como zero.\n- [x] Expor `formatCurrency()` em `app/helpers.php`.\n- [ ] Cobrir o helper diretamente com testes de BRL, locale alternativo, zero, negativo e `null`.\n- [ ] Confirmar se falha deve retornar `''` ou gerar erro observável.\n- [ ] Documentar o formato monetário adotado no domínio quando valores forem adicionados.\n\n## Relacionamentos\n\n- [Funções globais](doc:helper-funcoes-globais)\n- [Providers](doc:providers)\n- [Helpers](doc:helpers)",
  "sections": [
    {
      "id": "responsabilidade",
      "level": 2,
      "title": "Responsabilidade",
      "text": "Classe final com um método estático para formatar moeda usando `Illuminate\\Support\\Number::currency`.  | Método      | Entrada | Saída                                                              | | ----------- | ------- | ------------------------------------------------------------------ | | `format(int | float   | null $value, string $currency = 'BRL', ?string $locale = 'pt_BR')` | número, `null`, código ISO e locale | string formatada; `null` vira zero e falha do formatter vira string vazia. |  Exemplo esperado em `pt_BR`: `formatCurrency(1234.5)` → `R$ 1.234,50`, conforme o formatter do Laravel.",
      "line": 1
    },
    {
      "id": "decisoes",
      "level": 2,
      "title": "Decisões",
      "text": "- O padrão é BRL/`pt_BR`. - O locale pode ser sobrescrito por chamada. - O `AppServiceProvider` também configura locale e moeda globais. - O helper é apenas de apresentação; não deve converter valor para centavos nem persistir dinheiro.",
      "line": 11
    },
    {
      "id": "checklist",
      "level": 2,
      "title": "Checklist",
      "text": "- [x] Implementar `format()` com `Number::currency`. - [x] Tratar `null` como zero. - [x] Expor `formatCurrency()` em `app/helpers.php`. - [ ] Cobrir o helper diretamente com testes de BRL, locale alternativo, zero, negativo e `null`. - [ ] Confirmar se falha deve retornar `''` ou gerar erro observável. - [ ] Documentar o formato monetário adotado no domínio quando valores forem adicionados.",
      "line": 18
    },
    {
      "id": "relacionamentos",
      "level": 2,
      "title": "Relacionamentos",
      "text": "- [Funções globais](doc:helper-funcoes-globais) - [Providers](doc:providers) - [Helpers](doc:helpers)",
      "line": 27
    }
  ],
  "sourcePath": "content/helper-currencyhelper.md",
  "visuals": [],
  "apiVersion": 1
}