> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Regras de Decisão DMN

> Documentação completa das 16 regras dos módulos Financial Risk, AML e Behavior Score com exemplos de ativação.

O Scoring Engine usa três tabelas de decisão DMN com política `COLLECT + SUM`. Múltiplas regras podem ser ativadas por um único depósito — os pontos são somados em cada módulo antes do cálculo do score final.

<Info>
  Todas as regras são avaliadas com **FEEL** (Friendly Enough Expression Language) conforme a spec DMN 1.3. Intervalos fechados `[a..b]` incluem os extremos; `[a..b)` exclui o limite superior.
</Info>

***

## Módulo 1 — Risco Financeiro

**Decision ID:** `financial-risk-score` · **Peso no score final:** 40%

Avalia o valor do depósito individual, o volume mensal acumulado e a proporção de saques sobre depósitos.

### Regras

| # | ID                            | Condição                          | Pontos | Descrição                                |
| - | ----------------------------- | --------------------------------- | ------ | ---------------------------------------- |
| 1 | `HIGH_SINGLE_DEPOSIT`         | `amount >= 10000`                 | **40** | Depósito individual ≥ R\$ 10.000         |
| 2 | `ELEVATED_SINGLE_DEPOSIT`     | `5000 <= amount < 10000`          | **20** | Depósito individual entre R$ 5k e R$ 10k |
| 3 | `HIGH_MONTHLY_DEPOSIT_VOLUME` | `depositsTotal >= 50000`          | **30** | Volume mensal acumulado ≥ R\$ 50.000     |
| 4 | `ELEVATED_MONTHLY_VOLUME`     | `20000 <= depositsTotal < 50000`  | **15** | Volume mensal entre R$ 20k e R$ 50k      |
| 5 | `EXTREME_WITHDRAWAL_RATIO`    | `0.90 <= withdrawalRatio <= 1.00` | **25** | ≥ 90% do volume depositado foi sacado    |
| 6 | `HIGH_WITHDRAWAL_RATIO`       | `0.70 <= withdrawalRatio < 0.90`  | **15** | Entre 70% e 90% do volume foi sacado     |

<Note>
  `withdrawalRatio` é calculado pelo consumer Go antes da correlação: `withdrawalRatio = withdrawals_total_amount / deposits_total_amount`. Nunca divide por zero — se `deposits_total_amount = 0`, o ratio é `0.0`.
</Note>

### Exemplos — Risco Financeiro

<AccordionGroup>
  <Accordion title="Exemplo 1 — Score ZERO (sem triggers)">
    **Perfil:** Jogador recreativo, depósito pequeno, volume mensal baixo, sem saques expressivos.

    ```json theme={null}
    {
      "amount": 150.00,
      "deposits_total_amount": 800.00,
      "withdrawals_total_amount": 40.00
    }
    ```

    | Variável Camunda  | Valor  | Regras ativadas     |
    | ----------------- | ------ | ------------------- |
    | `amount`          | 150.00 | nenhuma (\< 5.000)  |
    | `depositsTotal`   | 800.00 | nenhuma (\< 20.000) |
    | `withdrawalRatio` | 0.05   | nenhuma (\< 0.70)   |

    **`scoresFinancial = 0`**
  </Accordion>

  <Accordion title="Exemplo 2 — Score MÁXIMO (todos os triggers)">
    **Perfil:** Depósito acima do COAF, volume mensal altíssimo, ratio de saque extremo.

    ```json theme={null}
    {
      "amount": 35000.00,
      "deposits_total_amount": 80000.00,
      "withdrawals_total_amount": 76000.00
    }
    ```

    | Variável Camunda  | Valor  | Regras ativadas                        | Pontos |
    | ----------------- | ------ | -------------------------------------- | ------ |
    | `amount`          | 35.000 | `HIGH_SINGLE_DEPOSIT` (≥ 10k)          | +40    |
    | `depositsTotal`   | 80.000 | `HIGH_MONTHLY_DEPOSIT_VOLUME` (≥ 50k)  | +30    |
    | `withdrawalRatio` | 0.95   | `EXTREME_WITHDRAWAL_RATIO` (\[0.9..1]) | +25    |

    **`scoresFinancial = 95`**

    > **Interpretação de risco:** Depósito de R\$ 35k com 95% sacado no mesmo mês é um padrão clássico de **layering** — o dinheiro passa pela plataforma sem finalidade legítima de jogo, apenas para obter histórico de transação "limpo".
  </Accordion>

  <Accordion title="Exemplo 3 — Risco Moderado (apostador regular elevado)">
    **Perfil:** Usuário frequente com depósitos médios e padrão saudável de saques.

    ```json theme={null}
    {
      "amount": 7500.00,
      "deposits_total_amount": 35000.00,
      "withdrawals_total_amount": 26250.00
    }
    ```

    | Variável Camunda  | Valor  | Regras ativadas                         | Pontos |
    | ----------------- | ------ | --------------------------------------- | ------ |
    | `amount`          | 7.500  | `ELEVATED_SINGLE_DEPOSIT` (\[5k..10k))  | +20    |
    | `depositsTotal`   | 35.000 | `ELEVATED_MONTHLY_VOLUME` (\[20k..50k)) | +15    |
    | `withdrawalRatio` | 0.75   | `HIGH_WITHDRAWAL_RATIO` (\[0.7..0.9))   | +15    |

    **`scoresFinancial = 50`**
  </Accordion>
