# Local / Gyomu / Api

## Overview

The `local.gyomu.api` package is the HTTP API gateway for the eo customer base system (eo顧客基幹システム). It exposes 102 REST endpoints as JAX-RS `@POST` resource classes, each handling one external interface (外部I/F). Every endpoint class extends [`ApiServerLocalBase`](source/koptWebRest/src/local/gyomu/ApiServerLocalBase.java) and delegates business logic to downstream business services (EJB layer) via wrapper methods. The package covers a wide range of domain areas — customer information management, contract operations, billing and usage queries, operator support workflows, web application intake processing, credit payments, promotional services (Netflix, gifts, campaigns), and construction / installation management.

There are no child wiki pages under this module. The 60 endpoint classes work together as a single integration layer; they do not depend on each other but instead all converge on the shared base class and the business service infrastructure.

## Architecture

Every class in this package follows a uniform three-phase pattern:

1. **`execute()`** — Public JAX-RS entry point annotated with `@POST`. Extracts the request and servlet context, then delegates to the base class's `exec()` method for common concerns (authentication, logging, error wrapping).
2. **`run()`** — Template method overridden from `ApiServerLocalBase`. The base class calls this after common processing completes. The override calls `logicExecute()`.
3. **`logicExecute()`** — Private method containing the domain-specific integration logic. It calls one or more business service methods, extracts the result, and returns a populated `ApiServerPartsBean`.

```mermaid
sequenceDiagram
    participant C as Client
    participant API as API Endpoint
    participant BASE as ApiServerLocalBase
    participant BP as Business Service
    participant R as Response

    C->>API: POST execute(request)
    API->>BASE: exec(APIID, request, context)
    BASE->>BASE: Common processing
    BASE->>API: run(partsBean)
    API->>API: logicExecute(partsBean)
    API->>BP: callBpService(serviceId, partsBean)
    BP-->>API: outMap(result)
    API->>API: Extract result from outMap
    API-->>BASE: ApiServerPartsBean(response)
    BASE-->>API: Response
    API-->>R: HTTP Response
```

### Business service invocation variants

The base class provides several methods for calling the EJB business layer, and different endpoint classes pick the appropriate one:

| Method | When used | Purpose |
|---|---|---|
| `callBpService()` | Most classes | Standard synchronous call to an EJB business service |
| `callBpService2()` | Classes needing a custom system ID at runtime (e.g. `CRIFE055`, `KKIFE489`) | Same as above but accepts a runtime system identifier |
| `callBpServiceForLine()` | LINE-specific classes (`ACIFE070`, `KKIFE411`, `KKIFE412`) | Calls LINE-integrated business services; the response body is nested under a `BODY_INFO` key |

### System ID routing

Each class defines a compile-time `SYSTEM_ID` constant (e.g. `"CMP1"`, `"ESS1"`, `"OPS1"`, `"FRN1"`, `"FTR1"`) indicating which upstream system the business service belongs to. Some classes — notably those modified under ticket **ANK-3355-08-00** for LINE integration — read the system ID from the HTTP header (`Sysid`) at runtime instead of using the static constant. This allows a single API gateway to serve multiple LINE environments.

### Error handling

Most classes return results directly. A subset — including [`FUIFE168`](source/koptWebRest/src/local/gyomu/api/FUIFE168.java), [`FUIFE194`](source/koptWebRest/src/local/gyomu/api/FUIFE194.java), [`FUIFE202`](source/koptWebRest/src/local/gyomu/api/FUIFE202.java), [`FUIFE195`](source/koptWebRest/src/local/gyomu/api/FUIFE195.java), [`KKIFE475`](source/koptWebRest/src/local/gyomu/api/KKIFE475.java), [`KKIFE445`](source/koptWebRest/src/local/gyomu/api/KKIFE445.java), and [`FUIFE170`](source/koptWebRest/src/local/gyomu/api/FUIFE170.java) — extract `ApiBpInterface.ERROR_INFO` from the service result. When present, they populate the response error list via `reqPartsBean.setErrList()` and throw an `ApiServerExceptionGyomuErr`, ensuring errors propagate to the caller with structured detail.

`[`FUIFE194`](source/koptWebRest/src/local/gyomu/api/FUIFE194.java)` is the most complex handler: it wraps service calls in `try/catch` blocks distinguishing `ApiServerExceptionGyomuErr` (business error) from general `Exception` (system error), injects an `errCode` of `"3001"` when the error list is empty, and for `func_code == "3"` additionally sends a completion notification and deletes the stored web application data after retrieving the contract list.

