# Business Logic — JKKAdchgTelInfoChgCC.addBmpCnclTaiorrk() [105 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKAdchgTelInfoChgCC` |
| Layer | CC/Common Component — part of the business logic common component layer handling telephone information changes |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`)

## 1. Role

### JKKAdchgTelInfoChgCC.addBmpCnclTaiorrk()

This method records a **bango (bancho/bangochu — construction site) cancellation notification log entry** in the customer response history system (対応履歴). It is invoked when a bango work order associated with a service contract line has reached a state where cancellation notification to the customer is warranted — specifically, when the work order status is neither "work completed" (050) nor "work cancelled" (090). The method follows a **gatekeeper pattern**: it first queries the bango work overview list (ETU0011B010CBSMsg1List), filters out entries already marked as cancelled (status "090"), matches against a provided service detail work number if given, then queries the detailed bango work permit information (ETU0011A010). Only if the detailed work status is active (in-progress) does it delegate to `addTaiorrk()` to persist the cancellation notification log. If at any point no bango record is found or the status is already terminal, the method returns silently.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addBmpCnclTaiorrk(params)"])
    
    START --> INIT["Initialize: mapper, scCall, condMap"]
    INIT --> QRY_BANGO_LIST["Query: setETU0011B010
(bango work overview list)"]
    QRY_BANGO_LIST --> PARSE_BANGO["Parse: getETU0011B010
-> tu0011_b010_list"]
    PARSE_BANGO --> RESULT_CHK["scResultCheck(param)"]
    RESULT_CHK --> CHECK_EMPTY{"tu0011_b010_list
empty or null?"}
    CHECK_EMPTY -->|Yes| EARLY_RET1["Return
(no bango info found)"]
    CHECK_EMPTY -->|No| BANGO_LOOP["Loop: iterate tu0011_b010_list"]
    
    BANGO_LOOP --> CHECK_STAT{"BMP_KOJI_STAT
== \"090\"?
(Cancelled)"}
    CHECK_STAT -->|Yes| CONTINUE["continue
(skip cancelled)"]
    CONTINUE --> BANGO_LOOP
    
    CHECK_STAT -->|No| SET_BMP["bmp_map =
tu0011_b010_map"]
    SET_BMP --> CHECK_UCWK{"svc_kei_ucwk_no
non-empty AND
matches?"}
    CHECK_UCWK -->|Yes| BREAK["break
(match found)"]
    CHECK_UCWK -->|No| BANGO_LOOP
    BREAK --> BMP_SET{"bmp_map
== null?"}
    
    BANGO_LOOP --> NO_BMP_END["no non-cancelled
record found"]
    NO_BMP_END --> BMP_SET
    BMP_SET -->|Yes| EARLY_RET2["Return
(bango info not found)"]
    
    BMP_SET -->|No| QRY_BANGO_DET["Query: setETU0011A010
(bango work permit detail)"]
    QRY_BANGO_DET --> PARSE_DET["Parse: getETU0011A010
-> tu0011_a010_map"]
    PARSE_DET --> RESULT_CHK2["scResultCheck(param)"]
    RESULT_CHK2 --> CHECK_DET{"tu0011_a010_map
empty or null?"}
    CHECK_DET -->|Yes| EARLY_RET3["Return
(detail not found)"]
    
    CHECK_DET -->|No| GET_STAT["Get: BMP_KOJI_STAT
-> bmpKojiSvcStat"]
    GET_STAT --> CHECK_ACTIVE{"Status is NOT
KOJIFIN(050) AND
NOT KOJICL(090)?"}
    
    CHECK_ACTIVE -->|No — terminal status| NO_LOG["No log entry
(work already complete/cancelled)"]
    CHECK_ACTIVE -->|Yes — active status| CALL_ADD["CALL: addTaiorrk()
(register cancellation notification log)"]
    
    CALL_ADD --> END(["Return / Next"])
    NO_LOG --> END
    EARLY_RET1 --> END
    EARLY_RET2 --> END
    EARLY_RET3 --> END
```

