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

docs/specs/customer_management/account.md

@@ -0,0 +1,46 @@
+---
+title: "Account"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Account
+
+## Requirement Definition
+Manages customer account information, which is either sent from an external system to OLS or added by users manually via the OLS system.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Account" module.
+- An account type must exist in OLS before an account of that type can be added.
+- The user must select a customer to access the Account tab.
+
+## Business Rules
+
+### Data Schema
+
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| CIF Number | CIF number of selected customer. | String | Required. Read-only on creation. |
+| Product Account Level (PAL) | Product Account Level. | Enum (Lookup) | Required. |
+| Product Account Type (PAT) | Product Account Type. | Enum (Lookup) | Required. PAL + PAT = Account Type. |
+| Account Number | Product Account Number. | String (20) | Required. Combination of Account No + Account Type must be unique. |
+| Account Open Date | Open date of the account. | Date | Required. |
+| Account Indicator | Personal [P] or Corporate [C]. | Enum (Lookup) | Required. |
+| Account Block Code | Used to block transactions. | String (10) | Optional. |
+| Block Code Reason | Reason for blocking. | String (100) | Optional. |
+| Block Code Last Update Date | Date block was applied. | Date | Optional. |
+| Cycle | Statement cycle date. | Integer (2) | > 0 if provided. |
+| Account Status | Status of the account. | Enum (Lookup) | Required. |
+
+### Execution
+- Each account belongs to one Customer. The CIF number cannot be changed via this screen (requires CIF Merge batch).
+- Records managed by OLSACCT batch cannot typically be changed from the admin screen.
+- On Add: Rejected if Account No + Account Type already exists. Else, record added to PRODUCT_ACCOUNT and LOYALTY_ACCOUNT_PRODUCT created.
+- On Update: Must exist in OLS. Original record moved to history.
+- On Delete: Rejected if linked to an active Card record. Else, logical delete applied (moved to history).
+
+## Exception Flow
+- Input validation failures stop the action.

docs/specs/customer_management/adjustment.md

@@ -0,0 +1,53 @@
+---
+title: "Adjustment"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Adjustment
+
+## Requirement Definition
+Allows manual posting of adjustment transactions to correct balance discrepancies.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Adjustment Entry" module.
+- Records require Maker-Checker approval.
+
+## Business Rules
+
+### Data Schema
+
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
+| Card / Account / CIF | Identifier based on above selection. | String | Required. |
+| Adjustment Quantity Sign | Positive or Negative adjustment. | Enum | Required. |
+| Store | Store of transaction. | Enum (Lookup) | Required. |
+| Pool Id | Pool to be adjusted. | Enum (Lookup) | Required. Must respect entity level logic. |
+| Transaction Date | Transaction date time. | Date | Required. |
+| Expiry Date (Positive) | Expiry date of the new bucket. | Date | Required if Positive Adjustment. Defaults to pool policy. |
+| Bucket Expiry Date (Negative)| Specific bucket to deduct from. | Enum (Lookup) | Optional. If empty, uses FIFO Redemption approach. |
+| Adjustment Quantity | Amount to adjust. | Decimal | Required. Must be > 0. |
+| Reason Code | Reason for adjustment. | Enum (Lookup) | Required. |
+| Transaction Code | OLS transaction code. | Enum (Lookup) | Required. |
+| Remarks | Additional notes. | String (100) | Optional. |
+
+### Execution
+- **Pending/Approve Flow**: New adjustments go to a Pending state. Authorized user must approve.
+- **Positive Adjustments**: 
+  - Offsets any negative balance buckets first.
+  - Remaining points added to a new bucket with specified Expiry Date.
+- **Negative Adjustments**: 
+  - If a specific Bucket Expiry Date is chosen, deduction happens there.
+  - Otherwise, points are deducted based on FIFO.
+- OLS validates status, permissions, and block codes for the entity.
+
+## Post-Conditions
+- Pool balance buckets updated.
+- Transaction logged in history.
+
+## Exception Flow
+- Validation failures or insufficient permissions.

