# Eo / Ejb / Cbs

## Overview

The `eo.ejb.cbs` package sits at the integration boundary between the frontend UI and the Central Billing System (CBS) within the eo broadband telephone service platform. It is the **Central Billing System message schema layer** — a collection of data contract classes that define every structured data exchange between EJB callers and backend CBS services.

This area of the codebase does not contain business logic. Instead, it provides the **data contracts** that the Fujitsu Futurity framework uses for validation, deserialization, and serialization across EJB boundaries. Every message class extends `com.fujitsu.futernity.model.base.CAANSchemaInfo`, relying on the framework's introspection infrastructure for schema management rather than annotations or reflection.

The business scope is broad, covering customer-facing operations across service contract management, equipment provisioning, option services, order processing, address changes, number reservations, returns, construction linkage, and reference data lookups.

## Sub-module Guide

This module currently has one child wiki page:

### `cbsmsg` — Service Contract Message Schema

The `cbsmsg` package contains nearly 100 classes that model every domain area of the CBS integration layer. Rather than organizing the package into subpackages, the codebase uses a naming convention to organize classes by business function. The classes fall into functional groups:

- **Service contract agreements** (`EKK0081`) — primary contract inquiry with the largest detail rows in the package (~955 lines, ~120 fields)
- **Service contract contents** (`EKK0161`, `EKK0191`) — contract detail search, number reservation inquiry, history lists, and eo light phone contract variants
- **Service contract line details** (`EKK0251`) — line-level breakdown within a service contract
- **Equipment provision contracts** (`EKK0341`) — the most complex functional group with nine paired classes; the primary detail class spans 1,469 lines, the largest in the entire package
- **Option services** (`EKK0351`, `EKK0361`, `EKK0401`, `EKK0411`, `EKK2811`) — a multi-layered hierarchy of option contracts, sub-options, ISP agreements, and equipment-specific options
- **Order processing** (`EKK1041`, `EKK1081`, `EKK1551`) — order settings, issuance conditions, and work registration; notable because EKK1081 includes both read and write operations
- **Address changes** (`EKK2091`, `EKK2101`) — address modification inquiry and detail listing
- **Return equipment** (`EDK0301`) — cancellation tracking with warehouse and shelf codes
- **Construction/installation** (`EKU0011`, `EKU0081`) — job case inquiries linking service contracts to construction schedules
- **Reference data** (`EZM0121`, `EZM0321`, `EZM0411`) — phone number lookups, business parameters, and indoor equipment model codes

All functional areas share the same two-class pattern (header `CBSMsg` + detail `CBSMsg1List`), making it possible to reason about new classes by learning one representative from each domain group.

## Architecture and Key Patterns

### Two-class parent-child schema pattern

Every business function uses exactly two classes:

| Class Type | Role |
|---|---|
| `CBSMsg` (header) | Search conditions, pagination, error flags, operator metadata. Embeds a reference to the detail class array. |
| `CBSMsg1List` (detail) | Function-specific data columns returned per record. |

The header class declares a `static final Object[][] CONTENTS` array as its schema template. This array lists field definitions as `{ name, type, description }` tuples and ends with a reference to the child detail class (e.g., `{"CONTENTS", "EKKxxxxCBSMsg1List[]", ...}`). The `getContents()` method returns this template, allowing the Futurity framework to introspect the schema at runtime.

### Universal header fields

All header classes share an identical set of common fields regardless of their business function — service identifiers (`templateID`, `identifyCD`), operator tracking (`operatorID`, `operateDate`), authorization (`ac_group_cd`, `func_code`), pagination (`max_search_num`, `total_page_num`), and per-field error flags (`*_err`). This uniformity means any header can be handled by generic EJB middleware code.

### Referential integrity across domains

The schemas share entity keys across boundaries, creating a network of cross-functional references:

