👤 Module: Customer Management

ID: customer-management | Legacy Source: CCUSTUPC.cbl + CBCUS01C.cbl + bridge.py:update_customer()

This guide covers the Customer Management module — view and update of customer profiles (name, address, contact, financial identifiers). In the legacy system, customer update was invoked from the Account Update screen (POST to Flask, which called CCUSTUPC if customer data changed). In the new system, customer updates are a dedicated REST endpoint, but can still be triggered from the Account Update page.

🔐 Security Notice — SSN Handling
The legacy system stored CUST-SSN as a plain 9-digit integer in custdata.txt. In the new system, SSN must be encrypted at rest using field-level encryption before storage in PostgreSQL. The API must never return a full SSN; it should be masked in responses (e.g., ***-**-4321). Implement this before the data migration sprint.

🏗️ Technical Foundation

Layer	Target Component	Legacy Equivalent
API Controller	`CustomersController.cs`	Customer section of Flask `account_update()`
Query	`GetCustomerQuery.cs` + `GetCustomerQueryHandler.cs`	`bridge.py:get_customer_for_account()` via CBCUS01C
Command	`UpdateCustomerCommand.cs` + `UpdateCustomerCommandHandler.cs`	`bridge.py:update_customer()` → CCUSTUPC subprocess
Validator	`UpdateCustomerCommandValidator.cs` (FluentValidation)	CCUSTUPC validation section (CUSVALUS.cpy rules)
Data Access	EF Core: `Customer` table (PostgreSQL)	Sequential read/write of `custdata.txt` (500-byte records, CVCUS01Y layout)
React Component	`CustomerUpdateForm.tsx` (embedded in AccountUpdatePage)	Customer section of `templates/account_update.html`
React Hook	`useCustomer.ts` + `useUpdateCustomer.ts`	Server-side render; form POST
Script	Data migration script (reads `CVCUS01Y` layout)	`scripts/fix_custdata_for_ccustupc.py`

🌐 Public APIs

GET /api/customers/{id}

Returns the customer profile. SSN is masked in the response.

{
  "id": 111111111,
  "firstName": "John",
  "middleName": "A",
  "lastName": "Doe",
  "addressLine1": "123 Main St",
  "addressLine2": "",
  "addressLine3": "New York",
  "addressStateCode": "NY",
  "addressCountryCode": "USA",
  "addressZip": "10001",
  "phoneNumber1": "2125551234",
  "phoneNumber2": "",
  "ssnMasked": "***-**-1234",
  "govtIssuedId": "DL-NY-12345",
  "dateOfBirth": "1985-06-15",
  "eftAccountId": "EFT12345",
  "primaryCardHolder": "Y",
  "ficoCreditScore": 720
}

PUT /api/customers/{id}

Updates customer profile fields. All CCUSTUPC validation rules apply. Returns 422 if no changes detected.

Request Body

{
  "firstName": "John",
  "middleName": "A",
  "lastName": "Doe",
  "addressLine1": "456 Park Ave",
  "addressLine2": "",
  "addressLine3": "New York",
  "addressStateCode": "NY",
  "addressCountryCode": "USA",
  "addressZip": "10022",
  "phoneNumber1": "2125559876",
  "phoneNumber2": "",
  "ssn": "123456789",
  "govtIssuedId": "DL-NY-12345",
  "dateOfBirth": "1985-06-15",
  "eftAccountId": "EFT12345",
  "primaryCardHolder": "Y",
  "ficoCreditScore": 720
}

📋 Business Rules (Extracted from CCUSTUPC.cbl + CUSVALUS.cpy)

Code	Field(s)	Rule	Error Message (en)
CUST_SSN	ssn	Exactly 9 numeric digits	"SSN must be exactly 9 numeric digits."
CUST_ZIP	addressZip	Exactly 5 or 9 digits (no letters, no dashes)	"ZIP code must be exactly 5 or 9 digits."
CUST_STATE	addressStateCode	Exactly 2 characters; must be a valid US state code (per CUSVALUS.cpy)	"State code must be a valid 2-character US state abbreviation."
CUST_PHONE	phoneNumber1, phoneNumber2	If provided, exactly 10 digits (stored padded to 15 chars in legacy)	"Phone number must be exactly 10 digits."
CUST_DOB	dateOfBirth	If provided, YYYY-MM-DD format and a valid calendar date; must be in the past	"Date of birth must be a valid past date in YYYY-MM-DD format."
CUST_FICO	ficoCreditScore	Integer in range 300–850	"FICO score must be between 300 and 850."
PRI_HOLDER	primaryCardHolder	Must be exactly "Y" or "N"	"Primary card holder indicator must be Y or N."

