# Business Logic — JKKAdchgKakuteiKikiDslCC.createKokanCancelKikiList() [96 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKAdchgKakuteiKikiDslCC` |
| Layer | CC/Common Component |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKAdchgKakuteiKikiDslCC.createKokanCancelKikiList()

This method builds a filtered list of equipment intended for **exchange cancellation processing** during a customer's relocation (住所変更, address change). In K-Opticom's telecom service management system, when a customer moves to a new address, previously subscribed equipment (network, telephone, or TV devices) may need to be cancelled if no replacement service exists at the new location. The method receives a list of location change detail records, iterates through each one, and determines which devices qualify for exchange cancellation based on their current status and the availability of replacement services. It implements a **query-and-filter** pattern: for each location change record, it queries the device contract agreement in detail (EKK0341B032) to check whether the equipment is in "exchange-in-progress" status (status code "110"), then applies conditional logic based on service type (network/telephone vs. TV) and whether replacement services exist for that category. Its role in the larger system is to supply the filtered list to the caller, which then executes the actual exchange cancellation transactions (via `executeKokanCancelKiki`) and performs delivery cancellation processing beforehand.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["createKokanCancelKikiList(params)"])
    START --> INIT["Initialize condMap, kk2101_b001_list"]
    INIT --> FETCH["getAdchgDtlList - Fetch location change details"]
    FETCH --> CHECK_EMPTY{List empty?}
    CHECK_EMPTY -->|Yes| RETURN_EMPTY["return (early exit)"]
    CHECK_EMPTY -->|No| LOOP["For each kk2101_b001_map in list"]
    LOOP --> EXTRACT_KT["Extract kktkSvcKeiNo, chbfSkbtNo, chafSkbtNo"]
    EXTRACT_KT --> EXCHANGE_CHECK{chbfSkbtNo != chafSkbtNo?}
    EXCHANGE_CHECK -->|No| NEXT_ITER["Next iteration"]
    EXCHANGE_CHECK -->|Yes| QUERY_CONTRACT["Query EKK0341B032 - Device contract agreement"]
    QUERY_CONTRACT --> GET_RESULT{kk0341_b032_map_af size > 0?}
    GET_RESULT -->|No| NEXT_ITER
    GET_RESULT -->|Yes| EXTRACT_STAT["Extract kktkSvcKeiStat"]
    EXTRACT_STAT --> STAT_CHECK{kktkSvcKeiStat == 110?}
    STAT_CHECK -->|No| NEXT_ITER
    STAT_CHECK -->|Yes| EXTRACT_SVCCD["Extract kktkSvcCd"]
    EXTRACT_SVCCD --> NETTEL_CHECK{isNetTelKktkSvcCd?}
    NETTEL_CHECK -->|No| TV_CHECK{isTvKktkSvcCd?}
    NETTEL_CHECK -->|Yes| NETTEL_EXISTS{!isNetExist && !isTelExist?}
    NETTEL_EXISTS -->|True| SET_NETTEL_SVC["Set svcKeiNo, add to kokanCancelKktkList"]
    NETTEL_EXISTS -->|False| NEXT_ITER
    TV_CHECK -->|No| NEXT_ITER
    TV_CHECK -->|Yes| TV_EXISTS{!isTvExist?}
    TV_EXISTS -->|True| SET_TV_SVC["Set svcKeiNo, add to kokanCancelKktkList"]
    TV_EXISTS -->|False| NEXT_ITER
    SET_NETTEL_SVC --> NEXT_ITER
    SET_TV_SVC --> NEXT_ITER
    NEXT_ITER --> LOOP
    LOOP --> END(["end"])
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `handle` | `SessionHandle` | Database session handle for executing service component queries and mapper operations |
| 2 | `param` | `IRequestParameterReadWrite` | Request parameter object used for passing data to/from mappers and service components |
| 3 | `fixedText` | `String` | Fixed text template string used by mapper methods for SQL parameter binding |
| 4 | `adchgNo` | `String` | Address change (location change) number — the unique identifier for the relocation transaction being processed |
| 5 | `isNetExist` | `boolean` | Flag indicating whether a replacement **network** service exists at the new address — when `true`, the network device does NOT need exchange cancellation |
| 6 | `isTelExist` | `boolean` | Flag indicating whether a replacement **telephone** service exists at the new address — when `true`, the telephone device does NOT need exchange cancellation |
| 7 | `isTvExist` | `boolean` | Flag indicating whether a replacement **TV** service exists at the new address — when `true`, the TV device does NOT need exchange cancellation |
| 8 | `svcKeiNoNet` | `String` | Service contract number for **network** return registration — the contract number to associate with the cancelled network device for return/reinstatement processing |
| 9 | `svcKeiNoTel` | `String` | Service contract number for **telephone** return registration — the contract number to associate with the cancelled telephone device |
| 10 | `svcKeiNoTv` | `String` | Service contract number for **TV** return registration — the contract number to associate with the cancelled TV device |
| 11 | `kokanCancelKktkList` | `ArrayList<HashMap<String, Object>>` | Output parameter — the list that is populated with device records qualifying for exchange cancellation. This list is passed in already instantiated by the caller and filled by this method |