</AccordionGroup>

***

## Módulo 2 — PLD / AML

**Decision ID:** `aml-rules` · **Peso no score final:** 30%

Implementa as obrigações da **Lei 9.613/98**, **Circular BACEN 3.978/2020** e **COAF Resolution 36/2021**. Avalia indicadores de lavagem de dinheiro com ênfase em operações de alto valor, ausência de KYC e redes de contas suspeitas.

### Regras

| # | ID                            | Condições                                                   | Pontos | Base Regulatória                                   |
| - | ----------------------------- | ----------------------------------------------------------- | ------ | -------------------------------------------------- |
| 1 | `COAF_HIGH_SINGLE_DEPOSIT`    | `amount >= 30000`                                           | **40** | Obrigação de reporte COAF (art. 4º Circular 3.978) |
| 2 | `MULTIPLE_LINKED_ACCOUNTS`    | `hasLinkedAccounts = true` E `linkedAccountsCount >= 5`     | **35** | Padrão de smurfing / fragmentação                  |
| 3 | `HIGH_AMOUNT_NO_KYC`          | `amount >= 10000` E `kycStatus IN ("", "pending")`          | **25** | Operação de alto valor sem due diligence           |
| 4 | `LINKED_ACCOUNT_SIGNAL`       | `hasLinkedAccounts = true` E `1 <= linkedAccountsCount < 5` | **15** | Sinal inicial de contas vinculadas                 |
| 5 | `DEPOSIT_WITH_LINKED_ACCOUNT` | `amount >= 5000` E `hasLinkedAccounts = true`               | **10** | Depósito relevante com qualquer conta vinculada    |

### Conceitos das Regras

**Contas vinculadas** são detectadas por IPS (IP/device fingerprint compartilhado). O campo `ips.linked_accounts` contém os `user_ext_id` das contas que compartilham o mesmo dispositivo ou endereço IP recente.

**Smurfing** é a técnica de fragmentar operações entre múltiplas contas para ficar abaixo dos limiares de reporte. A presença de 5+ contas vinculadas é um indicador forte desse padrão.

**KYC pendente** em operações de alto valor indica que o operador aceitou um depósito relevante antes de completar a identificação do usuário — violação potencial das obrigações de "conheça seu cliente".

### Exemplos — PLD / AML