📐 Phone Number Format Note

The legacy system stores phone numbers as 15-character padded strings (matching COBOL CUST-PHONE-NUM-1 PIC X(15)). The Python bridge splits the form's 3-part input (area code + 3 + 4 digits) and pads to 15. In the new system:

The API accepts phone as a plain 10-digit string.
The DB stores it as VARCHAR(15) for backward compatibility with the legacy layout.
The React form uses a masked input (e.g., (212) 555-1234) and strips formatting before submitting.

📐 SSN Split-Field Legacy Pattern

The legacy HTML form split SSN into 3 fields: ACTSSN1 (3 digits), ACTSSN2 (2 digits), ACTSSN3 (4 digits). The Python bridge reassembled them via _caup_ssn_from_form(). In the new system:

The React form may show SSN as a masked single field or 3 separate fields for UX parity.
The API accepts SSN as a single 9-digit string; masking is handled server-side in responses.

🎯 User Story Development Patterns

US-CM-01 · Update Customer Contact Information (3 pts)
As a bank clerk, I want to update a customer's address, phone numbers, and ZIP code so that contact information stays current.

Given valid inputs, When PUT /api/customers/{id} is called, Then the response is 200 OK and the DB is updated.
Given an invalid ZIP (e.g., "ABCDE"), Then the API returns 400 with error code CUST_ZIP.
Given a phone number with 9 digits, Then the API returns 400 with error code CUST_PHONE.

US-CM-02 · Update Customer FICO Score (2 pts)
As a bank clerk, I want to update a customer's FICO credit score (range 300–850) so that the credit profile reflects the latest bureau data.

Given I submit ficoCreditScore = 750, Then the update succeeds.
Given I submit ficoCreditScore = 200, Then the API returns 400 with error code CUST_FICO and message "FICO score must be between 300 and 850."
Given I submit ficoCreditScore = 851, Then same validation error.

US-CM-03 · SSN Must Be Stored Encrypted (5 pts)
As a security officer, I want the customer SSN to be encrypted at rest in the database so that a database breach does not expose full SSNs.

Given a customer update with SSN 123456789, When the record is saved, Then the raw value stored in the customers.ssn column is NOT the plain 9-digit number.
Given GET /api/customers/{id} is called, Then the response field ssnMasked shows only the last 4 digits (e.g., ***-**-6789); a raw SSN field is never included in the response.

US-CM-04 · Customer Update No-Change Guard (2 pts)
As the system, I want to skip a customer update if the submitted data matches the stored record so that unnecessary DB writes are avoided (mirrors legacy _customer_form_unchanged()).

Given the submitted customer fields are identical to the stored values (including SSN, phone, DOB, FICO), When PUT /api/customers/{id} is called, Then the response is 422 with message "No changes detected — record not updated."

US-CM-05 · Validate US State Code (2 pts)
As the system, I want to validate that the state code is a recognized US state abbreviation (per the US Postal Service list in CUSVALUS.cpy) so that invalid state entries are rejected.

Given addressStateCode = "NY", Then the update succeeds.
Given addressStateCode = "ZZ", Then the API returns 400 with error code CUST_STATE.
The valid state list must match exactly the states defined in app/cobol/CUSVALUS.cpy (generated by scripts/gen_cusvalus_cpy.py).

📊 Story Complexity Guidelines

Points	Example
1–2	Change address field max length. Add country code validation.
3–5	Implement SSN encryption + masking end-to-end. Add customer search by name.
8+	Customer audit trail (every field change logged with who/when/from-to). Customer deduplication detection.

⚡ Performance Requirements

PUT /api/customers/{id}: <200ms P95 (validation + encrypted SSN write).
SSN encryption must use a well-established library (e.g., Portable.BouncyCastle or .NET native AesGcm) — no homebrew crypto.
Index on customers.last_name to support future customer search.