**Constant Resolution:**
- `JKKSvcConst.BMP_KOJI_STAT_KOJIFIN = "050"` — Bango work status: Work Complete
- `JKKSvcConst.BMP_KOJI_STAT_KOJICL = "090"` — Bango work status: Work Cancelled
- `ETU0011B010CBSMsg1List.BMP_KOJI_STAT = "bmp_koji_stat"` — Field key for bango work status in the overview list
- `ETU0011B010CBSMsg1List.BMP_KOJI_NO = "bmp_koji_no"` — Field key for bango work number
- `ETU0011B010CBSMsg1List.SVC_KEI_UCWK_NO = "svc_kei_ucwk_no"` — Field key for service detail work number
- `ETU0011A010CBSMsg1List.BMP_KOJI_STAT = "bmp_koji_stat"` — Field key for bango work status in the detail
- `ETU0011A010CBSMsg1List.NTT_UK_NO = "ntt_uk_no"` — Field key for NTT acceptance number
- `JKKAdInfChgConstCC.COND_KEY_SVC_KEI_NO = "cond_key_svc_kei_no"` — Condition key for service contract number

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `sysid` | `String` | System ID — identifies the calling system/account in the K-Opticom telecommunications platform. Passed through to the response history log entry. |
| 2 | `svcKeiNo` | `String` | Service contract number (サービス契約番号) — the unique identifier for a customer's service line. Used to query the bango work overview list and recorded in the cancellation notification log. |
| 3 | `svc_kei_ucwk_no` | `String` | Service detail work number — internal tracking ID for a specific service contract line item/work order. When non-empty, used as a matching filter to find the exact bango record among multiple results. May be null. |
| 4 | `telno` | `String` | Telephone number — used as a secondary filter alongside `svcKeiNo` when querying the bango work overview list. Used in the initial ETU0011B010 query condition. |
| 5 | `orgCd` | `String` | Organization code (組織コード) — identifies the organizational unit performing the cancellation notification. Passed through to the response history log. |
| 6 | `orgNm` | `String` | Organization name (組織名) — human-readable name of the organizational unit. Passed through to the response history log for audit purposes. |