## Key Classes and Interfaces

Below are the most representative endpoint classes, grouped by business domain. Each class is a single public type annotated with `@Path("<CLASS_NAME>")` (though the `@Path` value is shown as `_None_` in the index because the JAX-RS router resolves the path from the class name when no explicit value is provided).

### Customer Information Management

#### [`CKIFE051`](source/koptWebRest/src/local/gyomu/api/CKIFE051.java) — Customer Address Update (CMP)

Handles address information updates for customers via the CMP system. Calls business service `CKSV0064` with `SYSTEM_ID = "CMP1"`. Simple, single-call pattern with no special error handling.

#### [`CKIFE052`](source/koptWebRest/src/local/gyomu/api/CKIFE052.java) — LINE-ID Registration (LINE)

Registers a LINE ID to a customer account. Modified under ticket ANK-3355-08-00. Uses the `callBpServiceForLine()` pattern to communicate with LINE-integrated services.

#### [`CKIFE053`](source/koptWebRest/src/local/gyomu/api/CKIFE053.java) — Customer Basic Info Lookup (Operator Support)

Allows operator support staff to look up a customer's basic information. Calls service `CKSV0066` with `SYSTEM_ID = "OPS1"`. Added under ANK-3593-00-00 as part of the operator support features overhaul.

#### [`CKIFE070`](source/koptWebRest/src/local/gyomu/api/CKIFE070.java) — Contact Info Lookup (OPMS)

Retrieves customer contact information from the OPMS (Operations Support) system.

#### [`CKIFE065`](source/koptWebRest/src/local/gyomu/api/CKIFE065.java) — Customer List Lookup (Operator Support)

Provides operators with a paginated list of customers matching search criteria.

#### [`CKIFE064`](source/koptWebRest/src/local/gyomu/api/CKIFE064.java) — Data Utilization Consent Update/Query (CMP)

Updates or queries customer consent information for data utilization, a compliance-critical operation supporting Japan's Act on the Protection of Personally Identifiable Information.

#### [`CKIFE066`](source/koptWebRest/src/local/gyomu/api/CKIFE066.java) — SYSID Uniqueness Query (CMP)

Checks whether a given SYSID is unique across the system. Used during registration to prevent key collisions.

#### [`CKIFE069`](source/koptWebRest/src/local/gyomu/api/CKIFE069.java) — Pre-Activation Mast Step Status

Queries and updates the status of mandatory steps that must be completed before a customer's service activation.

#### [`CKIFE059`](source/koptWebRest/src/local/gyomu/api/CKIFE059.java) & [`CKIFE060`](source/koptWebRest/src/local/gyomu/api/CKIFE060.java) — Prospect Info Search and Lookup

