# Business Logic — KKIFE499.run() [12 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `local.gyomu.api.KKIFE499` |
| Layer | API / Controller (REST entry point layer) |
| Module | `api` (Package: `local.gyomu.api`) |

## 1. Role

### KKIFE499.run()

This method serves as the core business logic entry point for the "KKIFE499 - Referral Code Issuance (CMP/LINE)" external API class (外部I/F:「KKIFE499_紹介コード発行（CMP・LINE)」受付処理クラス). It receives server-side business API interlocking data (サーバ業務AP連携データ) and delegates the actual business processing to the downstream BPM service layer.

The method implements a **delegation design pattern**: it receives request data, passes it to `logicExecute()` which routes the call to the BPM service `KKSV1013` (the referral code issuance service). Before delegation, `logicExecute()` determines the originating system context by inspecting the request header's `authId` field — this allows the same business service to be invoked from multiple client systems with the correct system identifier.

KKIFE499 is an external API entry point registered with JAX-RS (`@Path("KKIFE499")`), meaning it is called via REST HTTP POST from external systems. Its role in the larger system is to act as an intermediary that forwards referral code issuance requests from CMP (customer management platform), LINE (LINE mobile integration), and eo App (eo mobile application) systems to the central BPM workflow engine.

The method was updated in version 72.00.00 (2024/12/10) to support referral code issuance from the eo App (eoアプリから紹介コード発行対応) via the ANK-4629-00-00 change, adding a third authentication pathway alongside the original CMP and LINE systems.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["KKIFE499.run(reqPartsBean)"])
    RUN_BODY(["Process business logic"])

    RUN_BODY --> CALL_LOGIC["call logicExecute(reqPartsBean)"]

    CALL_LOGIC --> SETSVC["Set serviceId KKSV1013"]
    SETSVC --> CHECK_AUTH["Check header authId"]

    CHECK_AUTH --> D1{authId equals eoforwtsn?}
    D1 -->|True| SET_LINE["Set systemId API1 LINE"]
    D1 -->|False| D2{authId equals eoforeama?}

    D2 -->|True| SET_EOAPP["Set systemId EAM1 eo App"]
    D2 -->|False| SET_CMP["Set systemId CMP1 CMP"]

    SET_LINE --> CALLBP["callBpService2 serviceId reqPartsBean JOB_ID systemId"]
    SET_EOAPP --> CALLBP
    SET_CMP --> CALLBP

    CALLBP --> EXTRACT["Extract result from outMap key KKSV101301CC"]
    EXTRACT --> CREATERESP["Create new ApiServerPartsBean setBody resultMap"]
    CREATERESP --> RETURN(["Return resPartsBean"])

    RETURN --> END_END(["End"])
