# Risk Rules Implementation Status Report
**Generated:** March 27, 2026  
**Database:** shukria_transactions.risk_rules  
**Evaluation Code:** apps/risk_core/lib/risk_core/context.ex

---

## Executive Summary

**Total Rules in Database:** 46 rules per category (184 total across 4 categories)  
**Rules with Implementation:** 36 rules (78%)  
**Rules WITHOUT Implementation:** 10 rules (22%)  
**Critical Issue:** All missing rules are ENABLED in database but will return `:no_hit`

---

## ⚠️ CRITICAL ISSUE: Rules Enabled Without Code

The following **10 rules are ENABLED in the database** but have **NO evaluation code implemented**:

| Order | Rule Name | Status | Impact |
|-------|-----------|--------|--------|
| 9 | Suspicious High Value (10000 AED) Transaction | ❌ NO CODE | Will not trigger |
| 10 | High Frequency Chargeback Merchant's | ❌ NO CODE | Will not trigger |
| 11 | High Transactions Decline Rate Merchant's | ❌ NO CODE | Will not trigger |
| 12 | Round Figure Transaction using same card at Multiple Merchants | ❌ NO CODE | Will not trigger |
| 21 | Excessive Refunds or Reversals | ❌ NO CODE | Will not trigger |
| 26 | Sudden Drop in Daily Transaction Volume | ❌ NO CODE | Will not trigger |
| 27 | Significant Decrease in Weekly/Monthly Volume | ❌ NO CODE | Will not trigger |
| 31 | AML - Local transaction higher than 50K | ❌ NO CODE | Will not trigger |
| 32 | AML - Local transaction higher than 100K | ❌ NO CODE | Will not trigger |
| 39 | International BIN ( International Trax 100% 1 day) | ❌ NO CODE | Will not trigger |

**Consequences:**
- Transactions matching these rules will NOT be flagged
- Risk management gaps in AML monitoring
- Compliance issues with insufficient transaction monitoring
- False sense of security (rules appear enabled but are non-functional)

---

## How Rule Matching Works

The evaluation system uses **EXACT STRING MATCHING** on rule names:

```elixir
def evaluate_single_rule(%RiskRule{} = rule, transaction, transaction_type) do
  case rule.name do
    "Suspicious International transactions" -> evaluate_suspicious_international_rule(...)
    "Multiple Int'l card, low value" -> evaluate_multiple_international_rule(...)
    # ... more rules ...
    _ -> :no_hit  # ⚠️ NO IMPLEMENTATION - RULE IGNORED
  end
end
```

**If rule name doesn't match exactly, it returns `:no_hit` and the rule is skipped.**

---

## Complete Implementation Status (All 46 Rules)

### ✅ Implemented Rules (36 rules)