`[`CKIFE059`](source/koptWebRest/src/local/gyomu/api/CKIFE059.java)` searches for prospective customers (lead management), while [`CKIFE060`](source/koptWebRest/src/local/gyomu/api/CKIFE060.java)` queries the full details of a specific prospect. Both were added under ANK-3795-00-00 as part of the prospect system construction.

#### [`CKIFE058`](source/koptWebRest/src/local/gyomu/api/CKIFE058.java) — Prospect CRUD (Create/Update/Delete)

Enables creation, update, and deletion of prospect (lead) records. Called by ESS (sales channel) operations. The business service is `CKSV0072` with `SYSTEM_ID = "ESS1"`.

### LINE-Integrated Services

These classes were added or modified for LINE integration (ticket **ANK-3355-08-00**) and use `callBpServiceForLine()` and read the system ID from the HTTP `Sysid` header.

#### [`ACIFE070`](source/koptWebRest/src/local/gyomu/api/ACIFE070.java) — Usage Info Lookup (LINE)

Retrieves usage data (量情報) for LINE clients. Business service: `ACSV0037`, `SYSTEM_ID = "API1"`. Takes a `chsht_tg_seiky_ym` parameter to filter by billing year-month. The `logicExecute()` method reads the system ID from the `Sysid` HTTP header (instead of the request body) for multi-service API scenarios. The service response body is nested under a `BODY_INFO` key, which is extracted before being set on the response.

#### [`KKIFE411`](source/koptWebRest/src/local/gyomu/api/KKIFE411.java) — Contract Info Lookup (LINE)

Looks up contract information for LINE clients. Business service: `KKSV0922`. Same header-based system ID extraction pattern as `ACIFE070`. Response body is similarly unwrapped from `BODY_INFO`.

#### [`KKIFE412`](source/koptWebRest/src/local/gyomu/api/KKIFE412.java) — Member Rank Info Lookup (LINE)

Retrieves the customer's membership tier/rank for LINE clients. Business service: `KKSV0923`. Follows the same `callBpServiceForLine()` pattern.

### Billing and Contract Information

#### [`CHIFE067`](source/koptWebRest/src/local/gyomu/api/CHIFE067.java) — Billing Info Lookup (LINE)

Queries billing information for LINE clients. Business service: `CSVS0061` (by convention; verify from code). LINE-integrated with header-based system ID routing.

#### [`CHIFE528`](source/koptWebRest/src/local/gyomu/api/CHIFE528.java) — Billing Info Lookup (CHIFE528)

Alternative billing info endpoint for the CHIFE528 interface. Uses standard `callBpService()` rather than the LINE-specific variant.

#### [`CHIFE532`](source/koptWebRest/src/local/gyomu/api/CHIFE532.java) — Billing Discount Amount Lookup (CMP)

Looks up discount amounts applied to billing, used for displaying cost savings to customers. Modified under ticket **ANK-4628-00-00**.

#### [`CHIFE069`](source/koptWebRest/src/local/gyomu/api/CHIFE069.java) — Price Correspondence Record Integration

Integrates price correspondence records — used when pricing adjustments are made and need to be recorded in the system.

#### [`KKIFE403`](source/koptWebRest/src/local/gyomu/api/KKIFE403.java) — Discount-Related Contract Info Lookup

Retrieves contracts that are associated with discount promotions.

#### [`KKIFE414`](source/koptWebRest/src/local/gyomu/api/KKIFE414.java) — Customer Promotion Info Lookup (Operator Support)

Shows promotional offers available for a customer, viewed by operator support staff.

#### [`KKIFE415`](source/koptWebRest/src/local/gyomu/api/KKIFE415.java) — Service Contract Details List (Operator Support)

Lists all service contract details for a customer.

#### [`KKIFE416`](source/koptWebRest/src/local/gyomu/api/KKIFE416.java) — Service Contract Detail (Operator Support)

Shows a single service contract detail record.

#### [`KKIFE426`](source/koptWebRest/src/local/gyomu/api/KKIFE426.java) — Contract Transfer Info Lookup

Retrieves information about contract ownership transfers.

#### [`KKIFE475`](source/koptWebRest/src/local/gyomu/api/KKIFE475.java) — Post-Cancellation Contract State Lookup (Sales Support)

Looks up the contract state after a customer has cancelled. Modified under ANK-4173-00-00 for post-cancellation display and re-application support. The `logicExecute()` method contains custom logic to strip prefix underscores from field names to comply with SOAP naming conventions — the upstream bp layer adds underscores to fields starting with numbers, and this endpoint removes them for interface compatibility.

### Web Application Intake (WEB 申込)

These classes handle the web application intake workflow — the process by which customers apply for eo Hikari services online.

#### [`FUIFE194`](source/koptWebRest/src/local/gyomu/api/FUIFE194.java) — Customer Billing Contract List Retrieval

The most complex endpoint in the module. Retrieves a customer's billing contract list. Business services: `FUSV0355` (primary), `FUSV0356` (alternative for `func_code == "3"`), plus `FUSV0360` and `FUSV0369` for notification and cleanup. The `logicExecute()` method:

1. Reads `func_code` from the request body to decide which service to call.
2. Wraps the service call in `try/catch`, handling both business errors (`ApiServerExceptionGyomuErr`) and system errors (`Exception`) separately, injecting an error code of `"3001"` when the error list is empty.
3. For `func_code == "3"`, sends a completion notification (`SERVICE_ID_3`) and deletes the stored web application data (`SERVICE_ID_4`) after retrieving the result.

#### [`FUIFE201`](source/koptWebRest/src/local/gyomu/api/FUIFE201.java) — WEB Application Content List Lookup

Lists all web application submissions for a customer. Added under ANK-4231-00-00 for OMO (Omni-Channel) initiative. Business service: `FUSV0362`, `SYSTEM_ID = "CMP1"`.

#### [`FUIFE202`](source/koptWebRest/src/local/gyomu/api/FUIFE202.java) — WEB Application Content Detail Lookup

Looks up a single web application record.

#### [`FUIFE203`](source/koptWebRest/src/local/gyomu/api/FUIFE203.java) — WEB Application One-Time Password Issuance

Issues a one-time password for viewing application content securely.

#### [`FUIFE204`](source/koptWebRest/src/local/gyomu/api/FUIFE204.java) — WEB Application Content Display Availability

Checks whether application content can be displayed to the current user (authorization gate).

#### [`FUIFE205`](source/koptWebRest/src/local/gyomu/api/FUIFE205.java) & [`FUIFE207`](source/koptWebRest/src/local/gyomu/api/FUIFE207.java) — WEB Application Search and Lookup

`[`FUIFE205`](source/koptWebRest/src/local/gyomu/api/FUIFE205.java)` retrieves a web application record, while [`FUIFE207`](source/koptWebRest/src/local/gyomu/api/FUIFE207.java)` provides search functionality for applications.

