# Local

## Overview

The `local` package serves as the **HTTP API gateway** for the eo customer base system (eo顧客基幹システム). It is the primary integration layer that bridges external client applications — web frontends, the LINE messaging platform, operator support consoles, and external sales channels — with the backend EJB business service infrastructure.

Rather than organizing itself into sub-packages by concern, the `local` module is organized around a **single cohesive integration layer** under the `gyomu` sub-package. All 60+ REST endpoint classes share a common abstract base class (`ApiServerLocalBase`) that enforces a uniform request-processing pipeline: authentication, system-ID-based routing, business service invocation, and structured error handling. This makes the gateway highly regular and predictable, with each endpoint class typically consisting of 100–200 lines focused on domain-specific logic.

The module covers a broad range of business domains, from customer information management and LINE integration to billing, contract transfers, web application intake, promotional services, installation workflows, and credit processing. Each domain is served by its own set of JAX-RS `@POST` endpoints that delegate to upstream systems (CMP, ESS, OPS, FRN, FTR) via compile-time or runtime-determined system IDs.

## Sub-module Guide

The `local` module contains one documented sub-module:

### `gyomu` — The API Gateway Layer

The `gyomu` package is the core of the `local` module and contains all 60+ REST endpoint classes. These endpoints do not depend on each other; instead, they converge on shared foundations:

1. **`ApiServerLocalBase`** — The abstract base class that every endpoint extends. It implements the template method pattern (`execute` → `run` → `logicExecute`), provides shared service invocation methods, and handles common authentication and error processing.

2. **`local.gyomu.api.common`** — Helper utilities including `ApiBpInterface` (error info keys, service invocation constants) and `ApiCommonItem` (operational metadata such as job ID and operator ID).

The endpoint classes are organized into domains by their naming prefix (e.g., `CK*` for customer management, `KK*` for contracts, `AC*` for usage/charge information, `FUI*` for web frontend intake). Each domain group shares a common set of upstream business services and a consistent code naming convention.

#### Domain mapping

| Prefix | Domain | Example endpoints |
|---|---|---|
| `AC*` | Usage / charge information | `ACIFE070` (LINE usage) |
| `CC*` | Authentication / security | `CCIFE005`, `CCIFE006` (OTP, account auth) |
| `CH*` | Billing / charge | `CHIFE067`, `CHIFE528` (billing, discounts) |
| `CK*` | Customer management | `CKIFE051`, `CKIFE053` (address, prospects) |
| `CR*` | Response / inquiry records | `CRIFE054`, `CRIFE055` (inquiry history) |
| `FUI*` | Web / frontend user intake | `FUIFE168`, `FUIFE194` (application forms) |
| `KK*` | Contract / kyakuyaku information | `KKIFE403`, `KKIFE445` (transfers, discounts) |
| `KUI*` | Construction / unique operations | `KUIFE079`, `KUIFE081` (STB, provisioning) |
| `ZM*` | Address / master data | `ZMIFE059`, `ZMIFE060` (address lookups) |

#### How the sub-modules relate

The `gyomu` module is a **flat integration layer** — endpoints do not call each other, and there is no hierarchical sub-module structure beyond the shared base class and common helpers. The relationships are instead **horizontal**, organized by:

- **Upstream system target** — each endpoint maps to a specific upstream system (CMP, ESS, OPS, LINE, etc.) via its `SYSTEM_ID` constant or header.
- **Client origin** — LINE-integrated endpoints follow a different invocation path (`callBpServiceForLine` with `Sysid` header routing) compared to standard web/operator endpoints.
- **Domain complexity** — most endpoints are thin delegates (100–200 lines), but some (e.g., `FUIFE194`, `KKIFE475`) contain substantial custom logic for error handling, field name transformation, or multi-step workflows.

## Key Patterns and Architecture

### Template method request pipeline

Every endpoint follows a uniform three-phase flow, making the package highly regular:

1. **`execute()`** — Public JAX-RS entry point (`@POST`). Extracts the request and servlet context, then delegates to the base class's `exec()` for common processing.
2. **`run()`** — Template method called by the base class after authentication and validation. The override calls `logicExecute()`.
3. **`logicExecute()`** — Private method containing domain-specific logic: business service invocation, result extraction, and response envelope construction.

### Business service invocation variants

The base class provides multiple service invocation methods tailored to different scenarios:

| Method | When used | Purpose |
|---|---|---|
| `callBpService()` | Most classes | Standard synchronous call to an EJB business service |
| `callBpService2()` | Runtime system ID needed | Accepts a runtime system identifier instead of a compile-time constant |
| `callBpServiceForLine()` | LINE endpoints | LINE-integrated services; response body nested under `BODY_INFO` |
| `callBpService(id1, id2)` | Multi-service ops | Chains two sequential business service calls |

### System ID routing

Each endpoint defines a compile-time `SYSTEM_ID` constant (e.g., `"CMP1"`, `"ESS1"`, `"OPS1"`) indicating the target upstream system. LINE-integrated endpoints read the system ID from the HTTP `Sysid` header at runtime (modified under ticket **ANK-3355-08-00**), enabling a single gateway to serve multiple LINE environments. Credit endpoints extract the system ID from the request body for dynamic provider routing.

