# Fraud Rules Seed Plan

## Purpose

Define a repeatable plan for converting `docs/fraud-extension/fraud_rules.csv` into the current Elixir seed schema used by `apps/infra_repo`.

The goal is to keep the data split cleanly between:
- `RiskEntityModel` metadata for entity features
- `RiskActivationRule` / `RiskGatewayRule` definitions for rule logic
- optional transaction feature metadata if needed separately

## Current state

- `fraud_rules.csv` is a combined catalog containing:
  - transaction features (`Risk Level Context = transaction`)
  - entity features (`Risk Level Context = entity`)
  - few rows that can be interpreted as activation or expression rules
- Existing seed logic already supports:
  - `RiskEntityModel` insertion via `apps/infra_repo/priv/repo/seeds/risk_seeds.exs`
  - rule insertion via a separate script, but only when the row has explicit rule fields like `rule_type`, `operator`, or `rule_expression`

## Strategy

### 1. Split the source CSV into derived files

Create derived files from `fraud_rules.csv` so each target schema receives only the rows it needs.

Suggested outputs:

- `docs/fraud-extension/fraud_rule_entity_models.csv`
  - contains rows where `Risk Level Context = entity`
  - includes feature metadata fields: `entity_type`, `horizon`, `metric`, `name`, `description`, `update_strategy`, `active`

- `docs/fraud-extension/fraud_rule_activation_rules.csv`
  - contains rows that represent real rule definitions
  - includes fields: `rule_type`, `name`, `entity_type`, `feature_key`, `operator`, `threshold_value`, `list_values`, `decision`, `priority`, `rule_expression`, `description`

- optionally: `docs/fraud-extension/fraud_rule_transaction_features.csv`
  - contains transaction-only feature rows for documentation or future payload feature catalog needs

### 2. Convert entity feature rows to `RiskEntityModel`

Use a dedicated seeder for derived entity model data.

For each entity row:
- Map `Entity Target` → `entity_type`
- Map `Update Horizon` → `horizon`
- Map `Core Metric Name` → `metric`
- Build `name` from `Full Feature Header` or normalised concatenation
- Determine `update_strategy` from horizon semantics:
  - `1 day, updated daily`, `30 days, updated daily`, `90 days, updated daily` → `batch_daily`
  - `52 weeks, updated weekly`, `4 weeks, updated weekly`, `13 weeks, updated weekly` → `batch_weekly`
  - otherwise → `realtime`
- Set `active: true`

### 3. Convert rule definition rows to `RiskActivationRule` or `RiskGatewayRule`

Use a separate rule seeder for rows with real predicate data.

For each rule row:
- If `rule_expression` exists: insert or update a `RiskActivationRule` with `rule_expression`
- Else if `rule_type` is present: insert a legacy-style rule with `rule_type`, `entity_type`, `feature_key`, `operator`, `threshold_value`, `list_values`, `decision`, `priority`

### 4. Keep the current tracked seed file authoritative

The existing `apps/infra_repo/priv/repo/seeds/risk_seeds.exs` should remain the main seed entrypoint.

New derived seed files should be called from it or documented as additional tracked helpers.

## Proposed file layout

- `docs/fraud-extension/fraud_rule_entity_models.csv`
- `docs/fraud-extension/fraud_rule_activation_rules.csv`
- `apps/infra_repo/priv/repo/seeds/risk_entity_models_from_csv.exs`
- `apps/infra_repo/priv/repo/seeds/risk_rules_from_csv.exs`

## Execution plan

1. Generate derived CSV artifacts from `fraud_rules.csv`.
2. Review the extracted rows for entity vs rule classification.
3. Create/adjust seed scripts for each derived file.
4. Run seeds in a minimal startup environment:
   - start `:logger`, `:postgrex`, `:ecto_sql`
   - start `InfraRepo.Repo`
   - call the seed scripts directly
5. Validate inserted rows with counts and sample queries.

## Verification steps

- Confirm entity model count after seeding
- Confirm rule count after seeding
- Sample inserted records for correct `entity_type`, `horizon`, `metric`, and `feature_key`
- Confirm no transaction-only feature rows were accidentally inserted as entity models

## Notes

- A single sample row from `fraud_rules.csv` demonstrates the approach best.
- `RiskEntityModel` rows should be derived only from `Risk Level Context = entity`.
- Rule ingestion should be explicit and only use CSV rows that include rule predicate data.

## Next action

- I can create the derived CSV files and the corresponding seed script templates now.
- Then we can run one small example row end-to-end to confirm the conversion plan.