```

**Processing flow:**

1. The `run()` method delegates to `logicExecute(reqPartsBean)` to perform the core business logic (レスポンスデータ生成 — response data generation).
2. Inside `logicExecute()`, the service ID is fixed to `KKSV1013` (the referral code issuance BPM service). The system ID is determined dynamically by inspecting the `authId` value in the request header.
3. Three possible system contexts exist:
   - **LINE system**: `authId = "eoforwtsn"` → `systemId = "API1"`
   - **eo App (mobile)**: `authId = "eoforeama"` → `systemId = "EAM1"`
   - **CMP (default)**: any other authId → `systemId = "CMP1"`
4. The BPM service is invoked via `callBpService2()` with the resolved system ID, passing the service ID `KKSV1013`, request body, job ID `KKIFE499`, and the resolved system ID.
5. The response is extracted from the output map using the key `KKSV101301CC` (service ID + `_01CC`), packaged into a new `ApiServerPartsBean` as the response body, and returned.

**Constant resolution:**

| Constant | Value | Business Meaning |
|----------|-------|-----------------|
| `SERVICE_ID` | `"KKSV1013"` | BPM service ID for referral code issuance (紹介コード発行サービス) |
| `SYSTEM_ID_CMP` | `"CMP1"` | Predecessor system ID for CMP (customer management platform) |
| `SYSTEM_ID_LINE` | `"API1"` | Predecessor system ID for LINE |
| `SYSTEM_ID_EOAPP` | `"EAM1"` | Predecessor system ID for eo App (mobile application) |
| `AUTH_ID_LINE` | `"eoforwtsn"` | Authentication ID for LINE system |
| `AUTH_ID_EOAPP` | `"eoforeama"` | Authentication ID for eo App (mobile application) |
| `JOB_ID` | `"KKIFE499"` | Job identifier for BPM logging/tracking |
| `_01CC` | `"01CC"` | Convention suffix for CC (Control Component) map key |

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `reqPartsBean` | `ApiServerPartsBean` | Server business API interlocking data (リクエスト) — carries the referral code issuance request including the request body with order/customer details and a header map containing `authId` to identify the calling system (CMP, LINE, or eo App). The `authId` value determines which system context (`systemId`) is used when routing to the BPM service. |

**Instance fields read by this method:**

No instance fields are directly read in the `run()` method itself. All constant values (`SERVICE_ID`, `SYSTEM_ID_CMP`, `SYSTEM_ID_LINE`, `SYSTEM_ID_EOAPP`, `JOB_ID`) are `private static final` and accessed directly. The `logicExecute()` method reads `SERVICE_ID`, `AUTH_ID_LINE`, `AUTH_ID_EOAPP`, `SYSTEM_ID_LINE`, `SYSTEM_ID_EOAPP`, `SYSTEM_ID_CMP`, and `JOB_ID` as class-level constants.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `KKIFE499.logicExecute` | KKIFE499 | - | Internal method that determines system context and delegates to BPM service |
| - | `callBpService2` (ApiServerLocalBase) | ApiServerLocalBase | - | Base class method that invokes BPM service via `ApiBpInterface.invokeService()` with telegram info, job ID, and operator ID |
| - | `KKSV1013OPOperation.run` | KKSV1013 | - | BPM operation that forwards to `KKSV101301CC` for actual referral code issuance |

**How classification works:**

This method does not directly perform CRUD operations. Instead, it acts as an API gateway that delegates to the BPM service layer:
- `callBpService2` is an API-to-BPM bridge method in `ApiServerLocalBase` that invokes the BPM workflow engine via `ApiBpInterface.invokeService()`. It routes the request to the specified service (`KKSV1013`) with the resolved system context.
- The downstream BPM service `KKSV1013` contains an operation `KKSV1013OPOperation` that calls the control component `KKSV101301CC` (`JKKIntrCdHakkoReqCMPLINECC`), which handles the actual referral code issuance business logic including any database operations.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | External REST API | HTTP POST `/KKIFE499` → `KKIFE499.execute()` → `super.exec(APIID, ...)` → `KKIFE499.run()` | `logicExecute` → `callBpService2` → `KKSV1013OPOperation.run` → `KKSV101301CC.execute` |

**Notes:**
- `KKIFE499` is a JAX-RS REST endpoint (`@Path("KKIFE499")` with `@POST` method `execute()`). It is not called by any other Java class within the codebase.
- The `execute()` method delegates to `super.exec(APIID, pRequest, pContext)` which is inherited from `ApiServerLocalBase`. This base class method performs API common processing and ultimately invokes `run()` via the standard API execution flow.
- The downstream terminal of this method's processing chain is `KKSV101301CC.execute` (the control component for referral code issuance request CMP/LINE processing).

## 6. Per-Branch Detail Blocks

**Block 1** — METHOD (L109)

> The `run()` method body. Delegates to `logicExecute()` for all business processing.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `resPartsBean = this.logicExecute(reqPartsBean)` // Invoke business logic, generate response data |
| 2 | RETURN | `return resPartsBean` // Return response to caller |

**Block 1.1** — nested inside `logicExecute` — IF-ELSE-IF-ELSE CHAIN: System ID Determination (L130–L144)

> Determines which system context is invoking the service based on the `authId` in the request header. Routes to the appropriate predecessor system ID for BPM service invocation.

| # | Type | Code |
|---|------|------|
| 1 | SET | `serviceId = SERVICE_ID` // serviceId = "KKSV1013" — referral code issuance BPM service |
| 2 | SET | `systemId = null` // Initialize systemId, will be set by branch |
| 3 | EXEC | `reqPartsBean.getHeader().get("authId")` // Read authId from request header |
| 4 | IF | `AUTH_ID_LINE.equals(authId)` [AUTH_ID_LINE = "eoforwtsn"] (LINE system authentication) |
| 4.1 | SET | `systemId = SYSTEM_ID_LINE` // [SYSTEM_ID_LINE = "API1"] |
| 5 | ELSE-IF | `AUTH_ID_EOAPP.equals(authId)` [AUTH_ID_EOAPP = "eoforeama"] (eo App authentication) |
| 5.1 | SET | `systemId = SYSTEM_ID_EOAPP` // [SYSTEM_ID_EOAPP = "EAM1"] |
| 6 | ELSE | (default — CMP system) |
| 6.1 | SET | `systemId = SYSTEM_ID_CMP` // [SYSTEM_ID_CMP = "CMP1"] |

**Block 1.2** — Call BPM Service (L146)

| # | Type | Code |
|---|------|------|
| 1 | CALL | `outMap = callBpService2(serviceId, reqPartsBean, JOB_ID, systemId)` // Invoke BPM service with resolved system context |

**Block 1.3** — Extract Response Data (L148)

| # | Type | Code |
|---|------|------|
| 1 | SET | `resultMap = (Map<String, Object>)outMap.get(serviceId + _01CC)` // Extract from key "KKSV101301CC" [serviceId = "KKSV1013", _01CC = "01CC"] |

**Block 1.4** — Build Response Bean (L151–L152)

| # | Type | Code |
|---|------|------|
| 1 | SET | `resPartsBean = new ApiServerPartsBean()` // Create new response bean |
| 2 | EXEC | `resPartsBean.setBody(resultMap)` // Set response body with service processing result |
| 3 | RETURN | `return resPartsBean` // Return to caller |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `紹介コード` | Japanese | Referral Code — a code issued through referral programs for customer acquisition |
| `受付処理クラス` | Japanese | Reception Processing Class — API class that handles incoming requests |
| `CMP` | Acronym | Customer Management Platform — the core customer management system (preceding system ID: CMP1) |
| `LINE` | Business term | LINE — the Japanese messaging platform used as a channel for referral code issuance (preceding system ID: API1) |
| `eo App` | Business term | eo Mobile Application — the mobile app for eo (NTT docomo's brand) customers (preceding system ID: EAM1) |
| `KKSV1013` | Code | BPM Service ID for referral code issuance workflow (紹介コード発行サービス) |
| `KKSV101301CC` | Code | Control Component for KKSV1013 operation — handles referral code issuance request CMP/LINE processing |
| `JKKIntrCdHakkoReqCMPLINECC` | Code | Control Component class for Referral Code Issuance Request CMP/LINE — actual implementation of referral code issuance logic |
| `ApiServerPartsBean` | Type | Server business API interlocking data carrier — transfers request/response data between API layer and business logic |
| `authId` | Field | Authentication ID in request header — identifies which system is making the API call (eoforwtsn=LINE, eoforeama=eo App, default=CMP) |
| `systemId` | Field | Predecessor system ID — determines which system context to use for BPM service routing (CMP1, API1, EAM1) |
| `_01CC` | Constant | Convention suffix "01CC" — used as map key suffix to identify CC (Control Component) data in BPM input/output maps |
| `JOB_ID` | Constant | Job identifier "KKIFE499" — used for BPM job logging and tracking |
| `callBpService2` | Method | API-to-BPM service bridge — invokes the BPM workflow engine via ApiBpInterface with service ID, request data, job ID, and system ID |
| `ApiBpInterface.invokeService` | Method | Core BPM invocation method — executes the business process defined by the service ID and operation ID |