# Com / Fujitsu

## Overview

The `com.fujitsu` package sits at the root of a Fujitsu-maintained component within the K-Opticom eo Customer Core System — a Japanese broadband, telephone, and mobile service management platform. This package serves as a namespace for the Fujitsu integration layer, and to date its sole child module is `futurity`, which implements the **Service Order (SOD) Issuance** subsystem.

While the broader eo system handles customer contracts, billing, and provisioning across FTTH broadband, eo Hikari Denwa (light phone), and eo Mobile/UQ WiMAX services, the `com.fujitsu` module specifically orchestrates the conversion of customer requests (new contracts, course changes, suspensions, recoveries, cancellations, address modifications, and option adjustments) into operational work orders. It is the bridge between the customer-facing order request and the backend systems that actually provision service, update billing, and dispatch field technicians.

## Sub-module Guide

### `futurity` — The SOD Issuance Engine

The `futurity` module is the only child of `com.fujitsu` and it carries the full weight of the SOD subsystem. Its responsibility is end-to-end: receiving a customer's request, querying the current contract state from backend databases, determining what downstream actions are needed, and dispatching those actions to a suite of Service Interfaces (S-IFs).

#### Structure: `bp` (Business Processing)

`futurity` contains a single sub-package, `bp`, which itself splits into two tightly coupled sub-sub-modules:

- **`constant`** — Three constant classes (`JKKHakkoSODConstCC`, `JKKSvcConst`, `JKKItntokiStaEndConstCC`) that serve as the canonical source of truth for all business values across the SOD subsystem. These are non-instantiable containers of `public static final String` fields with no methods or instance state.

- **`common`** — A single class, `JKKHakkoSODCC`, which is the actual processing engine. At 42,000+ lines, it is the largest class in the system and handles the entire SOD dispatch flow, from the `hakkoSOD()` entry point through over 25 order-control handlers, an 80+ code order dispatcher, comprehensive contract data query methods, and S-IF call wrappers.

#### How the Sub-modules Relate

The relationship between `constant` and `common` is foundational: the constant classes define the map keys used to pass data between layers and the business codes used to branch processing logic. The `common` module is where those codes are consumed — in string comparisons, service-kind branching, S-IF input mapping, and order condition evaluation. If a business code changes, `constant` is the single place to update; `common` is where that change takes effect.

```mermaid
flowchart TD
    subgraph Fujitsu["com.fujitsu Module"]
        subgraph Futurity["futurity"]
            subgraph Bp["bp - Business Processing"]
                Constant["constant - Shared Constants"]
                Common["common - SOD Issuance Engine"]
            end
        end
    end

    subgraph Backend["Service Interfaces S-IF"]
        Lookup["Contract Option Lookups"]
        Provisioning["Equipment Provisioning"]
        Registration["Order Registration"]
    end

    subgraph Framework["Futurity Framework"]
        AbstractComp["AbstractCommonComponent"]
        Session["SessionHandle"]
        Invoker["ServiceComponentRequestInvoker"]
    end

    Constant -->|references| Common
    Common -->|extends| AbstractComp
    Common -->|uses| Session
    Common -->|invokes| Invoker
    Common -->|calls| Lookup
    Common -->|calls| Provisioning
    Common -->|calls| Registration
```

## Key Patterns and Architecture

### Centralized Dispatch Architecture

`JKKHakkoSODCC` follows a centralized dispatch pattern. Rather than distributing business logic across many small domain 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 provides a single, traceable entry point for every SOD request. 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 engine 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 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 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 the `common` 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`).