**Instance fields read:**
| Field | Type | Business Description |
|-------|------|---------------------|
| `keepReqParam` | `ThreadLocal` | Request parameter map — holds shared request context (used throughout mapper SC invocations) |
| `keepFixedText` | `ThreadLocal` | Fixed text dictionary — holds localized/display text for SC interactions |
| `keepSesHandle` | `ThreadLocal` | Session/handle reference — used for ServiceComponentRequestInvoker to pass the database session handle |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JKKAdchgMapperCC.getETU0011B010` | - | ETU0011B010 (Bango work overview list) | Retrieves the list of bango work records for a given service contract number and telephone number |
| R | `JKKAdchgMapperCC.getETU0011A010` | - | ETU0011A010 (Bango work permit detail) | Retrieves the detailed bango work permit information by bango work number |
| C | `JKKAdchgTelInfoChgCC.addTaiorrk` | - | T_RESPONSE_HISTORY (response history table) | Registers a bango cancellation notification log entry in the customer response history |
| - | `JKKAdchgMapperCC.setETU0011B010` | - | - | Populates the request parameter map with conditions for ETU0011B010 CBS message |
| - | `JKKAdchgMapperCC.setETU0011A010` | - | - | Populates the request parameter map with conditions for ETU0011A010 CBS message |
| - | `JKKAdchgMapperCC.scResultCheck` | - | - | Validates the result of a service component call, checks for errors in the request param map |
| - | `ServiceComponentRequestInvoker.run` | - | - | Invokes the underlying CBS (service component) for both ETU0011B010 and ETU0011A010 queries |
| R | `JCCBPCommon.getOpeDate` | - | - | Retrieves the current operational date (used as the submission date for the log entry) |

**How to classify:**
- **R (Read)**: The two main data retrieval steps — querying the bango work overview and the bango work permit detail.
- **C (Create)**: The sole write operation — inserting a cancellation notification record via `addTaiorrk()`.

The method performs a **two-phase read-then-write** pattern: first it queries and filters bango work data (Read), and only if an active bango record is found does it write the cancellation notification log (Create).

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 2 methods.
Terminal operations from this method: `addTaiorrk` [C], `getOpeDate` [R], `getETU0011A010` [R], `setETU0011B010` [-], `run` [-], `getETU0011B010` [R], `setETU0011A010` [-], `scResultCheck` [-], `scResultCheck` [-]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CBS:JKKAdchgTelInfoChgCC | `processBangoInfo` -> `addBmpCnclTaiorrk` (self-contained within same class) | `addTaiorrk [C]`, `getOpeDate [R]`, `getETU0011A010 [R]`, `getETU0011B010 [R]` |
| 2 | CBS:JKKAdchgCancelTelnoCC | `processBangoCancellation` -> `addBmpCnclTaiorrk` (cross-class call) | `addTaiorrk [C]`, `getOpeDate [R]`, `getETU0011A010 [R]`, `getETU0011B010 [R]` |

**Notes:**
- The method is called from two locations within the broader bango cancellation workflow: from `JKKAdchgTelInfoChgCC` itself (when processing bango info changes) and from `JKKAdchgCancelTelnoCC` (when cancelling telephone numbers associated with bango work).
- Both callers pass the method during a branch where `bmpUm == "1"` (bango present), meaning this is exclusively a **bango-specific** cancellation notification flow.
- The terminal CRUD endpoints all trace back to: `addTaiorrk` (Create), `getETU0011A010`/`getETU0011B010` (Read), and `getOpeDate` (Read for date).

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] Initialization (L813)

> Sets up the infrastructure for SC calls: creates condition map, obtains mapper and SC request invoker instances.

| # | Type | Code |
|---|------|------|
| 1 | SET | `condMap = new HashMap<String, String>()` // Pre-processing: prepare condition map |
| 2 | SET | `mapper = JKKAdchgMapperCC.getInstance()` // Mapping layer instance for SC request/response handling |
| 3 | SET | `scCall = new ServiceComponentRequestInvoker()` // SC request invoker instance |

**Block 2** — [SET] Query bango work overview list (L822–827)

> Sets query conditions for the ETU0011B010 CBS: filters by service contract number and telephone number, invokes SC, parses result.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `condMap.clear()` // Reset condition map |
| 2 | SET | `condMap.put(COND_KEY_SVC_KEI_NO = "cond_key_svc_kei_no", svcKeiNo)` // [-> "cond_key_svc_kei_no"] Map service contract number as condition |
| 3 | SET | `condMap.put("cond_key_telno", telno)` // Map telephone number as condition |
| 4 | CALL | `mapper.setETU0011B010(keepReqParam, keepFixedText, condMap)` // Populate request param with ETU0011B010 CBS message conditions |
| 5 | CALL | `scCall.run(reqMap, keepSesHandle)` // Execute SC request, get response map |
| 6 | CALL | `tu0011_b010_list = mapper.getETU0011B010(keepReqParam, keepFixedText, resMap)` // Extract bango work overview list |
| 7 | CALL | `mapper.scResultCheck(keepReqParam)` // Validate SC call result |

**Block 3** — [IF] Early return if no bango records (L828–831)

> `[tu0011_b010_list == null || tu0011_b010_list.isEmpty()]` — If no bango work records exist for the given service contract and phone number, return silently.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return` // No bango info found — early exit |

**Block 4** — [FOR + IF] Filter and match bango records (L833–852)

> Iterates through bango overview records. Skips cancelled records (status "090"), sets `bmp_map` to the first valid record. If `svc_kei_ucwk_no` is provided, matches exactly and breaks early.

