# Eo / Ejb

## Overview

The `eo.ejb` package serves as the integration boundary layer between the frontend UI and the Central Billing System (CBS) within the eo broadband telephone service platform. It sits at the cross-tier boundary — the point where frontend EJB callers hand off structured data to backend CBS services.

Rather than containing business logic, this package provides the **data contract layer**: a collection of Java classes that define every structured data exchange across the EJB boundary. These classes extend `com.fujitsu.futurity.model.base.CAANSchemaInfo` from the Fujitsu Futurity application framework, relying on that framework's introspection infrastructure for validation, deserialization, and serialization.

The business scope is broad, encompassing customer-facing operations across service contract management, equipment provisioning, option services, order processing, address changes, number reservations, returns, construction/linkage workflows, and reference data lookups. Every one of these domains is represented as a pair of message classes — a header with search conditions and metadata, and a detail list with function-specific data columns.

## Sub-module Guide

The `eo.ejb` module currently has one child wiki page:

### `cbs` — Central Billing System Schema Layer

The `cbs` sub-package (specifically the `cbsmsg` sub-sub-package within it) holds nearly 100 message schema classes that model every domain area of the CBS integration. These classes are the primary artifact of the `eo.ejb` module and serve as the shared vocabulary between the UI layer and the billing backend.

The classes are organized by business function using a naming convention rather than a subpackage hierarchy. Functional groups include service contract agreements, equipment provision, option services, order processing, address changes, returns, construction/installation, and reference data. Each functional area uses a consistent two-class pattern: a header class (`CBSMsg`) and a detail class (`CBSMsg1List`), making it possible to learn any new domain by studying just one representative pair.

The most complex functional group is equipment provision (`EKK0341`), which has nine paired classes and a detail class spanning 1,469 lines. The primary service contract agreement inquiry (`EKK0081`) is the largest single schema at ~955 lines and ~120 fields.

## Architecture and Key Patterns

### Two-class parent-child schema pattern

Every business function in the CBS integration layer uses exactly two classes:

- **`CBSMsg` (header)** — Carries search conditions, pagination parameters, error flags, and operator metadata. Embeds a reference to the detail class array type.
- **`CBSMsg1List` (detail)** — Contains the function-specific data columns returned per record.

The header 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, enabling the Futurity framework to introspect the schema at runtime without annotations or reflection.

### Universal header fields

All header classes share an identical set of common fields regardless of 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 enables generic EJB middleware to handle any header class without domain-specific knowledge.

### Referential integrity across domains

The schemas share entity keys across boundaries, creating a network of cross-functional references. 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.

```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
```

### Data flow through the schema layer

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
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. This pattern is shared by all child schema classes in the `cbs` sub-module.

## 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