docs/specs/customer_management/attribute.md

@@ -0,0 +1,51 @@
+---
+title: "Attribute"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Attribute
+
+## Requirement Definition
+Provides a consolidated view of all attributes assigned to a customer, account, or card, populated by batch processes or Campaign Rules.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Attribute" module.
+
+## Business Rules
+
+### Data Schema
+
+#### Attribute Value Detail
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Attribute Group | Group of attribute. | String | Read-only. |
+| Attribute ID | Attribute ID. | String | Read-only. |
+| Attribute Name | Attribute Name. | String | Read-only. |
+| Entity | Client, Product_Account, or Card. | Enum | Read-only. |
+| Entity ID | CIF Number, PA Number, or Card Number based on Entity. | String | Read-only. |
+| Account Type | Required for Account attribute. | String | Read-only. |
+| Attribute Value | Value of the attribute. | String/Number | Read-only. |
+| Effective Date From | Start date. | Date | Read-only. |
+| Effective Date To | End date. | Date | Read-only. |
+
+#### Linked Campaign Details
+Lists Campaign Rules referencing this attribute.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Campaign ID | Campaign ID. | String | Read-only. |
+| Campaign Name | Name of Campaign. | String | Read-only. |
+| Campaign Rule | Campaign Rules ID. | String | Read-only. |
+| Campaign Rule Name | Name of Campaign Rule. | String | Read-only. |
+| Effect Date | Effective from and to dates. | Date | Read-only. |
+
+### Execution
+- **View-only screen.**
+- Data from `ATTRIBUTE_VALUE` table.
+- Filterable by Entity level and effective dates. Only effective records listed by default.
+
+## Exception Flow
+- N/A

docs/specs/customer_management/award_transaction.md

@@ -0,0 +1,52 @@
+---
+title: "Award Transaction"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Award Transaction
+
+## Requirement Definition
+Allows users to review, verify, and manually create Award Transactions to grant points/rewards to a customer's account.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in both the "Customer Profile" and "Award Transaction" modules.
+- The user must select a customer on the customer profile listing page.
+- Dependent on access rights, users can view, add, edit, or approve manual Award Transaction records.
+
+## Business Rules
+
+### Data Schema
+
+#### General Information
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
+| Card / Account / CIF | Identifier based on above selection. | String | Required. |
+| Store | Store of transaction. | Enum (Lookup) | Required. |
+| Transaction Date | Transaction date time. | Date | Required. |
+| Reason Code | Reason for the award. | Enum (Lookup) | Required. |
+| Transaction Code | OLS transaction code. | Enum (Lookup) | Required. |
+| Remarks | Additional notes. | String (100) | Optional. |
+
+#### Award Details
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Pool Id | Pool to be awarded. | Enum (Lookup) | Required. Must respect entity level logic. |
+| Award Quantity | Points to award. | Decimal | Required. Must be > 0. |
+| Expiry Date | Expiry date of the awarded points bucket. | Date | Required. Defaults based on pool's expiry policy. |
+
+### Execution
+- **Pending/Approve Flow**: New award transactions go to a Pending state. An authorized user must approve them.
+- Manual awards act similarly to positive Adjustments but follow the Award business logic path (potentially triggering Campaign Rules if configured).
+- Points are added to a new bucket with the specified Expiry Date.
+
+## Post-Conditions
+- Pool balance buckets are updated.
+- Transaction is logged in history.
+
+## Exception Flow
+- Validation failures or insufficient permissions.

docs/specs/customer_management/card.md

