🔍 Module: Account Details

ID: account-details | Legacy Source: CBACT01C, CBACT02C, CBACT03C, CBCUS01C + Flask GET /account/<id>

This guide covers the Account Details module — a unified view of a single account including its financial data, associated credit cards, and the linked customer profile resolved via the card cross-reference (XREF). This module replaces four COBOL batch readers and their orchestration in bridge.py.

🏗️ Technical Foundation

Layer	Target Component	Legacy Equivalent
API Controller	`AccountsController.cs`	Flask `GET /account/<acct_id>`
Application Query	`GetAccountDetailsQuery.cs` + `GetAccountDetailsQueryHandler.cs`	`bridge.py:get_account()`, `get_cards_for_account()`, `get_customer_for_account()`
Response DTO	`AccountDetailsDto.cs` (nested: cards[], customer)	Multiple ACCT01\|CARD01\|XREF03\|CUST01 stream lines
Data Access	EF Core joins: Account → Cards → CardXref → Customer	Sequential reads of 4 ASCII flat files (CBACT01C/02C/03C, CBCUS01C)
React Page	`AccountDetailPage.tsx`	`templates/account_detail.html`
React Component	`AccountInfoPanel.tsx`	Account section in `account_detail.html`
React Component	`CardListPanel.tsx`	Cards section in `account_detail.html`
React Component	`CustomerInfoPanel.tsx`	Customer section in `account_detail.html`
React Hook	`useAccountDetail.ts` (TanStack Query)	Server-side render

🌐 Public APIs

GET /api/accounts/{id}

Returns full account detail: account fields, associated cards, and linked customer. Equivalent to the combined output of CBACT01C + CBACT02C + CBACT03C + CBCUS01C.

Response Shape

{
  "id": 4000000111,
  "activeStatus": "Y",
  "currentBalance": 1234.56,
  "creditLimit": 5000.00,
  "cashCreditLimit": 2500.00,
  "openDate": "2018-03-15",
  "expirationDate": "2028-03-15",
  "reissueDate": "2023-03-15",
  "currentCycleCredit": 0.00,
  "currentCycleDebit": 0.00,
  "addressZip": "10001",
  "groupId": "GOLD",
  "cards": [
    {
      "cardNumber": "4111111111111111",
      "cvv": 123,
      "embossedName": "JOHN A DOE",
      "expirationDate": "2028-03",
      "activeStatus": "Y"
    }
  ],
  "customer": {
    "id": 111111111,
    "firstName": "John",
    "middleName": "A",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "addressStateCode": "NY",
    "addressZip": "10001",
    "ficoScore": 720,
    "primaryCardHolder": "Y"
  },
  "xrefAmbiguityWarning": null
}

⚠️ XREF Ambiguity Warning
The legacy bridge.py:xref_cust_ambiguity_message() detects when multiple cards for the same account link to different customers. The xrefAmbiguityWarning field in the response must propagate this warning to the UI so users are informed when customer data may not be unique per account.

GET /api/accounts/{id}/cards

Returns only the list of cards associated with the account (no customer data).

📐 Data Model Involved

// AccountDetailsDto — composite response for the detail page
public record AccountDetailsDto(
    long Id,
    string ActiveStatus,
    decimal CurrentBalance,
    decimal CreditLimit,
    decimal CashCreditLimit,
    DateOnly OpenDate,
    DateOnly ExpirationDate,
    DateOnly? ReissueDate,
    decimal CurrentCycleCredit,
    decimal CurrentCycleDebit,
    string AddressZip,
    string GroupId,
    IReadOnlyList<CardDto> Cards,
    CustomerSummaryDto? Customer,
    string? XrefAmbiguityWarning   // null if no ambiguity detected
);

🎯 User Story Development Patterns

US-AD-01 · View Full Account Detail (5 pts)
As a bank clerk, I want to view the full details of a specific account — including financial data, associated credit cards, and linked customer — so that I can answer customer inquiries completely from a single screen.

Given account 4000000111 exists with 2 cards and a linked customer, When GET /api/accounts/4000000111 is called, Then the response includes all account fields, a 2-card array, and a customer object.
Given the account does not exist, When GET /api/accounts/9999999999 is called, Then the API returns 404 Not Found with a descriptive message.
The React page must show an "Account Not Found" message matching the legacy templates/404.html behavior (mirrors COACTVWC "account not found in XREF" path).
All monetary amounts must display with comma-thousands-separator and 2 decimal places (matching legacy ibm_money filter).

US-AD-02 · Handle Account with No Associated Cards (2 pts)
As a bank clerk, I want to see a clear message when an account has no associated credit cards, so that I know the data is complete and no cards are linked yet.

Given account 4000000999 has 0 cards in the cross-reference, When the detail page loads, Then the cards panel shows "No cards found for this account."
The account data and customer panel must still load successfully even when the cards array is empty.

US-AD-03 · XREF Ambiguity Warning (3 pts)
As a bank clerk, I want to see a warning when an account's cards are linked to multiple different customers in the cross-reference, so that I am aware of a data integrity issue and can investigate.

Given account 4000000222 has 2 cards linked to 2 different customer IDs, When the detail page loads, Then a warning banner is displayed: "Warning: Multiple customers linked to this account via card cross-reference. Showing primary customer."
The API response must include a non-null xrefAmbiguityWarning string describing the ambiguity.

US-AD-04 · Navigate to Update from Detail (1 pt)
As a bank clerk, I want an "Edit Account" button on the detail page that navigates to the update screen, so that I can make changes without memorizing URLs.

Given the user is on the detail page for account 4000000111, When they click "Edit Account", Then they are navigated to /accounts/4000000111/edit.

📊 Story Complexity Guidelines

Points	Example
1–2	Add a "Copy Account ID" button. Show card expiration as a human-readable month/year string.
3–5	Implement the XREF ambiguity warning end-to-end (API + UI). Add transaction history panel (requires new endpoint).
8+	Add real-time account status monitoring via SignalR WebSockets. Account audit trail with full change history.

⚡ Performance Requirements

GET /api/accounts/{id} response time: <200ms P95 (single EF Core query with Include).
Add composite index on card_customer_xref(account_id, customer_id) to support efficient ambiguity detection.