**External state / instance fields read:**
- `mapper` — mapper instance used to interact with database mappers (setEKK0341B032, getEKK0341B032, scResultCheck)
- `scCall` — service component request invoker for executing remote SC calls

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JKKAdchgKakuteiKikiDslCC.getAdchgDtlList` | - | EKK2101_B001 (Location change detail) | Fetches location change detail records filtered by address change number and target service contract number |
| R | `JKKAdchgMapperCC.setEKK0341B032` | EKK0341B032 | EKK0341 (Device contract agreement in detail) | Sets query parameters (kktkSvcKeiNo, default reservation apply date) to build the request map for the SC call |
| R | `scCall.run` | EKK0341B032 | EKK0341 (Device contract agreement in detail) | Invokes the EKK0341B032 SC to retrieve device contract agreement records for the given service contract number and default reservation apply date |
| R | `JKKAdchgMapperCC.getEKK0341B032` | EKK0341B032 | EKK0341 (Device contract agreement in detail) | Retrieves the query result from the SC call response map as a list of HashMaps |
| - | `JKKAdchgMapperCC.scResultCheck` | EKK0341B032 | - | Checks the SC execution result for errors; throws if the call failed |
| - | `JKKAdchgKakuteiKikiDslCC.isNetTelKktkSvcCd` | - | - | Checks whether a device service code corresponds to network or telephone service type |
| - | `JKKAdchgKakuteiKikiDslCC.isTvKktkSvcCd` | - | - | Checks whether a device service code corresponds to TV service type |

## 5. Dependency Trace

This method is called by another method within the same class `JKKAdchgKakuteiKikiDslCC`, which is the main relocation processing flow.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Method:JKKAdchgKakuteiKikiDslCC (line ~306) | `dslKaisenKiki()` (same class) -> `createKokanCancelKikiList` | `getAdchgDtlList [R] EKK2101_B001`, `run [R] EKK0341` |

The caller method first performs line cancellation processing (`dslKaisenKiki`), then calls `createKokanCancelKikiList` to build the exchange cancellation list, then executes delivery cancellation (`haisoCancel`) on the result, and finally executes the actual exchange cancellation transactions (`executeKokanCancelKiki`) for each item in the list.

Terminal operations reached from this method:

| Terminal | Type | Entity / SC |
|----------|------|-------------|
| `getAdchgDtlList` | R | EKK2101_B001 (Location change detail) |
| `setEKK0341B032` | R | EKK0341 (Device contract agreement in detail) |
| `scCall.run` | R | EKK0341 (Device contract agreement in detail) |
| `getEKK0341B032` | R | EKK0341 (Device contract agreement in detail) |
| `scResultCheck` | - | SC result check |
| `isNetTelKktkSvcCd` | - | Service code classification check |
| `isTvKktkSvcCd` | - | Service code classification check |

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] `(Initialize local variables)` (L493-L496)

This block declares local variables for the method: a condition map, request map, response map, and the list to hold location change detail records.

| # | Type | Code |
|---|------|------|
| 1 | SET | `HashMap<String, String> condMap = new HashMap<String, String>();` |
| 2 | SET | `HashMap<String, Object> reqMap;` |
| 3 | SET | `Map<?, ?> resMap;` |

**Block 2** — [EXEC / CALL] `(Fetch location change details)` (L501-L502)

Calls `getAdchgDtlList` to retrieve all location change detail records associated with the given address change number, filtered by the device provision service contract number constant `CD01241_KKTK_SVC_KEI_NO`. The Japanese comment translates to "Get device exchange from location change details" and the comment references `EKK2101B001` (Location change detail list screen).

| # | Type | Code |
|---|------|------|
| 1 | CALL | `getAdchgDtlList(param, fixedText, handle, adchgNo, JKKAdchgConstCC.CD01241_KKTK_SVC_KEI_NO)` |

**Block 3** — [IF] `(Empty list check — early exit)` (L503-L506)

If the fetched location change detail list is null or empty, the method returns immediately. The Japanese comment says "No corresponding data — return" (該当データなしの場合リターン).

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `if (kk2101_b001_list == null || kk2101_b001_list.isEmpty())` |
| 2 | RETURN | `return;` |

**Block 4** — [FOR] `(Iterate over location change detail records)` (L508)

Loops through each location change detail record map to process each device line. The loop variable `kk2101_b001_map` represents a single device within the relocation transaction.

| # | Type | Code |
|---|------|------|
| 1 | SET | `for (HashMap<String, Object> kk2101_b001_map : kk2101_b001_list)` |

**Block 5** — [SET] `(Extract service contract number and exchange codes)` (L511-L514)

Extracts the device provision service contract number and the exchange-before/after service book numbers (service book number before and after exchange). The Japanese comment for `chbfSkbtNo` translates to "service book number before exchange" and `chafSkbtNo` to "service book number after exchange".

| # | Type | Code |
|---|------|------|
| 1 | SET | `String kktkSvcKeiNo = (String) kk2101_b001_map.get(EKK2101B001CBSMsg1List.CHG_TG_KEI_NO)` // Device provision service contract number |
| 2 | SET | `String chbfSkbtNo = (String) kk2101_b001_map.get(EKK2101B001CBSMsg1List.CHBF_SKBT_NO)` // Service book number before exchange |
| 3 | SET | `String chafSkbtNo = (String) kk2101_b001_map.get(EKK2101B001CBSMsg1List.CHAF_SKBT_NO)` // Service book number after exchange |

**Block 6** — [IF] `(Exchange record check — service book numbers differ)` (L515-L518)

Checks if both the exchange-before and exchange-after service book numbers are non-empty AND differ from each other. This condition identifies records where an actual equipment exchange is planned (not just a cancellation). The Japanese comment says "In case of equipment exchange" (機器交換の場合). This is a diamond condition (two sub-conditions connected by AND).

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `!StringUtils.isEmpty(chbfSkbtNo)` |
| 2 | EXEC | `!StringUtils.isEmpty(chafSkbtNo)` |
| 3 | EXEC | `!chbfSkbtNo.equals(chafSkbtNo)` |

**Block 7** — [IF body: Query device contract agreement] `(Build SC request and execute query)` (L520-L532)

This block executes the EKK0341B032 SC call to query the device contract agreement in detail. It clears the condition map, populates it with the service contract number and the default reservation apply date `DEFAULT_RSV_APLY_YMD = "20991231"` [-> DEFAULT_RSV_APLY_YMD="20991231" (JKKAdchgConstCC.java:1847)], calls the mapper to set the request, invokes the SC via `scCall.run`, and retrieves the result. The Japanese comment refers to "Device provision service contract agreement in detail (including pre-registration)" (機器提供サービス契約照会(予約手続含む)).

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `condMap.clear()` |
| 2 | SET | `condMap.put(JKKAdchgMapperCC.COND_KEY_KKTK_SVC_KEI_NO, kktkSvcKeiNo)` |
| 3 | SET | `condMap.put(JKKAdchgMapperCC.COND_KEY_OPEDATE, JKKAdchgConstCC.DEFAULT_RSV_APLY_YMD)` [-> DEFAULT_RSV_APLY_YMD="20991231" (JKKAdchgConstCC.java:1847)] |
| 4 | SET | `reqMap = mapper.setEKK0341B032(param, fixedText, condMap)` |
| 5 | SET | `resMap = scCall.run(reqMap, handle)` |
| 6 | SET | `kk0341_b032_map_af = mapper.getEKK0341B032(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |

**Block 8** — [SET] `(Extract result and prepare device record)` (L534-L539)

Creates a new HashMap for the device record. If the SC query returned results, takes the first entry; otherwise continues to the next iteration (skipping this device).

| # | Type | Code |
|---|------|------|
| 1 | SET | `kk0341_a010_map = new HashMap<String, Object>()` |
| 2 | SET | `if (kk0341_b032_map_af.size() > 0) { kk0341_a010_map = kk0341_b032_map_af.get(0); }` |
| 3 | EXEC | `else { continue; }` |

**Block 9** — [SET] `(Extract device provision service status)` (L543)

Gets the device provision service status code from the device contract record. The Japanese comment says "Device provision service status" (機器提供サービスステータス).

| # | Type | Code |
|---|------|------|
| 1 | SET | `String kktkSvcKeiStat = (String) kk0341_a010_map.get(EKK0341B032CBSMsg1List.KKTK_SVC_KEI_STAT)` |

**Block 10** — [IF] `(Equipment in exchange check — status == "110")` (L545)

Checks whether the device status is "110", which represents "equipment in exchange" (交換中機器). Only devices in this status qualify for exchange cancellation processing.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `"110".equals(kktkSvcKeiStat)` |

**Block 11** — [IF body: Extract service code] `(Get device service code)` (L548)

Extracts the device provision service code to determine the type of equipment (network/telephone vs. TV). The Japanese comment says "Get device provision service code" (機器提供サービスコードの取得).

| # | Type | Code |
|---|------|------|
| 1 | SET | `String kktkSvcCd = (String) kk0341_a010_map.get(EKK0341A010CBSMsg1List.KKTK_SVC_CD)` |

**Block 12** — [IF] `(Network/telephone device check)` (L551)

Checks if the device service code matches network or telephone service types. The Japanese comment says "For devices associated with network/telephone" (ネット・電話につながる機器の場合). The method `isNetTelKktkSvcCd` returns true if the service code corresponds to FTTH (fiber-to-the-home) internet or telephone services.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `isNetTelKktkSvcCd(kktkSvcCd)` |

**Block 13** — [IF] `(Both network and telephone services unavailable)` (L554)

Checks whether neither a replacement network service NOR a replacement telephone service exists at the new address. The Japanese comment says "If both network and telephone are unavailable, execute exchange cancellation" (ネット・電話のどちらもなかったら交換取消を実行). When true, the method selects the appropriate return registration service contract number (network first, then telephone fallback) and adds the device record to the cancellation list.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `!isNetExist && !isTelExist` |

**Block 13.1** — [IF-ELSE] `(Set return registration service contract number)` (L556-L561)

If a replacement network service contract number is available, it is set on the device record. Otherwise, if a replacement telephone service contract number is available, it is used instead. The Japanese comment says "Set service contract number for return registration" (返品登録用のサービス契約番号を設定).

| # | Type | Code |
|---|------|------|
| 1 | IF | `!StringUtils.isEmpty(svcKeiNoNet)` |
| 2 | SET | `kk0341_a010_map.put("svcKeiNo", svcKeiNoNet)` |
| 3 | ELSE-IF | `else if (!StringUtils.isEmpty(svcKeiNoTel))` |
| 4 | SET | `kk0341_a010_map.put("svcKeiNo", svcKeiNoTel)` |

**Block 13.2** — [SET] `(Add to cancellation list)` (L563-L564)

The device record is added to the output `kokanCancelKktkList`.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `kokanCancelKktkList.add(kk0341_a010_map)` |

**Block 14** — [ELSE-IF] `(TV device check)` (L568)

Checks if the device service code matches TV service type. The Japanese comment says "For devices associated with TV" (テレビにつながる機器の場合). The method `isTvKktkSvcCd` returns true if the service code corresponds to TV services.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `isTvKktkSvcCd(kktkSvcCd)` |

**Block 15** — [IF] `(TV service unavailable)` (L571)

Checks whether a replacement TV service does NOT exist at the new address. The Japanese comment says "If TV is unavailable, execute exchange cancellation" (テレビがなかったら交換取消を実行). The method sets the TV return registration service contract number and adds the device to the cancellation list.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `!isTvExist` |

**Block 15.1** — [SET] `(Set TV service contract number and add to list)` (L573-L575)

Sets the TV service contract number for return registration and adds the device record to the cancellation list.

| # | Type | Code |
|---|------|------|
| 1 | SET | `kk0341_a010_map.put("svcKeiNo", svcKeiNoTv)` |
| 2 | EXEC | `kokanCancelKktkList.add(kk0341_a010_map)` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `adchgNo` | Field | Address change number — the unique identifier for a customer relocation transaction |
| `adchgDtlSbtCd` | Field | Address change detail service type code — classifies the type of address change operation |
| `chbfSkbtNo` | Field | Service book number before exchange — the service book identifier before an equipment exchange |
| `chafSkbtNo` | Field | Service book number after exchange — the service book identifier after an equipment exchange |
| `chbfSkbtNo != chafSkbtNo` | Condition | Exchange indicator — when these two service book numbers differ, it indicates an actual equipment exchange is planned |
| `chkTgKeiNo` / `CHG_TG_KEI_NO` | Field | Change target service contract number — the service contract line item being changed |
| `cd01241_kktk_svc_kei_no` | Constant | Location change detail filter — a constant used to filter location change details for device provision service contracts |
| `dslKaisenKiki` | Method | Line cancellation processing — processes cancellation of telecommunication lines during relocation |
| `EKK0341` | Entity | Device contract agreement in detail table — stores detailed records of device (equipment) service contract agreements, including status codes |
| `EKK0341B032` | SC Code | Device contract agreement in detail inquiry SC — service component for querying device contract details |
| `EKK2101` | Entity | Location change detail table — stores records of customer relocation / address change operations |
| `EKK2101B001` | SC Code | Location change detail list inquiry SC — service component for querying location change detail records |
| `isNetExist` | Parameter | Replacement network service exists flag — true if a new network service is provisioned at the relocation destination |
| `isTelExist` | Parameter | Replacement telephone service exists flag — true if a new telephone service is provisioned at the relocation destination |
| `isTvExist` | Parameter | Replacement TV service exists flag — true if a new TV service is provisioned at the relocation destination |
| `kk0341_a010_map` | Variable | Device contract record map — holds the queried device contract agreement record data for processing |
| `kk0341_b032_map_af` | Variable | Post-query result list — the list of device contract records returned by the EKK0341B032 SC query |
| `kk2101_b001_list` | Variable | Location change detail list — list of device records associated with the address change transaction |
| `kk2101_b001_map` | Variable | Individual location change detail record map — one device entry within the location change detail list |
| `kktkSvcCd` | Field | Device provision service code — classifies the type of device service (FTTH internet, telephone, TV, etc.) |
| `kktkSvcKeiNo` | Field | Device provision service contract number — the unique identifier for a device service contract line item |
| `kktkSvcKeiStat` | Field | Device provision service status code — status of the device service contract (e.g., "110" = in exchange) |
| `kokanCancelKktkList` | Parameter | Exchange cancellation device list — output list of devices that qualify for exchange cancellation processing |
| `DEFAULT_RSV_APLY_YMD` | Constant | "20991231" — default reservation application date used as a query condition to retrieve all active/pending reservations |
| `haisoCancel` | Method | Delivery cancellation processing — cancels delivery of equipment during the relocation flow |
| `executeKokanCancelKiki` | Method | Execute exchange cancellation transaction — processes the actual cancellation of an equipment exchange for a given device record |
| `isNetTelKktkSvcCd` | Method | Network/telephone service code check — returns true if the service code corresponds to network or telephone (FTTH or telephone line) services |
| `isTvKktkSvcCd` | Method | TV service code check — returns true if the service code corresponds to TV (cable/BS/CS) services |
| `svcKeiNo` | Field | Service contract number — internal identifier for a service contract line item, used for return registration |
| `svcKeiNoNet` | Parameter | Network service contract number for return registration — used to link a cancelled network device to a return record |
| `svcKeiNoTel` | Parameter | Telephone service contract number for return registration — used to link a cancelled telephone device to a return record |
| `svcKeiNoTv` | Parameter | TV service contract number for return registration — used to link a cancelled TV device to a return record |
| Address Change (住所変更) | Business term | Customer relocation process — when a customer moves to a new address, their subscribed services and equipment must be migrated, cancelled, or exchanged accordingly |
| Device Provision (機器提供) | Business term | Equipment service where K-Opticom provides hardware (modems, routers, set-top boxes) to customers as part of their service subscription |
| Equipment Exchange (機器交換) | Business term | Process of replacing customer equipment with new hardware, typically during service upgrades or hardware refresh cycles |
| Exchange Cancellation (交換取消) | Business term | Reversal of a planned equipment exchange — when a device no longer needs to be exchanged (e.g., no replacement service at the new address) |
| FTTH | Business term | Fiber To The Home — fiber-optic broadband internet service provided by K-Opticom |
| SC (Service Component) | Technical term | A reusable backend service unit that encapsulates business logic and database access |
| Service Book Number (サービスブック番号) | Field | Internal identifier for a service book record that tracks service contract changes |