# Com / Fujitsu / Futurity

## Overview

This area of the codebase is the **Service Order (SOD) Issuance** subsystem of the K-Opticom eo Customer Core System — a Japanese broadband, telephone, and mobile service management platform operated by K-Opticom and maintained by Fujitsu. It serves as the central orchestration layer that receives customer requests (new contracts, course changes, suspensions, recoveries, cancellations, address modifications, and option adjustments), queries backend databases for current contract state, determines what downstream actions are required, and dispatches those actions to a suite of Service Interfaces (S-IFs).

The end result of this module's processing is the creation of work orders that trigger billing updates, field dispatch, network provisioning, and customer notifications. In short: it is the system that turns a customer's request to change their service into actual operational work.

---

## Sub-module Guide

### `bp` — Business Processing

The `bp` package is the sole and most significant child of this module. It is composed of two tightly coupled sub-sub-modules:

#### `constant` — The Shared Vocabulary

This sub-sub-module defines three constant classes that serve as the single source of truth for all business values used across the SOD subsystem:

| Class | Domain | Role |
|-------|--------|------|
| `JKKHakkoSODConstCC` | SOD issuance | Data interchange keys, pricing/course codes, order type codes, equipment codes, UI template IDs |
| `JKKSvcConst` | General service | Service codes, contract lifecycle statuses, change classifications, cancellation reasons |
| `JKKItntokiStaEndConstCC` | Transfer work orders | State-machine codes for the transfer (itntoki) lifecycle |

These classes are non-instantiable containers of `public static final String` fields with no methods or instance state. Any code that needs to compare a business code — whether checking if a service is internet, determining if a contract is suspended, or building a work order map — references one of these constants instead of using magic strings.

#### `common` — The Processing Engine

This sub-sub-module contains a single class, `JKKHakkoSODCC`, which extends the Futurity framework's `AbstractCommonComponent`. Despite being a single file of 42,000+ lines, it is a well-organized orchestrator that handles the entire SOD dispatch flow:

1. **Entry point** — `hakkoSOD()` receives contract data, extracts SOD maps, sanitizes character encoding, and determines the service kind.
2. **Order control dispatch** — Over 25 `*OdrCtrl` methods each handle a specific business scenario (new contract, course change, cancellation, recovery, suspension, address change, option settings, light phone operations, ID/PW reset, etc.).
3. **Work registration** — `addSOD()` and `tsuikabunAddSOD()` map contract data to order conditions and order information creation work tables, dispatching on `orderNaiyoCd` codes (80+ codes covering FTTH auth, email, My Homepage, multi-function router, Wi-Fi spot, IPv6, etc.).
4. **Contract data queries** — A comprehensive set of `get*` methods fetch service contract info, option service lists, sub-option lists, service detail lists, and equipment provision lists.
5. **S-IF call wrappers** — For each backend Service Interface, four methods are implemented: `callEKKxxxxSC` (invocation), `mappingEKKxxxxInMsg` (input mapping), `mappingEKKxxxxOutMsg` (output mapping), and `editErrorInfoEKKxxxxCBS` (error mapping).

#### How the Sub-sub-modules Relate

The relationship between the two sub-sub-modules is fundamental to the system's architecture:

```mermaid
flowchart LR
    subgraph Constants["Constant Classes"]
        HAKKO["JKKHakkoSODConstCC
SOD-specific constants"]
        SVC["JKKSvcConst
General service constants"]
        ITN["JKKItntokiStaEndConstCC
Transfer state machine constants"]
    end

    subgraph Common["Common Module"]
        MAIN["JKKHakkoSODCC
SOD Issuance Engine
200+ methods"]
    end

    HAKKO -->|references| MAIN
    SVC -->|extends, shared| MAIN
    ITN -->|referenced by| MAIN
```

The `common` sub-sub-module imports constants from the `constant` package at every level — from the simplest string comparison to the most complex contract data lookups. The constant classes define both the **map keys** used to pass data between processing layers and the **business codes** used to branch processing logic.

The constant package serves as the **canonical reference** — if a business code changes (e.g., a new price course code is added), the constant class is the single place to update. The common sub-module is where that code is consumed in branching logic, S-IF input mapping, and order condition evaluation.

---

## Key Patterns and Architecture

### Centralized Dispatch Architecture

`JKKHakkoSODCC` follows a centralized dispatch pattern. Rather than distributing business logic across many small objects, the class acts as a switchboard:

```mermaid
flowchart TD
    subgraph Trigger["Customer Actions"]
        NEW["New Contract"]
        CHG["Course Change"]
        CXL["Cancellation"]
        SUS["Suspension Recovery"]
        OPT["Option Settings"]
    end

    subgraph Dispatch["JKKHakkoSODCC Engine"]
        ENTRY["hakkoSOD entry"]
        CTRL["OdrCtrl handlers
25+ methods"]
        ADD["addSOD dispatcher
80+ order codes"]
    end

    subgraph Backend["Service Interfaces"]
        S1["EKK0081 - Contract lookup"]
        S2["EKK0351 - Option list"]
        S10["EKK1081 - Same trn no"]
        S11["EKK1081D - Cond registration"]
        S12["EKK1551D - Work registration"]
    end

    NEW --> ENTRY
    CHG --> ENTRY
    CXL --> ENTRY
    SUS --> ENTRY
    OPT --> ENTRY

    ENTRY --> CTRL
    CTRL --> ADD
    ADD --> S1
    ADD --> S2
    ADD --> S10
    ADD --> S11
    ADD --> S12
```

This pattern has the advantage of a single, traceable entry point for every SOD request, but the cost is the extreme size of `JKKHakkoSODCC`. The class's 200+ methods are organized into clearly delineated sections: class fields (~300 lines), the `hakkoSOD` entry (~430 lines), the `addSOD` dispatch (~3,800 lines), the `*OdrCtrl` family (~11,400 lines), query methods (~2,000 lines), and S-IF call infrastructure (~4,400 lines).

### Stateful Per-Request Processing

The class uses instance fields as working storage within a single `hakkoSOD` invocation. Key state includes:

- `same_trn_no` — A shared transaction number that groups related orders into a single atomic business operation
- `prc_grp_cd` / `pcrs_cd` — Price group and course codes that determine service type
- `ido_div` — Discontinuation division indicating what kind of change is occurring
- Option service contract numbers for email, My Homepage, mailing list, dial-up, IPv6, and number porting
- Equipment provision contract numbers

This stateful design means the class must be instantiated per-request and must never be shared across concurrent requests. The `hakkoSOD` method clears key state variables at the start of each processing cycle. If new state fields are added, they must be cleared in the same location to avoid cross-request contamination.

### S-IF Call Pattern

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

1. **`callEKKxxxxSC`** — Constructs a `CAANMsg` template, invokes the service via `ServiceComponentRequestInvoker`, and returns a status code.
2. **`mappingEKKxxxxInMsg`** — Populates the `CAANMsg` template from a `HashMap` of input data.
3. **`mappingEKKxxxxOutMsg`** — Extracts result data from `CAANMsg[]` responses into a `HashMap`.
4. **`editErrorInfoEKKxxxxCBS`** — Maps S-IF error information for the calling layer.

This pattern is highly repetitive and is consistently applied across 30+ service interfaces. When adding a new S-IF, this pattern should be followed exactly.

### Service Kind Branching

The `jdgSvcKind()` method maps a price group code (`prc_grp_cd`) to one of three service kinds:

- `SVC_KIND_NET` — Internet services (FTTH, ADSL)
- `SVC_KIND_TEL` — Light phone (eo Hikari Denwa)
- `SVC_KIND_MOB` — Mobile services (eo Mobile, UQ WiMAX)

This single determination branches the entire processing flow for any given contract. New service types must add a new branch in `jdgSvcKind()` and in all `*OdrCtrl` methods where service-kind branching occurs. Note that many controllers hardcode service-kind checks rather than calling `jdgSvcKind()`, so new services must be wired in multiple locations.

### IPv6 Special Handling

IPv6 option processing has a unique code path with dedicated instance fields (`ipv6_svc_kei_ucwk_no`, `op_gadtm_ipv6`, `sod_pattern_ipv6`). The `addIpv6SODAft` method uses the `sod_pattern_ipv6` flag to control whether an IPv6 order should be issued. Modifications that affect contract data impacting IPv6 require careful attention to this code path.

---

## Dependencies and Integration

### Internal Dependencies

| Dependency | Purpose |
|-----------|---------|
| `eo.common.constant` | Shared string constants (`JKKStrConst`, `JKKTimeConst`, etc.) |
| `com.fujitsu.futurity.bp.custom.constant` | Module-specific constants (`JKKHakkoSODConstCC`, `JKKSvcConst`, `JKKItntokiStaEndConstCC`) |
| `eo.common.util` | Utility classes (`JKKStringUtil`) |
| `eo.ejb.cbs.cbsmsg` | CAANMsg type definitions for S-IF communication (20+ message classes) |

### Framework Dependencies

`JKKHakkoSODCC` extends the Futurity framework's `AbstractCommonComponent` and uses:

