# Getting Started

## What This Project Does

The **eo Customer Core System** is a Japanese broadband, telephone, and mobile service management platform operated by K-Opticom. It handles the full lifecycle of customer service contracts - from new subscriptions through course changes, suspensions, recoveries, and cancellations - by dispatching work orders to backend billing and provisioning systems. The system is built in Java using a layered EJB architecture over the Fujitsu Futurity framework.

---

## Recommended Reading Order

If you are new to the codebase, read the wiki pages in this order. Each page builds on the previous one:

1. **[Repository Overview](../overview.md)** - High-level architecture, modules, and technology stack. Read this first to understand the big picture.
2. **[`eo` Module](../eo.md)** - The shared foundation layer (constants, utilities, EJB schemas). This is where you learn the system's vocabulary.
3. **[`com.fujitsu` Module](../com/fujitsu/futurity.md)** - The SOD (Service Order) Issuance engine. This is where the orchestration logic lives.
4. **[`eo.common.constant`](../eo/common/constant.md)** - The constants reference. Browse this to learn business codes, device types, and encoding conventions.
5. **[`eo.ejb`](../eo/ejb.md)** - The CBS EJB schema contracts. Study this to understand how data flows between the UI and the billing backend.

### Suggested 30-minute path

For a quick orientation: read **[Repository Overview](../overview.md)** - skim **[`eo.common.constant`](../eo/common/constant.md)** for the constant tables - glance at the two-class schema pattern in **[`eo.ejb`](../eo/ejb.md)**. At that point you will know the naming conventions, data shapes, and where to look next.

---

## Key Entry Points

These are the classes and files to understand first. In rough priority order:

### 1. Constants (start here)

Constant classes are the easiest entry point: they contain no logic, just `public static final` fields. Start with the three classes in `eo.common.constant`:

| Class | File | Why Read It |
|-------|------|-------------|
| [`JDKStrConst`](../Source/koptCommon/src/eo/common/constant/JDKStrConst.java) | `eo/common/constant/JDKStrConst.java` | Infrastructure constants - file paths, encodings, device types, directory configs |
| [`JKKStrConst`](../Source/koptCommon/src/eo/common/constant/JKKStrConst.java) | `eo/common/constant/JKKStrConst.java` | Business-domain constants - pricing plans, service categories, contract statuses (~6,800 lines) |
| [`JPCModelConstant`](../Source/koptCommon/src/eo/common/constant/JPCModelConstant.java) | `eo/common/constant/JPCModelConstant.java` | Model-layer constants - function codes, error code ranges, search flags |

Then browse the SOD-specific constants:

| Class | File | Why Read It |
|-------|------|-------------|
| [`JKKHakkoSODConstCC`](../Source/koptBp/ejbModule/com/fujitsu/futurity/bp/constant/JKKHakkoSODConstCC.java) | `com/fujitsu/futurity/bp/constant/JKKHakkoSODConstCC.java` | SOD-specific codes - pricing course codes, order conditions, equipment codes |
| [`JKKSvcConst`](../Source/koptBp/ejbModule/com/fujitsu/futurity/bp/constant/JKKSvcConst.java) | `com/fujitsu/futurity/bp/constant/JKKSvcConst.java` | General service constants shared across all processing modules |

### 2. String Utilities

| Class | File | Why Read It |
|-------|------|-------------|
| [`JKKStringUtil`](../Source/koptCommon/src/eo/common/util/JKKStringUtil.java) | `eo/common/util/JKKStringUtil.java` | Null-safe string operations and Shift_JIS byte-length truncation. The `subStringByte` method is critical for Japanese text handling. |

### 3. The Business Engine

| Class | File | Why Read It |
|-------|------|-------------|
| [`JKKHakkoSODCC`](../Source/koptBp/ejbModule/com/fujitsu/futurity/bp/common/JKKHakkoSODCC.java) | `com/fujitsu/futurity/bp/common/JKKHakkoSODCC.java` | The central SOD issuance engine (~42,000 lines). Entry point `hakkoSOD()` dispatches all customer actions. |