@@ -0,0 +1,47 @@
+---
+title: "Card"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Card
+
+## Requirement Definition
+Manages customer card information. Generally updated in the external system and loaded into OLS, thus often view-only, though manual additions/replacements are supported with strict rules.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Card" module.
+- The parent account must exist in OLS before adding a card.
+- User must select a customer.
+
+## Business Rules
+
+### Data Schema
+
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| CIF Number | CIF Number of the card. | String | Required. Defaults to selected customer but can change for Supplement Cards. |
+| Account Type | Product Account Level + Type. | Enum (Lookup) | Required. |
+| Account Number | Parent Product Account Number. | Enum (Lookup) | Required. |
+| Card Number | The card number. | String (20) | Required. Must be globally unique. |
+| Masked Card Number | Masked version. | String (20) | Optional. |
+| Cardholder Name | Name on card. | String (50) | Required. |
+| Card Indicator | Supplement [S], Principal [P], Corporate [K]. | Enum (Lookup) | Required. If Principal, Card CIF must equal Account CIF. |
+| Card Status | Card status. | Enum (Lookup) | Required. |
+| Card Block Code | Block code for transactions. | String (10) | Optional. |
+| Card Activation Date | Date activated. | Date | Optional. |
+| Card Creation Date | Date created. | Date | Required. |
+| Card Expiry Date | Expiry date. | Date | Required. |
+| Old Card Number | For replacements only. | Enum (Lookup) | Required only if adding a replacement card for an existing one. |
+
+### Execution
+- Each Card belongs to one Account and one Customer. Changes to CIF/Account require CIF Merge batch.
+- On Add: Rejected if Card Number already exists, or if Account/CIF does not exist. Adds to CARD and CARD_PRODUCT_ACCOUNT_REL.
+- On Delete: Logical delete (moved to history).
+- Replacement Flow: When replacing an old card, the new card gets the same PSN (Plastic Serial Number). The old card remains active until its status/block code is updated. All attributes, counters, and pool buckets linked to the old card are automatically linked to the new card.
+
+## Exception Flow
+- Validation failures.

docs/specs/customer_management/counter.md

@@ -0,0 +1,51 @@
+---
+title: "Counter"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Counter
+
+## Requirement Definition
+Displays all counter buckets for a chosen customer, including Customer-level, Account-level, and Card-level counters, which are updated by Campaign Rules or manually.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Counter" module.
+
+## Business Rules
+
+### Data Schema
+
+#### Counter Value Detail
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Counter | Counter identifier. | String | Read-only. |
+| Entity | Cust [CU], Account [PA], Card [CA]. | Enum | Read-only. |
+| Entity ID | CIF Number, Account Number, or Card Number. | String | Read-only. |
+| What to count | The data entity tracked. | String | Read-only. |
+| Counter Value | Counter value. | Decimal | Read-only. |
+| Bucket Start Date | Start date. | Date | Read-only. |
+| Bucket End Date | End date. | Date | Read-only. |
+| Counter State | A: Awarded, C: New. | Enum | Read-only. |
+
+#### Counter Statistic (History)
+Lists transactions that updated this counter bucket.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Reference No | OLS Transaction Reference Number. | String | Read-only. |
+| Post Date | Post date of the transaction. | Date | Read-only. |
+| Counter Value | Value updated on this transaction. | Decimal | Read-only. |
+| Bucket Number | Bucket number of selected counter. | Integer | Read-only. |
+| Update Date | System date when updated. | Date | Read-only. |
+| Updated By | Batch/User who posted transaction. | String | Read-only. |
+
+### Execution
+- **View-only screen.**
+- Values retrieved from `Campaign_Counter` table.
+- Filterable by Entity level and bucket periods. Effective records listed by default.
+
+## Exception Flow
+- N/A

docs/specs/customer_management/customer_360.md

