# Root

## Overview

The root of this codebase encompasses the **eo Customer Core System** — a Japanese broadband, telephone, and mobile service management platform that handles customer contracts, billing, provisioning, and field-work order dispatch for NTT East's eo Hikari broadband, eo Hikari Denwa (light phone), and eo Mobile/UQ WiMAX services.

At the top level, the system is divided into two principal namespaces:

| Namespace | Responsibility |
|-----------|---------------|
| **`eo`** | Shared foundation, constants, utilities, and the EJB integration boundary layer |
| **`com.fujitsu`** | Fujitsu-maintained integration layer, currently centered on the SOD (Service Order) Issuance subsystem |

The `eo` namespace is the shared vocabulary and communication contract of the platform — constants, string utilities, and EJB message schemas that every other module depends on. The `com.fujitsu` namespace is where the active business orchestration happens, specifically the conversion of customer requests (new contracts, course changes, suspensions, recoveries, cancellations) into backend work orders. Together, `eo` provides the **building blocks** and `com.fujitsu` provides the **orchestration logic** that ties those blocks together.

## Sub-module Guide

### `eo` — Shared Foundation and EJB Boundary

The `eo` namespace is the foundation layer of the application. It has no classes of its own at the package level but instead contains two key child packages:

- **`eo.common`** — The centralized constants dictionary and string utilities used by every module in the system. It contains three constant classes (`JDKStrConst`, `JKKStrConst`, `JPCModelConstant`) organized by domain (infrastructure, business, model layer), plus a string utility class (`JKKStringUtil`) for null-safe operations and Shift_JIS byte-length truncation.

- **`eo.ejb`** — The EJB integration boundary between the frontend UI and the Central Billing System (CBS). It defines nearly 100 message schema classes that describe every structured data exchange across the EJB boundary, organized into header/detail pairs by business function.

These two sub-modules have a clear relationship: `eo.common` defines *what values are valid* (codes, status strings, encoding rules), while `eo.ejb.cbs` defines *how those values are exchanged* between tiers. A typical EJB message schema (`CBSMsg1List` detail row) will reference constants from `eo.common` — for example, the `SVC_KEI_STAT_A01` field in a schema corresponds to the same constant defined in `JKKStrConst` and `JDKStrConst`.

### `com.fujitsu` — Fujitsu Integration and SOD Issuance

The `com.fujitsu` namespace is the Fujitsu-maintained component of the system. Its only active child at this time is:

- **`com.fujitsu.futurity.bp`** — The SOD (Service Order) Issuance engine. This is where customer requests are received, contract state is queried from backend databases, downstream actions are determined, and orders are dispatched to the CBS through Service Interfaces (S-IFs). It consists of:
  - **`constant`** — Business code constants (price course codes, service kind values, discontinuation divisions) that serve as the SOD subsystem's source of truth.
  - **`common`** — The processing engine (`JKKHakkoSODCC`, 42,000+ lines), which implements a centralized dispatch pattern with over 25 order-control handlers and 80+ order-code dispatchers.

### How the Sub-modules Relate

The relationship between `eo` and `com.fujitsu` is **foundational → orchestration**:

```mermaid
flowchart TD
    subgraph EO[\"eo Package\"]
        subgraph COMMON[\"eo.common\"]
            CONSTANTS[\"Shared constants
JDK/JKK/JPCStrConst\"]
            UTILS[\"String utilities
JKKStringUtil\"]
        end
        subgraph EJB[\"eo.ejb\"]
            SCHEMA[\"CBS EJB schemas
CBSMsg / CBSMsg1List\"]
        end
    end

    subgraph FUJITSU[\"com.fujitsu Package\"]
        subgraph SOD[\"futurity.bp\"]
            SOD_CONST[\"SOD-specific constants\"]
            SOD_ENGINE[\"SOD Issuance engine
JKKHakkoSODCC\"]
        end
    end

    SOD_ENGINE -->|references| CONSTANTS
    SOD_ENGINE -->|references| UTILS
    SOD_ENGINE -->|uses| SCHEMA
    SCHEMA -->|references| CONSTANTS
    SOD_ENGINE -->|extends| FUTURITY_FRAMEWORK

    subgraph FW[\"Futurity Framework\"]
        ABSTR[\"AbstractCommonComponent\"]
        INV[\"ServiceComponentRequestInvoker\"]
        MSG[\"CAANMsg\"]
    end

    SOD_ENGINE -->|extends| ABSTR
    SOD_ENGINE -->|invokes| INV
    SOD_ENGINE -->|uses| MSG

    subgraph CBS[\"Central Billing System\"]
        BACKEND[\"Service Interfaces
EKK/EDK/EKU/ETU/EZM S-IFs\"]
    end

    SCHEMA -->|defines contract for| BACKEND
```