### Error handling convention

The base class distinguishes two exception types:

- **`ApiServerExceptionGyomuErr`** — Business error (expected, controllable). The return code is checked against a whitelist; the error code and message are placed in `reqPartsBean.setErrList()` and re-thrown.
- **`ApiServerExceptionGyomuSysErr`** — System error (unexpected). Wrapped from generic `Exception` in the base class's `mainExec()` catch block.

Most endpoints return results directly. A subset extracts `ERROR_INFO` from the service result for structured error propagation, with `FUIFE194` being the most complex handler (nested try/catch blocks, `errCode` injection, completion notifications, and data cleanup).

### Data envelope

All requests and responses use the generic `ApiServerPartsBean` envelope, which carries a `Header` map (routing metadata), a `Body` map (domain payload), and an `ErrList` (structured errors). Business service responses arrive as a `Map<String, Object>` keyed by `serviceId + "01CC"`, with data under standard keys (`BODY_INFO`, `ERROR_INFO`).

## System Interaction

```mermaid
flowchart TD
    subgraph CLIENT["Client Tier"]
        WEB["Web Frontend"]
        LINE["LINE Platform"]
        OPS["Operator Support"]
    end

    subgraph API_LAYER["API Gateway Layer<br/>local.gyomu.api"]
        END["60+ Endpoint Classes<br/>JAX-RS @POST"]
    end

    subgraph BASE["Common Base Class<br/>ApiServerLocalBase"]
        AUTH["Authentication<br/>Validation"]
        ROUTE["System ID<br/>Routing"]
        SERVCALL["callBpService<br/>callBpService2<br/>callBpServiceForLine"]
    end

    subgraph BP_LAYER["Business Service Layer<br/>eo.ejb.cbs.mainproc"]
        CMP["CMP - Customer Mgmt"]
        ESS["ESS - Sales Channel"]
        OPS_BP["OPS - Operator Support"]
        LINE_BP["LINE Platform"]
        OTHER["Other Systems<br/>FRN, FTR, DEN"]
    end

    WEB --> END
    LINE --> END
    OPS --> END
    END --> AUTH
    END --> ROUTE
    ROUTE --> SERVCALL
    AUTH --> SERVCALL
    SERVCALL --> CMP
    SERVCALL --> ESS
    SERVCALL --> OPS_BP
    SERVCALL --> LINE_BP
    SERVCALL --> OTHER
```

## Dependencies and Integration

### Package structure

| Source file | Role |
|---|---|
| `ApiServerLocalBase.java` | Abstract base class; template method, service invocation, error handling |

### Upstream systems

Each endpoint maps to one or more upstream systems via `SYSTEM_ID`:

- **`CMP1`** — Core customer management platform (largest consumer, covers customer data, billing, promotions)
- **`ESS1`** — Sales channel (ESS) system
- **`OPS1`** — Operator support system
- **`FRN1`** — FRN notification system
- **`API1`** — LINE integration platform
- **`FTR1`** — Web frontend integration
- **Runtime `system_id`** — Dynamic routing for credit/payment services

### External dependencies

| Dependency | Role |
|---|---|
| `eo.ejb.cbs.mainproc` | EJB call-by-service infrastructure |
| `eo.business.common` | Shared business utilities |
| `eo.business.service` | Business service interfaces |
| `local.gyomu.api.common` | Common API helpers |
| `com.fujitsu.futurity.bp.custom.bpm.chsv0065` | Fujitsu BPM service |
| `com.fujitsu.futurity.bp.custom.bpm.chsv0066` | Fujitsu BPM service |
| `com.fujitsu.futurity.bp.custom.bpm.chsv0067` | Fujitsu BPM service |
| `com.fujitsu.futurity.bp.custom.common` | Fujitsu runtime common libraries |
| JAX-RS / Servlet API | REST endpoint annotation and HTTP context |

## Notes for Developers

### Adding a new endpoint

1. Create a class extending `ApiServerLocalBase` in the `local.gyomu.api` 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 `ERROR_INFO` and handle accordingly.
   - Create and return a new `ApiServerPartsBean` with the result body.

### LINE integration caveat

Endpoints modified under **ANK-3355-08-00** read the system ID from the HTTP `Sysid` header rather than the request body. This was necessary because multiple services are called in sequence through the LINE platform, and the system ID must be globally determined rather than per-request-body. For new LINE endpoints, declare `private String HTTP_HEADER_SYSID = ""` and read it in `execute()`.

### File size awareness

Some endpoint files (e.g., `KKIFE475`) exceed typical sizes and contain custom logic beyond the standard delegation pattern — such as stripping prefix underscores from field names for SOAP naming compliance. Always inspect `logicExecute()` in larger files before applying bulk refactoring.

### Testing guidance

Each class is thin and mostly delegates to the base class and the business service layer. Unit testing should focus on:

- Correct `SERVICE_ID` and `SYSTEM_ID` assignment
- Proper error extraction and re-throwing
- LINE-specific system ID header extraction
- Response body unwrapping (especially `BODY_INFO` extraction for LINE services)

### Naming convention

The class name encodes the interface ID and domain. The prefix consistently indicates the business domain (see the domain mapping table above). When adding new endpoints, follow the existing prefix convention to maintain discoverability.