#### [`FUIFE206`](source/koptWebRest/src/local/gyomu/api/FUIFE206.java) — Pre-eoID Number Issuance and Binding

Issues a provisional eoID and binds it to an application before the formal registration flow.

#### [`FUIFE212`](source/koptWebRest/src/local/gyomu/api/FUIFE212.java) — eo Hikari Building Info Search

Searches for building/property information to determine eo Hikari service availability at a given address.

#### [`FUIFE213`](source/koptWebRest/src/local/gyomu/api/FUIFE213.java) — WEB Application Building Fee Search

Calculates building-related fees for a web application (installation costs, etc.).

#### [`FUIFE176`](source/koptWebRest/src/local/gyomu/api/FUIFE176.java), [`FUIFE177`](source/koptWebRest/src/local/gyomu/api/FUIFE177.java), [`FUIFE178`](source/koptWebRest/src/local/gyomu/api/FUIFE178.java), [`FUIFE179`](source/koptWebRest/src/local/gyomu/api/FUIFE179.java) — Customer Billing Contract List

Additional contract list retrieval endpoints, each delegating to the same business logic pattern but potentially with different service configurations.

#### [`FUIFE195`](source/koptWebRest/src/local/gyomu/api/FUIFE195.java) — eoID Usability Check

Checks whether an eoID can be used (validity, status, etc.).

#### [`FUIFE198`](source/koptWebRest/src/local/gyomu/api/FUIFE198.java) — Referral Code Validity Check

Validates a referral code used during the application process.

#### [`FUIFE199`](source/koptWebRest/src/local/gyomu/api/FUIFE199.java) — Number Portability Availability Check

Checks whether a phone number is eligible for number portability (MNP).

#### [`FUIFE200`](source/koptWebRest/src/local/gyomu/api/FUIFE200.java) — SYSID Lookup (iDA)

Retrieves a SYSID for the iDA (internet Delivery Account) system.

### Authentication and Security

#### [`FUIFE196`](source/koptWebRest/src/local/gyomu/api/FUIFE196.java) — One-Time Key Sending

Sends a one-time key (SMS or email) for authentication. Business service: `FUSV0352`, `SYSTEM_ID = "FRN1"`.

#### [`FUIFE197`](source/koptWebRest/src/local/gyomu/api/FUIFE197.java) — One-Time Key Authentication

Validates a one-time key submitted by the user.

#### [`CCIFE005`](source/koptWebRest/src/local/gyomu/api/CCIFE005.java) — One-Time Password Authentication (Operator Support)

Operator-focused OTP authentication. Business service: `CCSV0010`, `SYSTEM_ID = "OPS1"`. Added under ANK-3593-00-00.

#### [`CCIFE006`](source/koptWebRest/src/local/gyomu/api/CCIFE006.java) — One-Time Password Registration (Operator Support)

Registers a new one-time password for operator support. Same system pattern as `CCIFE005`.

#### [`FUIFE168`](source/koptWebRest/src/local/gyomu/api/FUIFE168.java) — Account Authentication (Sales Support)

Authenticates a user on the ESS (sales channel). Business service: `FUSV0333`, `SYSTEM_ID = "ESS1"`. Includes error extraction logic: when `ApiBpInterface.ERROR_INFO` is present, it populates the error list, removes the error info from the result map, sets the body, and throws `ApiServerExceptionGyomuErr`.

#### [`KKIFE501`](source/koptWebRest/src/local/gyomu/api/KKIFE501.java) — Payment Method Registration Login Authentication

Authenticates users during the payment method registration flow.

### Sales Support / Operator Support

#### [`FUIFE168`](source/koptWebRest/src/local/gyomu/api/FUIFE168.java) — Account Authentication (also listed above)

This class bridges the authentication and sales support domains.

#### [`KKIFE428`](source/koptWebRest/src/local/gyomu/api/KKIFE428.java) — Handling Code Reflection (Sales Support)

Reflects handling codes (operation codes entered by sales staff) into the system.

#### [`KKIFE433`](source/koptWebRest/src/local/gyomu/api/KKIFE433.java) — Malware Blocking Info Query/Update (CMP)

