# Business Logic — JKKKyoseiDslRunMapperCC.mappingEKK0401C170InMsg() [60 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKKyoseiDslRunMapperCC` |
| Layer | CC / Common Component — message mapping and data population layer for CBS (Contract Batch Service) request construction |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKKyoseiDslRunMapperCC.mappingEKK0401C170InMsg()

This method populates a **CBS request message template** for the forced service contract termination process identified by SC Code **EKK0401C170**. In the K-Opticom customer base system, service contracts may need to be forcibly terminated (強制作約解約 — *kyousei kaiyaku yagou*) when a customer's account requires intervention due to billing anomalies, compliance issues, or administrative action. This method builds the inbound CAANMsg payload that will be transmitted to the backend CBS (Contract Batch Service) layer to execute that forced termination.

It follows the **builder pattern**: starting with a clean template (all fields null-mapped), it progressively sets each required CBS field — template ID, function code, contract numbers, end dates, termination reason codes, migration classification, and penalty flags. The method retrieves the option service contract consent details (from a prior SC step EKK0401A010) via `resultHash` to pull the contract numbers, and uses the non-taxable judgment component result (`jdgHiChrgMapSvcKei`) to conditionally determine the service charge end date.

**Design pattern:** Data aggregation and mapping. This method is a **shared utility** called by the orchestration controller (`JKKKyoseiDslRunCC.callEKK0401C170SC()`), which coordinates a sequence of SC steps. It does not contain conditional business logic for routing — it always executes the same forced termination mapping path.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["mappingEKK0401C170InMsg params"]) --> S1["fillCAANMSGNullMapping template, contents"]
    S1 --> S2["template.set TEMPLATEID EKK0401C170"]
    S2 --> S3["template.set FUNC_CODE 1"]
    S3 --> S4["Get eKK0401A010Hash from resultHash TEMPLATE_ID_EKK0401A010"]
    S4 --> S5["template.set OP_SVC_KEI_NO from eKK0401A010Hash"]
    S5 --> S6["template.set SBOP_SVC_KEI_NO from eKK0401A010Hash"]
    S6 --> S7["template.set SVC_ENDYMD from inHash REQYMD"]
    S7 --> S8{jdgHiChrgMapSvcKei == null?}
    S8 -->|true| S9["template.set SVC_CHRG_ENDYMD from inHash SVC_CHRG_ENDYMD"]
    S8 -->|false| S10["template.set SVC_CHRG_ENDYMD from jdgHiChrgMapSvcKei svcChrgEndYmd"]
    S9 --> S11["template.set SVC_DLRE_CD 02 forced termination"]
    S10 --> S11
    S11 --> S12["template.set IDO_DIV 00064 forced migration"]
    S12 --> S13["template.set UPD_DTM_BF svcKeiUpdDtm"]
    S13 --> S14["template.set MSKM_DTL_NO from inHash"]
    S14 --> S15["template.set PNLTY_HASSEI_CD 1"]
    S15 --> END(["Return void"])
