# Business Logic — JEKKA0050004TPMA.executeKKIFE502() [69 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.ejb.cbs.mainproc.JEKKA0050004TPMA` |
| Layer | Service (EJB Main Process) |
| Module | `mainproc` (Package: `eo.ejb.cbs.mainproc`) |

## 1. Role

### JEKKA0050004TPMA.executeKKIFE502()

This method implements the **Premium Club Point Registration** business logic for the K-Opticom customer base system. It serves as the execution entry point for registering premium club points earned by a subscriber, delegating the core work to an external API component (`JKKcommonApiKKA0050004`).

The method implements a **delegation pattern**: it extracts relevant fields from the incoming CBS message (`inCBSMsg`), assembles them into a parameter map with semantic keys defined by the API component, instantiates the API handler, and invokes `callApiKKA0050004`. After the API returns, it maps response fields (application end date, presentation date, presentation reason) back into the message, processes any business error details, and sets an error flag based on the API's result code.

The design implements **API-standard refactoring** (IT1-2023-0000016): the original hand-coded external interface logic was replaced with a standardized API parts class. It is a shared utility method — the class implements `TemplateMainHandler`, meaning it can be invoked by the business process framework as a callback handler. There are no conditional branches based on service type; this method handles the single premium club point registration use case end-to-end.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["executeKKIFE502 start"])
    MAP["Build serviceMap from inCBSMsg fields"]
    API["Create JKKcommonApiKKA0050004 and call callApiKKA0050004(serviceMap)"]
    SETRESULT["Set RESULTCODE and RESULTDETAILCODE from response"]
    ERRCHK{"gyoumErrorList != null?"}
    ERREACH{"obj instanceof HashMap?"}
    ERREXTRACT["Extract error code/message, add to errList"]
    ERRSET{"errList.size > 0?"}
    ERRLISTSET["Set EKKA0050004CBSMSG1LIST on inCBSMsg"]
    BODYCHK{"bodyMap != null?"}
    BODYSET["Set response body fields on inCBSMsg"]
    RESULTCHK{"resultCode == 000?"}
    ERRFLAG1["Set ERR_FLG = 1"]
    ERRFLAG0["Set ERR_FLG = 0"]
    END(["Return / Next"])

    START --> MAP
    MAP --> API
    API --> SETRESULT
    SETRESULT --> ERRCHK
    ERRCHK -->|true| ERREACH
    ERRCHK -->|false| BODYCHK
    ERREACH -->|true| ERREXTRACT
    ERREACH -->|false| ERRCHK
    ERREXTRACT --> ERRCHK
    ERRCHK -->|false| BODYCHK
    ERRSET -->|true| ERRLISTSET
    ERRSET -->|false| BODYCHK
    ERRLISTSET --> BODYCHK
    BODYCHK -->|true| BODYSET
    BODYCHK -->|false| END
    BODYSET --> RESULTCHK
    RESULTCHK -->|true| ERRFLAG0
    RESULTCHK -->|false| ERRFLAG1
    ERRFLAG0 --> END
    ERRFLAG1 --> END