Manages malware blocking service enrollment for customers.

#### [`KKIFE436`](source/koptWebRest/src/local/gyomu/api/KKIFE436.java) — ID Aggregated Info Lookup (Operator Support)

Provides operators with an aggregated view of customer identity information.

#### [`KKIFE509`](source/koptWebRest/src/local/gyomu/api/KKIFE509.java) — Campaign Applicability Query/Registration

Checks and registers campaign eligibility for customers.

#### [`KKIFE510`](source/koptWebRest/src/local/gyomu/api/KKIFE509.java) — Net Migration Registration

Handles registration for customers migrating from a competing internet provider (net-hikou-sen).

#### [`KKIFE512`](source/koptWebRest/src/local/gyomu/api/KKIFE512.java) — CAS Number Query/Registration (CMP, DEN)

Manages CAS (Customer Authentication System) numbers.

#### [`KKIFE516`](source/koptWebRest/src/local/gyomu/api/KKIFE516.java) — NHK Group Bulk-Registration-Eligible Contract List

Retrieves contracts eligible for NHK broadcasting fee group billing.

#### [`KKIFE517`](source/koptWebRest/src/local/gyomu/api/KKIFE517.java) — NHK Group Bulk Registration

Registers customers for NHK group billing in bulk.

### Promotional Services

#### [`KKIFE445`](source/koptWebRest/src/local/gyomu/api/KKIFE445.java) — Netflix Contract/Service Start Request

Handles Netflix subscription requests and service activation for eo Hikari customers. Business service: `KKSV0949`, `SYSTEM_ID = "CMP1"`. Includes error extraction logic that populates the response error list and throws `ApiServerExceptionGyomuErr` when Netflix integration returns errors.

#### [`KKIFE456`](source/koptWebRest/src/local/gyomu/api/KKIFE456.java) — Cancellation Letter Lookup

Retrieves cancellation letters/documents.

#### [`KKIFE458`](source/koptWebRest/src/local/gyomu/api/KKIFE458.java) & [`KKIFE459`](source/koptWebRest/src/local/gyomu/api/KKIFE459.java) — Content Simultaneous Application Query/Update (CMP)

Manages simultaneous applications for additional content/services.

#### [`KKIFE460`](source/koptWebRest/src/local/gyomu/api/KKIFE460.java) — Service Reservation Status

Queries service reservation status.

#### [`KKIFE467`](source/koptWebRest/src/local/gyomu/api/KKIFE467.java) — SMS Delivery Result Notification

Receives and processes SMS delivery result notifications.

#### [`KKIFE470`](source/koptWebRest/src/local/gyomu/api/KKIFE470.java) — Discount Info List Lookup

Retrieves available discount information for a customer.

#### [`KKIFE471`](source/koptWebRest/src/local/gyomu/api/KKIFE471.java) — Discount Proposal Result Reflection

Records the results of discount proposals (whether the customer accepted).

#### [`KKIFE476`](source/koptWebRest/src/local/gyomu/api/KKIFE476.java) — Prize Code List Lookup (CMP)

Looks up available prize codes.

#### [`KKIFE477`](source/koptWebRest/src/local/gyomu/api/KKIFE477.java) — Gift Code Issuance Request (CMP)

Requests issuance of gift codes.

#### [`KKIFE499`](source/koptWebRest/src/local/gyomu/api/KKIFE499.java) — Referral Code Number Issuance (CMP, LINE)

Issues referral codes for the CMP and LINE platforms.

#### [`KUIFE079`](source/koptWebRest/src/local/gyomu/api/KUIFE079.java) —宅調 Auth Info Acquisition (CMP)

Acquires authentication information for construction surveys (宅内調査).

### Installation and Construction

#### [`KKIFE464`](source/koptWebRest/src/local/gyomu/api/KKIFE464.java) — Construction Case Info Lookup (Operator Support)

Retrieves construction case details for operator support. The `execute()` method reads from both request header and body, handling a non-standard parameter layout.

#### [`KKIFE465`](source/koptWebRest/src/local/gyomu/api/KKIFE465.java) — STB Course Reservation Detail (Operator Support)

Looks up set-top-box course reservation details.

#### [`KKIFE466`](source/koptWebRest/src/local/gyomu/api/KKIFE466.java) — Equipment Provision Service Reservation List (Operator Support)

Lists equipment provision service reservations.

#### [`KUIFE081`](source/koptWebRest/src/local/gyomu/api/KUIFE081.java) — Construction Progress Status Lookup