<AccordionGroup>
  <Accordion title="Exemplo 1 — Score ZERO (usuário verificado, isolado)">
    **Perfil:** Usuário com KYC aprovado, sem contas vinculadas, depósito dentro do normal.

    ```json theme={null}
    {
      "amount": 500.00,
      "kyc_status": "approved",
      "ips": {
        "has_linked_accounts": false,
        "linked_accounts_count": 0,
        "linked_accounts": []
      }
    }
    ```

    | Variável Camunda    | Valor      | Regras ativadas               |
    | ------------------- | ---------- | ----------------------------- |
    | `amount`            | 500        | nenhuma (\< 5.000 com linked) |
    | `kycStatus`         | "approved" | nenhuma                       |
    | `hasLinkedAccounts` | false      | nenhuma                       |

    **`scoresAml = 0`**
  </Accordion>

  <Accordion title="Exemplo 2 — Score MÁXIMO (lavagem clássica)">
    **Perfil:** Depósito COAF, KYC pendente, 7 contas no mesmo dispositivo.

    ```json theme={null}
    {
      "amount": 35000.00,
      "kyc_status": "pending",
      "ips": {
        "has_linked_accounts": true,
        "linked_accounts_count": 7,
        "linked_accounts": ["user_a1b2...", "user_c3d4...", "..."]
      }
    }
    ```

    | Variável Camunda                            | Valor          | Regras ativadas                      | Pontos |
    | ------------------------------------------- | -------------- | ------------------------------------ | ------ |
    | `amount`                                    | 35.000         | `COAF_HIGH_SINGLE_DEPOSIT` (≥ 30k)   | +40    |
    | `hasLinkedAccounts` + `linkedAccountsCount` | true, 7        | `MULTIPLE_LINKED_ACCOUNTS` (≥ 5)     | +35    |
    | `amount` + `kycStatus`                      | 35k, "pending" | `HIGH_AMOUNT_NO_KYC` (≥ 10k sem KYC) | +25    |
    | `hasLinkedAccounts` + `amount`              | true, 35k      | `DEPOSIT_WITH_LINKED_ACCOUNT` (≥ 5k) | +10    |

    **`scoresAml = 110`** *(capped em 100 no score final ponderado)*

    > **Interpretação de risco:** Combinação perfeita das três fases de lavagem: **placement** (depósito em cash equivalente), **layering** (múltiplas contas fragmentando a origem) e ausência de KYC que dificultaria rastreamento. Reporte COAF obrigatório.
  </Accordion>

  <Accordion title="Exemplo 3 — Sinal de alerta (linked accounts sem grandes valores)">
    **Perfil:** Usuário com 3 contas vinculadas, KYC aprovado, depósito moderado.

    ```json theme={null}
    {
      "amount": 8000.00,
      "kyc_status": "approved",
      "ips": {
        "has_linked_accounts": true,
        "linked_accounts_count": 3,
        "linked_accounts": ["user_x1...", "user_x2...", "user_x3..."]
      }
    }
    ```

    | Variável Camunda                            | Valor    | Regras ativadas                      | Pontos |
    | ------------------------------------------- | -------- | ------------------------------------ | ------ |
    | `hasLinkedAccounts` + `linkedAccountsCount` | true, 3  | `LINKED_ACCOUNT_SIGNAL` (\[1..5))    | +15    |
    | `amount` + `hasLinkedAccounts`              | 8k, true | `DEPOSIT_WITH_LINKED_ACCOUNT` (≥ 5k) | +10    |

    **`scoresAml = 25`**

    > **Interpretação:** Poderia ser uma família compartilhando dispositivo. Score baixo, mas merece monitoramento — especialmente se o volume de depósitos crescer.
  </Accordion>
</AccordionGroup>

***

## Módulo 3 — Comportamento / Ludopatia

**Decision ID:** `behavior-score` · **Peso no score final:** 30%

Detecta padrões comportamentais associados a jogo problemático (ludopatia) e uso intensivo que pode indicar transtorno de jogo. Alinhado às diretrizes da **Portaria SPA/MF nº 827/2024** sobre jogo responsável.

### Regras

| # | ID                          | Condições                                                                      | Pontos | Sinal Detectado                              |
| - | --------------------------- | ------------------------------------------------------------------------------ | ------ | -------------------------------------------- |
| 1 | `HIGH_SPORTS_BETTING_RISK`  | `sportsBetsHigh = true`                                                        | **20** | Volume de apostas esportivas ≥ R\$ 2.000/mês |
| 2 | `HIGH_CASINO_BETTING_RISK`  | `casinoBetsHigh = true`                                                        | **25** | Volume de apostas em cassino ≥ R\$ 2.000/mês |
| 3 | `COMBINED_BETTING_PATTERN`  | `sportsBetsHigh = true` E `casinoBetsHigh = true`                              | **15** | Combinação de alto risco esportivo e cassino |
| 4 | `HIGH_WINNINGS`             | `hasWinnings = true` E `winningsTotalAmount >= 10000`                          | **20** | Ganhos acima de R\$ 10.000                   |
| 5 | `CASINO_WITH_HIGH_WINNINGS` | `casinoBetsHigh = true` E `hasWinnings = true` E `winningsTotalAmount >= 5000` | **10** | Cassino alto + ganhos expressivos            |