| # | Type | Code |
|---|------|------|
| 1 | SET | `bmp_map = null` // Initialize bango map reference |
| 2 | FOR | `for (HashMap<String, Object> tu0011_b010_map : tu0011_b010_list)` // Iterate over bango overview records |
| 3 | IF | `[IF] BMP_KOJI_STAT == "090" (Cancelled)` (L837) |

> `tu0011_b010_map.get(ETU0011B010CBSMsg1List.BMP_KOJI_STAT)` equals "090" — Skip records already marked as cancelled.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `continue` // Skip cancelled bango records (BMP_KOJI_STAT == "090") |

4. **Block 4.1** — [SET] Store valid bango record (L839)

> `bmp_map = tu0011_b010_map` — Assign the first non-cancelled bango record to `bmp_map`.

| # | Type | Code |
|---|------|------|
| 1 | SET | `bmp_map = tu0011_b010_map` // Store first non-cancelled bango record |

**Block 4.2** — [IF] Match by service detail work number (L841–843)

> `[svc_kei_ucwk_no != null && equals(bango record)]` — If a service detail work number was provided and matches this record, break out of the loop (exact match found).

| # | Type | Code |
|---|------|------|
| 1 | IF | `[svc_kei_ucwk_no non-empty] && [svc_kei_ucwk_no equals bango record SVC_KEI_UCWK_NO]` (L841) |
| 2 | EXEC | `break` // Exact match found — exit loop |

> If the loop exhausts without finding a match or a non-null svc_kei_ucwk_no was not provided, `bmp_map` will hold the first non-cancelled record.

**Block 5** — [IF] Early return if no valid bango found (L853–856)

> `[bmp_map == null]` — If no non-cancelled bango record was found, return silently.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return` // Bango info not found after filtering — early exit |

**Block 6** — [SET] Query bango work permit detail (L858–866)

> Uses the bango work number from the matched record to query the detailed bango work permit information (ETU0011A010).

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `condMap.clear()` // Reset condition map |
| 2 | SET | `condMap.put("key_bmp_koji_no", bmp_map.get(BMP_KOJI_NO))` // [-> "key_bmp_koji_no"] Map bango work number as condition |
| 3 | CALL | `mapper.setETU0011A010(keepReqParam, keepFixedText, condMap)` // Populate request param with ETU0011A010 CBS message conditions |
| 4 | CALL | `scCall.run(reqMap, keepSesHandle)` // Execute SC request for bango work permit detail |
| 5 | CALL | `tu0011_a010_map = mapper.getETU0011A010(keepReqParam, keepFixedText, resMap)` // Extract bango work permit detail |
| 6 | CALL | `mapper.scResultCheck(keepReqParam)` // Validate SC call result |

**Block 7** — [IF] Early return if detail not found (L867–869)

> `[tu0011_a010_map == null || empty]` — If the bango work permit detail cannot be retrieved, return silently.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return` // Bango work detail not found — early exit |

**Block 8** — [SET] Retrieve bango work status (L873)

> Extracts the bango work status from the detail record for the status check that follows.

| # | Type | Code |
|---|------|------|
| 1 | SET | `bmpKojiSvcStat = tu0011_a010_map.get(BMP_KOJI_STAT)` // [-> "bmp_koji_stat"] Get bango work status |

**Block 9** — [IF] Check if bango cancellation notification is needed (L876–911)

> `[bmpKojiSvcStat != KOJIFIN(050) AND != KOJICL(090)]` — If the bango work status is neither "work completed" nor "work cancelled", issue a bango cancellation notification.

| # | Type | Code |
|---|------|------|
| 1 | IF | `[bmpKojiSvcStat != "050" (KOJIFIN)] && [bmpKojiSvcStat != "090" (KOJICL)]` (L876) |

> **Business meaning**: Only issue cancellation notification for active/in-progress bango work. If the work is already completed (050) or already cancelled (090), no further notification is needed.