@@ -0,0 +1,56 @@
+---
+title: "Customer 360"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Customer 360
+
+## Requirement Definition
+A centralized dashboard providing key information about a customer, giving a real-time view of customer behavior, balances, cards, and transaction statistics.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Customer Profile" module and select a customer to view the dashboard.
+
+## Business Rules
+
+### Dashboard Components
+
+#### 1. Customer Information
+- Summarized view of the customer's profile (name, CIF, status, etc.). Allows edit/delete actions from a pop-up.
+
+#### 2. Customer's Rewards Statistic
+- **Points**: Total available points.
+- **Cash back**: Total available cash back.
+- (Uses system date to determine balance bucket periods).
+
+#### 3. Account / Card Information
+- Lists all of the customer's accounts and cards.
+- If there are no cards, it shows just the accounts.
+- Columns include: Account Type, Account No, Card No, CIF, Card Status, Indicator, Expiry, Account Block Code, Account Status, Open Date.
+
+#### 4. Transaction Statistic
+- **Line Chart**: Shows fluctuation in balance (Earned/Redeemed/Adjusted) for a selected pool over a specified period (This month, Last month, Last 3/6 months). Data from TRANSACTION table.
+- **Combo Chart**: Illustrates relationship between total number of transactions (line) and total transacted merchants (bar) over a specified period.
+
+#### 5. Customer Activities
+- Logs loyalty program actions (enroll, earn, redeem, transfer), feedback/reviews, email engagement, and account management events.
+- Filterable by timeframe.
+
+#### 6. Customer Segmentation
+- Shows the demographic (Gender, Age, Marital Status, Income) and behavioral (Frequency, Membership class, Purchase channel, Hobby) segments the customer belongs to.
+
+#### 7. Most Redeemed Items
+- Displays the top N (configurable, default 10) redeemed items of the customer.
+- Shows Item Code, Name, Category, Quantity, Points used, Cash amount used.
+- Data from CAT_CATALOGUE_TRANS_DETAIL ordered by quantity descending.
+
+#### 8. Balance Information
+- Summary of all Pool balances for the customer.
+- Shows Pool ID, Pool Name, Balance (sum of all buckets), Redeemable Balance (non-expired/available), Earliest Expiring Balance and Date.
+
+## Post-Conditions
+- Strategy guide for personalized experiences.

docs/specs/customer_management/customer_profile.md

@@ -0,0 +1,62 @@
+---
+title: "Customer Profile"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Customer Profile
+
+## Requirement Definition
+Provides view-only access to Customer details within the OLS administration screens. Customer records are primarily updated from source systems via batch processes.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Customer Profile" module.
+
+## Business Rules
+
+### Data Schema
+
+#### General Information
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| CIF Number | Unique CIF Number assigned to each customer. | String (30) | Required. |
+| First Name | Customer First Name. | String (50) | Required. |
+| Last Name | Customer Last Name. (First Name + Last Name = Customer Name) | String (50) | Required. |
+| Date of Birth | Customer birth date. | Date | Required. |
+| Registration Date | Date customer opened an account. | Date | Optional. |
+| Gender | Customer Gender. | Enum (Lookup) | Optional. |
+| Customer Status | Customer status. | Enum (Lookup) | Required. |
+| Customer Block Code | Customer block code. | String (10) | Optional. |
+| Marital Status | Customer marital status. | Enum (Lookup) | Optional. |
+| ID Type | ID Type of cardholder ID. | Enum (Lookup) | Optional. |
+| Cardholder ID | Cardholder ID. | String (30) | Required if ID Type is selected. |
+| Country Origin | Customer country origin. | Enum (Lookup) | Optional. |
+| Customer Income | Customer income. | Decimal (14,2) | >= 0 if provided. |
+| Profile Picture | Uploaded image file. | Image / URL | Optional. |
+
+#### Contact Detail
+Each customer can have more than one contact detail (e.g., customer contact, guardian contact). At least one must be provided.
+
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Address Type | Home/Business/Shipping/Billing. | Enum | Required. Unique per customer. |
+| Phone Number | Phone number. | String (30) | Required. |
+| Email Address | Email address. | String (50) | Required. Must be valid email format. |
+| Address 1 | Main address. | String (100) | Optional. |
+| Address 2 | Other address. | String (100) | Optional. |
+| State | State code. | Enum (Lookup) | Optional. |
+| City | City code. | Enum (Lookup) | Optional. |
+| Zip Code | Postal code. | Enum (Lookup) | Optional. |
+
+### Execution
+- When a new customer is added in OLS, it is added to Client tables, and the corresponding LOYALTY_ACCOUNT is created.
+- A request to add a customer whose CIF already exists with an Active status is rejected.
+- A request to update/delete a CIF that does not exist or is inactive is rejected.
+- Deletion of a CIF linked to an active Account is rejected. Logical delete is used (moving to History).
+- Admin screen changes are generally restricted for records managed by the OLSCUST batch.
+
+## Exception Flow
+- N/A