```

**CRITICAL — Constant Resolution:**

The method uses `ApiClientConst.IF_HEADER_RESULTCODE`, `ApiClientConst.IF_HEADER_RESULTDETAILCODE`, `ApiClientConst.IF_HEADER_GYOMUERRORLIST`, and `ApiClientConst.IF_BODY` as map keys for the API request/response. The actual string values are defined in `ApiClientConst` (from `com.k_opti.api_parts.client.constant`).

The result code comparison `!(\"000\".equals(resposeMap.get(\"resultCode\")))` uses a hardcoded string `"000"` — which represents a **successful API call** (modified in #82591 to remove `"500"` as an acceptable success code).

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `inCBSMsg` | `CAANMsg` | The CBS message carrying the premium club point registration request and response payload. Contains input fields (functional code, SYSID, application start date, presentation kind, presentation point count, SNS subtype code, measure application branch number) and receives output fields (result code, result detail code, application end date, presentation date, presentation date/time, presentation reason, error flag, and error detail list). |
| 2 | `inContext` | `AgentDispatchContext` | The agent dispatch context providing runtime execution metadata (operator info, session data, etc.). Passed through to the API component for audit and traceability. |

**Instance fields / external state:** None read directly by this method. All state flows through `inCBSMsg` and `inContext`.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `callApiKKA0050004` | KKA0050004 | (external API) | Calls the external API to process premium club point registration. Delegates all data persistence to the API component. |
| - | `toStingObj` | (local) | - | Helper method to convert Object to String, used when extracting map values for error codes/messages and response body fields. |

### Called method details:

- **`JKKcommonApiKKA0050004.callApiKKA0050004(Map<String, Object>)`** — External API call that handles the premium club point point registration. The API component is responsible for all downstream data access (entity reads/writes, database operations). This method does not directly access any tables or entities.

- **`toStingObj(Object)`** — Local utility method within `JEKKA0050004TPMA`. Converts an `Object` to a `String` safely (handles `null` by returning an empty string).

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen: KKSV1021 | `KKSV1021` → `KKSV1021OP` → `EKKA0050004BSMapper.editInMsg()` → Business Process Framework → `JEKKA0050004TPMA.executeKKIFE502()` | `callApiKKA0050004 [R] external API (premium club point registration)` |

**Notes:**
- `JEKKA0050004TPMA` is the only caller of `executeKKIFE502` in the codebase.
- The entry point is the **KKSV1021** screen (premium club point registration operation), which uses the `KKSV1021_KKSV1021OP_EKKA0050004BSMapper` to build the input message for the business process framework.
- The mapper populates fields from `KKSV102101SC` data (functional code, SYSID, application dates, presentation info, SNS subtype, measure application).
- The business process framework routes the message to this handler via the `TemplateMainHandler` interface.

## 6. Per-Branch Detail Blocks

### Block 1 — SETUP (L62–L70)

> Build a parameter map from the incoming CBS message fields. Each field is extracted via `getString()` and mapped to an API input key constant.

| # | Type | Code |
|---|------|------|
| 1 | SET | `serviceMap = new LinkedHashMap<String, Object>()` // Create ordered parameter map |
| 2 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_FUNC_CODE, inCBSMsg.getString(EKKA0050004CBSMsg.FUNC_CODE))` // Functional code [-> "func_code"] |
| 3 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_SYSID, inCBSMsg.getString(EKKA0050004CBSMsg.SYSID))` // SYSID [-> "sysid"] |
| 4 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_TEKIYO_ST_YMD, inCBSMsg.getString(EKKA0050004CBSMsg.TEKIYO_ST_YMD))` // Application start date [-> "tekiyo_st_ymd"] |
| 5 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_PRESENT_KBN, inCBSMsg.getString(EKKA0050004CBSMsg.PRESENT_KBN))` // Presentation kind [-> "present_kbn"] |
| 6 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_PRESENT_PT_SU, inCBSMsg.getString(EKKA0050004CBSMsg.PRESENT_PT_SU))` // Presentation point count [-> "present_pt_su"] |
| 7 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_SNS_SBT_CD, inCBSMsg.getString(EKKA0050004CBSMsg.SNS_SBT_CD))` // SNS subtype code [-> "sns_sbt_cd"] |
| 8 | CALL | `serviceMap.put(JKKcommonApiKKA0050004.IN_PARAM_SISK_SINS_EDA_NO, inCBSMsg.getString(EKKA0050004CBSMsg.SISK_SINS_EDA_NO))` // Measure application branch number [-> "sisk_sins_eda_no"] |

### Block 2 — TRY BLOCK (L72–L128)

> Execute the API call and process the response. Encompasses API invocation, error list processing, body field extraction, and error flag setting.

#### Block 2.1 — API Invocation (L74–L77)

> Create the API instance and invoke it with the prepared parameter map.

| # | Type | Code |
|---|------|------|
| 1 | SET | `instance = new JKKcommonApiKKA0050004()` // Instantiate API handler |
| 2 | CALL | `resposeMap = instance.callApiKKA0050004(serviceMap)` // External API call [-> R (external API)] |

#### Block 2.2 — Result Code Extraction (L78–L80)

> Extract the API response header fields and build an error detail list.

| # | Type | Code |
|---|------|------|
| 1 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.RESULTCODE, (String)resposeMap.get(ApiClientConst.IF_HEADER_RESULTCODE))` // Set result code from API response header |
| 2 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.RESULTDETAILCODE, (String)resposeMap.get(ApiClientConst.IF_HEADER_RESULTDETAILCODE))` // Set result detail code from API response header |
| 3 | SET | `errList = new ArrayList<CAANMsg>()` // Initialize error detail list |
| 4 | SET | `gyoumErrorList = (ArrayList<?>)resposeMap.get(ApiClientConst.IF_HEADER_GYOMUERRORLIST)` // Get error list from API response header [-> constant: IF_HEADER_GYOMUERRORLIST] |

