# SPECIFICATIONS/02_REQUIREMENTS/03_ACCEPTANCE_CRITERIA.md

**PURPOSE:** Testable criteria that define when a requirement is considered complete. Each criterion validates specific business rules or functional requirements. This file acts as the master checklist for Quality Assurance.

**REFERENCES:**
- Business Rules validated by these criteria: `../01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md`
- Functional Requirements validated by these criteria: `01_FUNCTIONAL.md`
- Testing mandates (coverage, structure): `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Testing Mandates

---

### AC-001: Math Validation
All unit tests for the contract math validator pass with 100% coverage.
- **Validates:** BR-006-1 through BR-006-4

### AC-002: Integration Test Coverage
All feature tests pass with ≥80% code coverage across the entire codebase.

### AC-003: Customer List Performance
Sorting 10,000 customers by nearest due date completes in under 100ms.
- **Validates:** NFR-001-3

### AC-004: Client Immutability
Any programmatic attempt to delete a client — regardless of role, regardless of whether the client has associations — is blocked without any database change.
- **Validates:** BR-001-1

### AC-005: LIFO Violation Rejection
Attempting to delete a payment that is not the most recent is rejected by the system.
- **Validates:** BR-004-6

### AC-006: Exact Match Enforcement
Submitting a payment with an amount that does not match the next due installment amount is rejected.
- **Validates:** BR-004-1

### AC-007: Sequencing Enforcement
Attempting to pay a later installment while an earlier installment is pending or overdue is rejected.
- **Validates:** BR-004-3

### AC-008: Narrative Generation
A contract that has a company payout, multiple payments, and a deleted payment produces a correct, self-contained narrative timeline that is fully understandable without querying the payments table.
- **Validates:** BR-004-9

### AC-009: Automatic Contract Completion
Paying the last due installment automatically changes the contract status to `completed` without any manual intervention.
- **Validates:** BR-002-5, BR-003-4

### AC-010: Client Type Flags Transaction Safety
When a customer is created, a contract is created, or an investor is created — the `client_type_flags` are updated correctly within the same transaction. If any part fails, no flag change persists. The `investor` flag is never removed even when all shares are withdrawn.
- **Validates:** BR-001-4, BR-001-5, BR-001-6, BR-001-8
- **Testing Standard Reference:** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Transactional Integrity

### AC-011: Share Log Logical Operations
Share log records are never physically deleted from the database. Modification changes the status to `modified`. Deletion changes the status to `deleted`.
- **Validates:** BR-005-6, BR-005-7

### AC-012: Draft Contract Cascade Deletion
Deleting a draft contract removes the contract, all its installments, all its payments (including company payout), and all its audit logs. No records from this contract remain in any table.
- **Validates:** BR-002-6

### AC-013: Customer List Data Freshness and Filtering
Customer list returns data that reflects contract state within the expected refresh window. Time range filtering by first contract date returns only customers whose first contract falls within the specified range.
- **Validates:** NFR-001-3, NFR-001-5, FR-2.2

### AC-014: Due Date Immutability
Paying an installment before its due date does NOT change the due date of any subsequent installment.
- **Validates:** BR-003-5

### AC-015: Explicit Installment Linking
When a payment is deleted (LIFO), the system uses the stored installment link to restore exactly the correct installment — not determined by amount or date guessing.
- **Validates:** BR-004-2, BR-004-8

### AC-016: Analytics Period Limit
An analytics request with a date range exceeding 365 days, or with invalid date ordering, or with a future date is rejected.
- **Validates:** FR-7.1, BR-007-1

### AC-017: Reference Number Generation
Every customer receives a unique `CUS-XXXXXXXXXX` reference number upon creation. Every contract receives a unique `CTR-XXXXXXXXXX` reference number upon creation. Numbers are sequential with leading zeros and unique across the system.
- **Validates:** BR-001-7, BR-002-8

### AC-018: Customer List Advanced Features
Customer list supports:
- Reverse sorting (descending)
- Status filtering by category (overdue, due this month, fully paid, no installments)
- Customers without active installments always appear last regardless of sort direction
- **Validates:** FR-2.2

### AC-019: Response Message Localization
All user-facing messages in API responses (success messages, error messages, exception messages) are resolved through the translation system. No hardcoded English or Arabic strings appear in any response.
- **Validates:** NFR-007

### AC-020: Investor Creation Without Shares
Creating an investor via API assigns the `investor` flag permanently without requiring any shares. The investor appears in investor lists with a shares balance of zero until shares are added independently via the Shares module.
- **Validates:** BR-001-6, BR-001-8, FR-9.2

### AC-021: Investor Detail Without Agent Flag
Viewing an investor's detail who does not have the `agent` flag returns the investor profile with zero profit and an empty referred_customers array (no 404, no error).
- **Validates:** FR-9.3