docs/specs/customer_management/item_redemption.md

@@ -0,0 +1,59 @@
+---
+title: "Item Redemption"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Item Redemption
+
+## Requirement Definition
+Allows users (e.g., call center staff) to manually redeem items for customers in real-time, exchanging points (and optionally cash) for catalog items.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Item Redemption Entry" module.
+- Real-time catalog configuration and customer balances must be available.
+
+## Business Rules
+
+### Data Schema
+
+#### General Information
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
+| Card / Account / CIF | Identifier. | String | Required. |
+| Redemption Channel | Channel of redemption. | Enum (Lookup) | Required. |
+| Redemption Date | Transaction date. | Date | Required. |
+| Store | Active store in OLS. | Enum (Lookup) | Required. |
+| Applicable Fee | Apply item fee if configured. | Boolean | Default False. |
+
+#### Item Details
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Catalogue Code | Catalog to redeem from. | Enum (Lookup) | Required. |
+| Item | Item code. | Enum (Lookup) | Required. Item must have a matched price. |
+| Redemption Mode | Fixed Points or Fixed Partial (Cash + Points).| Enum | Required based on price configuration. |
+| Unit Price (Points) | Point cost per item. | Decimal | Required. Fixed for Fixed Points; editable but >= minimum for Fixed Partial. |
+| Unit Cash Amount | Cash cost per item. | Decimal | Required for Fixed Partial. Calculated: (Full Price - Unit Price) * Price in Cash. |
+| Unit Face Value | Face value of item. | Decimal | Read-only. Base face value or price config face value. |
+| Quantity on Hand | Available inventory. | Integer | Read-only. Displayed if tracked by quantity. |
+| Redemption Quantity | Amount to redeem. | Integer | Required. Must be > 0 and <= Quantity on Hand. |
+| Total Price (Points) | Total points required. | Decimal | Read-only. Unit Price * Redemption Quantity. |
+| Total Cash Amount | Total cash required. | Decimal | Read-only. Unit Cash Amount * Redemption Quantity. |
+| Delivery Address | Delivery details for Physical/Evoucher. | String | Auto-populated from profile, editable. |
+
+### Execution
+- Transactions cannot be modified after posting.
+- Validates block codes and permissions.
+- Net transaction value is sum of tax, total fee, and total cash required.
+- At EOD, approved items are output to a file for partners to fulfill.
+
+## Post-Conditions
+- Balances and inventory updated.
+- Transaction viewable in history.
+
+## Exception Flow
+- Insufficient balance or TP validation failure blocks transaction.

docs/specs/customer_management/no_hit_cp_transaction.md

