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

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.