### 4. CBS Message Schemas

Browse the schema classes in `eo/ejb/cbs/cbsmsg/` to understand data shapes. Study one pair to learn the pattern:

| Schema Pair | Domain |
|-------------|--------|
| `EKK0081A010CBSMsg` / `EKK0081A010CBSMsg1List` | Service contract agreement search |
| `EKK0161B008CBSMsg` / paired detail | Number reservation type inquiry |
| `EKK0341A010CBSMsg` / paired detail | Equipment provision (9 pairs - most complex) |
| `EDK0301B060CBSMsg` / paired detail | Return equipment cancellation |

---

## Project Structure

The repository uses three Maven/EJB modules plus the Fujitsu integration layer:

```
Root
├── Source/koptBp/            [Business Processing Layer]
│   └── ejbModule/
│       └── com/fujitsu/futurity/bp/
│           ├── constant/     SOD business code constants
│           └── common/       JKKHakkoSODCC - the SOD engine
│
├── Source/koptCommon/        [Shared Utilities]
│   └── src/eo/common/
│       ├── constant/         JDKStrConst, JKKStrConst, JPCModelConstant
│       └── util/             JKKStringUtil
│
├── Source/koptModel/         [Data / Schema Layer]
│   └── src/eo/ejb/cbs/cbsmsg/
│       └── EKK*/CBSMsg classes  CBS message schemas (~100 classes)
│
└── Source/koptEjb/           [EJB Integration Boundary]
    └── src/eo/ejb/
        └── cbs/cbsmsg/       CBSMsg/CBSMsg1List schema definitions
```

### Module responsibilities

| Module | Responsibility |
|--------|---------------|
| **koptBp** | Core business logic - the Service Order (SOD) issuance engine that orchestrates customer contract actions |
| **koptCommon** | Shared constants and string utilities consumed by all other modules |
| **koptModel** | CBS message schema definitions that describe data shapes for inter-module communication |
| **koptEjb** | EJB integration boundary - the contract layer between the frontend UI and the Central Billing System |

### Dependency flow

The modules form a layered architecture with `koptCommon` at the base:

```mermaid
flowchart TD
    subgraph koptBp["koptBp - Business Processing"]
        SOD["JKKHakkoSODCC
SOD Engine"]
        SOD_CONST["JKKHakkoSODConstCC
SOD Constants"]
    end

    subgraph koptCommon["koptCommon - Shared Utilities"]
        STRC["JKKStrConst
Business constants"]
        INFRA["JDKStrConst
Infrastructure constants"]
        UTIL["JKKStringUtil
String utilities"]
    end

    subgraph koptModel["koptModel - Data Layer"]
        EKK["EKK*CBSMsg
CBS schemas"]
    end

    SOD --> SOD_CONST
    SOD --> STRC
    SOD --> INFRA
    SOD --> UTIL
    SOD --> EKK
    EKK --> STRC
    EKK --> INFRA
```

---

## Configuration

### Key config files

| File / Location | What It Controls |
|-----------------|------------------|
| `Source/koptCommon/src/eo/common/constant/JDKStrConst.java` | File paths, directory env vars, encodings, device types, record type codes. The constants here define the file-based dispatch protocol (`DKIFM` files). |
| `Source/koptCommon/src/eo/common/constant/JKKStrConst.java` | Business-domain constants - pricing plans, service categories, statuses. The largest constant file at ~6,800 lines. |
| `Source/koptModel/src/eo/ejb/cbs/cbsmsg/` | CBS schema `CONTENT` arrays that define every field in every cross-tier message. These arrays serve as runtime templates for the Futurity framework. |

### Environment variables

Directory paths are resolved from runtime environment variables, not hardcoded:

| Environment Variable | Resolved To |
|---------------------|-------------|
| `IND` | Output file definition directory |
| `MID_DIR_DK` | Intermediate file directory |
| `GAIBU_SEND_DIR_DK` | Send file directory to other systems |
| `GAIBU_RECEIVE_DIR_DK` | Receive file directory from other systems |
| `BUS_LOG_DIR_DK` | Business log output directory |