| Order | Database Name | Code Name | Match Type |
|-------|---------------|-----------|------------|
| 1 | Suspicious International transactions | Same | Exact ✅ |
| 2 | Suspicious-Multiple International card transactions for low values | Multiple Int'l card, low value | Similar ⚠️ |
| 3 | Suspicious-Abnormal Time transaction | Abnormal Time transaction | Similar ⚠️ |
| 4 | Suspicious-Split transaction | Split transaction | Similar ⚠️ |
| 5 | Suspicious-Duplicate transaction | Duplicate transaction | Similar ⚠️ |
| 6 | Suspicious-High Velocity transaction | High Velocity transaction | Similar ⚠️ |
| 7 | Transactions above-average ticket size | Above-average ticket size | Similar ⚠️ |
| 8 | Dormant Merchant | Same | Exact ✅ |
| 13 | Round Figure Transaction on same Terminal | Same | Exact ✅ |
| 14 | Transaction followed by Fraud-Suspect declined transaction with Same Card | Transaction followed by Fraud-Suspect declined (Same Card) | Similar ⚠️ |
| 15 | Transaction followed by Fraud-Suspect declined transaction with different Card but same amount | Transaction followed by Fraud-Suspect declined (Different Card) | Similar ⚠️ |
| 16 | Transaction followed by Suspect declined transaction wrong PIN entry attempts | Transaction followed by Wrong PIN Entry Attempts | Similar ⚠️ |
| 17 | Daily volume above daily average volume of a Merchant | Daily Volume Above Average (4x) | Similar ⚠️ |
| 18 | Multiple Transactions Same Amount | Same | Exact ✅ |
| 19 | Transactions done by Self Card of the Merchants | Self Card Transactions by Merchant | Similar ⚠️ |
| 20 | Out-of-Profile Geographic Behavior (Domestic to International Shift) | Out-of-Profile Geographic Shift (Domestic to International) | Similar ⚠️ |
| 22 | High Chargeback Rate | High Chargeback Rate (>1%) | Similar ⚠️ |
| 23 | High Fraud Rate | High Fraud Rate (>0.5%) | Similar ⚠️ |
| 24 | Round or Unusual Amount Patterns | Round or Unusual Amount Patterns (Alert) | Similar ⚠️ |
| 25 | High Decline/Authorization Failure Rate | High Decline/Authorization Failure Rate (>20%) | Similar ⚠️ |
| 28 | Declines of high value Fallback transactions | Machines of High Value Fallback Transactions | Similar ⚠️ |
| 29 | Decline Transaction Monitoring | Same | Exact ✅ |
| 30 | New Onboarded Merchant High Decline | Same | Exact ✅ |
| 33 | AML - Local transaction higher than 400K | MI - Local Transaction Higher than 400K | Similar ⚠️ |
| 34 | AML - International transaction higher than 100K | MI - International Transaction Higher than 100K | Similar ⚠️ |
| 35 | AML - International transaction higher than 25K | MI - International Transaction Higher than 25K | Similar ⚠️ |
| 36 | AML - 10 cards same BIN | MV - 10 Cards Same BIN | Similar ⚠️ |
| 37 | AML - 20 cards same BIN | MH - 20 Cards Same BIN | Similar ⚠️ |
| 38 | AML - Daily amount limit per card ( Accumulated 25k Day) | MI - Daily Amount Limit Per Card | Similar ⚠️ |
| 40 | High Value Transaction on New Merchant (First 90 Days) | Same | Exact ✅ |
| 41 | AML Suspicious International Transaction | MI - Suspicious International Transaction (High-Risk Countries) | Similar ⚠️ |
| 42 | Suspicious domestic/international high value tranx for manual entry ( Key-IN) | Suspicious High Value Manual Entry | Similar ⚠️ |
| 43 | New onboarded merchant International Card ( Min 90 days ) | New Merchant International Card (First 50 Days) | Similar ⚠️ |
| 44 | Expired Card Reuse at Same Merchant | Same | Exact ✅ |
| 45 | High Amount of Aggregative Refunds | Same | Exact ✅ |
| 46 | To alert high value refund of greater than 5000 which should include only refund transaction | High Value Single Refund Alert | Similar ⚠️ |

**Legend:**
- ✅ **Exact** = Names match exactly, rule will work
- ⚠️ **Similar** = Implementation exists but names DON'T match, rule will return `:no_hit`

### ❌ NOT Implemented Rules (10 rules)

| Order | Rule Name | Description | Criticality |
|-------|-----------|-------------|-------------|
| 9 | Suspicious High Value (10000 AED) Transaction | Flag transactions above 10K AED | HIGH |
| 10 | High Frequency Chargeback Merchant's | Track merchants with frequent chargebacks | HIGH |
| 11 | High Transactions Decline Rate Merchant's | Monitor merchants with high decline rates | MEDIUM |
| 12 | Round Figure Transaction using same card at Multiple Merchants | Detect round amounts across merchants | MEDIUM |
| 21 | Excessive Refunds or Reversals | Track unusual refund patterns | HIGH |
| 26 | Sudden Drop in Daily Transaction Volume | Detect sudden volume drops | MEDIUM |
| 27 | Significant Decrease in Weekly/Monthly Volume | Monitor volume trends | MEDIUM |
| 31 | AML - Local transaction higher than 50K | AML threshold monitoring (50K AED) | CRITICAL |
| 32 | AML - Local transaction higher than 100K | AML threshold monitoring (100K AED) | CRITICAL |
| 39 | International BIN ( International Trax 100% 1 day) | Monitor 100% international BIN usage | HIGH |

---

## Recommended Actions (Priority Order)

### 🔴 CRITICAL (Immediate Action Required)

**1. Implement Missing AML Rules (Rules 31, 32)**
- **Rule 31:** AML - Local transaction higher than 50K
- **Rule 32:** AML - Local transaction higher than 100K
- **Why Critical:** AML compliance requirements, regulatory gaps
- **Similar Implementation Exists:** `evaluate_local_high_value_rule` can be adapted
- **Action:** Create evaluation functions with proper thresholds (50K, 100K)

### 🟠 HIGH PRIORITY (Implement Within Sprint)

**2. Implement Missing Risk Rules**
- **Rule 9:** Suspicious High Value (10000 AED) Transaction
- **Rule 10:** High Frequency Chargeback Merchant's
- **Rule 21:** Excessive Refunds or Reversals
- **Rule 39:** International BIN monitoring
- **Why High:** Risk management gaps, fraud detection holes

### 🟡 MEDIUM PRIORITY (Next Sprint)

