# Com / Fujitsu / Futurity / Bp

## Overview

This package 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 is responsible for generating downstream work orders whenever a customer's contract state changes: new contracts, course (plan) changes, suspensions, recoveries, cancellations, address modifications, option adjustments, and light phone number operations.

In practice, this module is the central orchestration layer that receives a customer request, queries the current contract and option state from backend databases, evaluates what downstream actions are required, and dispatches those actions to a suite of Service Interfaces (S-IFs). The end result is the creation of work orders that trigger billing updates, field dispatch, provisioning, and customer notifications.

---

## Sub-module Guide

The `bp` package is composed of two child sub-modules that together define the subsystem's domain vocabulary and its processing engine.

### `constant` — The Shared Vocabulary

This sub-module defines three 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-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-modules Relate

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

```mermaid
flowchart LR
    subgraph Constant["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` 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 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 Action"]
        NEW["New Contract"]
        CHG["Course Change"]
        CXL["Cancellation"]
        SUS["Suspension Recovery"]
        OPT["Option Settings"]
    end

    subgraph Dispatch["JKKHakkoSODCC"]
        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`).