# Business Logic — JKKAdInfChgCC.guideShsAdUpd() [574 LOC]

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

## 1. Role

### JKKAdInfChgCC.guideShsAdUpd()

This method performs **Guide Magazine Delivery Address Change Processing** (ガイド誌送付先住所変更処理). It is invoked as one of several address change sub-processes within a larger unified address update operation (likely a "one-stop address change" screen where the customer updates their residential address and all associated delivery destinations are synchronized). The method iterates over a list of service contracts that receive guide magazines, and for each contract, it: (1) queries the current service contract agreement, option service agreement, and option service TV agreement data from the database; (2) replaces the relevant fields with new address information supplied from the request; (3) assembles progression supplemental text (進捗特記事項) describing what values changed (used for audit/information notifications); (4) executes an option service contract TV info update to validate the address change; (5) updates the application date of the option service contract; and (6) registers a progression record (進捗登録) to record that an emergency address change (緊急通報住所変更) occurred for the associated TV service. The method implements a **routing/dispatch pattern** — it dispatches to multiple service components (SC) in sequence, each handling a specific contract data table. It also implements a **caching pattern** by tracking the last-update datetime per service contract number in a local map, avoiding redundant SC reads for duplicate contracts within the same list.

The method branches by the `updateNaiyo` (更新内容 — update content type) parameter to determine which address fields to populate. If `UPDATE_ALL="0"` or `UPDATE_NM="3"`, it updates name and kana fields. If `updateNaiyo` is neither `UPDATE_TEL="2"` nor `UPDATE_NM="3"`, it also populates address code and individual address fields. If it is neither `UPDATE_AD="1"` nor `UPDATE_NM="3"`, it populates phone fields. This design allows the same method to handle partial updates (address-only, name-only, phone-only) or a full update.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["guideShsAdUpd param, fixedText"])

    START --> INIT["Initialize: condMap, paramMap, mapper, scCall"]

    INIT --> GET_GUIDE_SHS["Extract guide_shs_ad_list from paramMap"]

    GET_GUIDE_SHS --> LOOP_START["For each guide_shs in guide_shs_list"]

    LOOP_START --> EXTRACT_FIELDS["Extract: keiNo, opSvcKeiNo, aplyYmd, address fields"]

    EXTRACT_FIELDS --> UPDATE_TIME["Check serviceUpdateTimeMap for keiNo
Use cached update time if found"]

    UPDATE_TIME --> GET_LAST_UPD["Query EKK0081A010 SC
Service Contract Agreement
Fetch LAST_UPD_DTM"]

    GET_LAST_UPD --> QUERY_OP_SVC["Query EKK0351A010 SC
Option Service Contract Agreement
Use guide_shs_ad_aply_ymd"]

    QUERY_OP_SVC --> QUERY_TV_SVC["Query EKK0381A010 SC via setEKK0381A010_2
Option Service Contract TV
Use GENE_ADD_DTM from EKK0351A010"]

    QUERY_TV_SVC --> UPDATE_OP_SVC["Update kk0351_a010_map fields
IDO_DIV, MSKM_DTL_NO, UPD_DTM_BEF"]

    UPDATE_OP_SVC --> GET_UPDATE_NAIYO["Get UPDATE_NAIYO from paramMap"]

    GET_UPDATE_NAIYO --> CHECK_NM["UPDATE_NAIYO equals UPDATE_ALL or UPDATE_NM?"]

    CHECK_NM -->|Yes| HANDLE_NM["Handle Name and Kana updates
Compare old vs new values
Build prg_tkjk with before-values"]

    CHECK_NM -->|No| UPDATE_ADDR_ONLY["Skip name-only fields"]

    HANDLE_NM --> UPDATE_NAME_FIELDS["Update GUIDEMG_SOHUS_KANA, GUIDEMG_SOHUS_NM"]

    UPDATE_NAME_FIELDS --> CHECK_UPDATE_TEL_NM["UPDATE_NAIYO not UPDATE_TEL and not UPDATE_NM?"]

    CHECK_UPDATE_TEL_NM -->|Yes| SET_AD_CD["Set GUIDEMG_SOHUS_AD_CD
Check address fields: State, City, Oaztsu, Azcho, Bnchigo, Adrttm, Adrrm
Set AdChangeFlg if any differ"]

    CHECK_UPDATE_TEL_NM -->|No| CHECK_UPDATE_TEL

    SET_AD_CD --> ASSEMBLE_AD["If AdChangeFlg, build full address string in prg_tkjk and prg_tkjk2"]

    ASSEMBLE_AD --> UPDATE_ALL_ADDR["Update all address fields in kk0381_a010_map
Set GUDMG_SHS_AD_MAN_INPUT_FLG
Set GUIDEMG_SOHUS_AD_CHK_LV to 1"]

    UPDATE_ALL_ADDR --> CHECK_UPDATE_TEL["UPDATE_NAIYO not UPDATE_AD?"]

    CHECK_UPDATE_TEL -->|Yes| UPDATE_TELNO["Set GUIDEMG_SOHUS_TELNO
Check phone changes for prg_tkjk"]

    CHECK_UPDATE_TEL -->|No| UPDATE_TV_INFO

    UPDATE_TELNO --> UPDATE_TV_INFO["Execute EKK0381C050 SC
Option Service Contract TV Info Update
Get GUIDEMG_SOHUS_AD_CHK_LV_ERR"]

    UPDATE_TV_INFO --> REQUERY_OP["Re-query EKK0351A010 SC with PARAM_KEY_OPE_DATE"]

    REQUERY_OP --> UPDATE_MAP2["Update kk0351_a010_map2 fields
IDO_DIV, MSKM_DTL_NO, APLY_YMD, LAST_UPD_DTM"]

    UPDATE_MAP2 --> UPDATE_APPLY_DATE["Execute EKK0351C030 SC
Option Service Contract Advance Application Date Input"]

    UPDATE_APPLY_DATE --> SET_UPD_DTM_AF["Set UPD_DTM_AF in cur_guide_shs
Update serviceUpdateTimeMap"]

    SET_UPD_DTM_AF --> PROCESS_TEXT["Process prg_tkjk progression text
Strip trailing delimiter
Truncate to 128 chars if needed
Same for prg_tkjk2"]

    PROCESS_TEXT --> QUERY_TV_LIST["Query EKK0081B003 SC
Service Contract List for SYSID
Find TV service SVC_CD equals 03"]

    QUERY_TV_LIST --> CHECK_TV_EXISTS["TvSvcKeiNo found?"]

    CHECK_TV_EXISTS -->|No| LOOP_NEXT["Next iteration"]

    CHECK_TV_EXISTS -->|Yes| PROCEED_REG["Progression Registration for Emergency Address Change"]

    PROCEED_REG --> QUERY_AGREEMENT["Query EKK0081A010 SC
Get SVC_KEI_STAT and IDO_DIV"]

    QUERY_AGREEMENT --> SVC_STAT_010["SVC_KEI_STAT equals 010?"]

    SVC_STAT_010 -->|Yes| QUERY_PROGRESS["Query EKK1091B001 SC
Progress List to get IDO_DTM"]

    SVC_STAT_010 -->|No| SET_DEFAULT["Set IDO_DIV to E080
Set IDO_DTM to system datetime"]

    QUERY_PROGRESS --> GET_IDO_DTM_VAL["Get IDO_DTM from result"]

    GET_IDO_DTM_VAL --> BUILD_PARENT["Build parent_map
SVC_KEI_NO, IDO_DIV, IDO_DTM
PRG_STAT equals E080
PRG_TKJK_1, PRG_TKJK_2, MSKM_DTL_NO"]

    SET_DEFAULT --> BUILD_PARENT

    BUILD_PARENT --> EXEC_REG["Execute EKK1091D010 SC
Progress Registration
Pass getIdoRsnList result"]

    EXEC_REG --> READ_RESULT["Read EKK1091D010 result
scResultCheck"]

    READ_RESULT --> LOOP_NEXT

    LOOP_NEXT --> RETURN_END(["Return"])

    RETURN_END --> END_NODE(["End"])
```

**CRITICAL -- Constant Resolution:**

| Constant | Value | Business Meaning |
|----------|-------|------------------|
| `UPDATE_ALL` | `"0"` | Update content: All fields |
| `UPDATE_AD` | `"1"` | Update content: Address only |
| `UPDATE_TEL` | `"2"` | Update content: Phone only |
| `UPDATE_NM` | `"3"` | Update content: Name only |
| `UPDATE_AD_TEL` | `"4"` | Update content: Address + Phone |
| `SVC_CD_TV` | `"03"` | Service code: TV service |
| `CD00647_E080` | `"E080"` | Progress status: Guide magazine delivery address change |
| `CD00647_E040` | `"E040"` | Progress status: Emergency address change |
| `CD00647_E090` | `"E090"` | Progress status: Customer-specified delivery address change |
| `PRG_TKJK_MAX_VALUE` | `128` | Maximum length for progression supplemental text |
| `PCG_KUTEN_CANMA` | `"、"` | Common string: Japanese comma delimiter |

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `param` | `IRequestParameterReadWrite` | Request parameter holder containing the model group and control map. Specifically, it provides access to `guide_shs_ad_list` (a list of guide magazine delivery address records to update), `upd_naiyo` (update content type selector), `ido_div` (progress division code), `ope_date` (operation date), `svc_kei_no` (service contract number), `sysid` (system ID), and address field values. |
| 2 | `fixedText` | `String` | User-defined arbitrary string used as a key/discriminator when extracting data from the request parameter via `param.getData(fixedText)`. It scopes the data extraction to a specific business context (e.g., "guideMagAdChange" or similar). |

**Instance Fields / External State read by this method:**
- `keepSesHandle` (`ThreadLocal<SessionHandle>`) -- The session handle kept across SC calls within the same request thread. Access via `keepSesHandle.get()`.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JKKAdInfChgMapperCC.setEKK0081A010` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0081A010` | EKK0081A010SC | KK_T_SVC_KEI (Service Contract) | Query service contract agreement to retrieve LAST_UPD_DTM (last update timestamp). Called once per unique service contract number. |
| R | `JKKAdInfChgMapperCC.setEKK0351A010` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0351A010` | EKK0351A010SC | KK_T_OP_SVC_KEI (Option Service Contract) | Query option service contract agreement. First pass uses aplyYmd from guide_shs; second pass uses system ope_date. |
| C | `JKKAdInfChgMapperCC.setEKK0381A010_2` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0381A010` | EKK0381A010SC | KK_T_OP_SVC_KEI_TV (Option Service Contract TV) | Query option service contract TV data. Uses GENE_ADD_DTM from first EKK0351A010 result. Populates address fields (kana, name, address code, postcode, state, city, oaztsu, azcho, bnchigo, adrttm, adrrm, telno). |
| U | `JKKAdInfChgMapperCC.setEKK0381C050` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0381C050` | EKK0381C050SC | KK_T_OP_SVC_KEI_TV (Option Service Contract TV Info) | Update option service contract TV info with the new address data. Returns UPD_DTM and address check level error. |
| U | `JKKAdInfChgMapperCC.setEKK0351C030` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0351C030` | EKK0351C030SC | KK_T_OP_SVC_KEI_APLY (Option Service Contract Application) | Advance application date input update. Updates the application date to the guide magazine delivery address change date. Returns UPD_DTM. |
| R | `JKKAdInfChgMapperCC.setEKK0081B003` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0081B003` | EKK0081B003SC | KK_T_SVC_KEI (Service Contract) | Query service contract list by SYSID to find TV service contract number (SVC_CD = "03"). |
| R | `JKKAdInfChgMapperCC.setEKK0081A010` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK0081A010` (second call) | EKK0081A010SC | KK_T_SVC_KEI (Service Contract) | Re-query service contract agreement for the TV service to get SVC_KEI_STAT and IDO_DIV. |
| R | `JKKAdInfChgMapperCC.setEKK1091B001` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK1091B001` | EKK1091B001SC | KK_T_PRG (Progress/Advancement) | Query progress list for the TV service to obtain IDO_DTM (advance datetime) when SVC_KEI_STAT is 010 (Accepted). |
| C | `JKKAdInfChgMapperCC.setEKK1091D010` + `scCall.run` + `JKKAdInfChgMapperCC.getEKK1091D010` | EKK1091D010SC | KK_T_PRG_DTL (Progress Detail) | Register progression record for emergency address change. Sets PRG_STAT = E080, includes progression supplemental text (prg_tkjk1/prg_tkjk2) and MSKM_DTL_NO. |
| R | `JKKAdInfChgCC.getIdoRsnList` | Self | - | Retrieve progress division reason list from request parameters. Passed to EKK1091D010 registration. |
| - | `JKKAdInfChgMapperCC.scResultCheck` | Self | - | Standard result validation after each SC call. Throws exception if error result code is present. |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | `JKKAdInfChgCC` (same class) | `guideShsAdUpdChk` -> `guideShsAdUpd` | `scResultCheck [-], getEKK1091D010 [R], run [-], run [-], run [-], run [-], run [-], setEKK1091D010 [-], getIdoRsnList [R], getSysDateTimeStamp [R], getSysDateTimeStamp [R], getSysDateTimeStamp [R], getSysDateTimeStamp [R], getSysDateTimeStamp [R], getMapString [R], scResultCheck [-], getEKK1091B001 [R], run [-], run [-], run [-]` |
| 2 | `JKKAdInfChgCC` (same class) | `guideShsChg` -> `guideShsAdUpd` | Same as above |

**Note:** The method is called from other private methods within `JKKAdInfChgCC` itself (e.g., `guideShsChg` at line 347, and `guideShsAdUpdChk` at line 7234). It is an internal processing component invoked during the broader guide magazine address change workflow.

**Terminal operations from this method (all CRUD endpoints reached):**

| Terminal | SC | CRUD | Entity/Description |
|----------|-----|------|-------------------|
| `scResultCheck` | JKKAdInfChgMapperCC | - | Result validation after each SC call |
| `getEKK1091D010` | EKK1091D010SC | R | Read progression registration result |
| `run` (SC) | EKK0081A010SC, EKK0351A010SC, EKK0381A010SC, EKK0381C050SC, EKK0351C030SC, EKK0081B003SC, EKK1091B001SC | R | Run service component invoker (various SC codes) |
| `setEKK1091D010` | EKK1091D010SC | C | Set progression registration data |
| `getIdoRsnList` | JKKAdInfChgCC | R | Get progress division reason list |
| `getSysDateTimeStamp` | JCCBatCommon, JCCBPCommon | R | Get system date/time stamp |
| `getMapString` | JKKAdInfChgCC | R | Safe map string extraction helper |
| `getEKK1091B001` | EKK1091B001SC | R | Read progress list for advance datetime |
| `run` | Multiple SC invocations | - | Service component execution (7 calls per loop iteration) |

## 6. Per-Branch Detail Blocks

**Block 1** -- [SET] Preparation (L4865)

> Initialize local variables and obtain the mapper and SC request invoker.

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap = new HashMap<String, String>()` |
| 2 | SET | `paramMap = (HashMap<String, Object>) param.getData(fixedText)` |
| 3 | SET | `reqMap`, `resMap` declared |
| 4 | SET | `mapper = JKKAdInfChgMapperCC.getInstance()` |
| 5 | SET | `scCall = new ServiceComponentRequestInvoker()` |

**Block 2** -- [SET] Extract guide magazine delivery address list (L4878)

> Extract the list of guide magazine delivery address records from the parameter map.

| # | Type | Code |
|---|------|------|
| 1 | SET | `guide_shs_list = (ArrayList) paramMap.get(JKKAdInfChgConstCC.PARAM_KEY_GUIDE_SHS_AD_LIST)` |
| 2 | SET | `serviceUpdateTimeMap = new HashMap<String, String>()` -- cache for per-service-contract update timestamps |
| 3 | SET | `kk0081_a010_map = new HashMap<String, Object>()` |
| 4 | SET | `guide_shs_list_ite = guide_shs_list.iterator()` |

**Block 3** -- [WHILE] Iterate over guide magazine delivery address records (L4880)

> Loop through each guide magazine delivery address entry to process the address change.

| # | Type | Code |
|---|------|------|
| 1 | SET | `cur_guide_shs = guide_shs_list_ite.next()` |

**Block 3.1** -- [IF/ELSE] Service contract update time resolution (L4887)

> If the service contract number was already processed in this loop iteration, use the cached update time. Otherwise, query the service contract agreement to get the LAST_UPD_DTM.

| # | Type | Code |
|---|------|------|
| 1 | SET | `keiNo = cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_SVC_KEI_NO)` |
| 2 | IF | `serviceUpdateTimeMap.containsKey(keiNo)` [L4890] |
| 3 | SET | `cur_guide_shs.put(PARAM_KEY_GUIDE_SHS_AD_UPD_DTM_BF, serviceUpdateTimeMap.get(keiNo))` -- use cached update time |
| 4 | ELSE | [L4892] |
| 5 | SET | `condMap.clear()` |
| 6 | SET | `condMap.put("key_svc_kei_no", keiNo)` |
| 7 | SET | `condMap.put("key_rsv_aply_ymd", paramMap.get(PARAM_KEY_OPE_DATE))` |
| 8 | SET | `reqMap = mapper.setEKK0081A010(param, fixedText, condMap)` |
| 9 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0081A010SC** |
| 10 | SET | `kk0081_a010_map = mapper.getEKK0081A010(param, fixedText, resMap)` |
| 11 | EXEC | `mapper.scResultCheck(param)` |
| 12 | SET | `cur_guide_shs.put(PARAM_KEY_GUIDE_SHS_AD_UPD_DTM_BF, kk0081_a010_map.get(EKK0081A010CBSMsg1List.LAST_UPD_DTM))` |

**Block 4** -- [SET] Query option service contract agreement (L4901)

> Retrieve the option service contract agreement data using the op_svc_kei_no from the current guide_shs record.

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap.clear()` |
| 2 | SET | `condMap.put(COND_KEY_OP_SVC_KEI_NO, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_OP_SVC_KEI_NO))` |
| 3 | SET | `condMap.put(COND_KEY_OPEDATE, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_APLY_YMD))` -- uses guide_shs aplyYmd (OM-2014-0001265 change) |
| 4 | SET | `reqMap = mapper.setEKK0351A010(param, fixedText, condMap)` |
| 5 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0351A010SC** |
| 6 | SET | `kk0351_a010_map = mapper.getEKK0351A010(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |

**Block 5** -- [SET] Query option service contract TV (L4913)

> Retrieve the option service contract TV data. Uses GENE_ADD_DTM from the option service contract result.

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap.clear()` |
| 2 | SET | `condMap.put(COND_KEY_OP_SVC_KEI_NO, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_OP_SVC_KEI_NO))` |
| 3 | SET | `condMap.put(KEY_GENE_ADD_DTM, kk0351_a010_map.get(EKK0351A010CBSMsg1List.GENE_ADD_DTM))` |
| 4 | SET | `reqMap = mapper.setEKK0381A010_2(param, fixedText, condMap)` -- modified method (OM-2014-0001265) |
| 5 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0381A010SC** |
| 6 | SET | `kk0381_a010_map = mapper.getEKK0381A010(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |

**Block 6** -- [SET] Update option service contract agreement fields (L4925)

> Replace fields in the retrieved agreement data with the new address change values.

| # | Type | Code |
|---|------|------|
| 1 | SET | `kk0351_a010_map.put(IDO_DIV, paramMap.get(PARAM_KEY_IDO_DIV))` |
| 2 | IF | `!StringUtils.isEmpty(paramMap.get(PARAM_KEY_MSKM_DTL_NO))` [ST2-2013-0001729] |
| 3 | SET | `kk0351_a010_map.put(MSKM_DTL_NO, paramMap.get(PARAM_KEY_MSKM_DTL_NO))` |
| 4 | SET | `kk0351_a010_map.put(JKKAdInfChgConstCC.UPD_DT_OP_SVC_KEI_UPD_DTM_BEF, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_UPD_DTM_BF))` |

**Block 7** -- [IF/ELSE-IF] Handle name/kana/address update based on updateNaiyo (L4930)

> Branch by `updateNaiyo` to determine which fields to populate.

**Block 7.1** -- [IF] `updateNaiyo` equals `UPDATE_ALL="0"` or `UPDATE_NM="3"` (L4936)

> When updating all fields or name-only, populate name and kana fields and build progression supplemental text.

| # | Type | Code |
|---|------|------|
| 1 | IF | Check `GUIDEMG_SOHUS_KANA` null/empty comparison with `PARAM_KEY_GUIDE_SHS_AD_KANA` (3 branches: both empty, old non-empty/new empty, old empty/new non-empty) -- ANK-1820-00-00 |
| 2 | SET | `prg_tkjk = prg_tkjk + PCG_TGS_SHS_KANA_TEXT + oldKana + PCG_KUTEN_CANMA` -- format: "変更前送付先カナ名:" + old_value + "、" |
| 3 | ELSE-IF | `GUIDEMG_SOHUS_KANA` changed -- same prg_tkjk assembly |
| 4 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_KANA, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_KANA))` |
| 5 | IF | Check `GUIDEMG_SOHUS_NM` null/empty comparison with `PARAM_KEY_GUIDE_SHS_AD_NM` (3 branches) -- ANK-1820-00-00 |
| 6 | SET | `prg_tkjk = prg_tkjk + PCG_TGS_SHS_NM_TEXT + oldNm + PCG_KUTEN_CANMA` -- format: "変更前送付先名:" + old_value + "、" |
| 7 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_NM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_NM))` |

**Block 8** -- [IF] `updateNaiyo` not `UPDATE_TEL="2"` and not `UPDATE_NM="3"` (L4989)

> When updating address code and full address (not phone-only or name-only).

**Block 8.1** -- [IF] `updateNaiyo` not `UPDATE_AD="1"` and not `UPDATE_NM="3"` (L4989 extended)

> When updating address fields, populate address code and check each address component for changes.

| # | Type | Code |
|---|------|------|
| 1 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_AD_CD, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_AD_CD))` |
| 2 | SET | `prg_tkjk2 = ...` -- post-change value tracking (ANK-2394-00-00) |
| 3 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_PCD` (postcode) null/empty changed -- 3 branches |
| 4 | SET | `prg_tkjk = prg_tkjk + PCG_TGS_SHS_PCD_TEXT + oldPostcode + PCG_KUTEN_CANMA` |
| 5 | SET | `prg_tkjk2 = prg_tkjk2 + PCG_TGS_SHS_PCD_TEXT_AF + newPostcode + PCG_KUTEN_CANMA` |
| 6 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_PCD, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_PCD))` |

**Block 8.2** -- [IF] Address change detection flag (L5029)

> Compare each address sub-field between old DB value and new guide_shs value. Set `AdChangeFlg` if any field differs.

| # | Type | Code |
|---|------|------|
| 1 | SET | `AdChangeFlg = false` |
| 2 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_STATE_NM` vs `PARAM_KEY_GUIDE_SHS_AD_STATE` (4 branches) |
| 3 | SET | `AdChangeFlg = true` if changed |
| 4 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_CITY_NM` vs `PARAM_KEY_GUIDE_SHS_AD_CITY` (4 branches) |
| 5 | SET | `AdChangeFlg = true` if changed |
| 6 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_OAZTSU_NM` vs `PARAM_KEY_GUIDE_SHS_AD_OAZTSU` (4 branches) |
| 7 | SET | `AdChangeFlg = true` if changed |
| 8 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_AZCHO_NM` vs `PARAM_KEY_GUIDE_SHS_AD_AZCHO` (4 branches) |
| 9 | SET | `AdChangeFlg = true` if changed |
| 10 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_BNCHIGO` vs `PARAM_KEY_GUIDE_SHS_AD_BNCHIGO` (4 branches) |
| 11 | SET | `AdChangeFlg = true` if changed |
| 12 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_ADRTTM` vs `PARAM_KEY_GUIDE_SHS_AD_ADRTTM` (4 branches) |
| 13 | SET | `AdChangeFlg = true` if changed |
| 14 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_ADRRM` vs `PARAM_KEY_GUIDE_SHS_AD_ADRRM` (4 branches) |
| 15 | SET | `AdChangeFlg = true` if changed |

**Block 8.3** -- [IF] `AdChangeFlg` is true (L5226)

> If any address field changed, assemble the full old and new address strings for the progression supplemental text.

| # | Type | Code |
|---|------|------|
| 1 | SET | `prg_tkjk = prg_tkjk + PCG_TGS_SHS_AD_TEXT + old_state + old_city + old_oaztsu + old_azcho + old_bnchigo + old_adrttm + old_adrrm + PCG_KUTEN_CANMA` -- format: "変更前住所:" + concatenated_old_address + "、" |
| 2 | SET | `prg_tkjk2 = prg_tkjk2 + PCG_TGS_SHS_AD_TEXT_AF + new_state + ... + new_adrrm + PCG_KUTEN_CANMA` -- post-change tracking |

**Block 8.4** -- [SET] Update all address fields (L5238)

> Write the new address values into the kk0381_a010_map for the SC update.

| # | Type | Code |
|---|------|------|
| 1 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_STATE_NM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_STATE))` |
| 2 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_CITY_NM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_CITY))` |
| 3 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_OAZTSU_NM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_OAZTSU))` |
| 4 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_AZCHO_NM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_AZCHO))` |
| 5 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_BNCHIGO, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_BNCHIGO))` |
| 6 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_ADRTTM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_ADRTTM))` |
| 7 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_ADRRM, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_ADRRM))` |
| 8 | SET | `kk0381_a010_map.put(GUDMG_SHS_AD_MAN_INPUT_FLG, (Boolean)paramMap.get(PARAM_KEY_REIGAI) ? "1" : "0")` -- OM-2013-0000871 |
| 9 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_AD_CHK_LV, "1")` -- ST3-2013-0000040 |

**Block 9** -- [IF] `updateNaiyo` not `UPDATE_AD="1"` (L5253)

> When not updating address-only, also handle phone number changes.

**Block 9.1** -- [IF/ELSE-IF] Phone number change detection (L5258)

> Check if phone number changed and assemble progression text.

| # | Type | Code |
|---|------|------|
| 1 | IF/ELSE-IF | Check `GUIDEMG_SOHUS_TELNO` vs `PARAM_KEY_GUIDE_SHS_AD_TELNO` (3 branches) |
| 2 | SET | `prg_tkjk = prg_tkjk + PCG_TGS_SHS_TELNO_TEXT + oldTelNo + PCG_KUTEN_CANMA` |
| 3 | SET | `prg_tkjk2 = prg_tkjk2 + PCG_TGS_SHS_TELNO_TEXT_AF + newTelNo + PCG_KUTEN_CANMA` |
| 4 | SET | `kk0381_a010_map.put(GUIDEMG_SOHUS_TELNO, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_TELNO))` |

**Block 10** -- [SET] Execute option service contract TV info update (L5292)

> Run the TV info update SC with the prepared address data.

| # | Type | Code |
|---|------|------|
| 1 | SET | `reqMap = mapper.setEKK0381C050(param, fixedText, kk0351_a010_map, kk0381_a010_map)` |
| 2 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0381C050SC** |
| 3 | SET | `kk0381_c050_map = mapper.getEKK0381C050(param, fixedText, resMap)` |
| 4 | EXEC | `mapper.scResultCheck(param)` |
| 5 | IF | `!StringUtils.isEmpty(paramMap.get(EKK0381C050CBSMsg.GUIDEMG_SOHUS_AD_CHK_LV_ERR))` [ST3-2013-0000040] |
| 6 | SET | `paramMap.put("ad_chk_lv_res", ad_chk_lv_res)` |

**Block 11** -- [SET] Re-query option service contract and update application date (L5311)

> After the TV info update, re-query the option service contract agreement using system operation date and then execute the application date input update.

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap.clear()` |
| 2 | SET | `condMap.put(COND_KEY_OP_SVC_KEI_NO, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_OP_SVC_KEI_NO))` |
| 3 | SET | `condMap.put(COND_KEY_OPEDATE, paramMap.get(PARAM_KEY_OPE_DATE))` -- uses ope_date from param |
| 4 | SET | `reqMap = mapper.setEKK0351A010(param, fixedText, condMap)` |
| 5 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0351A010SC** (second call) |
| 6 | SET | `kk0351_a010_map2 = mapper.getEKK0351A010(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |
| 8 | SET | `kk0351_a010_map2.put(IDO_DIV, paramMap.get(PARAM_KEY_IDO_DIV))` |
| 9 | IF | `!StringUtils.isEmpty(paramMap.get(PARAM_KEY_MSKM_DTL_NO))` [ST2-2013-0001729] |
| 10 | SET | `kk0351_a010_map2.put(MSKM_DTL_NO, paramMap.get(PARAM_KEY_MSKM_DTL_NO))` |
| 11 | SET | `kk0351_a010_map2.put(PARAM_KEY_GUIDE_SHS_AD_APLY_YMD, cur_guide_shs.get(PARAM_KEY_GUIDE_SHS_AD_APLY_YMD))` |
| 12 | SET | `kk0351_a010_map2.put(LAST_UPD_DTM, kk0381_c050_map.get(EKK0381C050CBSMsg.UPD_DTM))` |
| 13 | SET | `reqMap = mapper.setEKK0351C030(param, fixedText, kk0351_a010_map2)` |
| 14 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0351C030SC** |
| 15 | SET | `kk0351_c030_map = mapper.getEKK0351C030(param, fixedText, resMap)` |
| 16 | EXEC | `mapper.scResultCheck(param)` |
| 17 | SET | `cur_guide_shs.put(PARAM_KEY_GUIDE_SHS_AD_UPD_DTM_AF, kk0351_c030_map.get(EKK0351C030CBSMsg.UPD_DTM))` |
| 18 | SET | `serviceUpdateTimeMap.put(keiNo, kk0351_c030_map.get(EKK0351C030CBSMsg.UPD_DTM))` |

**Block 12** -- [IF] Process progression supplemental text (L5320)

> Clean up the progression text: remove trailing delimiter, truncate to 128 chars if too long.

| # | Type | Code |
|---|------|------|
| 1 | SET | `prg_tkjk_length = prg_tkjk.length()` |
| 2 | IF | `prg_tkjk != null && !"".equals(prg_tkjk) && prg_tkjk_length > 0` [ANK-1820-00-00] |
| 3 | SET | `prg_tkjk_getalue = prg_tkjk.substring(0, prg_tkjk_length-1)` -- strip trailing "、" |
| 4 | SET | `prg_tkjk = prg_tkjk_getalue` |
| 5 | IF | `prg_tkjk_length-1 > PRG_TKJK_MAX_VALUE (128)` |
| 6 | SET | `prg_tkjk_select = prg_tkjk.substring(0, 128)` -- truncate to 128 chars |
| 7 | SET | `prg_tkjk = prg_tkjk_select` |
| 8 | SET | `prg_tkjk2_length = prg_tkjk2.length()` |
| 9 | IF | `prg_tkjk2 != null && !"".equals(prg_tkjk2) && prg_tkjk2_length > 0` [ANK-2394-00-00] |
| 10 | SET | `prg_tkjk2_getalue = prg_tkjk2.substring(0, prg_tkjk2_length-1)` |
| 11 | SET | `prg_tkjk2 = prg_tkjk2_getalue` |
| 12 | IF | `prg_tkjk2_length-1 > PRG_TKJK_MAX_VALUE (128)` |
| 13 | SET | `prg_tkjk2_select = prg_tkjk2.substring(0, 128)` |
| 14 | SET | `prg_tkjk2 = prg_tkjk2_select` |

**Block 13** -- [SET] Query TV service contract number (L5332)

> Query the service contract list for the system to find the TV service contract number.

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap.clear()` |
| 2 | SET | `condMap.put(COND_KEY_SYSID, paramMap.get(PARAM_KEY_SYSID))` |
| 3 | SET | `condMap.put(COND_KEY_OPEDATE, paramMap.get(PARAM_KEY_OPE_DATE))` |
| 4 | SET | `reqMap = mapper.setEKK0081B003(param, fixedText, condMap)` |
| 5 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0081B003SC** |
| 6 | SET | `kk0081_b003_list = mapper.getEKK0081B003(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |
| 8 | SET | `TvSvcKeiNo = ""` |
| 9 | FOR | `i = 0; i < kk0081_b003_list.size(); i++` |
| 10 | SET | `SvcCd = kk0081_b003_list.get(i).get(EKK0081B003CBSMsg1List.SVC_CD)` |
| 11 | IF | `"03".equals(SvcCd)` -- TV service code |
| 12 | SET | `TvSvcKeiNo = kk0081_b003_list.get(i).get(EKK0081B003CBSMsg1List.SVC_KEI_NO)` |
| 13 | BREAK | from loop |

**Block 14** -- [IF] `TvSvcKeiNo` exists (L5351)

> If a TV service contract exists, register the progression record for emergency address change.

**Block 14.1** -- [SET] Query TV service contract agreement (L5355)

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap.clear()` |
| 2 | SET | `condMap.put("key_svc_kei_no", TvSvcKeiNo)` |
| 3 | SET | `condMap.put("key_rsv_aply_ymd", getMapString(paramMap, PARAM_KEY_OPE_DATE))` |
| 4 | SET | `reqMap = mapper.setEKK0081A010(param, fixedText, condMap)` |
| 5 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK0081A010SC** |
| 6 | SET | `kk0081_010_map = mapper.getEKK0081A010(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |
| 8 | SET | `svcKeiStat = getMapString(kk0081_010_map, EKK0081A010CBSMsg1List.SVC_KEI_STAT)` |
| 9 | SET | `idoDiv = getMapString(kk0081_010_map, EKK0081A010CBSMsg1List.IDO_DIV)` |

**Block 14.2** -- [IF/ELSE] SVC_KEI_STAT check (L5360)

> If the service contract status is 010 (Accepted), query the progress list to get the advance datetime.

| # | Type | Code |
|---|------|------|
| 1 | IF | `JKKSvcConst.SVC_KEI_STAT_010.equals(svcKeiStat)` -- status 010 = Accepted |
| 2 | SET | `condMap.clear()` |
| 3 | SET | `condMap.put("key_svc_kei_no", TvSvcKeiNo)` |
| 4 | SET | `reqMap = mapper.setEKK1091B001(param, fixedText, condMap)` |
| 5 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK1091B001SC** |
| 6 | SET | `kk1091_a010_map = mapper.getEKK1091B001(param, fixedText, resMap)` |
| 7 | EXEC | `mapper.scResultCheck(param)` |
| 8 | SET | `idoDtm = getMapString(kk1091_a010_map, EKK1091B001CBSMsg1List.IDO_DTM)` |
| 9 | ELSE | `idoDtm` not set -- progress list not queried |

**Block 14.3** -- [SET] Build parent_map and register progression (L5382)

> Assemble all data for the progression registration and execute it.

| # | Type | Code |
|---|------|------|
| 1 | SET | `parent_map = new HashMap<String, Object>()` |
| 2 | SET | `parent_map.put(SVC_KEI_NO, TvSvcKeiNo)` |
| 3 | IF | `JKKSvcConst.SVC_KEI_STAT_010.equals(svcKeiStat)` [OM-2014-0004032] |
| 4 | SET | `parent_map.put(IDO_DIV, idoDiv)` -- use actual IDO_DIV from TV service |
| 5 | SET | `parent_map.put(IDO_DTM, idoDtm)` -- use actual IDO_DTM from progress list |
| 6 | ELSE | [OM-2014-0004032] |
| 7 | SET | `parent_map.put(IDO_DIV, paramMap.get(PARAM_KEY_IDO_DIV))` |
| 8 | SET | `parent_map.put(IDO_DTM, JCCBPCommon.getSysDateTimeStamp())` -- system datetime |
| 9 | SET | `parent_map.put(PRG_STAT, JKKAdInfChgConstCC.CD00647_E080)` -- E080 = Guide magazine delivery address change |
| 10 | IF | `prg_tkjk != null && !"".equals(prg_tkjk)` |
| 11 | SET | `parent_map.put(PRG_TKJK_1, prg_tkjk)` |
| 12 | IF | `prg_tkjk2 != null && !"".equals(prg_tkjk2)` [ANK-2394-00-00] |
| 13 | SET | `parent_map.put(PRG_TKJK_2, prg_tkjk2)` |
| 14 | IF | `!StringUtils.isEmpty(paramMap.get(PARAM_KEY_MSKM_DTL_NO))` |
| 15 | SET | `parent_map.put(MSKM_DTL_NO, paramMap.get(PARAM_KEY_MSKM_DTL_NO))` |
| 16 | SET | `reqMap = mapper.setEKK1091D010(param, fixedText, parent_map, getIdoRsnList(param, fixedText))` |
| 17 | SET | `resMap = scCall.run(reqMap, keepSesHandle.get())` -- **EKK1091D010SC** |
| 18 | SET | `mapper.getEKK1091D010(param, fixedText, resMap)` |
| 19 | EXEC | `mapper.scResultCheck(param)` |

**Block 15** -- [CATCH] Exception handler (L5434)

> Map any exception to CCException with the standard error message.

| # | Type | Code |
|---|------|------|
| 1 | CATCH | `Exception ex` |
| 2 | THROW | `new CCException(JKKAdInfChgConstCC.ERR_STR_RESULT_CD, ex.getCause())` -- "サービスコンポーネントの実行結果にエラーがあります" (Error in service component execution result) |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `guideShsAdUpd` | Method | Guide Magazine Delivery Address Change Processing |
| `keiNo` | Field | Service contract number -- internal identifier for a service contract line item |
| `opSvcKeiNo` | Field | Option service contract number -- number for an option service (TV, internet, etc.) attached to a main service contract |
| `aplyYmd` | Field | Application date -- YYYYMMDD formatted date when the service change takes effect |
| `upd_naiyo` | Field | Update content type -- determines which fields are updated (all, address only, phone only, name only, address+phone) |
| `IDO_DIV` | Field | Progress division code -- classifies the type of advance/progress record |
| `PRG_STAT` | Field | Progress status code -- e.g., E080 = Guide magazine delivery address change |
| `prg_tkjk` | Field | Progression supplemental text -- change history text describing before-values of changed fields |
| `prg_tkjk2` | Field | Progression supplemental text (post-change) -- after-value tracking text (ANK-2394-00-00) |
| `AdChangeFlg` | Field | Address change flag -- set to true when any address sub-field differs between old DB and new value |
| `GUIDEMG_SOHUS_KANA` | Field | Guide magazine delivery recipient name (kana) -- phonetic name of the delivery recipient |
| `GUIDEMG_SOHUS_NM` | Field | Guide magazine delivery recipient name -- kanji/hanzi name of the delivery recipient |
| `GUIDEMG_SOHUS_AD_CD` | Field | Guide magazine delivery address code -- classification code for the delivery address type |
| `GUIDEMG_SOHUS_PCD` | Field | Guide magazine delivery postcode |
| `GUIDEMG_SOHUS_STATE_NM` | Field | Guide magazine delivery prefecture name (都道府県名) |
| `GUIDEMG_SOHUS_CITY_NM` | Field | Guide magazine delivery city/town/village name (市区町村名) |
| `GUIDEMG_SOHUS_OAZTSU_NM` | Field | Guide magazine delivery district/village name (大字町名) |
| `GUIDEMG_SOHUS_AZCHO_NM` | Field | Guide magazine delivery block name (字丁目名) |
| `GUIDEMG_SOHUS_BNCHIGO` | Field | Guide magazine delivery plot number (番地号) |
| `GUIDEMG_SOHUS_ADRTTM` | Field | Guide magazine delivery building name (建物名) |
| `GUIDEMG_SOHUS_ADRRM` | Field | Guide magazine delivery room number (部屋番号) |
| `GUIDEMG_SOHUS_TELNO` | Field | Guide magazine delivery phone number |
| `GUIDEMG_SOHUS_AD_CHK_LV` | Field | Address change check level -- validation level for address change processing (set to "1") |
| `GUDMG_SHS_AD_MAN_INPUT_FLG` | Field | Guide magazine delivery address manual input flag -- indicates if address was manually entered |
| `SVC_KEI_STAT` | Field | Service contract status -- e.g., "010" = Accepted/受付済 |
| `SVC_CD` | Field | Service code -- classifies service type: "01"=Net, "02"=Tel, "03"=TV, "04"=Hosting |
| `SVC_KEI_NO` | Field | Service contract number |
| `IDO_DTM` | Field | Advance/progress datetime -- timestamp when the service advance was registered |
| `LAST_UPD_DTM` | Field | Last update datetime -- timestamp of the most recent modification to a record |
| `GENE_ADD_DTM` | Field | Generation/addition datetime -- when the option service contract TV record was generated |
| EKK0081A010SC | SC Code | Service Component for Service Contract Agreement query |
| EKK0081B003SC | SC Code | Service Component for Service Contract List query (by SYSID) |
| EKK0351A010SC | SC Code | Service Component for Option Service Contract Agreement query |
| EKK0351C030SC | SC Code | Service Component for Option Service Contract Advance Application Date Input update |
| EKK0381A010SC | SC Code | Service Component for Option Service Contract TV agreement query |
| EKK0381C050SC | SC Code | Service Component for Option Service Contract TV info update |
| EKK1091B001SC | SC Code | Service Component for Progress List query |
| EKK1091D010SC | SC Code | Service Component for Progress Registration (進捗登録) |
| UPDATE_ALL | Constant | `"0"` -- Update all fields |
| UPDATE_AD | Constant | `"1"` -- Update address only |
| UPDATE_TEL | Constant | `"2"` -- Update phone only |
| UPDATE_NM | Constant | `"3"` -- Update name only |
| CD00647_E080 | Constant | `"E080"` -- Progress status: Guide magazine delivery address change |
| CD00647_E040 | Constant | `"E040"` -- Progress status: Emergency address change |
| CD00647_E090 | Constant | `"E090"` -- Progress status: Customer-specified delivery address change |
| PRG_TKJK_MAX_VALUE | Constant | `128` -- Maximum length for progression supplemental text |
| PCG_KUTEN_CANMA | Constant | `"、"` -- Japanese comma delimiter used to separate progression text entries |
| PCG_TGS_SHS_KANA_TEXT | Constant | `"変更前送付先カナ名:"` -- Prefix for progression text: "Before: Delivery Recipient Kana:" |
| PCG_TGS_SHS_NM_TEXT | Constant | `"変更前送付先名:"` -- Prefix for progression text: "Before: Delivery Recipient Name:" |
| PCG_TGS_SHS_PCD_TEXT | Constant | `"変更前郵便番号:"` -- Prefix for progression text: "Before: Postcode:" |
| PCG_TGS_SHS_AD_TEXT | Constant | `"変更前住所:"` -- Prefix for progression text: "Before: Address:" |
| PCG_TGS_SHS_TELNO_TEXT | Constant | `"変更前電話番号:"` -- Prefix for progression text: "Before: Phone Number:" |
| ERR_STR_RESULT_CD | Constant | `"サービスコンポーネントの実行結果にエラーがあります"` -- Error message: "Error in service component execution result" |
| SS | Acronym | Service Contract (サービス契約) |
| SC | Acronym | Service Component -- the layer that handles business logic and database access |
| CC | Acronym | Common Component -- the shared utility/service layer in the application architecture |
| ADV | Acronym | Progression/Advancement (進捗) -- the status tracking system for service changes |
| TV | Business term | Television service -- a broadband TV service offered by K-Opticom (SVC_CD = "03") |
| NET | Business term | Internet service -- broadband internet (SVC_CD = "01") |
| GUIDE_MAG | Business term | Guide Magazine -- a periodic publication sent to customers, requiring a delivery address |
| EKK | Prefix | Enterprise K-Opticom -- database/entity prefix for K-Opticom business tables |
| ECK | Prefix | Enterprise Customer K-Opticom -- database/entity prefix for customer-specific tables |