1. **Constants flow downward:** Every module imports from `eo.common.constant`. The `com.fujitsu.futurity.bp.constant` classes are *additional* constants specific to SOD processing, but they often mirror or extend values defined in `eo.common` (e.g., `SVC_KIND_NET`, `IDO_DIV_*`). When adding a new shared constant, `JKKSvcConst` (in `eo.common`) is the canonical location.

2. **Schemas flow upward:** The `eo.ejb.cbs.cbsmsg` schema classes define the message contract used by `com.fujitsu` when calling backend S-IFs. The SOD engine (`JKKHakkoSODCC`) constructs `CAANMsg` objects from these schemas, maps business data into them, and dispatches to the CBS.

3. **Utilities flow everywhere:** `JKKStringUtil` methods are used across all modules — the SOD engine uses null-safe guards when processing contract data, the EJB layer uses them when building response objects, and the I/O layer uses `subStringByte` for Shift_JIS-safe truncation.

## Key Patterns and Architecture

### Constant-class layering

The `eo.common.constant` package establishes a three-tier constant pattern that permeates the entire system:

| Tier | Class | Prefix | Role |
|------|-------|--------|------|
| Bottom | `JDKStrConst` | JDK | Infrastructure — encodings, file paths, device codes, record types |
| Middle | `JKKStrConst` | JKK | Business domain — pricing plans, service categories, statuses |
| Top | `JPCModelConstant` | JPC | Model layer — error codes, function codes, search flags |

The `com.fujitsu.futurity.bp.constant` classes follow the same pattern but for the SOD-specific domain:

| Class | Role |
|-------|------|
| `JKKHakkoSODConstCC` | SOD-specific business codes (price courses, order conditions) |
| `JKKSvcConst` | General service constants shared across all processing modules |
| `JKKItntokiStaEndConstCC` | Transfer-work-order end-state codes |

This uniformity means developers can navigate from one module's constants to another's by recognizing the prefix convention — a skill that transfers across the entire codebase.

### Centralized dispatch orchestration

The `JKKHakkoSODCC` engine is the largest class in the system at 42,000+ lines, and it operates as a **centralized dispatch switchboard**. Customer actions (new contract, course change, cancellation, suspension recovery) all converge on a single `hakkoSOD()` entry method, which branches through 25+ order-control handlers into an 80+ code dispatcher that calls the appropriate backend Service Interfaces.

This pattern is intentional — it provides a single, traceable entry point for every SOD request. However, it creates a significant maintenance burden. New service types must be wired in multiple `*OdrCtrl` methods that each hardcode service-kind checks rather than delegating to the central `jdgSvcKind()` method. The two-class constant pattern (defined in `constant`, consumed in `common`) is the primary mechanism for branching on business codes.

### Two-class schema pattern

Across `eo.ejb.cbs`, every business function uses a consistent **parent-child schema pair**:

- **Header (`CBSMsg`)** — Search conditions, pagination, error flags, operator metadata
- **Detail (`CBSMsg1List`)** — Function-specific data columns

The header declares a `static final Object[][] CONTENTS` array that lists field definitions as `{ name, type, description }` tuples. This template-based approach (rather than annotations) enables the Futurity framework to introspect schemas at runtime without reflection. The same pattern is used across ~100 schema classes covering service contracts, equipment provision, option services, orders, address changes, and returns.

### S-IF call quadruple