#### Block 2.3 — Error List Processing (L81–L99)

> Iterate through the error list returned by the API, extract error codes and messages, and write them to the response message.

##### Block 2.3.1 — NULL CHECK (L81–L82) `[gyoumErrorList != null]`

| # | Type | Code |
|---|------|------|
| 1 | EXEC | Conditional check: `if (gyoumErrorList != null)` // Proceed only if error list exists |

##### Block 2.3.2 — ITERATION (L83–L97) `[for (Object obj : gyoumErrorList)]`

> Loop through each element of the error list.

| # | Type | Code |
|---|------|------|
| 1 | SET | `msg = new CAANMsg(EKKA0050004CBSMsg1List.class.getName())` // Create error detail message using list schema |
| 2 | SET | `errMap = (HashMap<?, ?>)obj` // Cast error item to HashMap |
| 3 | SET | `msg.set(EKKA0050004CBSMsg1List.ERRORCODE, toStingObj(errMap.get(JKKcommonApiKKA0050004.ERR_CODE)))` // Set error code [-> constant: ERR_CODE] |
| 4 | SET | `msg.set(EKKA0050004CBSMsg1List.ERRORMESSAGE, toStingObj(errMap.get(JKKcommonApiKKA0050004.ERR_MESSAGE)))` // Set error message [-> constant: ERR_MESSAGE] |
| 5 | EXEC | `errList.add(msg)` // Add formatted error to list |

##### Block 2.3.3 — ERROR LIST SET CONDITION (L95–L99) `[errList.size() > 0]`

