{
  "id": "tags-financeiras",
  "title": "Tags financeiras",
  "description": "Classificação flexível de transações e itens financeiros.",
  "type": "feature",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "finanças",
    "tags",
    "classificação"
  ],
  "related": [
    "financas",
    "transacoes",
    "relatorios"
  ],
  "sourceRefs": [
    "https://github.com/james-suite/james/blob/master/app/Models/FinancialTag.php",
    "https://github.com/james-suite/james/blob/master/routes/financial.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Visão Geral\n\nAs **Tags Financeiras** substituem o conceito clássico e engessado de \"Categorias\". Elas oferecem liberdade para classificar transações ou itens de transação sob múltiplas perspectivas sem a necessidade de árvores complexas de \"Categoria > Subcategoria\".\n\n## Tabela: `financial_tags`\n\n| Coluna | Tipo | Descrição |\n| --- | --- | --- |\n| `id` | bigint | Chave primária. |\n| `name` | string | Nome identificador único da tag. |\n| `icon` | string | Nome do componente de ícone (ex: `heroicon-o-shopping-cart`, `tabler-basket`, `phosphor-coffee`). |\n| `color_hex` | string | Código de cor hexadecimal associado à tag (ex: `#10b981`). |\n| `is_protected` | boolean | Flag que impede edição ou exclusão das tags obrigatórias do sistema. |\n| `created_at` | timestamp | Data de criação. |\n| `updated_at` | timestamp | Data da última atualização. |\n\n## Tabela Auxiliar: `financial_taggables` (Polimórfica)\n\nPara garantir flexibilidade, a relação é polimórfica através da tabela `financial_taggables`:\n- Diretamente em uma **Transação Completa** (`financial_transactions`).\n- Apenas em um **Item da Transação** (`financial_transaction_items`), ideal para separar impostos, juros e produtos de uma única Nota Fiscal.\n- Possui a coluna booleana `is_primary` para definir qual tag resume a transação nos gráficos de Sankey e Fluxo de Caixa.\n\n## Diagrama Relacional (ER)\n\n{{diagram:tags-model}}\n\n## Regras de Negócio e Comportamento\n\n- **Exclusão Definitiva (Hard Deletes):** Tags não possuem Lixeira (soft deletes). A exclusão é estritamente bloqueada caso a tag já esteja associada a alguma transação ou item. Se ela estiver livre, é deletada definitivamente.\n- **Tags de Sistema Protegidas:** As tags estruturais (ex: *Transferência*, *Reembolso*, *Juros*, *Saldo Inicial*, *Pagamento Parcial*) são semeadas pelo sistema com `is_protected = true`. O usuário não pode deletá-las nem renomeá-las.\n- **Ecossistema Expandido de Ícones (Blade Icons):** O sistema suporta ícones das bibliotecas Heroicons (`heroicon-o-*`), Tabler Icons (`tabler-*`) e Phosphor Icons (`phosphor-*`), validados dinamicamente através da regra `ValidIcon`.\n- **Seeder Flexível:** Ao configurar o ambiente inicial, tags comuns (como *Alimentação*, *Mercado*, *Transporte*, *Moradia*) são criadas desprotegidas via `FinancialTagSeeder`, permitindo personalização livre.\n- **Seleção Avançada na Interface:** A criação de tags disponibiliza um seletor visual de cores e uma busca rápida de ícones com autofoco e renderização instantânea via Ajax.",
  "sections": [
    {
      "id": "visao-geral",
      "level": 2,
      "title": "Visão Geral",
      "text": "As **Tags Financeiras** substituem o conceito clássico e engessado de \"Categorias\". Elas oferecem liberdade para classificar transações ou itens de transação sob múltiplas perspectivas sem a necessidade de árvores complexas de \"Categoria > Subcategoria\".",
      "line": 1
    },
    {
      "id": "tabela-financial-tags",
      "level": 2,
      "title": "Tabela: financial_tags",
      "text": "| Coluna | Tipo | Descrição | | --- | --- | --- | | `id` | bigint | Chave primária. | | `name` | string | Nome identificador único da tag. | | `icon` | string | Nome do componente de ícone (ex: `heroicon-o-shopping-cart`, `tabler-basket`, `phosphor-coffee`). | | `color_hex` | string | Código de cor hexadecimal associado à tag (ex: `#10b981`). | | `is_protected` | boolean | Flag que impede edição ou exclusão das tags obrigatórias do sistema. | | `created_at` | timestamp | Data de criação. | | `updated_at` | timestamp | Data da última atualização. |",
      "line": 5
    },
    {
      "id": "tabela-auxiliar-financial-taggables-polimorfica",
      "level": 2,
      "title": "Tabela Auxiliar: financial_taggables (Polimórfica)",
      "text": "Para garantir flexibilidade, a relação é polimórfica através da tabela `financial_taggables`: - Diretamente em uma **Transação Completa** (`financial_transactions`). - Apenas em um **Item da Transação** (`financial_transaction_items`), ideal para separar impostos, juros e produtos de uma única Nota Fiscal. - Possui a coluna booleana `is_primary` para definir qual tag resume a transação nos gráficos de Sankey e Fluxo de Caixa.",
      "line": 17
    },
    {
      "id": "diagrama-relacional-er",
      "level": 2,
      "title": "Diagrama Relacional (ER)",
      "text": "",
      "line": 24
    },
    {
      "id": "regras-de-negocio-e-comportamento",
      "level": 2,
      "title": "Regras de Negócio e Comportamento",
      "text": "- **Exclusão Definitiva (Hard Deletes):** Tags não possuem Lixeira (soft deletes). A exclusão é estritamente bloqueada caso a tag já esteja associada a alguma transação ou item. Se ela estiver livre, é deletada definitivamente. - **Tags de Sistema Protegidas:** As tags estruturais (ex: *Transferência*, *Reembolso*, *Juros*, *Saldo Inicial*, *Pagamento Parcial*) são semeadas pelo sistema com `is_protected = true`. O usuário não pode deletá-las nem renomeá-las. - **Ecossistema Expandido de Ícones (Blade Icons):** O sistema suporta ícones das bibliotecas Heroicons (`heroicon-o-*`), Tabler Icons (`tabler-*`) e Phosphor Icons (`phosphor-*`), validados dinamicamente através da regra `ValidIcon`. - **Seeder Flexível:** Ao configurar o ambiente inicial, tags comuns (como *Alimentação*, *Mercado*, *Transporte*, *Moradia*) são criadas desprotegidas via `FinancialTagSeeder`, permitindo personalização livre. - **Seleção Avançada na Interface:** A criação de tags disponibiliza um seletor visual de cores e uma busca rápida de ícones com autofoco e renderização instantânea via Ajax.",
      "line": 28
    }
  ],
  "sourcePath": "content/tags-financeiras.md",
  "visuals": [
    {
      "id": "tags-model",
      "kind": "er",
      "title": "Modelo relacional de tags financeiras",
      "description": "Tags se associam a transações e itens por uma relação polimórfica.",
      "summary": "Tags financeiras são ligadas a transações ou itens por FINANCIAL_TAGGABLES, que guarda o tipo polimórfico e o marcador de tag primária.",
      "renderMode": "mermaid",
      "api": "api/diagrams/tags-model.json",
      "human": "diagrams/tags-model.html"
    }
  ],
  "apiVersion": 1
}