# Com

## Overview

The `com` package sits at the root of the Java package hierarchy for the K-Opticom eo Customer Core System — a Japanese broadband, telephone, and mobile service management platform. While the broader `com` namespace serves as the top-level Java package for the entire application, only the `fujitsu` sub-package currently holds documented, indexed content.

The `com.fujitsu` area specifically implements the **Service Order (SOD) Issuance** subsystem, which is the bridge between customer-facing order requests and the backend systems that provision service, update billing, and dispatch field technicians. It handles the full lifecycle of customer actions — new contracts, course changes, suspensions, recoveries, cancellations, address modifications, and option adjustments — converting each into operational work orders dispatched through a suite of backend Service Interfaces (S-IFs).

Within this package, service requests flow across FTTH broadband, eo Hikari Denwa (light phone), and eo Mobile/UQ WiMAX services, all managed through a single, centralized dispatch engine.

## Sub-module Guide

### `fujitsu` — The Fujitsu Integration Layer

The `fujitsu` module is the sole documented child of `com` and it carries the full weight of the SOD subsystem. It is a Fujitsu-maintained component within the eo system, and its responsibility is end-to-end SOD issuance:

1. **Receive** a customer's order request.
2. **Query** the current contract state from backend databases.
3. **Determine** what downstream actions are needed based on service kind (internet, phone, mobile) and order control type.
4. **Dispatch** those actions to approximately 20 backend Service Interfaces.

At the heart of `fujitsu` is the `futurity` module, which contains a single business processing package (`bp`) split into two tightly coupled sub-sub-modules:

- **`constant`** — Three constant classes 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`) at 42,000+ lines, which is the largest class in the entire system. It handles the entire SOD dispatch flow from the `hakkoSOD()` entry point through 25+ order-control handlers, an 80+ code order dispatcher, comprehensive contract data query methods, and S-IF call wrappers.

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.

## Key Patterns and Architecture

### Centralized Dispatch Architecture

Rather than distributing business logic across many small domain objects, `JKKHakkoSODCC` acts as a switchboard — a single class that receives every SOD request, routes it through one of 25+ order-control handlers, dispatches it through 80+ order codes, and invokes the appropriate backend S-IFs. This provides a single, traceable entry point for every SOD request.

```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"]
        ADD["addSOD dispatcher"]
    end

    subgraph Backend["Service Interfaces"]
        S1["Contract lookup"]
        S2["Option list"]
        S10["Same process number"]
        S11["Order registration"]
        S12["Work registration"]
    end

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

### Stateful Per-Request Processing

The engine uses instance fields as working storage within a single `hakkoSOD` invocation. Key state includes a shared transaction number (`same_trn_no`) that groups related orders into a single atomic business operation, price group and course codes, discontinuation division, and various option and equipment provision contract numbers. This design means the class must be instantiated per-request and must never be shared across concurrent requests — any new state fields must be cleared at the start of each processing cycle to avoid cross-request contamination.

### Service Kind Branching

A single determination (`jdgSvcKind()`) maps price group codes to one of three service kinds: internet services (FTTH, ADSL), light phone (eo Hikari Denwa), or mobile services (eo Mobile, UQ WiMAX). This single branching point determines the entire processing flow for any given contract, and new service types require wiring in multiple locations across the controller methods.

### S-IF Call Pattern

Each backend Service Interface follows a consistent four-method pattern: a call method that constructs the message template, an inbound mapping method, an outbound mapping method, and an error mapping method. This pattern is highly repetitive and is consistently applied across 30+ service interfaces.

The interaction across sub-modules can be visualized as follows:

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

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

    Constant -->|references| Common
    Common -->|extends| Abstract
    Common -->|uses| Session
    Common -->|invokes| Invoker
```

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

### Framework Dependencies

The SOD engine extends the Futurity framework's `AbstractCommonComponent` and relies on `SessionHandle` for database connections, `ServiceComponentRequestInvoker` for invoking backend service components, and `CAANMsg` as the canonical message envelope for S-IF communication.

### Backend Service Interfaces

The module calls approximately 20 backend S-IFs covering contract lookups, option management, equipment provisioning, and order registration. Key interfaces include `EKK0081` (service contract single lookup), `EKK0351` (option service contracts), `EKK1081` (same process number assignment), and `EKK1081D` (order condition registration).

### 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 the SOD-specific constants 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 and organized into clearly delineated sections:

| Section | Lines |
|---------|-------|
| Class definition and state fields | ~302–500 |
| `hakkoSOD` entry method | ~611–1038 |
| `addSOD` dispatcher | ~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 if it uses a new backend S-IF.
4. Wire the dispatch in the appropriate `*OdrCtrl` method.

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

The `same_trn_no` is a critical concept — it groups multiple SODs that belong to the same business operation. 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_*`). 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 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. 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.