Queries the progress status of ongoing construction/installation work.

### Credit and Payment

#### [`KKIFE489`](source/koptWebRest/src/local/gyomu/api/KKIFE489.java) — Credit Pre-approval Request

Requests credit pre-approval for a customer. Business service: `KKSV0998`. Notably uses `callBpService2()` with a runtime-determined `systemID` extracted from the request body field `system_id`, making it flexible across different credit providers.

#### [`KKIFE490`](source/koptWebRest/src/local/gyomu/api/KKIFE490.java) — Credit Payment Approval Request

Requests credit payment authorization. Similar pattern to `KKIFE489` with runtime system ID resolution.

### Promotional Discount Analysis

#### [`FUIFE170`](source/koptWebRest/src/local/gyomu/api/FUIFE170.java) — Telephone Option Service Discount Determination

Determines whether a customer is eligible for telephone option service discounts. Business service: `FUSV0336`, `SYSTEM_ID = "CMP1"`. Includes full error extraction: reads `ApiBpInterface.ERROR_INFO`, populates the error list on the request bean, removes it from the result map, and throws `ApiServerExceptionGyomuErr` when errors are present.

#### [`FUIFE171`](source/koptWebRest/src/local/gyomu/api/FUIFE171.java) — Telephone Option Pack Application/Cancellation (CMP)

Handles application and cancellation of telephone option packs.

#### [`FUIFE172`](source/koptWebRest/src/local/gyomu/api/FUIFE172.java) — Telephone Option Related Master Integration (CMP)

Integrates telephone option service master data.

### Operator Support Workflows

#### [`CRIFE054`](source/koptWebRest/src/local/gyomu/api/CRIFE054.java) — Inquiry History Lookup (Operator Support)

Retrieves inquiry history records for operators. Business service: `CRSV0287`.

#### [`CRIFE055`](source/koptWebRest/src/local/gyomu/api/CRIFE055.java) — Response History Registration and Document Delivery Request

Registers response history and requests document delivery. Uses `callBpService2()` with a runtime system ID from the `uketsukesya` (受付者) body field, allowing different operator codes to route to different backend systems.

#### [`CRIFE056`](source/koptWebRest/src/local/gyomu/api/CRIFE056.java) — Response History Search (Sales Support)

Searches response history records for sales support.

#### [`CRIFE057`](source/koptWebRest/src/local/gyomu/api/CRIFE057.java) — Response History Lookup (Sales Support)

Looks up individual response history records.

#### [`CRIFE062`](source/koptWebRest/src/local/gyomu/api/CRIFE062.java) — Inquiry Customer Info List Lookup (Operator Support)

Retrieves a list of customers associated with inquiries.

#### [`CRIFE063`](source/koptWebRest/src/local/gyomu/api/CRIFE063.java) — Incoming Call Record Registration (Operator Support)

Registers incoming call records for operator support tracking.

### LINE-Specific Services (Additional)

#### [`ACIFE072`](source/koptWebRest/src/local/gyomu/api/ACIFE072.java) — Data Volume Info Lookup (Operator Support)

Looks up data volume information, primarily used by operator support interfaces.

### Address and Location Services

#### [`ZMIFE059`](source/koptWebRest/src/local/gyomu/api/ZMIFE059.java) — Address Kana Lookup (Operator Support)

Looks up the kana (phonetic) reading of an address.

#### [`ZMIFE060`](source/koptWebRest/src/local/gyomu/api/ZMIFE060.java) — Address Master Dropdown Info (Sales Support)

Provides address master dropdown data for sales support UIs.

### Other Services

#### [`KKIFE417`](source/koptWebRest/src/local/gyomu/api/KKIFE417.java) — Service Contract Attach Info Lookup (TV) (Operator Support)

Looks up TV-related service contract attachments.

#### [`KKIFE418`](source/koptWebRest/src/local/gyomu/api/KKIFE418.java) — Service Contract Attach Info Lookup (Construction, Installment) (Operator Support)

Looks up construction and installment contract attachments.

#### [`KKIFE419`](source/koptWebRest/src/local/gyomu/api/KKIFE419.java) — Service Contract Attach Info Lookup (Phone) (Operator Support)

Looks up phone-related service contract attachments.

#### [`KKIFE420`](source/koptWebRest/src/local/gyomu/api/KKIFE420.java) — Connected Device Info Lookup (Operator Support)

Retrieves information about devices connected to the customer's line.

#### [`KKIFE421`](source/koptWebRest/src/local/gyomu/api/KKIFE421.java) — Usage Location Address Info Lookup (Operator Support)