- `SessionHandle` — Session management for database connections
- `IRequestParameterReadWrite` / `IRequestParameterReadOnly` — Parameter passing abstraction
- `ServiceComponentRequestInvoker` — Invokes backend service components
- `CAANMsg` — The canonical message envelope for S-IF communication

### Backend Service Interfaces

The module calls approximately 20 backend S-IFs for contract lookups, option management, equipment provisioning, and order registration:

| S-IF Code | Purpose |
|-----------|---------|
| `EKK0081A010` | Service contract single lookup |
| `EKK0161*` | Service contract detail lookups |
| `EKK0191*` | eo Light Phone service details |
| `EKK0251B001` | Service contract line detail (current usage) |
| `EKK0341*` | Equipment provision service contracts |
| `EKK0351*` | Option service contracts |
| `EKK0361A010` | Option service contract (ISP) |
| `EKK0401*` / `EKK0411*` | Sub-option service contracts |
| `EKK1041*` | Order setting lookups |
| `EKK1081C011` | Same process number assignment |
| `EKK1081D010` | Order condition registration |
| `EKK1551D010` | Order information creation work registration |
| `EZM0411A010` | In-home equipment model lookup |
| `ETU0011B010` | Banpo construction list lookup |

### Cross-Module Relationships

The `constant` classes are referenced by multiple processing modules beyond `common`, not just the SOD engine. `JKKSvcConst` serves as a general-purpose constant hub for the entire application, while `JKKHakkoSODConstCC` and `JKKItntokiStaEndConstCC` are consumed primarily by the `common` module but may also be used by other downstream SOD processing or transfer-work-order modules.

---

## Notes for Developers

### Large File Awareness

The source file for `JKKHakkoSODCC` is 42,000+ lines. Key sections:

| Section | Lines |
|---------|-------|
| Class definition and state fields | ~302–500 |
| `hakkoSOD` entry method | ~611–1038 |
| `addSOD` dispatch | ~1123–4908 |
| `tsuikabunAddSOD` (additional orders) | ~4926–5313 |
| `addTakinoSOD` (multi-function router) | ~5333–5761 |
| All `*OdrCtrl` methods | ~6088–17465 |
| S-IF query methods | ~21916–23920 |
| S-IF call infrastructure | ~26668–31105 |
| IPv6 handling | ~29976–30704 |

### Extension Points

To add a new order operation:

1. Define a new `ODR_NAIYO_CD` constant in `JKKHakkoSODConstCC`
2. Add a new `if` branch in `addSOD` (or `tsuikabunAddSOD` for additional orders)
3. Implement the required S-IF call methods (`call*SC`, `mapping*InMsg`, `mapping*OutMsg`, `editErrorInfoEKK*CBS`) if it uses a new backend S-IF
4. Wire the dispatch in the appropriate `*OdrCtrl` method

For new service types, add a new branch in `jdgSvcKind()` and in all `*OdrCtrl` methods where service-kind branching occurs.

### Same Process Number (同一処理番号)

The `same_trn_no` is a critical concept — it groups multiple SODs that belong to the same business operation. The `callEKK1081C011SC` method assigns this number, and it must be propagated to all related order registrations. Failing to share this across orders in the same operation can cause data inconsistency.

### Duplicate Constants

Some constants appear in both `JKKHakkoSODConstCC` and `JKKSvcConst` (e.g., `SVC_KIND_NET`, `IDO_DIV_*`, `SVC_KEI_STAT_*`). This duplication exists because the two classes evolved independently. When adding a new shared constant, prefer `JKKSvcConst` as the canonical location.

### State Management Discipline

If you add new state fields to `JKKHakkoSODCC`, ensure they are cleared in the same location where existing state is cleared (at the start of `hakkoSOD`, around line 633). Failure to clear state will cause cross-request data leakage.

### Japanese Comments

The Javadoc and inline comments are primarily in Japanese, as the eo Customer Core System is a Japanese product used by Japanese operations teams. Do not translate existing comments; instead, write new comments in Japanese to match the codebase convention.

### Version History

The module has undergone 70+ version changes since 2011. 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). When modifying any file, add your change to the file header following the existing format.

### New Code Addition Checklist

When adding a new constant:

1. Determine which class owns the relevant domain (SOD-specific → `JKKHakkoSODConstCC`, general service → `JKKSvcConst`, transfer-specific → `JKKItntokiStaEndConstCC`).
2. If it's a business code (not a map key), add it to the appropriate grouped section.
3. If it's a map key for SOD data interchange, add it to the corresponding info section.
4. Add a Javadoc comment describing the meaning in Japanese.
5. Add a version entry in the file header.
6. Use a value that fits the existing code scheme (e.g., `A98` for the next price course code after `A97`).