@@ -0,0 +1,51 @@
+---
+title: "No-Hit CP Transaction"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# No-Hit CP Transaction
+
+## Requirement Definition
+Tracks all incoming transactions that trigger a campaign rule but are not eligible (do not meet criteria) OR transactions that have no linked campaign rule. Helps in troubleshooting why a customer did not receive an expected reward.
+
+## Process Flow
+
+### Pre-Conditions
+- Incoming transactions trigger campaigns but do not hit the rule criteria.
+- Users must have access rights in the "No hit CP- Transaction" module.
+
+## Business Rules
+
+### Data Schema
+
+#### Transaction Detail (Incoming request data)
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| CIF Number | CIF Number. | String | Read-only. |
+| Product Account No | Product Account No. | String | Read-only. |
+| Card Number | Card Number. | String | Read-only. |
+| Invoice No | Generated unique incoming transaction ID. | String | Read-only. |
+| Transaction Type | AWD / RED / ADJ. | Enum | Read-only. |
+| OLS Transaction Code | Used to locate CP rule. | String | Read-only. |
+| Transaction Amount | Gross amount or adjust point. | Decimal | Read-only. |
+| Various | Store, Terminal, MCC, Currency, etc. | Various | Sourced from incoming transaction. |
+
+#### CP Rule Listing (Error Details)
+Displays details for each Campaign Rule the transaction triggered but failed to hit.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Campaign ID | Campaign ID. | String | Read-only. |
+| Campaign Rule | Campaign Rule ID. | String | Read-only. |
+| Pool ID | Reward pool. | String | Read-only. |
+| Error Code | Error response code from OLS. | String | Read-only. |
+| Error Descriptions | Detailed description of why criteria failed. | String | Read-only. |
+
+### Execution
+- **View-only screen.**
+- Data is sourced from `OLS_ORPHAN_TXN_NO_HIT`.
+- The error description should specify exactly which criteria failed (e.g., MCC didn't match, Minimum amount not met).
+
+## Exception Flow
+- N/A

docs/specs/customer_management/pool_balance_detail.md

@@ -0,0 +1,54 @@
+---
+title: "Pool Balance Detail"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Pool Balance Detail
+
+## Requirement Definition
+Provides a summary and detailed breakdown of all reward pools and their balance buckets for a selected customer.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Balance Enquiry" module.
+
+## Business Rules
+
+### Data Schema
+
+#### Pool Balance Summary
+Displays a row for each pool the customer interacts with.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Pool ID | Pool ID. | String | Read-only. |
+| Pool Name | Pool Name. | String | Read-only. |
+| Pool Type | Pool Type. | String | Read-only. |
+| Pool Entity Level | Customer, Account, or Card level. | String | Read-only. |
+| Balance | Sum of all balance buckets. | Decimal | Read-only. |
+| Redeemable Balance | Sum of non-expired, available buckets. | Decimal | Read-only. |
+| Next Expiring Balance | The earliest non-expired balance bucket amount. | Decimal | Read-only. |
+
+#### Pool Balance Detail (Bucket Breakdown)
+Displays the individual expiry buckets for a selected pool.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Account Type | Account Type. | String | Read-only. |
+| Account No | Account Number. | String | Read-only. |
+| Card Number | Card Number (only if Card pool entity level). | String | Read-only. |
+| Pool ID | Selected Pool ID. | String | Read-only. |
+| Balance | Non-zero balance of the bucket. | Decimal | Read-only. |
+| Expiry Date | Expiring date of the bucket. | Date | Read-only. |
+
+### Execution
+- **View-only screen.** No modifications allowed directly.
+- Grouping/Visibility is dependent on the Pool Entity Level:
+  - Customer level: Shows buckets grouped under accounts, even though earned at customer level.
+  - Account level: Shows buckets earned by the specific Account.
+  - Card level: Shows buckets earned by the specific Card.
+- Expired buckets that have not yet forfeited are shown.
+
+## Exception Flow
+- N/A

docs/specs/customer_management/re_instatement.md

@@ -0,0 +1,46 @@
+---
+title: "Re-Instatement"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Re-Instatement
+
+## Requirement Definition
+Allows manual re-instatement of expired balance buckets that have not yet been forfeited.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Re-Instatement" module.
+- The customer must have expired pool buckets that are within the grace period (not yet forfeited).
+- Requires Maker-Checker approval.
+
+## Business Rules
+
+### Data Schema
+
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
+| Card / Account / CIF | Identifier based on above selection. | String | Required. |
+| Store | Store of transaction. | Enum (Lookup) | Required. |
+| Pool Id | Pool of the bucket to re-instate. | Enum (Lookup) | Required. Lists pools with non-forfeited expired balances. |
+| Bucket to Re-instate | Specific expired bucket to reinstate. | Enum (Lookup) | Required. |
+| Expiry Date | New expiry date of the reinstated points. | Date | Required. |
+| Reason Code | Reason for re-instatement. | Enum (Lookup) | Required. |
+| Remarks | Additional notes. | String (100) | Optional. |
+
+### Execution
+- **Pending/Approve Flow**: New requests go to a pending list. Authorised user approves.
+- Re-instatement is posted as an Adjustment.
+- The expired bucket balance is set to 0.
+- If a bucket with the new Expiry Date already exists, the amount is added to it.
+- Otherwise, a new bucket is created with the new Expiry Date.
+
+## Post-Conditions
+- Balances updated and logged as adjustments.
+
+## Exception Flow
+- Rejected by TP validation or block code.

docs/specs/customer_management/statement.md

@@ -0,0 +1,52 @@
+---
+title: "Statement"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Statement
+
+## Requirement Definition
+Provides a list of all transactions for an account/customer over a set period (usually monthly). Includes earned, redeemed, adjusted points, beginning/ending balances, and expired points.
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Statement Enquiry" module.
+
+## Business Rules
+
+### Data Schema
+
+#### Statement Summary
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Loyalty Account Number | Identifier. | String | Read-only. |
+| Product Account Number | Identifier. | String | Read-only. |
+| Pool ID | Statement Pool. | String | Read-only. |
+| Cycle Start Date | Previous statement cycle start. | Date | Read-only. |
+| Statement Opening Balance | Previous points balance. | Decimal | Read-only. |
+| Total Award | Earned points in cycle. | Decimal | Read-only. |
+| Total Redeem | Redeemed points in cycle. | Decimal | Read-only. |
+| Total Adjust | Adjusted points in cycle. | Decimal | Read-only. |
+| Statement Closing Balance | Accumulated points at cycle end. | Decimal | Read-only. |
+| Expired Points | Balance in expired but not forfeited buckets. | Decimal | Read-only. |
+| Cycle Statement Date | Generation date. | Date | Read-only. |
+
+#### Transaction Detail
+Lists transactions within the cycle.
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Reference Number | OLS Reference Number. | String | Read-only. |
+| Transaction Type | Award, Redeem, Adjust. | Enum | Read-only. |
+| Unit | Earned/Redeemed/Adjusted points. | Decimal | Read-only. |
+| Post Date | Post Date. | Date | Read-only. |
+| Transaction Date | Transaction Date Time. | Date | Read-only. |
+
+### Execution
+- **View-only screen.** Records are updated by OLS batch jobs.
+- Output supports Customer and Account level, but stored under Account level.
+
+## Exception Flow
+- N/A

docs/specs/customer_management/transaction_history.md

@@ -0,0 +1,72 @@
+---
+title: "Transaction History"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Transaction History
+
+## Requirement Definition
+Provides a running record of all transactions logged in OLS for a customer, including cancellations, over a configurable period (normally the last 12 months).
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Transaction History" module.
+
+## Business Rules
+
+### Data Schema
+
+#### Transaction Detail
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Invoice No | Internal invoice No generated by OLS. | String | Read-only. |
+| Reference No | OLS Transaction Reference Number. | String | Read-only. |
+| Source Reference Number | Reference number from source system. | String | Read-only. |
+| OLS Transaction Code | OLS Transaction Code. | String | Read-only. |
+| Gross Amount | Gross transaction amount. | Decimal | Read-only. |
+| Nett Amount | Nett transaction amount. | Decimal | Read-only. |
+| Redeem Points | Total redeem points. | Decimal | Read-only. |
+| Points Redeemed Amount | Total redeem points amount. | Decimal | Read-only. |
+| Adjust Points | Total adjustment points. | Decimal | Read-only. |
+| Points Adjustment Amount | Total adjust point amount. | Decimal | Read-only. |
+| Award Points | Total award points. | Decimal | Read-only. |
+| Points Awarded Amount | Total award point amount. | Decimal | Read-only. |
+| Transaction Date | Transaction Date Time. | Date | Read-only. |
+| Post Date | Post Date. | Date | Read-only. |
+| Settlement Date | Settlement Date. | Date | Read-only. |
+| Cancellation Indicator | Cancellation Indicator. | Boolean | Read-only. |
+| MCC | Transaction MCC Code. | String | Read-only. |
+| Store | Transaction Store ID. | String | Read-only. |
+| Terminal | Transaction Terminal ID. | String | Read-only. |
+| Transaction Description | Transaction Description. | String | Read-only. |
+
+#### Quick View Details (Right Panel)
+Provides a breakdown of the transaction into its component effects.
+
+**Reward Details** (Award/Redeem/Adjust)
+- Campaign Rule triggered.
+- Transaction Type.
+- OLS Transaction Code.
+- Reward Pool.
+- Pool Unit / Amount.
+
+**Counter Transaction Detail**
+- Campaign Rule triggered.
+- Counter updated.
+- Entity level.
+- Counter Value.
+- Bucket Number, Start Date, End Date.
+
+**Item Redemption Detail**
+- Item, Description.
+- Redeemed Quantity, Redeemed Points, Cash Amount Used.
+
+### Execution
+- **View-only screen.**
+- Represents all successful transaction impacts on balances, counters, and redemptions.
+
+## Exception Flow
+- N/A

docs/specs/customer_management/transfer_balance.md

@@ -0,0 +1,48 @@
+---
+title: "Transfer Balance"
+type: OpenSpec
+status: Draft
+domain: Customer Management
+---
+
+# Transfer Balance
+
+## Requirement Definition
+Allows manual transfer of points from a customer/account to another customer/account (External) or between the customer's own accounts (Internal).
+
+## Process Flow
+
+### Pre-Conditions
+- Users must have access rights in the "Transfer Balance" module.
+- Requires Maker-Checker approval.
+
+## Business Rules
+
+### Data Schema
+
+| Field Name | Description | Logic Type | Constraints / Rules |
+|---|---|---|---|
+| Transfer Mode | Internal (self) or External (to another). | Enum | Required. |
+| Transfer Type | Entity type to transfer from (Card, Account, Client). | Enum | Required. |
+| From | Card/Account/CIF Number to transfer from. | String | Required. |
+| To | Card/Account/CIF Number to transfer to. | String | Required. |
+| Pool ID | The pool from which to transfer. | Enum (Lookup) | Required. Must respect "From" entity level. |
+| Store | The store where transaction is logged. | Enum (Lookup) | Required. |
+| Amount to Transfer | Amount. | Decimal | Required. > 0. Defaults to whole pool balance. |
+| Expiry Date | Expiry date of transferred points. | Date | Required. Defaults to source expiry date. |
+| Transaction Code | OLS transaction code. | Enum (Lookup) | Required. |
+| Reason Code | Pre-defined reason for transfer. | Enum (Lookup) | Required. Determines GL posting accounts. |
+| Remarks | Additional remarks. | String (100) | Optional. |
+
+### Execution
+- **Pending/Approve Flow**: Goes to a pending list. Authorised user approves.
+- OLS validates status, block codes, and permissions for both "From" and "To".
+- Rejected if "From" pool balance is insufficient.
+- Execution transfers all linked pools directly from "From" to "To".
+- Logged as a negative Adjustment on "From" and positive Adjustment on "To".
+
+## Post-Conditions
+- Pool balances updated.
+
+## Exception Flow
+- Insufficient balance, TP validation failures, or input errors block the action.