| # | Type | Code |
|---|------|------|
| 1 | SET | `mskmYmd = JCCBPCommon.getOpeDate(null)` // [-> "Submission date"] Get current operational date |
| 2 | SET | `nttUkNo = tu0011_a010_map.get(NTT_UK_NO)` // [-> "ntt_uk_no"] Get NTT acceptance number from detail |
| 3 | CALL | `addTaiorrk(handle, param, fixedText, "02" (Registration type: Bango cancellation notification), sysid, null (Customer name — resolved internally), mskmYmd (Submission date), nttUkNo (NTT acceptance number), null (Telephone number), null (Installation location postal code), svcKeiNo (Service contract number), null (Work completion datetime), orgCd (Organization code), orgNm (Organization name))` // Register the bango cancellation notification response history log |

**Block 9.1** — [ELSE] Implicit — when status IS terminal (KOJIFIN or KOJICL)

> The condition `!(KOJIFIN || KOJICL)` is negated. When the status IS terminal, the entire block body is skipped — no log entry is created. This is intentional: completed or already-cancelled bango work does not require cancellation notification.

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `bmp_koji_stat` | Field | Bango work status — a status code indicating the current state of a construction site (bango) work order |
| `bmp_koji_no` | Field | Bango work number — unique identifier for a bango construction work order |
| `svc_kei_ucwk_no` | Field | Service detail work number — internal tracking ID for a service contract line item/work order |
| `svc_kei_no` | Field | Service contract number — unique identifier for a customer's service line in K-Opticom's system |
| `ntt_uk_no` | Field | NTT acceptance number — the number assigned by NTT when accepting a fiber installation request |
| `org_cd` | Field | Organization code — identifies the organizational unit performing the action |
| `org_nm` | Field | Organization name — human-readable name of the organizational unit |
| KOJIFIN | Constant | "050" — Bango work status: Work Complete (bancho koji kanryo) |
| KOJICL | Constant | "090" — Bango work status: Work Cancelled (bancho koji torikeshi) |
| "090" (in loop filter) | Status code | Bango work cancelled status — records with this status are excluded from the matching loop |
| bango (番父) | Business term | Bango / bancho — refers to a construction site or work site for fiber installation work. Used in Japanese telecom to denote the physical location where construction takes place |
| kansei (完了) | Business term | Completion — the terminal state of a bango work order when construction is finished |
| torikeshi (取消) | Business term | Cancellation — the terminal state when a bango work order is cancelled |
| Taiorrk (対応履歴) | Business term | Response history — a log/audit trail table recording customer-facing actions and notifications |
| addTaiorrk | Method | Registers a response history log entry — the method responsible for writing to the T_RESPONSE_HISTORY equivalent table |
| ETU0011B010 | CBS Msg | Bango work overview list message — retrieves a list of bango work records for a given service contract and telephone number |
| ETU0011A010 | CBS Msg | Bango work permit detail message — retrieves detailed information for a specific bango work permit |
| SC | Acronym | Service Component — the microservice/enterprise service in the K-Opticom architecture that handles business logic for specific operations |
| CBS | Acronym | CBS Message Service — the message-based service communication layer used to invoke SC operations |
| K-Opticom | Business term | A Japanese telecommunications carrier providing fiber-optic internet and telecom services |
| FTTH | Business term | Fiber To The Home — the fiber-optic broadband service type where K-Opticom installs physical infrastructure at customer premises |
| `keepReqParam` | Instance field | ThreadLocal request parameter map — shared context holder for SC request parameters across method calls |
| `keepFixedText` | Instance field | ThreadLocal fixed text dictionary — holds localized text resources for SC message handling |
| `keepSesHandle` | Instance field | ThreadLocal session handle — database/transaction session reference passed to SC invocations |
| SYSID | Field | System ID — identifies the calling application or system within the K-Opticom platform |
| `mskmYmd` | Variable | Moushikomi Bi (申込日月) — the submission date for the response history log entry, derived from the current operational date |