For each backend Service Interface, the SOD engine implements a consistent four-method pattern:

1. `callEKKxxxxSC` — Constructs a `CAANMsg` template, invokes via `ServiceComponentRequestInvoker`
2. `mappingEKKxxxxInMsg` — Populates the template from a `HashMap` of input data
3. `mappingEKKxxxxOutMsg` — Extracts results from `CAANMsg[]` into a `HashMap`
4. `editErrorInfoEKKxxxxCBS` — Maps S-IF error information

This pattern is applied consistently across 30+ service interfaces. Adding a new S-IF requires following this pattern exactly.

### Stateful per-request processing

The SOD engine uses instance fields as working storage within a single `hakkoSOD` invocation. The most critical of these is `same_trn_no` (the shared transaction number), which groups related orders into a single atomic business operation. Because the class must be instantiated per-request, state fields must be cleared at the start of each `hakkoSOD` call — any new state fields added must follow this discipline, or cross-request data leakage will occur.

```mermaid
flowchart LR
    subgraph EO_Found[\"eo Foundation\"]
        CONST[\"eo.common.constant
Shared constants\"]
        UTIL[\"eo.common.util
String utilities\"]
        SCHEMA[\"eo.ejb.cbs
CBS schemas\"]
    end

    subgraph SOD_Orch[\"com.fujitsu SOD Orchestration\"]
        SOD_ENT[\"JKKHakkoSODCC
42K lines\"]
        SOD_STATE[\"Per-request instance
fields: same_trn_no,
ido_div, prc_grp_cd\"]
        SOD_DISPATCH[\"hakkoSOD → OdrCtrl → addSOD
25 handlers, 80+ codes\"]
    end

    CONST -->|imports| SOD_ENT
    UTIL -->|imports| SOD_ENT
    SCHEMA -->|imports| SOD_ENT
    SOD_ENT -->|uses| SOD_STATE
    SOD_ENT -->|dispatches| SOD_DISPATCH
    SOD_DISPATCH -->|calls| SIF[\"CBS Service Interfaces
EKK/EDK/EKU/ETU/EZM\"]
```

## Dependencies and Integration

### Internal package dependencies

| Dependency | Consumed by | Purpose |
|------------|------------|---------|
| `eo.common.constant` | `com.fujitsu.futurity.bp`, `eo.ejb.cbs` | Shared string constants, business codes |
| `eo.common.util` | `com.fujitsu.futurity.bp`, `eo.ejb` | String utilities (null guards, byte truncation) |
| `eo.ejb.cbs.cbsmsg` | `com.fujitsu.futurity.bp` | Message schema definitions for S-IF communication |

### Framework dependencies

The `com.fujitsu` module extends the **Futurity framework** (`com.fujitsu.futurity`), which provides:

- `AbstractCommonComponent` — Base class for all business processing components
- `SessionHandle` — Database session management
- `ServiceComponentRequestInvoker` — S-IF invocation infrastructure
- `CAANMsg` — Canonical message envelope for Service Interface communication

### External integration

The `eo.ejb.cbs` schemas define the contract for calling the **Central Billing System (CBS)** via approximately 20 Service Interfaces:

| S-IF Range | Purpose |
|------------|---------|
| `EKK0081*` | Service contract inquiry |
| `EKK0161*`, `EKK0251*` | Contract detail / usage lookups |
| `EKK0191*` | Light phone service details |
| `EKK0341*` | Equipment provision |
| `EKK0351*`, `EKK0361*`, `EKK0401*` | Option service contracts |
| `EKK1041*` | Order settings |
| `EKK1081*`, `EKK1551*` | Order registration and work creation |

### Dependency direction

```mermaid
flowchart LR
    FUI[\"Frontend / UI
layer\"] -->|uses schemas| EJB
    EJB[\"eo.ejb.cbs.cbsmsg
EJB schemas\"] -->|references| EOC
    EOC[\"eo.common.constant\"]
    EOU[\"eo.common.util\"]
    CMP[\"com.fujitsu.futurity.bp
SOD engine\"] -->|uses schemas| EJB
    CMP -->|imports constants| EOC
    CMP -->|imports utils| EOU
```

