feat: initialize project backend structure and document system specifications across all modules

docs/specs/reward_campaign/pool_definition.md

@@ -0,0 +1,68 @@
+---
+title: "Pool Definition"
+type: OpenSpec
+status: Draft
+domain: Reward Campaign Management
+---
+
+# Pool Definition
+
+## Requirement Definition
+Defines Reward Pools which track stored values (Points, Cash Rebates, Lucky Draw chances, eVouchers). Pools dictate expiry policies, entity tracking levels (Customer, Account, Card), and velocity controls.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights.
+- Pool Conversion Rate must be active.
+- Account Type Groups (if applicable) must be active.
+
+## Business Rules
+
+### Data Schema
+
+#### General Information
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Pool Id | System-generated identifier. | String (10) | Required. |
+| Pool Name | Name of the pool. | String (30) | Required. |
+| Pool Type | Points, Cash Rebate, Lucky Draw, eVoucher. | Enum | Required. |
+| Expiry Policy | Method to calculate expiry date. | Enum (Lookup) | Required (except eVoucher). |
+| Policy Parameter N | Numeric parameter for Expiry Policy. | Integer | Conditional based on policy. |
+| Expiry Date | Fixed expiry date. | Date | Conditional (if policy is Fixed Date). |
+| Ripening Period | Days before reward is redeemable. | Integer | Conditional. Default 0. |
+| Conversion Rate Code | Currency representing a unit of reward. | Enum (Lookup) | Conditional. |
+| Allow Negative Balance | Allow pool to go negative on adjust/cancel. | Boolean | Conditional. Default False. |
+| Precision | Number of decimal places. | Enum (Lookup) | Conditional. Default 2. |
+| Account Type Group | Restricts earning to specific accounts. | Enum (Lookup) | Optional. |
+| Grace Period | Months to keep expired buckets before forfeit. | Integer | Optional. |
+| Entity Level | Tracks balance at Customer, Account, Card. | Enum | Required. |
+
+#### Product Specific Policy
+Overrides general expiry policy for specific Account Types.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Product Account Level | PAL. | Enum (Lookup) | Required. |
+| Product Account Type | PAT. | Enum (Lookup) | Required. Unique per row. |
+| Expiry Policy | Specific expiry policy. | Enum (Lookup) | Required. |
+
+#### Velocity Control
+Defines thresholds for sending alerts (Exception Alert Reports).
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Maximum | Threshold limit. | Decimal | Required. |
+| Transaction Type | Award, Redeem, Adjust. | Enum | Required. |
+| Units | Per Pool Units or Per Transaction. | Enum | Required. |
+| Per Entity 1 | Customer, Account, Card. | Enum | Optional (System-wide if null). |
+| Per Entity 2 | Corporation, Chain, Store, Terminal. | Enum | Optional. |
+| Per Period | Quarter, Month, Week, Day. | Enum | Required. |
+| Alert Template | Message template for alert. | Enum | Required. |
+| Alert Group | Recipient group (SMS/Email). | Enum | Required. |
+
+### Execution
+- Precision cannot be reduced after transactions are posted.
+- Entity Level cannot be moved downwards (e.g., Customer to Card) after transactions are posted.
+- Evoucher pools have No Expiry, no Precision, and no Negative Balances.
+
+## Exception Flow
+- N/A