# Business Logic — JKKKyoseiDslRunMapperCC.mappingEKK0341C340InMsg() [75 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKKyoseiDslRunMapperCC` |
| Layer | CC / Common Component (Business logic mapping and data transformation layer) |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKKyoseiDslRunMapperCC.mappingEKK0341C340InMsg()

This method is a **message mapper** for the forced service cancellation service component EKK0341C340. It constructs a `CAANMsg` template by populating all required fields from incoming parameter hashes and pre-computed results. Specifically, it performs the business operation of preparing the input message for an **automatic forced service cancellation** (強制解約) performed by the batch scheduler. The method reads the equipment-provided service contract summary (EKK0341A010) and the equipment-provided service summary (EKK0771A010) from a shared result hash to determine whether penalty fees have been incurred (違約金発生). It sets the service cancellation reason code to "forced" (強制解約, code "02") and the displacement classification to "forced displacement" (強制異動, code "00064"). The method also handles the **penalty determination logic** (added via ANK-1421-00-00 / IP-STB enhancement in 2013/02/08) — checking whether a penalty event exists, but then **unconditionally overwrites** the penalty code to "1" (penalty occurred) later in the flow (per change ticket ST2-2013-0001182). Its role in the larger system is as a **shared DSL mapper component** called exclusively by the `callEKK0341C340SC` method in `JKKKyoseiDslRunCC`, which is invoked during the forced cancellation batch execution flow. This method implements the **builder pattern** — assembling a message object field by field from disparate sources.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["mappingEKK0341C340InMsg"])
    N1["Null Mapping via fillCAANMSGNullMapping"]
    N2["Set TEMPLATEID = EKK0341C340"]
    N3["Set FUNC_CODE = 1"]
    N4["Load eKK0341A010Hash from resultHash"]
    N5["Load eKK0771A010Hash from resultHash"]
    N6["Init pnltyHasseiUm = 0"]
    N7{"eKK0771A010Hash != null?"}
    N8["pnltyHasseiUm = eKK0771A010Hash.PNLTY_HASSEI_UM"]
    N9["Set KKTK_SVC_KEI_NO from eKK0341A010Hash"]
    N10["Set SVC_ENDYMD from inHash.REQYMD"]
    N11["Set SVC_CHRG_ENDYMD from inHash"]
    N12["Set SVC_DLRE_CD = 02 Forced Cancellation"]
    N13{"pnltyHasseiUm == 1?"}
    N14["Set PNLTY_HASSEI_CD = 1 Penalty Occurs"]
    N15["Set PNLTY_HASSEI_CD = 0 No Penalty"]
    N16["Set IDO_DIV = 00064 Forced Displacement"]
    N17["Set UPD_DTM_BF from eKK0341A010Hash"]
    N18["Set MSKM_DTL_NO from inHash"]
    N19["Overwrite PNLTY_HASSEI_CD = 1"]
    N20["Set TAKNKIKI_IDO_CD from eKK0341A010Hash"]
    N21(["Return"])

    START --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
    N7 -->|yes| N8
    N7 -->|no| N9
    N8 --> N9
    N9 --> N10 --> N11 --> N12 --> N13
    N13 -->|yes| N14 --> N16
    N13 -->|no| N15 --> N16
    N16 --> N17 --> N18 --> N19 --> N20 --> N21