| # | Type | Code |
|---|------|------|
| 1 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.EKKA0050004CBSMSG1LIST, errList.toArray(new CAANMsg[0]))` // Write error detail list to response message [-> constant: EKKA0050004CBSMSG1LIST] |

#### Block 2.4 — Body Map Extraction (L100–L101)

> Extract the response body map from the API result.

| # | Type | Code |
|---|------|------|
| 1 | SET | `bodyMap = (HashMap<?,?>)resposeMap.get(ApiClientConst.IF_BODY)` // Get response body [-> constant: IF_BODY] |

#### Block 2.5 — Response Body Field Setting (L102–L116) `[bodyMap != null]`

> Set each response body field onto the CBS message.

##### Block 2.5.1 — NULL CHECK `[bodyMap != null]`

| # | Type | Code |
|---|------|------|
| 1 | EXEC | Conditional check: `if (bodyMap != null)` |

##### Block 2.5.2 — FIELD EXTRACTION (L103–L106)

| # | Type | Code |
|---|------|------|
| 1 | SET | `tekiyoEdYmd = bodyMap.get(JKKcommonApiKKA0050004.OUT_PARAM_TEKIYO_ED_YMD)` // Application end date [-> constant: OUT_PARAM_TEKIYO_ED_YMD] |
| 2 | SET | `presentYmd = bodyMap.get(JKKcommonApiKKA0050004.OUT_PARAM_PRESENT_YMD)` // Presentation date [-> constant: OUT_PARAM_PRESENT_YMD] |
| 3 | SET | `presentYmdHms = bodyMap.get(JKKcommonApiKKA0050004.OUT_PARAM_PRESENT_YMD_HMS)` // Presentation date/time [-> constant: OUT_PARAM_PRESENT_YMD_HMS] |
| 4 | SET | `presentRiyu = bodyMap.get(JKKcommonApiKKA0050004.OUT_PARAM_PRESENT_RIYU)` // Presentation reason [-> constant: OUT_PARAM_PRESENT_RIYU] |

##### Block 2.5.3 — FIELD ASSIGNMENT (L107–L110)

| # | Type | Code |
|---|------|------|
| 1 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.TEKIYO_ED_YMD, toStingObj(tekiyoEdYmd))` // Set application end date on response [-> constant: TEKIYO_ED_YMD = "tekiyo_ed_ymd"] |
| 2 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.PRESENT_YMD, toStingObj(presentYmd))` // Set presentation date [-> constant: PRESENT_YMD = "present_ymd"] |
| 3 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.PRESENT_YMD_HMS, toStingObj(presentYmdHms))` // Set presentation date/time [-> constant: PRESENT_YMD_HMS = "present_ymd_hms"] |
| 4 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.PRESENT_RIYU, toStingObj(presentRiyu))` // Set presentation reason [-> constant: PRESENT_RIYU = "present_riyu"] |

##### Block 2.5.4 — ERROR FLAG SETTING (L113–L126) `[resultCode check]`

> Set the error flag based on the API result code. Modified in #82591 to only accept `"000"` as success (previously also accepted `"500"`).

###### Block 2.5.4.1 — SUCCESS CHECK `[resultCode == "000"]`

| # | Type | Code |
|---|------|------|
| 1 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.ERR_FLG, "1")` // Set error flag = "1" (error) [-> constant: ERR_FLG = "err_flg"] — Branch: result is NOT "000" |
| 2 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.ERR_FLG, "0")` // Set error flag = "0" (success) [-> constant: ERR_FLG = "err_flg"] — Branch: result IS "000" |

**#82591 Modification note:** The original code (commented out) accepted both `"000"` and `"500"` as success result codes. The modified version only accepts `"000"`, ensuring `"500"` (internal server error) now sets `ERR_FLG = "1"` to trigger miner alarm output (マイナーアラーム出力).

### Block 3 — CATCH BLOCK (L128–L131) `[Exception e]`

> Handle any unexpected exceptions during the API call. Sets the STATUS field to an external interface error code.

| # | Type | Code |
|---|------|------|
| 1 | SET | `inCBSMsg.set(EKKA0050004CBSMsg.STATUS, StatusCodes.EXTERNAL_IF_ERR1)` // Set status to external interface error [-> constant: EXTERNAL_IF_ERR1] — comment: Exception caught during API processing |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `func_code` | Field | Function code — identifies the type of function being executed (e.g., "1" for default premium club point registration) |
| `sysid` | Field | System ID — identifies the subscribing customer system/account |
| `tekiyo_st_ymd` | Field | Application start date (YYYYMMDD format) — the date from which the premium club point registration becomes effective |
| `present_kbn` | Field | Presentation kind — classifies the type of point presentation (e.g., regular, bonus, promotional) |
| `present_pt_su` | Field | Presentation point count — the number of premium club points to be registered |
| `sns_sbt_cd` | Field | SNS subtype code — classifies the SNS service subtype associated with this registration |
| `sisk_sins_eda_no` | Field | Measure application branch number — internal tracking number for the promotional measure application |
| `tekiyo_ed_ymd` | Field | Application end date (YYYYMMDD format) — the date until which the premium club point registration remains valid (returned from API) |
| `present_ymd` | Field | Presentation date (YYYYMMDD) — the date of point presentation (returned from API) |
| `present_ymd_hms` | Field | Presentation date/time (YYYYMMDDHHmmss) — the precise timestamp of point presentation (returned from API) |
| `present_riyu` | Field | Presentation reason — the business reason for the point presentation (returned from API) |
| `err_flg` | Field | Error flag — "0" indicates successful API processing, "1" indicates an error occurred |
| `resultCode` | Field | API result code — "000" means success; any other value indicates failure (post-#82591, "500" is no longer considered success) |
| `EKKA0050004CBSMSG1LIST` | Field | Premium club point registration business error detail list — array of error items, each containing an error code and error message |
| `STATUS` | Field | Processing status — set to `EXTERNAL_IF_ERR1` when an exception occurs during the API call |
| PREMIUM CLUB POINT | Business term | A loyalty reward point system for K-Opticom premium subscribers |
| TemplateMainHandler | Interface | Framework interface indicating this class is invoked as a callback handler by the business process execution framework |
| JKKcommonApiKKA0050004 | Class | External API standard component — encapsulates the API call for premium club point registration, replacing hand-coded external interface logic |
| ApiClientConst | Class | Constant definition for API client layer — defines standard keys for IF headers, body, and response fields |
| EXTERNAL_IF_ERR1 | Constant | Status code indicating an external interface (API) error — set when any exception occurs during `callApiKKA0050004` |
| KKSV1021 | Screen ID | Premium club point registration operation screen — the primary user-facing screen for this business function |
| KKSV102101SC | SC Code | Service component for premium club point data acquisition — provides input data (func_code, sysid, dates, SNS subtype) to the mapper |