Looks up the address of the customer's usage location.

#### [`KKIFE422`](source/koptWebRest/src/local/gyomu/api/KKIFE422.java) — Fee Calculation Contract Info (Operator Support)

Retrieves contract information needed for fee calculation.

#### [`KKIFE423`](source/koptWebRest/src/local/gyomu/api/KKIFE423.java) — Fee Calculation Discount Info (Operator Support)

Retrieves discount information for fee calculation.

#### [`KKIFE424`](source/koptWebRest/src/local/gyomu/api/KKIFE424.java) — Fee Calculation Building Penalty Info (Operator Support)

Retrieves building early-termination penalty information for fee calculation.

#### [`KKIFE453`](source/koptWebRest/src/local/gyomu/api/KKIFE453.java) — STB User Info Lookup

Looks up set-top-box user information.

#### [`KKIFE506`](source/koptWebRest/src/local/gyomu/api/KKIFE506.java) — Standard Construction Fee Installment Total Notice Lookup (CMP)

Retrieves the total installment notice for standard construction fees.

#### [`KKIFE500`](source/koptWebRest/src/local/gyomu/api/KKIFE500.java) — eoID Post-Login Display Determination

Determines what to display on screen after eoID login.

#### [`KKIFE507`](source/koptWebRest/src/local/gyomu/api/KKIFE507.java) — Display/Information

Displays or provides information.

## Data Model

This package does not define its own data model. Instead, it uses the generic [`ApiServerPartsBean`](source/koptWebRest/src/local/gyomu/api/ACIFE070.java) from the `com.k_opti.api_parts.server.bean` package as the request/response envelope. This bean carries:

- **Header** — a `Map<String, Object>` containing routing and metadata (e.g., `sysid`, `uketsukesya`).
- **Body** — a `Map<String, Object>` carrying the domain payload. The key names in this map are determined by the target business service's contract.
- **ErrList** — a `List<Object>` of error maps, each containing at minimum `errCode` and `errMessage` keys.

The response from a business service call is stored in the return value as a `Map<String, Object>` keyed by `serviceId + _01CC` (a convention-defined suffix). Within that result map, error information is stored under the key defined by `ApiBpInterface.ERROR_INFO`, and the actual business data is under `BODY_INFO` for LINE-integrated services.

```mermaid
flowchart TD
    subgraph Request["Request Envelope: ApiServerPartsBean"]
        Header["Header Map<br/>sysid, uketsukesya, ..."]
        Body["Body Map<br/>Domain-specific keys"]
        ErrList["ErrList List<Object>"]
    end

    subgraph ServiceResponse["BP Service Result: Map<String, Object>"]
        Key["serviceId + _01CC"]
        BodyInfo["BODY_INFO Map<br/>For LINE services"]
        ErrInfo["ERROR_INFO<br/>ApiBpInterface key"]
        Data["Business data Map"]
    end

    Header --> Request
    Body --> Request
    ErrList --> Request
    Key --> ServiceResponse
    BodyInfo --> Key
    ErrInfo --> Key
    Data --> Key
```

## How It Works — A Typical Request Flow

Let's trace a request through [`CKIFE053`](source/koptWebRest/src/local/gyomu/api/CKIFE053.java) (Customer Basic Info Lookup) as a representative example:

1. **HTTP POST arrives** at the endpoint mapped to `CKIFE053`. JAX-RS invokes [`execute()`](source/koptWebRest/src/local/gyomu/api/CKIFE053.java).

2. **Common processing**: `execute()` calls `super.exec("CKIFE053", pRequest, pContext)`. The base class [`ApiServerLocalBase`](source/koptWebRest/src/local/gyomu/ApiServerLocalBase.java) handles authentication, request validation, and routing. It deserializes the request body into an `ApiServerPartsBean`.

3. **Business logic dispatch**: The base class invokes the overridden [`run()`](source/koptWebRest/src/local/gyomu/api/CKIFE053.java) method, which calls [`logicExecute()`](source/koptWebRest/src/local/gyomu/api/CKIFE053.java).

4. **Service call**: [`logicExecute()`](source/koptWebRest/src/local/gyomu/api/CKIFE053.java) calls `callBpService("CKSV0066", reqPartsBean, "CKIFE053", "OPS1")`. This sends the request to the EJB business service `CKSV0066` in the OPS1 (operator support) system.

5. **Response extraction**: The service returns a `Map<String, Object>` where the key is `"CKSV0066" + _01CC`. This map is extracted and set as the body of a new `ApiServerPartsBean`.