```

**Processing summary:**
1. **Null-map the template** — initializes all CBS message fields to null using the EKK0401C170 schema contents.
2. **Set template ID** — assigns `"EKK0401C170"` (the SIF — System Interface — ID for forced termination).
3. **Set function code** — assigns `"1"` indicating check-and-register (チェック＆登録) mode.
4. **Retrieve contract details** — fetches the option service contract consent map from `resultHash` keyed by `EKK0401A010`.
5. **Extract and set contract numbers** — pulls option service contract number and sub-option service contract number from the consent details map.
6. **Set service end date** — retrieves the request date from `inHash` (`REQYMD`).
7. **Conditionally set service charge end date** — if `jdgHiChrgMapSvcKei` is null, falls back to `inHash`; otherwise uses the judgment component's `svcChrgEndYmd`.
8. **Set forced termination reason code** — fixed value `"02"`.
9. **Set forced migration classification** — fixed value `"00064"`.
10. **Set pre-update timestamp** — the service contract line item's last update datetime before this modification.
11. **Set application detail number** — retrieved from `inHash`.
12. **Set penalty flag** — fixed value `"1"` indicating a penalty (違約金) is triggered.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `template` | `CAANMsg` | The CBS request message template to be populated. This is the payload that will be sent to the backend CBS to execute the forced service contract termination (EKK0401C170). It is pre-allocated by the caller and filled in by this method. |
| 2 | `inHash` | `HashMap<String, Object>` | Input parameters map carrying request-level data from the screen/batch entry point. Contains: `REQYMD` (request date / service end date), `SVC_CHRG_ENDYMD` (service charge end date — used as fallback), and `MSKM_DTL_NO` (application detail number). |
| 3 | `resultHash` | `HashMap<String, Object>` | Hash map holding results from prior SC steps in the orchestration flow. Specifically contains the result of step `EKK0401A010` (option service contract consent details), from which `OP_SVC_KEI_NO` and `SBOP_SVC_KEI_NO` are extracted. |
| 4 | `jdgHiChrgMapSvcKei` | `HashMap<String, Object>` | Non-taxable judgment component result for service charge line items (非課金判定部品結果＜サービス＞). If not null, contains `svcChrgEndYmd` (service charge end date determined by the non-taxable judgment logic). If null, the method falls back to `inHash` for the end date. |
| 5 | `svcKeiUpdDtm` | `String` | The pre-update datetime (更新前) of the service contract line item — the timestamp from the database record before this modification. Used for optimistic concurrency control and audit trail. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `JKKKyoseiDslRunMapperCC.fillCAANMSGNullMapping` | - | - | Populates the template with null values for all fields defined in the EKK0401C170CBSMsg schema |
| R | `KK0401CBMMsg.getContents` | EKK0401C170 | - | Returns the contents (field definitions) of the EKK0401C170 CBS message schema for null-mapping |
| R | `KK0401CBMMsg.getContents` | EKK0401A010 | - | Returns the contents (field definitions) of the EKK0401A010 CBS message schema |

**Detailed breakdown:**

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `fillCAANMSGNullMapping` | N/A | N/A | Initializes all fields of the `CAANMsg` template to null using the schema from `EKK0401C170CBSMsg.getContents()`. Ensures a clean slate before field assignment. |
| R | `EKK0401C170CBSMsg.getContents` | EKK0401C170 | N/A | Returns the array of field name/type pairs for the EKK0401C170 service contract termination message schema. Used by `fillCAANMSGNullMapping`. |
| R | `resultHash.get` (TEMPLATE_ID_EKK0401A010) | EKK0401A010 | N/A | Retrieves the option service contract consent details map from the result hash. The consent details contain the contract numbers needed for the termination request. |
| R | `HashMap.get` (OP_SVC_KEI_NO) | EKK0401A010 | N/A | Extracts the option service contract number (オプションサービス契約番号) from the consent details map. |
| R | `HashMap.get` (SBOP_SVC_KEI_NO) | EKK0401A010 | N/A | Extracts the sub-option service contract number (サブオプションサービス契約番号) from the consent details map. |
| R | `HashMap.get` (REQYMD) | N/A | N/A | Retrieves the request date from the input hash — used as the service end date. |
| R | `HashMap.get` (SVC_CHRG_ENDYMD) | N/A | N/A | Retrieves the fallback service charge end date from the input hash (used when `jdgHiChrgMapSvcKei` is null). |
| R | `HashMap.get` (svcChrgEndYmd) | N/A | N/A | Retrieves the service charge end date from the non-taxable judgment component result map. |
| R | `HashMap.get` (MSKM_DTL_NO) | N/A | N/A | Retrieves the application detail number from the input hash. |

**Note:** This method does **not** perform direct database CRUD operations. It is a pure data-mapping method that assembles a `CAANMsg` request object. The actual database CRUD (update of service contract line items) is performed by the CBS backend identified by SC Code `EKK0401C170`.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CBS:JKKKyoseiDslRunCC | `JKKKyoseiDslRunCC.callEKK0401C170SC()` -> `JKKKyoseiDslRunMapperCC.mappingEKK0401C170InMsg()` | `fillCAANMSGNullMapping [-]`, `EKK0401C170 getContents [R]`, `EKK0401A010 getContents [R]`, `resultHash.get [R]` |

**Notes:**
- The direct caller is `JKKKyoseiDslRunCC.callEKK0401C170SC()`, which is an orchestration-level CBS caller method. This method is part of the DSL (Dedicated Service Logic) run engine that sequences multiple SC (Service Component) steps for custom business processing.
- No screen (KKSV) or batch (KKSB) entry point is directly calling this method — it is a shared mapper invoked exclusively by the orchestration controller.

## 6. Per-Branch Detail Blocks

### Block 1 — [SET] Null-map the template (L1198)

> Initialize all fields of the template to null using the EKK0401C170CBSMsg schema contents.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | CALL | `fillCAANMSGNullMapping(template, new EKK0401C170CBSMsg().getContents())` | Sets all template fields to null based on the EKK0401C170 schema — ensures clean slate before mapping |

### Block 2 — [SET] Set template ID (L1201)

> Assigns the SIF (System Interface) ID for the forced termination process.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.TEMPLATEID, JKKKyoseiDslRunCC.TEMPLATE_ID_EKK0401C170)` | `template.set("templateID", "EKK0401C170")` — Service Interface ID for forced termination |