```

**Constant Resolution:**

| Constant Key | Resolved Value | Business Meaning |
|-------------|---------------|-----------------|
| `CD_DIV_UM_NASHI` | `"0"` | No penalty event (違約金なし) |
| `CD_DIV_UM_ARI` | `"1"` | Penalty event occurred (違約金あり) |
| `CD01375_PNLTY_HASSEI` | `"1"` | Penalty occurred code (違約金発生コード) |
| `CD01375_PNLTY_NASHI` | `"0"` | No penalty code (違約金なしコード) |
| `SVC_DLRE_CD_KYOSEI` | `"02"` | Forced cancellation reason (強制解約) |
| `IDO_DIV_KYOSEI` | `"00064"` | Forced displacement classification (強制異動) |
| `TEMPLATE_ID_EKK0341C340` | `"EKK0341C340"` | Service contract cancellation template ID |
| `TEMPLATE_ID_EKK0341A010` | `"EKK0341A010"` | Equipment-provided service contract summary template |
| `TEMPLATE_ID_EKK0771A010` | `"EKK0771A010"` | Equipment-provided service summary template |

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `template` | `CAANMsg` | The SIF message template being built for the EKK0341C340 service component. This is the target message object that all fields are populated into. It represents the request payload for the forced service cancellation SC. |
| 2 | `inHash` | `HashMap<String, Object>` | Input parameter hash carrying request-level data from the batch caller. Contains `REQYMD` (request date in YYYYMMDD format) which becomes the service end date, `SVC_CHRG_ENDYMD` (service charge end date), and `MSKM_DTL_NO` (application detail number / 申請明細番号). |
| 3 | `resultHash` | `HashMap<String, Object>` | Shared result hash containing pre-fetched data from prior SC executions in the same batch transaction. Looked up by template IDs `EKK0341A010` (equipment-provided service contract summary) and `EKK0771A010` (equipment-provided service summary for IP-STB penalty determination). |
| 4 | `svcKeiUpdDtm` | `String` | Service contract update date-time stamp (更新年月日時分秒) representing the timestamp before the update. Originally intended to be set directly as `UPD_DTM_BF`, but per fix OM-2014-0001746 (2014/05/08), it is now sourced from the pre-fetched `LAST_UPD_DTM` in `eKK0341A010Hash` instead, to avoid exclusion errors during V-ONU cancellation. |

**External State Read:**

| Source | Field / Constant | Business Meaning |
|--------|-----------------|-----------------|
| `JKKKyoseiDslRunCC` | `TEMPLATE_ID_EKK0341C340` | Template ID constant for EKK0341C340 |
| `JKKKyoseiDslRunCC` | `TEMPLATE_ID_EKK0341A010` | Template ID constant for EKK0341A010 |
| `JKKKyoseiDslRunCC` | `TEMPLATE_ID_EKK0771A010` | Template ID constant for EKK0771A010 |
| `JKKKyoseiDslRunCC` | `REQYMD` | Key constant for request date |
| `JKKKyoseiDslRunCC` | `SVC_CHRG_ENDYMD` | Key constant for service charge end date |
| `JKKKyoseiDslRunCC` | `MSKM_DTL_NO` | Key constant for application detail number |
| `JKKKyoseiDslRunCC` | `SVC_DLRE_CD_KYOSEI` | Forced cancellation reason code = "02" |
| `JKKKyoseiDslRunCC` | `IDO_DIV_KYOSEI` | Forced displacement classification = "00064" |
| `JKKStrConst` | `CD_DIV_UM_NASHI` | No penalty event flag = "0" |
| `JKKStrConst` | `CD_DIV_UM_ARI` | Penalty event flag = "1" |
| `JKKStrConst` | `CD01375_PNLTY_HASSEI` | Penalty occurred code = "1" |
| `JKKStrConst` | `CD01375_PNLTY_NASHI` | No penalty code = "0" |

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `JKKKyoseiDslRunMapperCC.fillCAANMSGNullMapping` | - | - | Calls `fillCAANMSGNullMapping` to initialize all template fields to null/empty defaults before populating values. No database interaction — pure in-memory message initialization. |
| R | `KK0371CBMMsg.getContents` | - | - | Called indirectly via `new EKK0341C340CBSMsg().getContents()` to retrieve the list of message field keys for null-mapping. |
| R | `KK0381CBMMsg.getContents` | - | - | Same pattern — `getContents()` provides the field key list for the EKK0341C340 message structure. |
| R | `KK0391CBMMsg.getContents` | - | - | Same pattern — `getContents()` provides the field key list. |
| R | `KK0401CBMMsg.getContents` | - | - | Same pattern — `getContents()` provides the field key list. |
| R | `KK0411CBMMsg.getContents` | - | - | Same pattern — `getContents()` provides the field key list. |

**Analysis:** This method is a **pure message mapper** — it performs no database CRUD operations itself. All data is sourced from the `inHash`, `resultHash`, and the `template` object. The `fillCAANMSGNullMapping` call initializes all fields of the `EKK0341C340CBSMsg` message structure to null defaults, and `getContents()` methods on CBSMsg classes return the field key definitions (not database queries). The actual database reads/write are performed by the EKK0341C340 service component (SC) that this message is destined to call via the `callEKK0341C340SC` wrapper method.

## 5. Dependency Trace

### Pre-computed evidence from code analysis graph:

No screen/batch entry points found within 8 hops. Direct callers found: 1 method.
Terminal operations from this method: `fillCAANMSGNullMapping` [-], `getContents` [R], `getContents` [R], `getContents` [R], `getcents` [R], `getContents` [R]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CBS:JKKKyoseiDslRunCC.callEKK0341C340SC | `callEKK0341C340SC(param, handle, requestParam, resultHash)` -> `mappingEKK0341C340InMsg(template, inHash, resultHash, svcKeiUpdDtm)` | `fillCAANMSGNullMapping [-]` |

**Call chain context:** The method is invoked by `JKKKyoseiDslRunCC.callEKK0341C340SC()` (private method at line 5026), which is called during forced cancellation batch processing (e.g., at line 2839 and 3259). The batch runner in `JKKKyoseiDslRunCC` fetches the equipment-provided service contract summary (EKK0341A010) and the IP-STB service summary (EKK0771A010) into `resultHash` **before** calling `callEKK0341C340SC`, making them available for this mapper to consume.

## 6. Per-Branch Detail Blocks

### Block 1 — [Initialization] Null Mapping (L1334)

> Initializes all fields of the template to null/empty defaults based on the EKK0341C340CBSMsg field definitions. This ensures no stale data from previous operations contaminates the new message.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `fillCAANMSGNullMapping(template, new EKK0341C340CBSMsg().getContents())` // Set null defaults for all fields in the template |

### Block 2 — [Initialization] Template ID and Function Code (L1337–L1342)

> Sets the SIF message template ID and function code on the template. The template ID identifies the service component, and the function code "1" indicates the primary (registration) function.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(TEMPLATEID, JKKKyoseiDslRunCC.TEMPLATE_ID_EKK0341C340)` // [-> "EKK0341C340"] Template ID (SIFのID) |
| 2 | SET | `template.set(FUNC_CODE, "1")` // Function code -- Check & Registration (機能コード - チェック＆登録) |