```mermaid
flowchart LR
    subgraph SC["Service Contracts"]
        SC_A["EKK0081A010
Agreement Search"]
        SC_191["EKK0191A010
Contract Contents"]
    end

    subgraph EQ["Equipment Provision"]
        EQ_A["EKK0341A010
Equipment Search"]
        EQ_Serial["EKK0341B001
By Serial No"]
    end

    subgraph OPT["Option Services"]
        OPT_A["EKK0351A010
Option Contract"]
        OPT_ISP["EKK0361A010
ISP Agreement"]
    end

    subgraph OPS["Operations"]
        ORD["EKK1041A010
Order Settings"]
        RET["EDK0301B060
Return Cancellation"]
        ADDR["EKK2091A010
Address Change"]
    end

    SC_A --- EQ_A
    SC_A --- OPT_A
    SC_A --- ORD
    SC_A --- RET
    SC_A --- ADDR
    EQ_Serial --- EQ_A
    OPT_A --- OPT_ISP
```

The most frequently shared key is `SVC_KEI_NO` (service contract number), which appears across service contracts, line details, equipment provision, option services, and address changes. A single customer's service record is queryable from many different angles using different schema pairs, all linked through this shared identifier.

### Data flow

A typical request cycle proceeds through seven steps:

```mermaid
flowchart TD
    UI["Web UI
Operator Console"] -->|"1. Search Request"| EJB
    EJB["CBS EJB Services
Business Logic"] -->|"2. Schema Validation"| HDR
    EJB -->|"3. DB Query"| DB
    DB["CBS Relational Database"] -->|"4. Result Set"| EJB
    EJB -->|"5. Map to CBSMsg1List[]"| DET
    HDR["CBSMsg Header
ejb.cbs.cbsmsg schema"] -->|"6. Embed List"| HDR
    EJB -->|"7. Response"| UI
    DET["CBSMsg1List Detail
Function-specific data"] -->|"Embedded in"| HDR
```

### Error tracking convention

Every header class includes error tracking fields following a consistent naming pattern (`*_err`, `*_err_err`, `*_List_err`), which the UI layer reads to render inline error messages next to form fields.

## Dependencies and Integration

- **Framework dependency**: All classes extend `com.fujitsu.futurity.model.base.CAANSchemaInfo` from the Fujitsu Futurity application framework. This single base class provides the entire serialization, validation, and schema introspection layer.
- **EJB boundary**: The package path `eo.ejb.cbs.cbsmsg` positions these classes as the contract boundary between frontend EJB callers and the CBS backend. They define the message format for all cross-tier communication in this domain.
- **Cross-module references**: While no explicit cross-package dependencies are indexed at the schema layer, field names (service contract numbers, equipment serial numbers, pricing codes) reference entities defined in other model packages throughout the eo system. The schemas act as a shared vocabulary.
- **Japanese source documentation**: All source files contain Japanese comments on data columns, which are the authoritative source for field semantics when no additional documentation exists.

## Notes for Developers

### Naming conventions

| Prefix | Domain |
|---|---|
| `EKK` | Equipment / service operations |
| `EDK` | Return / equipment operations |
| `EKU` | Construction / installation operations |
| `ETU` | Number reservation construction |
| `EZM` | Reference data operations |

| Suffix | Meaning |
|---|---|
| `A010` | Primary search/inquiry variant (headers) |
| `Bxxx` | Specific processing detail variants |
| `C/D/E` | Write operations (registration, logical deletion) |

### Adding a new business function

1. Create a `CBSMsg` header class with the common header fields plus any function-specific search keys.
2. Create a `CBSMsg1List` detail class with the function-specific data columns.
3. Reference the `CBSMsg1List[]` type inside the header's `CONTENTS` array to establish the parent-child link.
4. Export column-name constants as `public static final String` for cross-module reference.

### Working with large schema classes

Some `CBSMsg1List` classes are exceptionally large (1,400+ lines for `EKK0341A010CBSMsg1List`). When working with these:

- Use line-number-based navigation rather than scrolling through the entire file.
- Field count grows organically with new business requirements; consider whether a split into sub-detail classes is warranted for very wide tables.
- Check for `*_nm` suffix columns, which are display-name variants maintained in parallel with code columns.

### Schema file structure

Each class follows this layout:

1. `static final Object[][] CONTENTS` — schema template at file top
2. `static final String` constants — one per field
3. `static { ... }` block — binds constants to string values
4. `getContents()` — returns the template array
5. `static final String` export constants — public column names for cross-module use