### Block 3 — [SET] Set function code (L1204)

> Sets the operation mode to check-and-register.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.FUNC_CODE, "1")` | `template.set("func_code", "1")` — Function code 1 = Check & Register (チェック＆登録) |

### Block 4 — [SET] Retrieve option service contract consent details (L1207–1208)

> Fetches the result from the prior SC step EKK0401A010 (option service contract consent details) from the result hash.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | SET | `eKK0401A010Hash = (HashMap<String, Object>) resultHash.get(JKKKyoseiDslRunCC.TEMPLATE_ID_EKK0401A010)` | Casts the result hash entry to a HashMap; `TEMPLATE_ID_EKK0401A010 = "EKK0401A010"` |

### Block 5 — [SET] Set option service contract number (L1211)

> Extracts the option service contract number from the consent details map.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.OP_SVC_KEI_NO, eKK0401A010Hash.get(EKK0401A010CBSMsg1List.OP_SVC_KEI_NO))` | Sets the option service contract number (オプションサービス契約番号) on the template |

### Block 6 — [SET] Set sub-option service contract number (L1214)

> Extracts the sub-option service contract number from the consent details map.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.SBOP_SVC_KEI_NO, eKK0401A010Hash.get(EKK0401A010CBSMsg1List.SBOP_SVC_KEI_NO))` | Sets the sub-option service contract number (サブオプションサービス契約番号) on the template |

### Block 7 — [SET] Set service end date (L1217–1218)

> Sets the service end date from the request date provided in the input hash.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.SVC_ENDYMD, inHash.get(JKKKyoseiDslRunCC.REQYMD))` | `REQYMD = "REQYMD"` — Request date, used as the service termination end date (サービス終了年月日) |

### Block 8 — [IF] Conditionally set service charge end date (L1221–1228)

> Determines the service charge end date (サービス課金終了年月日) based on whether the non-taxable judgment component result is available.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | IF | `jdgHiChrgMapSvcKei == null` | Non-taxable judgment component result for service |

**Block 8.1 — [ELSE-IF branch: jdgHiChrgMapSvcKei is null] (L1223–1224)**

> Fallback: retrieve the service charge end date from the input hash.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.SVC_CHRG_ENDYMD, inHash.get(JKKKyoseiDslRunCC.SVC_CHRG_ENDYMD))` | `SVC_CHRG_ENDYMD = "SVC_CHRG_ENDYMD"` — Fallback service charge end date from input parameters |

**Block 8.2 — [ELSE branch: jdgHiChrgMapSvcKei is not null] (L1226–1227)**

> Use the service charge end date determined by the non-taxable judgment component.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.SVC_CHRG_ENDYMD, jdgHiChrgMapSvcKei.get("svcChrgEndYmd"))` | The non-taxable judgment component has already computed the correct service charge end date based on billing eligibility |

### Block 9 — [SET] Set service termination reason code (L1231)

> Fixed value indicating forced termination.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.SVC_DLRE_CD, JKKKyoseiDslRunCC.SVC_DLRE_CD_KYOSEI)` | `SVC_DLRE_CD_KYOSEI = "02"` — Forced termination reason code (サービス解約理由コード：強制作約解約) |

### Block 10 — [SET] Set migration classification (L1234)

> Fixed value indicating forced migration.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.IDO_DIV, JKKKyoseiDslRunCC.IDO_DIV_KYOSEI)` | `IDO_DIV_KYOSEI = "00064"` — Forced migration classification (異動区分：強制作約) |

### Block 11 — [SET] Set pre-update datetime (L1237)

> Records the last known update timestamp from the database record before this modification.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.UPD_DTM_BF, svcKeiUpdDtm)` | Sets the pre-update timestamp for optimistic concurrency control and audit trail |

### Block 12 — [SET] Set application detail number (L1240)

> Retrieves the application detail number from the input hash.

| # | Type | Code | Business Description |
|---|------|------|---------------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.MSKM_DTL_NO, inHash.get(JKKKyoseiDslRunCC.MSKM_DTL_NO))` | Sets the application detail number (申請明細番号) for traceability |