### Block 3 — [Data Loading] Fetch Pre-computed Hash Results (L1344–L1352)

> Retrieves the pre-fetched results of the equipment-provided service contract summary (EKK0341A010) and the equipment-provided service summary (EKK0771A010) from the shared resultHash. EKK0341A010 contains core service contract data (service contract number, last update timestamp, etc.). EKK0771A010 was added for ANK-1421-00-00 (IP-STB) to carry penalty occurrence information.

| # | Type | Code |
|---|------|------|
| 1 | SET | `eKK0341A010Hash = null` // Initialize equipment service contract summary hash (機器提供サービス契約照会の結果取得) |
| 2 | SET | `eKK0341A010Hash = (HashMap<String, Object>) resultHash.get(JKKKyoseiDslRunCC.TEMPLATE_ID_EKK0341A010)` // [-> "EKK0341A010"] |
| 3 | SET | `eKK0771A010Hash = null` // ANK-1421-00-00 2013/02/08 ADD — equipment service summary (機器提供サービス照会結果) |
| 4 | SET | `eKK0771A010Hash = (HashMap<String, Object>) resultHash.get(JKKKyoseiDslRunCC.TEMPLATE_ID_EKK0771A010)` // [-> "EKK0771A010"] |
| 5 | SET | `pnltyHasseiUm = JKKStrConst.CD_DIV_UM_NASHI` // [-> "0"] Default penalty status (違約金発生コードの初期値) |

### Block 4 — [IF] Penalty Status Check (ANK-1421-00-00 IP-STB) (L1352–L1358)

> Conditionally reads the penalty occurrence status from the EKK0771A010 result hash. If the hash is null (no prior EKK0771A010 execution), the default "0" (no penalty) is retained. If non-null, the `PNLTY_HASSEI_UM` field from the hash overrides the default.

**Block 4.M** — [IF] `eKK0771A010Hash != null` (L1354)

| # | Type | Code |
|---|------|------|
| 1 | SET | `pnltyHasseiUm = (String) eKK0771A010Hash.get(EKK0771A010CBSMsg1List.PNLTY_HASSEI_UM)` // Read penalty event flag from IP-STB summary result |

### Block 5 — [Field Mapping] Equipment Service Contract Number (L1361)

> Copies the equipment-provided service contract number (KKTK_SVC_KEI_NO) from the pre-fetched EKK0341A010 hash. This is the key contract identifier linking this cancellation to the original service agreement.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(KKTK_SVC_KEI_NO, eKK0341A010Hash.get(EKK0341A010CBSMsg1List.KKTK_SVC_KEI_NO))` // Equipment-provided service contract number (機器提供サービス契約番号) |

### Block 6 — [Field Mapping] Service End Date (KT1-2013-0000691) (L1364–L1365)

> Sets the service end date (SVC_ENDYMD) from the input hash's REQYMD field. Per change ticket KT1-2013-0000691 (2013/07/06), the service end date is sourced from the request date provided by the caller.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(SVC_ENDYMD, inHash.get(JKKKyoseiDslRunCC.REQYMD))` // Service end date (サービス終了年月日) |

