# Eo / Service

## Overview

The `eo.service` package serves as the **SOAP web service layer** for the eo customer core system (`eo顧客基幹システム`), a telecommunications customer management platform originally developed by Fujitsu for K-Opticom (now part of KDDI's "eo" brand). It exposes a set of JAX-WS web service endpoints that act as the outermost boundary of the application — receiving SOAP requests from external clients and delegating business processing to the underlying BPM (Business Process Management) engine.

Each class in this package implements a single `PortType` interface defined in its corresponding `eo.service.client.*` sub-package. The services collectively cover a broad range of customer-facing operations: payment and billing, service plan registration, customer authentication, contract management, and administrative lookups.

The module is a top-level `subpackage` with **13 indexed source files**, **13 classes**, and **39 methods/constructors**. It has no child wiki pages beyond `client.md`, but its direct dependencies span numerous client packages (`eo.service.client.*`), the Fujitsu Futurity BPM framework, the business layer (`eo.business.*`), and web mapping infrastructure (`eo.web.webview.mapping`).

## Sub-module Guide

The `eo.service` package contains **13 service implementation classes**, each acting as a SOAP endpoint for a distinct business capability. Rather than organizing code into sub-modules, the package keeps all endpoints flat — each class is self-contained and responsible for one business transaction.

Below is an overview of each service and how it fits into the broader system:

### Payment and Billing Services

- **[CNIFE039](source/koptWebS/src/eo/service/CNIFE039.java)** — Payment method initialization. Handles payment way configuration including credit card company codes, card numbers, cardholder names, and payment flags. This appears to be the entry point for setting up or modifying how a customer pays their bills.

- **[CHIFE522](source/koptWebS/src/eo/service/CHIFE522.java)** — Billing detail retrieval. Returns comprehensive billing transaction records including billing method, payment IDs, shop codes, collection amounts, payment dates, bank information, and CVS (convenience store) codes. This is one of the most data-rich services, handling dozens of fields related to billing lifecycle tracking.

- **[CHIFE527](source/koptWebS/src/eo/service/CHIFE527.java)** — Payment status inquiry. A concise service that takes a service plan number (`svc_kei_no`) and returns the current payment status (`pay_jokyo`). Acts as a quick check into whether a customer's payments are current.

- **[FUIFE152](source/koptWebS/src/eo/service/FUIFE152.java)** — Key system service plan result lookup. Queries the result code for a given key system ID and service plan number. This appears to be an internal coordination service, possibly used by other services or batch processes to determine service plan outcomes.

### Customer Authentication and Identity Services

- **[CCIFE001](source/koptWebS/src/eo/service/CCIFE001.java)** — User authentication. Validates a one-time password and returns the authenticated user's identity information including user ID, name, organization code and name, position code and name, and update/deletion timestamps. This is a core identity service used for login verification.

- **[CKIFE045](source/koptWebS/src/eo/service/CKIFE045.java)** — Customer ID lookup. Given a key system ID, returns a list of EO IDs (customer identifiers) and their associated system IDs. This appears to be used for cross-referencing customers across different internal systems.

- **[CKIFE046](source/koptWebS/src/eo/service/CKIFE046.java)** — Web authentication ID lookup. Given a key system ID, returns a list of service plan numbers paired with authentication IDs and web IDs. This supports the web self-service portal by mapping internal system IDs to web-accessible accounts.

### Contract and Service Plan Management Services

- **[CNIFE038](source/koptWebS/src/eo/service/CNIFE038.java)** — Member contract inquiry. Given a phone number (`telno`), returns the member's system ID, member subtype code, and contract plan number. This is a lookup service for finding a customer's contract details from their phone number.

- **[KKIFE335](source/koptWebS/src/eo/service/KKIFE335.java)** — Service plan information search. Retrieves service plan records by function code and system ID, returning plan numbers, statuses, names, process group codes, pricing codes, plan codes, and member rank judgment target service subtype codes. Provides a detailed view of a customer's service plan portfolio.

- **[KKIFE336](source/koptWebS/src/eo/service/KKIFE336.java)** — Optional service addition inquiry. Given a service plan number, returns optional service add-on details including start codes and up to five optional target keys. Supports the management of add-on services attached to a base plan.

- **[KKIFE350](source/koptWebS/src/eo/service/KKIFE350.java)** — Customer information search. A comprehensive search service that takes wide-ranging filters (date ranges, transaction codes, customer name, phone, MID, step process info, cancellation days across channels, EO service codes) and returns customer records with result codes, plan codes, customer names, thank-you call dates, and operation details. This is the primary customer search endpoint.

- **[KKIFE352](source/koptWebS/src/eo/service/KKIFE352.java)** — Customer information update. Updates the target scope of a customer record by EO ID, taking an EO number and update target flag. This is the write-path counterpart to `KKIFE350`.

- **[KKIFE364](source/koptWebS/src/eo/service/KKIFE364.java)** — Operation plan management. Retrieves operation plan records by key system ID and transaction division code, returning service plan numbers, operation plan codes, operation statuses, writing codes, and writing statuses. Supports the operational management side of service delivery.

### How They Relate

These services form **distinct entry points** to the underlying business layer rather than a hierarchical chain. A typical customer interaction might touch multiple services in sequence:

1. **Login** — `CCIFE001` validates the user
2. **Identity lookup** — `CKIFE045` or `CKIFE046` resolves the customer's internal identifiers
3. **Contract check** — `CNIFE038` finds the customer's contract details
4. **Service plan view** — `KKIFE335` shows their active plans
5. **Payment info** — `CHIFE527` confirms billing status
6. **Detail view** — `CHIFE522` shows transaction history

The `client.md` child page documents the `eo.service.client` package, which provides the **client-side port type interfaces and data types** that each service class implements or uses. Those client packages define the SOAP contracts (`PortType` interfaces, `InitType`/`InitResponseType` message types, and field wrapper classes) that the service layer exposes.

## Key Patterns and Architecture

### Uniform SOAP Endpoint Pattern

Every service class follows an **identical structural pattern**, making this one of the most highly templated areas of the codebase:

```
1. Receive SOAP init() request via Holder parameters
2. Set operate datetime from System.currentTimeMillis()
3. Build RequestData from the Holder headers and typed request object
4. Extract service-specific fields into a LinkedHashMap ("userData")
5. Invoke BPMController.run(context, requestData)
6. Extract response LinkedHashMap from ResponseData
7. Map response back to typed Java beans ("ResponseBean")
8. Return via Holder response parameter
```

### Request-to-Response Data Flow

The data transformation follows a strict pipeline:

```mermaid
flowchart TD
    A["SOAP Request
(Holder params + InitType)"] --> B["extractUserData()
Typed beans -> LinkedHashMap"]
    B --> C["BPMController.run()
Business process execution"]
    C --> D["LinkedHashMap
ResponseData"]
    D --> E["createResponseBean()
LinkedHashMap -> Typed beans"]
    E --> F["SOAP Response
(Holder params + InitResponseType)"]
```

All services extract their business-specific data from the incoming `InitType` into a `LinkedHashMap<String, Object>` key (e.g., `"CNSV005201SC"`, `"KKSV083301SC"`). The BPM engine processes this flat map, and the service class reconstructs the strongly-typed response `InitResponseType` from it. This pattern decouples the SOAP contract from the internal business data model — the BPM engine works exclusively with flat maps, while the SOAP layer handles type conversion.

### BPM Delegation Model

Each service class instantiates a fresh `BPMController` and delegates all business logic to it:

```java
BPMController controller = new BPMController();
ResponseData responseData = controller.run(context, requestData);
```

This means the `eo.service` package is essentially a **presentation/adapter layer** — it does not contain business logic itself but rather translates between the SOAP world (JAX-WS `Holder` parameters, typed beans) and the BPM world (flat `LinkedHashMap` payloads). The actual business rules live in the BPM engine and the underlying business layer packages (`eo.business.*`, `eo.business.service`).

### Error Handling Hierarchy

All 13 services implement **identical error handling** with a three-tier classification:

| Error Level | Trigger | Error Level Code | Return Code | Message (Japanese) |
|---|---|---|---|---|
| System error | `responseData.getErrorLevel()` starts with `"9"` | `988` | `9000` | システムエラー (System Error) |
| System error | `BPMControllerException` thrown | `988` | `9000` | システムエラー (System Error) |
| System error | `IllegalReflectionException` thrown | `988` | `9000` | システムエラー (System Error) |
| Business error | `BusinessException` thrown | `888` | `9000` | 業務エラー (Business Error) |

The error handling is uniform across all services — there is no per-service customization. Errors cause `initResponse.value` to be set to `null`, and `printStackTrace()` is called (though in production this may be replaced by structured logging).

### Request/Response Wrapper Architecture

Each service class uses `Holder<String>` for the seven standard SOAP header fields:

- `requestIDPart` — Request identifier
- `serviceIDPart` — Service identifier
- `channelPart` — Channel (e.g., web, phone, counter)
- `viewIDPart` — UI view identifier
- `operatorIDPart` — Operator ID
- `ipAddressPart` — Client IP address
- `operateDatetimePart` — Timestamp of invocation

These headers flow through the BPM controller and are populated back from the response's `ResponseData`, ensuring that tracing and audit information is preserved end-to-end.

### Typed Field Wrapper Classes

Each field in the SOAP request/response is wrapped in a strongly-typed class (e.g., `FuncCode`, `Sysid`, `Telno`, `SvcKeiNo`). These wrapper classes appear to be auto-generated from XSD schemas and serve as the type-safe boundary between Java and XML serialization. The `RequestBuildHelper.getValue()` and `ResponseBuildHelper.createObject()` utility methods handle the boxing and unboxing between wrapper classes and their underlying string values.

## Dependencies and Integration

### External Dependencies

This module depends on a rich set of external packages:

**Fujitsu Futurity BPM Framework:**
- `com.fujitsu.futurity.bp.controller.ws.BPMController` — Core business process orchestrator
- `com.fujitsu.futurity.bp.controller.ws.data.*` — Request/Response data structures
- `com.fujitsu.futurity.bp.controller.ws.exception.*` — Exception types
- `com.fujitsu.futurity.bp.controller.ws.helper.*` — Request/Response building utilities
- `com.fujitsu.futurity.bp.controller.ws.util.TimeFormatter` — Timestamp formatting
- `com.fujitsu.futurity.bp.custom.bpm.chsv0065`, `chsv0066`, `chsv0067` — Custom BPM extensions

**Internal Package Dependencies:**
- `eo.service.client.*` — 12 client packages defining SOAP port types and data types (one per service)
- `eo.business.common` — Shared business utilities
- `eo.business.service` — Service-layer business logic
- `eo.web.webview.mapping` — Web view mapping infrastructure
- `local.gyomu.api.common` — Local operations API

### Integration Points

The `eo.service` module sits at the **boundary between external SOAP callers and the internal BPM engine**. It has the following integration relationships:

```mermaid
flowchart LR
    Client["External SOAP Client"] -->|"SOAP/HTTP"| SVC["eo.service
(Web Services)"]
    SVC -->|"BPMController.run()"| BPM["Fujitsu Futurity
BPM Engine"]
    BPM -->|"delegates to"| BUS["eo.business.*
(Business Layer)"]
    BPM -->|"uses"| BPM_CUSTOM["Custom BPM
extensions (chsv006x)"]
    SVC -->|"uses types from"| CLIENTS["eo.service.client.*
(PortType + DTOs)"]
    Client -->|"uses| also --> CLIENTS
```

The BPM engine is the critical integration point — all service classes pass through it to execute business logic. Changes to BPM process definitions or the BPM API surface would affect all 13 services simultaneously.

## Notes for Developers

- **All services are templated.** When adding a new service, follow the exact pattern of existing classes: create a `PortType` interface, corresponding `InitType`/`InitResponseType` types, the typed field wrapper classes, and then the service implementation. The pattern is mechanical and predictable.

- **Error codes are fixed.** The `988`/`888` error level system is universal across all services. Do not introduce per-service error codes — any new error classification should be evaluated against this existing hierarchy.

- **The `Holder` pattern is mandatory.** JAX-WS `Holder<String>` parameters are used for all seven header fields and for request/response objects. This is not optional — it is dictated by the SOAP binding.

- **Thread safety.** Each service method creates a new `BPMController` instance, which means the service classes are effectively stateless. The `WebServiceContext` injected via `@Resource` is thread-safe and shared across requests.

- **Field naming convention.** The `userData` map keys use a consistent pattern: the service-specific type suffix (e.g., `CNSV005201SC`, `KKSV083301SC`). The field names within the map use snake_case (e.g., `func_code`, `svc_kei_no`). Maintain this convention when extending.

- **Record/list handling.** Services that return multiple records (`CNIFE038`, `CKIFE045`, `CKIFE046`, `KKIFE335`, `KKIFE336`, `KKIFE350`, `KKIFE364`) use a `Record` wrapper containing a list of `Element` objects. Each `Element` holds one row's worth of typed fields. This is the standard multi-row response pattern.

- **Japanese strings in error messages.** Error messages are in Japanese (`システムエラー` for system errors, `業務エラー` for business errors). If localizing, maintain these as the primary messages and add translations elsewhere.

- **Source file headers.** Files in this codebase include Fujitsu version history headers. New files should follow this convention.

- **No child wiki pages beyond `client.md`.** All 13 services live in this single parent-level document. If a service requires deeper documentation (e.g., field-by-field schemas), that should go in the corresponding `eo.service.client.*` wiki page.