**3. Implement Volume Monitoring Rules**
- **Rule 11:** High Transactions Decline Rate Merchant's
- **Rule 12:** Round Figure Transaction using same card at Multiple Merchants
- **Rule 26:** Sudden Drop in Daily Transaction Volume
- **Rule 27:** Significant Decrease in Weekly/Monthly Volume

### 🔵 MAINTENANCE (Name Sync)

**4. Fix Name Mismatches for Existing Rules**

Many rules HAVE implementation but won't trigger due to name mismatch. Choose one approach:

**Option A: Update Database Names (Recommended)**
- Update database rule names to match code
- Less risky, no code changes needed
- Maintains existing test coverage

**Option B: Update Code Names**
- Update case statement in context.ex
- Requires code changes and testing
- Risk of breaking existing functionality

**Rules Needing Name Sync (26 rules with ⚠️ Similar):**
- Rule 2, 3, 4, 5, 6, 7, 14, 15, 16, 17, 19, 20, 22, 23, 24, 25, 28, 33, 34, 35, 36, 37, 38, 41, 42, 43, 46

---

## Testing Recommendations

### Before Implementing New Rules:
1. Review existing similar implementations
2. Understand transaction data structure (POS vs QR)
3. Test with sample data for each category (Cat A, B, C, D)
4. Verify MCC filtering works correctly

### After Implementation:
1. Unit tests for each evaluation function
2. Integration tests with real transaction data
3. Test with all 4 merchant categories
4. Verify rule hits are logged correctly
5. Test supervisor dashboard displays flagged transactions

### Regression Testing:
1. Run all existing tests: `mix test`
2. Manual testing of working rules (1, 8, 13, 18, 29, 30, 40, 44, 45)
3. Check audit logs for rule evaluation history
4. Verify no performance degradation with new rules

---

## Implementation Guidelines

### For New Rule Implementation:

```elixir
# 1. Add case in evaluate_single_rule/3 (line ~270)
case rule.name do
  "Your Exact Rule Name" -> 
    evaluate_your_rule(rule, transaction, transaction_type)
  # ... existing rules ...
end

# 2. Implement evaluation function
defp evaluate_your_rule(rule, transaction, transaction_type) do
  # Get parameters from rule
  threshold = get_parameter(rule, "amount_threshold", 50000)
  
  # Extract transaction data
  amount = get_transaction_amount(transaction)
  merchant_id = get_field(transaction, :merchant_id)
  
  # Apply rule logic
  if amount > threshold do
    # Build hit metadata
    metadata = %{
      amount: amount,
      threshold: threshold,
      reason: "Transaction exceeds threshold"
    }
    
    # Return hit
    build_rule_hit(rule, transaction, transaction_type, metadata)
  else
    :no_hit
  end
end
```

### Helper Functions Available:
- `get_parameter(rule, key, default)` - Extract from rule.parameters
- `get_transaction_amount(transaction)` - Get amount (handles Decimal)
- `get_card_type(transaction, type)` - Get card type (local/regional/international)
- `get_merchant_mcc(transaction)` - Get merchant MCC code
- `get_transaction_time(transaction)` - Get timestamp
- `build_rule_hit(rule, transaction, type, metadata)` - Create hit record

---

## Files to Modify

### For Adding New Rule Implementation:
- **apps/risk_core/lib/risk_core/context.ex** (add case and evaluation function)

### For Name Sync (Database Approach):
- **Database Update SQL:**
  ```sql
  UPDATE risk_rules 
  SET name = 'Exact Code Name'
  WHERE name = 'Current Database Name';
  ```

### For Name Sync (Code Approach):
- **apps/risk_core/lib/risk_core/context.ex** (update case statements)

### For Testing:
- **test/risk_core/context_test.exs** (add test cases)

---

## Related Documentation
- **IMPLEMENTATION_SUMMARY.md** - API endpoints and rule management
- **RISK_MANAGEMENT_README.md** - Risk management system overview
- **apps/risk_core/lib/risk_core/context.ex** - Rule evaluation engine source code

---

## Questions to Consider

1. **Should we disable non-implemented rules in database?**
   - Current state: Enabled but non-functional
   - Risk: False sense of security

2. **What's the timeline for implementing missing rules?**
   - Immediate: AML rules (31, 32)
   - This sprint: High-priority rules (9, 10, 21, 39)
   - Next sprint: Medium-priority rules (11, 12, 26, 27)

3. **Should we sync names or keep them separate?**
   - Recommendation: Update database names to match code
   - Alternative: Add name mapping layer

4. **Do we have test data for new rules?**
   - Need sample transactions for each scenario
   - Need to define expected behavior for edge cases

---

**End of Report**