### Block 7 — [Field Mapping] Service Charge End Date (L1368)

> Sets the service charge end date (SVC_CHRG_ENDYMD) from the input hash. This determines until when service charges apply after the forced cancellation.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(SVC_CHRG_ENDYMD, inHash.get(JKKKyoseiDslRunCC.SVC_CHRG_ENDYMD))` // Service charge end date (サービス課金終了年月日) |

### Block 8 — [Field Mapping] Service Cancellation Reason — Fixed (L1371)

> Sets the service cancellation reason code to "02" (強制解約 / forced cancellation). This is a fixed constant indicating this is an administrative/system-initiated cancellation, not a customer-requested one.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(SVC_DLRE_CD, JKKKyoseiDslRunCC.SVC_DLRE_CD_KYOSEI)` // [-> "02"] Service cancellation reason code — forced cancellation (サービス解約理由コード(強制解約)固定) |

### Block 9 — [IF/ELSE] Penalty Occurrence Code (ANK-1421-00-00 IP-STB) (L1359–L1384)

> Sets the penalty occurrence code based on the previously read penalty status. If `pnltyHasseiUm` equals "1" (CD_DIV_UM_ARI), the penalty code is set to "1" (CD01375_PNLTY_HASSEI — penalty occurred). Otherwise, it is set to "0" (CD01375_PNLTY_NASHI — no penalty). This logic implements the IP-STB penalty determination enhancement (ANK-1421-00-00).

**Block 9.M** — [IF] `pnltyHasseiUm == CD_DIV_UM_ARI` ["1"] (L1359)

> Penalty occurred branch — sets penalty code to "1".

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(PNLTY_HASSEI_CD, JKKStrConst.CD01375_PNLTY_HASSEI)` // [-> "1"] Penalty occurrence code — penalty occurred (違約金発生コード) |

**Block 9.M** — [ELSE] `pnltyHasseiUm != CD_DIV_UM_ARI` (L1362)

> No-penalty branch — sets penalty code to "0".

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(PNLTY_HASSEI_CD, JKKStrConst.CD01375_PNLTY_NASHI)` // [-> "0"] Penalty occurrence code — no penalty (違約金発生コード) |

### Block 10 — [Field Mapping] Displacement Classification — Fixed (L1387)

> Sets the displacement classification code to "00064" (IDO_DIV_KYOSEI — forced displacement). This categorizes the service contract change as a forced administrative action.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(IDO_DIV, JKKKyoseiDslRunCC.IDO_DIV_KYOSEI)` // [-> "00064"] Displacement classification — forced displacement (異動区分(強制異動)固定) |

### Block 11 — [Field Mapping] Update Date-Time Before (OM-2014-0001746) (L1390–L1392)

> Sets the "update date-time before" (UPD_DTM_BF) field. Per fix OM-2014-0001746 (2014/05/08), instead of using the `svcKeiUpdDtm` parameter directly, the method now sources the last update timestamp from the pre-fetched `eKK0341A010Hash.LAST_UPD_DTM` field. This change was made to prevent exclusion errors (排他エラー) during V-ONU cancellation when forced cancellation processing is executed. The original `svcKeiUpdDtm` line is commented out.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(UPD_DTM_BF, (String) eKK0341A010Hash.get(EKK0341A010CBSMsg1List.LAST_UPD_DTM))` // Update date-time before (更新年月日時分秒(更新前)) — sourced from pre-fetched last update timestamp |
| 2 | — | `// template.set(UPD_DTM_BF, svcKeiUpdDtm);` // [COMMENTED OUT] Original approach — replaced to avoid exclusion errors |

### Block 12 — [Field Mapping] Application Detail Number (L1395)

> Sets the application detail number (MSKM_DTL_NO) from the input hash. This identifies the specific line item within the application.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(MSKM_DTL_NO, inHash.get(JKKKyoseiDslRunCC.MSKM_DTL_NO))` // Application detail number (申請明細番号) |

### Block 13 — [Fixed Override] Penalty Occurrence Code (ST2-2013-0001182) (L1398–L1400)

> **Overwrites** the penalty occurrence code (previously set in Block 9 based on the IP-STB penalty determination) to a fixed value of "1" (penalty occurred). Per change ticket ST2-2013-0001182 (2013/03/07), this forces the penalty code to always be "1" regardless of what was set in Block 9. This effectively makes the conditional logic in Block 9 dead code — the penalty code will always end up as "1". This is likely a business rule change where all forced cancellations now carry a penalty.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(PNLTY_HASSEI_CD, "1")` // Penalty occurrence code — fixed to "1" (違約金発生コード(1:有)固定) |