---

## Common Patterns

### Coding conventions

**Constant class pattern** - Every constant class uses private constructors and `public static final String` (or `int`) fields with `UPPER_SNAKE_CASE` naming. The prefix encodes the layer:

| Prefix | Layer | Class |
|--------|-------|-------|
| `JDK` | Infrastructure | `JDKStrConst` |
| `JKK` | Business domain | `JKKStrConst` |
| `JPC` | Model / persistence | `JPCModelConstant` |

New constants must wrap additions in revision markers: `// ANK-XXXX-00-00 ADD START` / `ADD END`.

**Two-class schema pattern** - Every CBS business function uses exactly two paired classes:

| Class | Role |
|-------|------|
| `CBSMsg` (header) | Search conditions, pagination, error flags, operator metadata |
| `CBSMsg1List` (detail) | Function-specific data columns |

The header embeds a `static final Object[][] CONTENTS` array listing field definitions as `{ name, type, description }` tuples. A child reference at the end of the array (e.g., `{ "CONTENTS", "EKKxxxxCBSMsg1List[]", ... }`) ties the pair together.

**S-IF call quadruple** - For each backend Service Interface (S-IF), four methods are implemented in a consistent pattern:

```java
callEKKxxxxSC(...)      // Constructs CAANMsg, invokes via ServiceComponentRequestInvoker
mappingEKKxxxxInMsg(...) // Populates template from HashMap input
mappingEKKxxxxOutMsg(...) // Extracts results from CAANMsg[] to HashMap
editErrorInfoEKKxxxxCBS(...) // Maps S-IF error information
```

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

**Centralized dispatch** - The `JKKHakkoSODCC` engine follows a single-entry dispatch pattern:

1. `hakkoSOD()` - The single entry point that receives all contract actions
2. `*OdrCtrl` methods - Over 25 order-control handlers, one per business scenario
3. `addSOD()` - Maps data to order conditions and dispatches on `orderNaiyoCd` codes (80+ codes)

### Encoding conventions

| Encoding | Where Used | Note |
|----------|-----------|------|
| `Shift_JIS` | File I/O, legacy fields | Default Japanese encoding. Use `JKKStringUtil.subStringByte` for truncation. |
| `Windows-31J` | Some file headers | Java alias for Shift_JIS. |
| `EUC-JP` | Some legacy files | Alternate Japanese encoding - handled by `subStringByte`. |
| `UTF-8` | Newer interfaces | Do NOT use `subStringByte` with UTF-8 (multi-byte characters are 3-4 bytes, not 2). |

### Important gotchas

- **Preserved typo** - `JPCModelConstant.SAERCH_TYPE_IKT` has a misspelling and must not be changed for backward compatibility.
- **Large files** - `JKKStrConst.java` is ~6,800 lines and `JKKHakkoSODCC.java` is ~42,000 lines. Use file search (`Ctrl+Shift+F`) rather than scanning.
- **Private constructors** - All constant classes have private constructors. They cannot be instantiated or mocked directly.
- **Stateful per-request** - `JKKHakkoSODCC` uses instance fields as working storage within a single `hakkoSOD` invocation. New state fields must be cleared at the start of each call to avoid cross-request data leakage.
- **Japanese source comments** - Many `eo.ejb` source files contain Japanese comments on data columns - these are the authoritative source for field semantics when no additional documentation exists.

---

## Framework Dependencies

The system relies on the **Fujitsu Futurity framework** for its infrastructure layer:

| Framework Class | Purpose |
|----------------|---------|
| `AbstractCommonComponent` | Base class for all business processing components (including `JKKHakkoSODCC`) |
| `SessionHandle` | Database session management |
| `ServiceComponentRequestInvoker` | S-IF invocation infrastructure |
| `CAANMsg` | Canonical message envelope for Service Interface communication |
| `CAANSchemaInfo` | Base class for all CBS schema classes (e.g., `CBSMsg`, `CBSMsg1List`) |

No external third-party frameworks were detected - the entire application is built around the internal Futurity framework and custom domain logic.