6. **Response sent back**: The base class receives the result bean and constructs an HTTP `Response` to send back to the client.

For error paths (e.g., [`FUIFE168`](source/koptWebRest/src/local/gyomu/api/FUIFE168.java)), step 5 differs: `logicExecute()` checks for `ApiBpInterface.ERROR_INFO` in the result map. If present, it extracts the error list, sets it on the request bean, throws `ApiServerExceptionGyomuErr`, and the base class converts this to an HTTP error response.

## Dependencies and Integration

### Internal dependencies

| Dependency | Description |
|---|---|
| `eo.common.util` | Shared utility classes (string handling, formatting) |
| `com.fujitsu.futurity.bp.custom.common` | Fujitsu runtime common libraries |
| `local.gyomu` | Parent module; contains the base class `ApiServerLocalBase` |
| `local.gyomu.api.common` | Common API helpers, notably `ApiBpInterface` (error info keys, constants) |
| `eo.ejb.cbs.mainproc` | EJB call-by-service infrastructure |
| `eo.business.service` | Business service interfaces |

### External dependencies

| Dependency | Role |
|---|---|
| JAX-RS (javax.ws.rs) | REST endpoint annotation (`@POST`, `@Path`, `@Context`) |
| Servlet API (javax.servlet) | HTTP request/response context injection |
| `com.k_opti.api_parts.server.bean.ApiServerPartsBean` | Request/response envelope |
| `com.k_opti.api_parts.server.exception.ApiServerExceptionGyomuErr` | Business error exception |

### Upstream integration

Each endpoint class maps to exactly one (or occasionally multiple) business service IDs (e.g., `CKSV0066`, `FUSV0333`, `KKSV0949`). The `SYSTEM_ID` field determines which upstream system the call is routed to:

- `CMP1` — Core customer management platform
- `ESS1` — ESS (sales channel) system
- `OPS1` — Operator support system
- `FRN1` — FRN (notification) system
- `API1` — LINE integration platform
- `FTR1` — Web frontend integration
- `"system_id"` — Dynamic, determined from request body (payment services)

## Notes for Developers

### Adding a new endpoint

1. Create a new class extending `ApiServerLocalBase` in this package.
2. Define the constants: `APIID` (class name), `SERVICE_ID` (business service name), `SYSTEM_ID` (upstream system), and `JOB_ID` (operation trace ID).
3. Override `execute()` to call `super.exec(APIID, pRequest, pContext)`.
4. Override `run()` to call `this.logicExecute(reqPartsBean)`.
5. Implement `logicExecute()`:
   - Call the appropriate `callBpService*()` method.
   - Extract the result using `outMap.get(serviceId + _01CC)`.
   - If the business service may return errors, check for `ApiBpInterface.ERROR_INFO` and handle as needed.
   - Create and return a new `ApiServerPartsBean` with the result body.

### LINE integration caveat

Classes modified under **ANK-3355-08-00** read the system ID from the `Sysid` HTTP header rather than the request body. This was done because multiple services are called in sequence through the LINE platform, and the system ID needs to be globally determined rather than per-request-body. If you add a new LINE-integrated endpoint, follow this pattern — declare a `private String HTTP_HEADER_SYSID = ""` field and read it in `execute()`.

### Error handling conventions

The `ApiBpInterface.ERROR_INFO` key is used consistently to flag business errors from the bp layer. When present:
- Set it on `reqPartsBean.setErrList()` before throwing.
- Remove it from the result map to prevent leakage.
- The base class converts `ApiServerExceptionGyomuErr` into a proper HTTP error response.

### Naming convention

The class name encodes the interface ID (e.g., `ACIFE070`). The prefix indicates the system:
- `AC*` — Usage/charge information
- `CC*` — Authentication/security
- `CH*` — Billing/charge
- `CK*` — Customer management
- `CR*` — Response/inquiry records
- `FUI*` — Web/frontend user intake
- `KK*` — Contract/kyakuyaku information
- `KUI*` — Construction/unique operations
- `ZM*` — Address/master data

### Testing

Each class is thin (typically 100-200 lines) and mostly delegates to the base class and the bp service layer. Unit testing should focus on:
- Correct service ID and system ID assignment
- Proper error extraction and re-throwing in classes that handle errors
- LINE-specific system ID header extraction
- Response body unwrapping (especially `BODY_INFO` extraction for LINE services)

### File size note

Some source files (e.g., `KKIFE475.java`) exceed typical sizes and contain custom logic beyond the standard delegation pattern. Always check for non-standard logic in `logicExecute()` before applying bulk refactoring.