### Block 14 — [Field Mapping] Home Equipment Displacement Code (OM-2013-0002975) (L1403–L1405)

> Sets the home equipment displacement code (TAKNKIKI_IDO_CD) from the pre-fetched EKK0341A010 hash. Added for the home equipment management system integration (ANK-0342-00-00, 2012/08/03) to correlate the forced cancellation with equipment-level displacement tracking.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(TAKNKIKI_IDO_CD, eKK0341A010Hash.get(EKK0341A010CBSMsg1List.TAKNKIKI_IDO_CD))` // Home equipment displacement code (自宅機器異動コード) |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `EKK0341C340` | SC Code | Service Contract Cancellation SC — the service component that processes equipment-provided service contract cancellations |
| `EKK0341A010` | SC Code | Equipment-provided Service Contract Summary SC — returns details of the equipment-provided service contract (contract number, timestamps, equipment displacement codes) |
| `EKK0771A010` | SC Code | Equipment-provided Service Summary SC — returns equipment-provided service details including IP-STB penalty occurrence status |
| `CAANMsg` | Technical | Fujitsu's canonical message object used for SIF (Service Interoperability Framework) communication between SCs |
| `TEMPLATEID` | Field | SIF template ID — identifies which CBS message schema to use for the request |
| `FUNC_CODE` | Field | Function code — "1" indicates the primary/registration function of the SC |
| `KKTK_SVC_KEI_NO` | Field | Equipment-provided service contract number — the primary key identifier for the service contract line item being cancelled |
| `SVC_ENDYMD` | Field | Service end date (サービス終了年月日) — the YYYYMMDD date when the service terminates |
| `SVC_CHRG_ENDYMD` | Field | Service charge end date (サービス課金終了年月日) — the YYYYMMDD date until which billing charges apply |
| `SVC_DLRE_CD` | Field | Service cancellation reason code (サービス解約理由コード) — "02" denotes forced (administrative) cancellation vs. customer-requested |
| `PNLTY_HASSEI_CD` | Field | Penalty occurrence code (違約金発生コード) — "1" means a penalty fee applies, "0" means no penalty |
| `IDO_DIV` | Field | Displacement classification (異動区分) — "00064" denotes forced displacement (強制異動), used for administrative service changes |
| `UPD_DTM_BF` | Field | Update date-time before (更新年月日時分秒(更新前)) — the last update timestamp prior to this cancellation operation, used for optimistic locking |
| `MSKM_DTL_NO` | Field | Application detail number (申請明細番号) — identifies the specific detail line within a batch application |
| `TAKNKIKI_IDO_CD` | Field | Home equipment displacement code (自宅機器異動コード) — links the service cancellation to a physical equipment movement/disposal event |
| `PNLTY_HASSEI_UM` | Field | Penalty occurrence status (違約金発生有無) — flag from IP-STB result indicating whether a penalty fee has been generated for this customer |
| `REQYMD` | Field | Request date (依頼年月日) — the YYYYMMDD date of the batch request, used as the service end date |
| `CD_DIV_UM_NASHI` | Constant | No penalty event flag = "0" (違約金なし) |
| `CD_DIV_UM_ARI` | Constant | Penalty event flag = "1" (違約金あり) |
| `CD01375_PNLTY_HASSEI` | Constant | Penalty occurred code = "1" (違約金発生) |
| `CD01375_PNLTY_NASHI` | Constant | No penalty code = "0" (違約金なし) |
| `SVC_DLRE_CD_KYOSEI` | Constant | Forced cancellation code = "02" (強制解約) |
| `IDO_DIV_KYOSEI` | Constant | Forced displacement code = "00064" (強制異動) |
| 強制解約 | Business term | Forced cancellation — an administrative/system-initiated service contract termination, as opposed to a customer-requested cancellation |
| 強制異動 | Business term | Forced displacement — the classification of a service contract change triggered by an administrative action rather than a customer request |
| 違約金 | Business term | Penalty fee — contractual penalty charged to a customer for early or involuntary service termination |
| IP-STB | Business term | IP Set-Top Box — a digital set-top box delivered via IP network, used in K-Opticom's IPTV service; ANK-1421-00-00 added penalty determination for IP-STB |
| SIF | Acronym | Service Interoperability Framework — Fujitsu's middleware for SC-to-SC communication |
| CBS | Acronym | Customer Billing System — the core billing system component in the eo customer base system |
| SC | Acronym | Service Component — a modular business logic unit in the SIF architecture |