# Eo

## Overview

The `eo` module is the customer foundation system for the EO broadband telephone service platform — the Japanese customer backbone system that manages end-to-end customer lifecycle operations. It covers the entire chain from service contract agreements through equipment provisioning, option services, address changes, returns, and construction workflows, all integrated with the Central Billing System (CBS).

The module is organized into two sub-packages that serve distinct architectural roles:

| Sub-package | Role |
|---|---|
| [`eo.common`](Source/koptCommon/src/eo/common/) | Shared constants and string utilities — the foundational vocabulary layer |
| [`eo.ejb`](Source/koptEjb/src/eo/ejb/) | EJB integration boundary — structured data contracts for CBS communication |

`eo.common` is the leaf node of the dependency tree: it depends only on standard Java libraries and is consumed by every other layer in the system. `eo.ejb` sits at the cross-tier boundary, defining the message formats between the frontend operator console and the CBS backend services. Together they form a layered architecture where constants and utilities enable safe data handling, and EJB schema classes define the contract for every business-domain interaction with the billing system.

## Sub-module Guide

### eo.common — the shared vocabulary

The [`eo.common`](Source/koptCommon/src/eo/common/) package is the application's shared library. It has no operational logic of its own; instead, it provides two complementary artifacts:

- **Constants** — Centralized `public static final` fields organized into three classes by domain layer. These eliminate magic strings across the codebase and serve as the single source of truth for valid values, pricing codes, device types, and error codes.
- **Utilities** — A single `JKKStringUtil` class providing null-safe string guards and Shift_JIS / EUC-JP byte-length-aware truncation. This is critical for the Japanese data encoding context where multi-byte character boundaries must be respected.

The constants package itself has three classes arranged as a vertical architectural slice:

| Class | Domain | Purpose |
|---|---|---|
| [`JDKStrConst`](Source/koptCommon/src/eo/common/constant/JDKStrConst.java) | Infrastructure | File I/O encodings, device types, logistics statuses |
| [`JKKStrConst`](Source/koptCommon/src/eo/common/constant/JKKStrConst.java) | Business domain | Pricing plans, service categories, contract statuses, display text |
| [`JPCModelConstant`](Source/koptCommon/src/eo/common/constant/JPCModelConstant.java) | Model / persistence | Function codes, error codes, DB error ranges |

The naming prefix (`JDK` / `JKK` / `JPC`) encodes which layer a constant belongs to. A single service method may import all three — reading a file with `JDKStrConst` encoding, looking up a pricing plan from `JKKStrConst`, and returning an error code from `JPCModelConstant`.

The utility class is the only part of `eo.common` with operational logic. Its `subStringByte` method ensures data truncated for Shift_JIS fields remains a valid encoding prefix, while its null-guard methods (`isNullBlank`, `isNullSpace`, `isNullEmpty`) prevent `NullPointerException` across a codebase where null string fields are common.

### eo.ejb — the CBS integration boundary

The [`eo.ejb`](Source/koptEjb/src/eo/ejb/) package defines the message contract layer between the frontend UI and the Central Billing System. It contains nearly 100 schema classes in the `cbsmsg` sub-sub-package, each representing a structured data exchange across the EJB boundary.

These classes do not contain business logic. Instead, they model the shape of every cross-tier message:

- **Header classes** (`CBSMsg` subclasses) carry search conditions, pagination parameters, error flags, and operator metadata.
- **Detail classes** (`CBSMsg1List` subclasses) contain function-specific data columns — typically paired one-to-one with a header class.

The schema classes extend `com.fujitsu.futurity.model.base.CAANSchemaInfo` from the Fujitsu Futurity application framework, relying on that framework's introspection for validation, deserialization, and serialization. The `CONTENT` arrays at the top of each class serve as the runtime schema template.

Business functions are organized by naming convention prefixes: `EKK` for equipment/service operations, `EDK` for returns, `EKU` for construction/installation, `ETU` for number reservations, and `EZM` for reference data. Each functional area follows the consistent two-class pattern, making new domains easy to learn by studying a representative pair.

### How the sub-modules relate

The relationship between `eo.common` and `eo.ejb` is one of foundation and facade:

- `eo.common` defines *what values mean* (encoding rules, valid codes, error ranges).
- `eo.ejb` defines *how those values travel* (structured messages sent across the EJB boundary to CBS).
- `eo.ejb` schema classes reference entity keys defined in `eo.common` constants — for example, service contract numbers (`SVC_KEI_NO`) and pricing plan codes from `JKKStrConst` appear in CBSMsg detail classes as shared identifiers across domains.

In practice, a typical request flows: the UI reads constants from `eo.common` to populate a form, the service layer constructs an EJB message using `eo.ejb` schema classes, and the CBS backend processes it. Constants travel embedded inside the EJB messages as field values.

```mermaid
flowchart TD
    subgraph COMMON["eo.common
Foundation Layer"]
        A["constant/
JDKStrConst"]
        B["constant/
JKKStrConst"]
        C["constant/
JPCModelConstant"]
        D["util/
JKKStringUtil"]
    end

    subgraph EJB["eo.ejb
CBS EJB Contracts"]
        E["cbs/cbsmsg/
CBSMsg (header)"]
        F["cbs/cbsmsg/
CBSMsg1List (detail)"]
    end

    subgraph CONSUMERS["Consumers"]
        G["UI Layer"]
        H["Service Layer"]
        I["I/O Layer"]
        J["Model/DAO Layer"]
    end

    A --> I
    A --> G
    B --> H
    B --> G
    C --> J
    C --> H
    D --> I
    D --> J
    E --> G
    F --> E
```

## Key Patterns and Architecture