The `eo.common` and `eo.ejb` modules are **leaf nodes** in the dependency tree — they import no application packages. Everything flows toward `com.fujitsu`, which is the primary consumer of both `eo` modules' artifacts.

## Notes for Developers

### Large-file awareness

Several files in this codebase are exceptionally large:

| File | Lines | Location |
|------|-------|----------|
| `JKKHakkoSODCC` | 42,000+ | `com/fujitsu/futurity/bp/common` |
| `JKKStrConst` | ~6,800 | `eo/common/constant` |
| `EKK0341A010CBSMsg1List` | 1,469 | `eo/ejb/cbs/cbsmsg` |
| `EKK0081A010CBSMsg` | ~955 | `eo/ejb/cbs/cbsmsg` |

Use line-number-based navigation rather than scrolling. The `JKKHakkoSODCC` class is sectioned into clearly delineated regions: class state (~500 lines), `hakkoSOD` entry (~430), `addSOD` dispatch (~3,800), `*OdrCtrl` methods (~11,400), and S-IF call infrastructure (~4,400).

### Extension checklist

When adding a new order operation or service type:

1. **Choose the right constants class.** Infrastructure → `JDKStrConst`, business domain → `JKKStrConst` (in `eo.common`), SOD-specific → `JKKHakkoSODConstCC`, transfer-specific → `JKKItntokiStaEndConstCC`. Prefer `JKKSvcConst` as the canonical location for shared constants.

2. **Add the constant** with a `// ANK-XXXX-00-00 ADD START/END` marker and a Japanese Javadoc comment (matching the codebase convention).

3. **Wire into the SOD engine.** Add a branch in `addSOD` or the appropriate `*OdrCtrl` method. If new service types are involved, add a branch in `jdgSvcKind()` and in all `*OdrCtrl` methods where service-kind branching occurs.

4. **If a new S-IF is needed.** Follow the four-method call pattern (`call*SC`, `mapping*InMsg`, `mapping*OutMsg`, `editErrorInfoEKK*CBS`) using the existing `CBSMsg` schemas from `eo.ejb.cbs`.

5. **Clear new state fields** at the start of `hakkoSOD` (around line 633) to avoid cross-request contamination.

### Japanese source documentation

The codebase is primarily in Japanese. Javadoc and inline comments should remain in Japanese. When adding new code, write new comments in Japanese to match the existing convention. This reflects the product's use by Japanese operations teams.

### Encoding considerations

Many dispatch files use `Shift_JIS`. The `subStringByte` utility in `eo.common.util` is specifically designed for Shift_JIS / EUC-JP character widths. Do not use it for UTF-8 data, where multi-byte characters are 3–4 bytes. When in doubt, `ENCODE_SJIS` is the default for dispatch and legacy file operations.

### Cross-request state discipline

If you add new state fields to `JKKHakkoSODCC`, ensure they are cleared at the start of `hakkoSOD`. The `same_trn_no` field is the most critical — it groups related SODs into a single atomic operation and must be shared across all orders in the same business operation.

### Preserved imperfections

- `JPCModelConstant.SAERCH_TYPE_IKT` has a typo (`SAERCH` instead of `SEARCH`) that must not be changed for backward compatibility.
- The `isNullEmpty` method in `JKKStringUtil` uses raw `ArrayList` types — prefer `instanceof List<?>` in new code.
- Some constants are duplicated between `JKKHakkoSODConstCC` and `JKKSvcConst` due to independent evolution. Use `JKKSvcConst` as the canonical location.

### Version history

The SOD module has undergone 70+ version changes since 2011. When modifying any file, add your change to the file header following the existing format. Major feature additions include IPv6 support (2012), mobile services (2012), multi-function router (2013), VLAN-ID (2012), malware blocking (2020), Netflix integration (2020), 5G/10G courses (2021), PSTN migration ENUM (2021), MT existing lease (2022), e-o Home Gateway (2023), Rakuten Fletts (2023), eo Hikari Net Simple Plan (2024), and NTT response / Fiber wiring course update (2024).