### Block 13 — [SET] Set penalty occurrence code (L1243–1245)

> Fixed value indicating a penalty (違約金) is triggered by this termination.

| # | Type | Code | Code (Resolved) |
|---|------|------|----------------|
| 1 | SET | `template.set(EKK0401C170CBSMsg.PNLTY_HASSEI_CD, "1")` | Fixed value `"1"` — Penalty occurrence code: 1 = Yes (違約金発生コード：有). Added per ticket ST2-2013-0001182. |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| EKK0401C170 | SC Code | Forced Service Contract Termination SC (サービス契約解約スキーマクロ) — service component that processes forced termination of option service contracts |
| EKK0401A010 | SC Code | Option Service Contract Consent Details SC (オプションサービス契約同意書詳細) — prior step that retrieves the consent details containing contract numbers |
| CAANMsg | Technical | Message object used for CBS (Contract Batch Service) request/response communication — a structured message container extending CAANSchemaInfo |
| CBS | Acronym | Contract Batch Service — the backend batch processing layer for service contract operations |
| SIF | Acronym | System Interface — the interface identifier used to select the correct CBS processing flow |
| TEMPLATE_ID_EKK0401C170 | Constant | `"EKK0401C170"` — SIF identifier for the forced service contract termination process |
| TEMPLATE_ID_EKK0401A010 | Constant | `"EKK0401A010"` — SIF identifier for the option service contract consent details process |
| FUNC_CODE | Field | Function code — identifies the operation mode. Value `"1"` = Check & Register (チェック＆登録) |
| OP_SVC_KEI_NO | Field | Option Service Contract Number (オプションサービス契約番号) — the unique identifier for the option service contract line item |
| SBOP_SVC_KEI_NO | Field | Sub-Option Service Contract Number (サブオプションサービス契約番号) — the unique identifier for the sub-option service contract line item |
| SVC_ENDYMD | Field | Service End Date (サービス終了年月日) — the date when the service terminates |
| SVC_CHRG_ENDYMD | Field | Service Charge End Date (サービス課金終了年月日) — the date when billing for the service ends; may differ from the service end date if prorated |
| REQYMD | Constant | `"REQYMD"` — Input hash key for the Request Date (依頼年月日), used as the service end date |
| SVC_DLRE_CD | Field | Service Termination Reason Code (サービス解約理由コード) — codes specifying why the service is being terminated |
| SVC_DLRE_CD_KYOSEI | Constant | `"02"` — Forced Termination (強制作約解約) reason code |
| IDO_DIV | Field | Migration Classification (異動区分) — categorizes the type of migration/transfer event |
| IDO_DIV_KYOSEI | Constant | `"00064"` — Forced Migration (強制作約) classification code |
| UPD_DTM_BF | Field | Update Datetime Before (更新年月日時分秒：更新前) — the last known update timestamp of the record for optimistic concurrency control |
| MSKM_DTL_NO | Field | Application Detail Number (申請明細番号) — internal tracking number for the application detail line |
| PNLTY_HASSEI_CD | Field | Penalty Occurrence Code (違約金発生コード) — indicates whether a penalty (liquidated damages) is triggered. `"1"` = Yes (有), `"0"` = No (無) |
| jdgHiChrgMapSvcKei | Parameter | Non-Taxable Judgment Component Result for Service (非課金判定部品結果＜サービス＞) — map containing the result of the billing eligibility check for the service contract line item |
| svcChrgEndYmd | Field (in jdgHiChrgMapSvcKei) | Service Charge End Date (サービス課金終了年月日) — computed by the non-taxable judgment component based on billing eligibility rules |
| KYOSEI (強制作約) | Japanese term | Forced contract termination — administrative action to terminate a service contract, typically due to billing issues, compliance, or policy enforcement |
| fillCAANMSGNullMapping | Method | Utility method that initializes all fields of a CAANMsg template to null using the provided schema — ensures a clean payload before field assignment |
| ST2-2013-0001182 | Ticket | Development ticket that added the penalty occurrence code (`PNLTY_HASSEI_CD = "1"`) to the EKK0401C170 inbound message |
| KT1-2013-0000691 | Ticket | Development ticket that added the service end date mapping (`SVC_ENDYMD`) from `inHash` using `REQYMD` |