### Two-class parent-child schema pattern

Every business function in the CBS integration uses exactly two classes — a header (`CBSMsg`) and a detail (`CBSMsg1List`). The header embeds a reference to the detail class array type in its `CONTENT` schema template. This allows the Futurity framework to introspect the full message shape at runtime. A typical cycle:

```mermaid
flowchart LR
    subgraph UI["Web UI Operator Console"]
        UI_A["Search Request"]
    end

    subgraph EJB_L["CBS EJB Contract Layer"]
        EJB_HDR["CBSMsg Header
Schema Validation"]
        EJB_LIST["CBSMsg1List[] Detail Mapping"]
    end

    subgraph CBS["Central Billing System"]
        DB["Relational Database"]
    end

    UI_A -->|"1. Search Request"| EJB_HDR
    EJB_HDR -->|"2. Schema Validation"| EJB_L
    EJB_L -->|"3. DB Query"| DB
    DB -->|"4. Result Set"| CBS
    CBS -->|"5. Map to List"| EJB_LIST
    EJB_HDR -->|"6. Embed List"| EJB_LIST
    EJB_LIST -->|"7. Response"| UI_A
```

### Universal header fields

All `CBSMsg` 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, and per-field error flags. This uniformity enables generic EJB middleware to handle any header class without domain-specific knowledge.

### Error code range convention

`JPCModelConstant` organizes error codes into numbered ranges that indicate the error domain. A developer can glance at an error code and immediately know which subsystem to investigate — ranges 0-9 for function codes, 1000-1450 for schema validation, 2000 for search limits, 6000-6100 for external interface errors, 8011-8023 for DB errors, and so on.

### Cross-domain entity sharing

The schemas share entity keys across functional 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. This means a single customer's service record is queryable from many different angles using different schema pairs, all linked through this shared identifier.

### File-based dispatch protocol

The constants in `JDKStrConst` describe a file-based dispatch protocol: `.def` template files define the layout of corresponding `.csv` data files, records are tagged with numeric type codes (`"0"` for header, `"1"` for data, `"9"` for trailer), and directory paths resolve from environment variables at runtime. This enables configurable file exchange between systems without code changes.

## Dependencies and Integration

### Internal dependencies

`eo.common` has no internal package dependencies — it imports only standard Java libraries (`java.util.ArrayList`, `java.util.Arrays`, `java.util.List`). It is a leaf node in the dependency tree, consumed by every other layer.

### External consumers

| Layer | What it consumes |
|---|---|
| **UI / Operator Console** | Fixed Japanese text strings, display constants, device type labels |
| **Service / Controller** | Pricing plans, service categories, function codes for request routing |
| **I/O / Dispatch Layer** | File names, record type codes, encoding constants, directory paths |
| **Model / DAO Layer** | DB error codes, search error flags, transaction error ranges |
| **EJB Contract Layer** | Schema classes define the cross-tier message format |

### Cross-module references

The `eo.ejb` schema classes reference entity fields defined elsewhere in the eo system — service contract numbers, equipment serial numbers, pricing codes. While no explicit cross-package dependencies are indexed at the schema layer, these field names create a network of referential integrity across the broader application. The schemas act as a shared vocabulary that other model packages depend on for data consistency.

## Notes for Developers

### Adding constants

1. Choose the right class by domain: infrastructure → `JDKStrConst`, business domain → `JKKStrConst`, model layer → `JPCModelConstant`.
2. Use `public static final` fields with `UPPER_SNAKE_CASE` naming.
3. Wrap new constant blocks with revision markers (`// ANK-XXXX-00-00 ADD START` / `ADD END`), mirroring the existing pattern.

### Working with EJB schemas

1. Create a `CBSMsg` header with the common fields plus function-specific search keys.
2. Create a paired `CBSMsg1List` detail with function-specific columns.
3. Reference the detail class type inside the header's `CONTENT` array.
4. Export column-name constants as `public static final String` for cross-module reference.

### Gotchas

- **Japanese encoding.** Many files use `Shift_JIS`. Ensure file I/O respects this encoding. The `subStringByte` method assumes Shift_JIS / EUC-JP semantics — do not use it for UTF-8 data (where multi-byte characters are 3-4 bytes, not 2).
- **Preserved typo.** `JPCModelConstant.SAERCH_TYPE_IKT` has a misspelling (`SAERCH` instead of `SEARCH`) and must not be changed for backward compatibility.
- **Large files.** `JKKStrConst.java` is approximately 6,800 lines. Use file search rather than scanning the whole file. Some `CBSMsg1List` classes exceed 1,400 lines — use line-number navigation.
- **Private constructors.** All three constant classes have private constructors. They cannot be instantiated, extended, or mocked directly. Static reflection or direct static access is required for testing.
- **Environment variables.** Directory constants are resolved from runtime environment variables, not hardcoded. Changing them requires environment configuration, not code changes.
- **Japanese source comments.** All `eo.ejb` source files contain Japanese comments on data columns — these are the authoritative source for field semantics when no additional documentation exists.

### Cross-module references

- **Service contract lifecycle:** Defined by `SVC_KEI_STAT_*` constants in `JDKStrConst`, mirrored for billing/ops by `SEIOPSVC_KEI_STAT_*` in `JKKStrConst`.
- **Price plan hierarchy:** `CD00133` (group) contains `CD00134` (individual plans). Each plan is identified by a short code (`A05`, `AB0`, etc.) and encodes product family, speed tier, customer type, and add-ons.
- **Device type taxonomy:** `JDKStrConst` defines hex-like device codes (`"A0"` for STB, `"B0"` for B-CAS, `"F0"` for Router) used across dispatch and logistics operations.