### Definição dos flags de volume

Os flags `sportsBetsHigh`, `casinoBetsHigh`, `sportsBetsModerate` e `sportsBetsLow` são computados pelo consumer antes de enviados ao Camunda:

| Flag                   | Condição de ativação                                                 |
| ---------------------- | -------------------------------------------------------------------- |
| `sports_bets_high`     | `has_sports_bets = true` E `sports_bets_total_amount >= 2.000`       |
| `sports_bets_moderate` | `has_sports_bets = true` E `500 <= sports_bets_total_amount < 2.000` |
| `sports_bets_low`      | `has_sports_bets = true` E `sports_bets_total_amount < 500`          |
| `casino_bets_high`     | `has_casino_bets = true` E `casino_bets_total_amount >= 2.000`       |
| `casino_bets_moderate` | `has_casino_bets = true` E `500 <= casino_bets_total_amount < 2.000` |
| `casino_bets_low`      | `has_casino_bets = true` E `casino_bets_total_amount < 500`          |

### Exemplos — Comportamento

<AccordionGroup>
  <Accordion title="Exemplo 1 — Score ZERO (lazer saudável)">
    **Perfil:** Apostas esportivas leves, sem cassino, sem ganhos expressivos.

    ```json theme={null}
    {
      "has_sports_bets": true,
      "sports_bets_total_amount": 80.00,
      "sports_bets_high": false,
      "sports_bets_moderate": false,
      "sports_bets_low": true,
      "has_casino_bets": false,
      "casino_bets_high": false,
      "has_winnings": false,
      "winnings_total_amount": 0.00
    }
    ```

    | Variável Camunda | Valor | Regras ativadas |
    | ---------------- | ----- | --------------- |
    | `sportsBetsHigh` | false | nenhuma         |
    | `casinoBetsHigh` | false | nenhuma         |
    | `hasWinnings`    | false | nenhuma         |

    **`scoresBehavior = 0`**
  </Accordion>

  <Accordion title="Exemplo 2 — Score MÁXIMO (ludopatia severa)">
    **Perfil:** Alto volume em esportes e cassino, ganhos de R\$ 12k — padrão de jogo compulsivo.

    ```json theme={null}
    {
      "has_sports_bets": true,
      "sports_bets_total_amount": 5000.00,
      "sports_bets_high": true,
      "has_casino_bets": true,
      "casino_bets_total_amount": 4500.00,
      "casino_bets_high": true,
      "has_winnings": true,
      "winnings_total_amount": 12000.00,
      "winnings_high": true
    }
    ```

    | Variável Camunda                                         | Valor           | Regras ativadas                    | Pontos |
    | -------------------------------------------------------- | --------------- | ---------------------------------- | ------ |
    | `sportsBetsHigh`                                         | true            | `HIGH_SPORTS_BETTING_RISK`         | +20    |
    | `casinoBetsHigh`                                         | true            | `HIGH_CASINO_BETTING_RISK`         | +25    |
    | `sportsBetsHigh` + `casinoBetsHigh`                      | true + true     | `COMBINED_BETTING_PATTERN`         | +15    |
    | `hasWinnings` + `winningsTotalAmount`                    | true, 12.000    | `HIGH_WINNINGS` (≥ 10k)            | +20    |
    | `casinoBetsHigh` + `hasWinnings` + `winningsTotalAmount` | true, true, 12k | `CASINO_WITH_HIGH_WINNINGS` (≥ 5k) | +10    |

    **`scoresBehavior = 90`**

    > **Interpretação de risco:** Volume de apostas incompatível com a renda típica, combinação esportes+cassino (multimodal compulsive gambling) e ganhos de R\$ 12k em cassino online são vetores clássicos de **integração** na lavagem e de jogo compulsivo severo. Intervenção de jogo responsável recomendada.
  </Accordion>

  <Accordion title="Exemplo 3 — Risco Moderado (cassino recreativo com algum ganho)">
    **Perfil:** Apostas de cassino moderadas com ganho relevante.

    ```json theme={null}
    {
      "has_sports_bets": false,
      "sports_bets_high": false,
      "has_casino_bets": true,
      "casino_bets_total_amount": 2500.00,
      "casino_bets_high": true,
      "has_winnings": true,
      "winnings_total_amount": 6000.00,
      "winnings_moderate": true
    }
    ```

    | Variável Camunda                                         | Valor          | Regras ativadas                    | Pontos |
    | -------------------------------------------------------- | -------------- | ---------------------------------- | ------ |
    | `casinoBetsHigh`                                         | true           | `HIGH_CASINO_BETTING_RISK`         | +25    |
    | `casinoBetsHigh` + `hasWinnings` + `winningsTotalAmount` | true, true, 6k | `CASINO_WITH_HIGH_WINNINGS` (≥ 5k) | +10    |

    **`scoresBehavior = 35`**
  </Accordion>
