# Business Scenarios

**PURPOSE:** Demonstrates business rule application through concrete examples. Each scenario validates specific rules from `03_BUSINESS_RULES.md`. This file acts as a specification for test cases (Acceptance Criteria).

---

## Scenario 1: Complete Contract Lifecycle

**Validates:** BR-001-4, BR-001-5, BR-001-7, BR-002-3, BR-002-4, BR-002-5, BR-002-7, BR-003-1, BR-003-2, BR-003-3, BR-003-4, BR-004-1, BR-004-2

**Context:** Full contract from creation to completion.

### Step 1: Admin creates new customer
- `customer` flag added immediately [BR-001-4]
- `reference_number` generated: `CUS-0000000001` [BR-001-7]

### Step 2: Admin creates draft contract with $500 initial payment
- `company_payout` record created automatically [BR-002-7]
- 12 installments generated, each $200 [BR-003-1, BR-003-2]
- `agent` flag added to agent's flags [BR-001-5]
- Contract status: `draft`

### Step 3: Admin signs contract
- Status changes: `draft` → `active` [BR-002-3, BR-002-4]
- `signed_at` set
- Contract is now immutable

### Steps 4–15: Admin records 12 payments (each $200)
- Each payment matches exact installment amount [BR-004-1]
- Each payment linked to its installment [BR-004-2]
- Each installment status: `pending/overdue` → `paid` [BR-003-3]

### Step 16: After 12th payment
- Contract status automatically: `active` → `completed` [BR-002-5, BR-003-4]

---

## Scenario 2: Late Payment + Early Payment

**Validates:** BR-004-3, BR-003-5

**Context:** Testing payment sequencing with mixed timing.

**Initial State:**

| Installment | # | Due Date | Status |
|:---|:---|:---|:---|
| A | 1 | 2024-01-01 | overdue |
| B | 2 | 2024-02-01 | pending |
| C | 3 | 2024-03-01 | pending |
| D | 4 | 2024-04-01 | pending |

**Current Date:** 2024-02-15

**Action 1:** Admin attempts to pay installment B directly
- **Result:** REJECTED [BR-004-3] — Installment A is overdue and must be paid first

**Action 2:** Admin pays installment A ($200)
- **Result:** ACCEPTED — Installment A status: `overdue` → `paid`

**Action 3:** Admin pays installment B ($200)
- **Result:** ACCEPTED — Installment B status: `pending` → `paid`

**Action 4:** Admin pays installment C ($200) — 15 days early
- **Result:** ACCEPTED [BR-004-3 allows early payment] — Installment C status: `pending` → `paid`

**Final State:**

| Installment | # | Due Date | Status |
|:---|:---|:---|:---|
| A | 1 | 2024-01-01 | paid |
| B | 2 | 2024-02-01 | paid |
| C | 3 | 2024-03-01 | paid |
| D | 4 | 2024-04-01 | **pending (due_date unchanged)** |

**Key Validation:** Due date of D did NOT change despite early payment of C [BR-003-5]

---

## Scenario 3: LIFO Deletion with Explicit Linking

**Validates:** BR-004-6, BR-004-8, BR-004-9

**Context:** Correcting a mistaken payment.

**Initial State:** Contract with 3 paid installments, each payment has its installment link stored.

**Action 1:** Admin attempts to delete payment #2
- **Result:** REJECTED [BR-004-6] — Payment #3 is more recent, must delete #3 first

**Action 2:** Admin deletes payment #3
- **Result:** ACCEPTED
- Audit log records self-contained narrative with the amount [BR-004-9]
- Payment record physically deleted [BR-004-8]
- Stored installment link used directly to identify which installment to restore
- Linked installment status: `paid` → `overdue` (since due_date < today) [BR-004-8]

**Action 3:** Admin enters new payment with correct amount
- **Result:** ACCEPTED — New payment created and linked to same installment

---

## Scenario 4: Agent Becomes Investor, Then Withdraws

**Validates:** BR-001-6

**Context:** Testing permanent investor status.

**Step 1:** Create agent
- Flags: `["agent"]`

**Step 2:** Add 10 shares
- Flags: `["agent", "investor"]` [BR-001-6]

**Step 3:** Withdraw 10 shares
- Flags: `["agent", "investor"]` ← **UNCHANGED** [BR-001-6]
- Shares balance: 0
- Agent STILL appears in investor lists

---

## Scenario 5: Draft Contract Deletion (Cascade)

**Validates:** BR-002-6

**Context:** Deleting a contract that was never signed.

**Initial State:**
- Draft contract with $500 initial payment
- `company_payout` of $5000 recorded
- 12 installments generated
- Audit logs for payout and initial payment

**Action:** Admin deletes draft contract
- **Result:** ACCEPTED [BR-002-6]

**CASCADE deletes:**
- ✅ 12 installments
- ✅ `company_payout` payment record
- ✅ `initial_payment` payment record
- ✅ ALL audit logs for this contract
- ✅ The contract itself

**Final State:**

| Table | Records Remaining |
|:---|:---|
| `contracts` | 0 (this contract) |
| `installments` | 0 (this contract's) |
| `payments` | 0 (this contract's) |
| `payment_audit_logs` | 0 (this contract's) |

**No trace remains in the database.**