</AccordionGroup>

***

## Cenário Completo: Low Risk vs. High Risk

A tabela abaixo resume como os dois perfis de teste do `make kafka-produce` ativam as regras DMN:

### Perfil LOW RISK — Jogador Recreativo

| Módulo          | Regras ativadas               | Sub-score |
| --------------- | ----------------------------- | --------- |
| Financial Risk  | nenhuma                       | **0**     |
| AML Rules       | nenhuma                       | **0**     |
| Behavior Score  | nenhuma                       | **0**     |
| **Score Final** | `0 × 0.4 + 0 × 0.3 + 0 × 0.3` | **0**     |

```json theme={null}
{
  "amount": 150.00,
  "deposits_total_amount": 800.00,
  "withdrawals_total_amount": 40.00,
  "kyc_status": "approved",
  "ips": { "has_linked_accounts": false, "linked_accounts_count": 0 },
  "sports_bets_total_amount": 80.00, "sports_bets_low": true,
  "has_casino_bets": false,
  "has_winnings": false
}
```

***

### Perfil HIGH RISK — Indicadores Máximos

| Módulo          | Regras ativadas                                                                                                                        | Pontos         | Sub-score |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------- |
| Financial Risk  | HIGH\_SINGLE\_DEPOSIT + HIGH\_MONTHLY\_DEPOSIT\_VOLUME + EXTREME\_WITHDRAWAL\_RATIO                                                    | 40+30+25       | **95**    |
| AML Rules       | COAF\_HIGH\_SINGLE\_DEPOSIT + MULTIPLE\_LINKED\_ACCOUNTS + HIGH\_AMOUNT\_NO\_KYC + DEPOSIT\_WITH\_LINKED\_ACCOUNT                      | 40+35+25+10    | **110**   |
| Behavior Score  | HIGH\_SPORTS\_BETTING\_RISK + HIGH\_CASINO\_BETTING\_RISK + COMBINED\_BETTING\_PATTERN + HIGH\_WINNINGS + CASINO\_WITH\_HIGH\_WINNINGS | 20+25+15+20+10 | **90**    |
| **Score Final** | `95 × 0.4 + 110 × 0.3 + 90 × 0.3`                                                                                                      | = 38+33+27     | **98**    |

```json theme={null}
{
  "amount": 35000.00,
  "deposits_total_amount": 80000.00,
  "withdrawals_total_amount": 76000.00,
  "kyc_status": "pending",
  "ips": { "has_linked_accounts": true, "linked_accounts_count": 7 },
  "sports_bets_total_amount": 5000.00, "sports_bets_high": true,
  "casino_bets_total_amount": 4500.00, "casino_bets_high": true,
  "has_winnings": true, "winnings_total_amount": 12000.00, "winnings_high": true
}
```

<Warning>
  Score acima de **75** indica risco crítico. Recomenda-se revisão manual imediata, bloqueio preventivo de saques e avaliação de reporte ao COAF.
</Warning>