# Business Logic — JBSbatKKMiStcKikiInfStku.executeKKtkAndUcwk() [71 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.business.service.JBSbatKKMiStcKikiInfStku` |
| Layer | Service (Batch Processing Layer) |
| Module | `service` (Package: `eo.business.service`) |

## 1. Role

The `executeKKtkAndUcwk()` method retrieves and validates equipment-provided service contracts and their associated service contract line items (detailed breakdowns) within the K-Opticom customer core system. It serves as a data-integrity gate used during equipment provision operations — specifically when transferring or migrating equipment-related service contract records. The method first queries the equipment-provided service contract table (`KK_T_KKTK_SVC_KEI`) using the STB (Set-Top Box) service code `"C009"` to locate the relevant contract. If the contract exists and its status is "Contract Change In Progress" (契約変更中), the method returns early with the contract number, generation timestamp, and terminal model code, signaling that the system should handle the contract-change path separately. For all other valid cases, it proceeds to search for the linked service contract detail record via a dedicated select service component. If the detail record is missing, it throws a business exception. If the detail record exists but is in an unexpected status (i.e., not "Contracted" / 締結済 or "Service In Progress" / サービス提供中), it logs an error and aborts processing. On successful validation, it transfers the service contract detail number and its generation timestamp to the output map. The method follows a **delegation + early-return** pattern, where self-contained status checks trigger early exits, and a dedicated service-component call delegates the actual database query for contract details.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["executeKKtkAndUcwk(params)"])
    A["Search Equipment-Provided Service Contract<br/>searchKktk(svc_no, C009=STB, err_val)"]
    B{db_map != null?<br/>Contract found?}
    C["Check Service Status<br/>isSvcStatKktkChg()"]
    D{Status = 'Contract<br/>Change In Progress'?}
    E["Set svc_no_key, gene_key,<br/>TAKNKIKI_MODEL_CD on out_map"]
    F["Set outFlg = true<br/>Return out_map"]
    G["Set svc_no_key, gene_key<br/>on out_map"]
    H["Extract ucwk_no from<br/>SVC_KEI_UCWK_NO"]
    I["Build param[0]=ucwk_no,<br/>param[1]=opeDate"]
    J["Search Service Contract Detail<br/>executeKK_T_SVC_KEI_UCWK_KK_SELECT_020(param)"]
    K["Retrieve next row<br/>db_KK_T_SVC_KEI_UCWK.selectNext()"]
    L{db_map != null?<br/>Detail found?}
    M["Throw JBSbatBusinessException<br/>Error: detail contract missing"]
    N["Check Valid Status<br/>isSvcStatUcwk()"]
    O{Status = 'Contracted'<br/>or 'Service In Progress'?}
    P["Log Error + Throw<br/>JBSbatBusinessError<br/>Status mismatch"]
    Q["Set ucwk_no_key, ucwk_gene_key<br/>on out_map"]
    R["Set outFlg = true"]
    S["Return out_map"]

    START --> A
    A --> B
    B -->|No| S
    B -->|Yes| C
    C --> D
    D -->|Yes| E
    E --> F
    D -->|No| G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> L
    L -->|No| M
    L -->|Yes| N
    N --> O
    O -->|No| P
    O -->|Yes| Q
    Q --> R
    R --> S
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `svc_no` | `String` | Equipment-provided service contract number — the unique identifier for the equipment provision service contract record in the system (e.g., a Set-Top Box service agreement). This is the primary key used to look up the contract. |
| 2 | `out_map` | `JBSbatServiceInterfaceMap` | Output information map — the shared data structure into which this method writes its results (contract number, timestamps, model code, detail contract number, etc.). It is both read and mutated throughout the method's lifecycle. |
| 3 | `svc_no_key` | `String` | The key/name used within `out_map` to store the transferred equipment-provided service contract number. |
| 4 | `gene_key` | `String` | The key/name used within `out_map` to store the transferred generation registration timestamp (年月日時分秒 — year/month/day/hour/minute/second) of the service contract. |
| 5 | `ucwk_no_key` | `String` | The key/name used within `out_map` to store the transferred service contract detail (line item) number. |
| 6 | `ucwk_gene_key` | `String` | The key/name used within `out_map` to store the transferred generation registration timestamp of the service contract detail. |
| 7 | `err_val` | `String` | Error log output text — a contextual label or value embedded into error messages and log entries, used to identify which processing instance or context triggered the error. |

**Instance fields / external state read:**
| Name | Type | Business Description |
|------|------|---------------------|
| `db_KK_T_SVC_KEI_UCWK` | `JBSbatKK_T_SVC_KEI_UCWK` (instance field) | The entity/table handler for the service contract detail table (`KK_T_SVC_KEI_UCWK`), used to retrieve queried rows via `selectNext()`. |
| `super.opeDate` | `String` (inherited) | The operation date (processing date), set by a parent class. Used as a parameter when querying service contract details. |
| `super.logPrint` | `LogPrint` (inherited) | The logging utility for printing business error logs, used when reporting status mismatches. |

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `searchKktk` | EKK (Equipment Provision) | `KK_T_KKTK_SVC_KEI` | Searches the equipment-provided service contract table for the contract matching `svc_no` with service code `"C009"` (STB). Reads contract record including status, generation timestamp, model code, and detail contract number. |
| R | `isSvcStatKktkChg` | EKK (Self) | `KK_T_KKTK_SVC_KEI` | Internal helper that checks whether the equipment-provided service contract status is "Contract Change In Progress" (契約変更中). Evaluates status code from `KKTK_SVC_KEI_STAT` column. |
| C | `executeKK_T_SVC_KEI_UCWK_KK_SELECT_020` | EKK (Self) | `KK_T_SVC_KEI_UCWK` | Invokes the service component to search for the service contract detail record using the detail contract number and operation date as parameters. Sets up the query context on `db_KK_T_SVC_KEI_UCWK`. |
| R | `db_KK_T_SVC_KEI_UCWK.selectNext` | EKK (Self) | `KK_T_SVC_KEI_UCWK` | Retrieves the next row from the already-queried service contract detail entity. Returns the matching contract detail record (including status, generation timestamp, etc.) or `null` if not found. |
| R | `isSvcStatUcwk` | EKK (Self) | `KK_T_SVC_KEI_UCWK` | Internal helper that checks whether the service contract detail status is in a valid state — specifically "Contracted" (締結済) or "Service In Progress" (サービス提供中). Evaluates status code from `SVC_KEI_UCWK_STAT` column. |
| R | `getStatNm` | EKK (Self) | — | Internal helper that returns the human-readable name of a contract status code (e.g., maps status code to "Contracted", "Service In Progress", etc.). Used in error logging. |
| - | `JBSbatStringUtil.Rtrim` | Common / Utility | — | Trims trailing whitespace from string values read from database maps. Applied to timestamp, model code, and detail number fields. |
| - | `out_map.set` | Common / Utility | — | Stores key-value pairs into the output map (transfers data to caller). Used for `svc_no`, `gene_key`, `TAKNKIKI_MODEL_CD`, `ucwk_no`, `ucwk_gene_key`. |
| - | `out_map.setOutFlg` | Common / Utility | — | Sets an output flag on the map to signal that processing completed successfully and data is available. |
| - | `JKKBatOneTimeLogWriter.printBusinessErrorLog` (via super.logPrint) | Common / Logging | — | Logs a business error when the service contract detail status is unexpected (not "Contracted" or "Service In Progress"). |

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Class: JBSbatKKMiStcKikiInfStku | `JBSbatKKMiStcKikiInfStku.execute()` -> `JBSbatKKMiStcKikiInfStku.executeKKtkAndUcwk()` | `searchKktk [R] KK_T_KKTK_SVC_KEI`, `executeKK_T_SVC_KEI_UCWK_KK_SELECT_020 [R] KK_T_SVC_KEI_UCWK`, `selectNext [R] KK_T_SVC_KEI_UCWK`, `setOutFlg [-]`, `printBusinessErrorLog [-]` |

## 6. Per-Branch Detail Blocks

**Block 1** — [LOCAL DECLARATION] `(Line 1073)`

Initialize local variables for the method.

| # | Type | Code |
|---|------|------|
| 1 | SET | `String[] param = null;` // Local array to hold parameters for service contract detail search |

**Block 2** — [METHOD CALL] `(Line 1077)`

Search for the equipment-provided service contract. Updated in v22.00.00 to use the constant `JBSbatKKConst.KKTK_SVC_CD_STB` instead of a direct reference.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `db_map = searchKktk(svc_no, JBSbatKKConst.KKTK_SVC_CD_STB, err_val)` // Search equipment-provided service contract. `[-> KKTK_SVC_CD_STB = "C009" (STB = Set-Top Box)]` |

**Block 3** — [IF] `(null != db_map)` — Contract exists — `(Line 1081)`

If the equipment-provided service contract was found, proceed to validate its status and process the service contract detail.

**Block 3.1** — [IF] `(isSvcStatKktkChg(db_map, KKTK_SVC_KEI_STAT))` — Contract status is "Contract Change In Progress" — `(Line 1084)`

When the equipment-provided service contract status is "Contract Change In Progress" (契約変更中), return early with the contract-level information. This allows the caller to handle the contract-change flow separately without querying for the service contract detail.

| # | Type | Code |
|---|------|------|
| 1 | SET | `out_map.set(svc_no_key, svc_no)` // Transfer the equipment-provided service contract number to out_map |
| 2 | EXEC | `out_map.set(gene_key, JBSbatStringUtil.Rtrim(db_map.getString(GENE_ADD_DTM)))` // Transfer the generation registration timestamp, trimming whitespace |
| 3 | EXEC | `out_map.set(TAKNKIKI_MODEL_CD, JBSbatStringUtil.Rtrim(db_map.getString(TAKNKIKI_MODEL_CD)))` // Transfer the terminal (home equipment) model code, trimming whitespace |
| 4 | EXEC | `out_map.setOutFlg(true)` // Set output flag to true, indicating data is available |
| 5 | RETURN | `return out_map` // Early return — do not proceed to service contract detail query |

**Block 3.2** — [PROCESSING] — Contract exists but status is NOT "Contract Change In Progress" — `(Line 1092)`

Continue normal processing: transfer contract-level data and then search for the service contract detail.

| # | Type | Code |
|---|------|------|
| 1 | SET | `out_map.set(svc_no_key, svc_no)` // Transfer service contract number to out_map |
| 2 | EXEC | `out_map.set(gene_key, JBSbatStringUtil.Rtrim(db_map.getString(GENE_ADD_DTM)))` // Transfer generation timestamp of the service contract |
| 3 | SET | `String ucwk_no = JBSbatStringUtil.Rtrim(db_map.getString(SVC_KEI_UCWK_NO))` // Extract the service contract detail number from the contract record |
| 4 | SET | `param = new String[2]` // Allocate parameter array for the detail search |
| 5 | SET | `param[0] = ucwk_no` // Set first parameter: the service contract detail number |
| 6 | SET | `param[1] = super.opeDate` // Set second parameter: the operation date from parent class |
| 7 | CALL | `executeKK_T_SVC_KEI_UCWK_KK_SELECT_020(param)` // Search for the service contract detail by detail number and operation date |
| 8 | SET | `db_map = db_KK_T_SVC_KEI_UCWK.selectNext()` // Retrieve the queried service contract detail record |

**Block 3.2.1** — [IF] `(null == db_map)` — Service contract detail NOT found — `(Line 1104)`

If the service contract detail query returns no record, this is a data integrity error — the linked detail contract is missing. Throw a business exception with a descriptive message including both the detail number and the parent service contract number.

| # | Type | Code |
|---|------|------|
| 1 | SET | `String value = "Service contract detail number: " + ucwk_no + " (Equipment-provided service contract number (" + err_val + "): " + svc_no + ")"` // Build error message with detail number and service contract number |
| 2 | CALL | `throw new JBSbatBusinessException(JPCBatchMessageConstant.EKKB0210CE, new String[]{"KK_T_SVC_KEI_UCWK", value})` // Throw business exception indicating the detail contract is missing from table KK_T_SVC_KEI_UCWK |

**Block 3.2.2** — [IF] `(!isSvcStatUcwk(db_map, SVC_KEI_UCWK_STAT))` — Service contract detail status is NOT valid — `(Line 1111)`

When the service contract detail record exists but its status is neither "Contracted" (締結済) nor "Service In Progress" (サービス提供中), log an error and abort. The status value is appended to the error message for diagnostic purposes.

| # | Type | Code |
|---|------|------|
| 1 | SET | `String value = "Service contract detail number: " + ucwk_no + " (Equipment-provided service contract number (" + err_val + "): " + svc_no + ")"` // Build error message |
| 2 | SET | `value = value + " " + getStatNm(db_map, SVC_KEI_UCWK_STAT)` // Append human-readable status name for diagnostics |
| 3 | EXEC | `super.logPrint.printBusinessErrorLog(JPCBatchMessageConstant.EKKB0010CW, new String[]{value})` // Log the error via business error log with error code EKKB0010CW |
| 4 | CALL | `throw new JBSbatBusinessError()` // Throw generic business error to abort processing |

**Block 3.2.3** — [ELSE] — Service contract detail status IS valid — `(Line 1118)`

The service contract detail is found and has a valid status ("Contracted" or "Service In Progress"). Transfer the detail number and its generation timestamp to the output map and mark processing as successful.

| # | Type | Code |
|---|------|------|
| 1 | SET | `out_map.set(ucwk_no_key, ucwk_no)` // Transfer the service contract detail number to out_map |
| 2 | EXEC | `out_map.set(ucwk_gene_key, JBSbatStringUtil.Rtrim(db_map.getString(GENE_ADD_DTM)))` // Transfer the generation registration timestamp of the detail record |
| 3 | EXEC | `out_map.setOutFlg(true)` // Set output flag to true, indicating successful completion |

**Block 4** — [RETURN] `(Line 1129)`

Return the output map to the caller. If the original contract search found no record (`db_map == null`), this returns the unmodified `out_map`.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return out_map` // Return output map — either with transferred data or unmodified if no contract was found |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `svc_no` | Field | Service contract number (契約番号) — The unique identifier for an equipment-provided service contract, used as the primary lookup key. |
| `ucwk_no` | Field | Service contract detail number (サービス契約内訳番号) — The unique identifier for a line item within a service contract, linking to the detailed breakdown of services. |
| `gene_key` / `ucwk_gene_key` | Field | Generation registration timestamp key — Keys used to store the year/month/day/hour/minute/second (年月日時分秒) of when a contract or detail record was created/registered. |
| `svc_no_key` | Field | Service contract number transfer key — The key used in the output map to store the transferred service contract number. |
| TAKNKIKI_MODEL_CD | Field | Terminal (home equipment) model code (家電機器型式コード) — The model identifier for home equipment (e.g., Set-Top Box) provided as part of the service contract. |
| KKTK_SVC_CD_STB | Constant | Service code for STB / Set-Top Box equipment = `"C009"` — Used to filter equipment-provided service contracts by equipment type. |
| `KKTK_SVC_KEI_STAT` | Field | Equipment-provided service contract status (機器提供サービス契約ステータス) — The status field of the `KK_T_KKTK_SVC_KEI` table, indicating the current lifecycle state of the contract. |
| `SVC_KEI_UCWK_STAT` | Field | Service contract detail status (サービス契約内訳ステータス) — The status field of the `KK_T_SVC_KEI_UCWK` table, indicating the current lifecycle state of the contract detail. |
| `GENE_ADD_DTM` | Field | Generation registration timestamp (世代登録年月日時分秒) — The date/time when a record was registered into the system as a new generation/version. |
| `SVC_KEI_UCWK_NO` | Field | Service contract detail number (サービス契約内訳番号) — The foreign key linking a service contract to its detailed line-item records. |
| `opeDate` | Field | Operation date (操作日) — The business processing date inherited from the parent class, used as a parameter for contract detail queries. |
| KK_T_KKTK_SVC_KEI | Table | Equipment-provided service contract table (機器提供サービス契約表) — Database table storing equipment provision service contract records including status, model code, generation timestamp, and linked detail contract number. |
| KK_T_SVC_KEI_UCWK | Table | Service contract detail table (サービス契約内訳表) — Database table storing individual line-item records within a service contract, including status, payment method, and plan information. |
| "Contract Change In Progress" | Status | 契約変更中 — A contract lifecycle state indicating that the equipment-provided service contract is currently being modified. Causes early return from this method. |
| "Contracted" | Status | 締結済 — A valid service contract detail status indicating the contract has been formally executed/agreed. |
| "Service In Progress" | Status | サービス提供中 — A valid service contract detail status indicating the service is actively being provided to the customer. |
| STB | Acronym | Set-Top Box — A telecommunications device provided as part of a fiber-optic or broadband service contract. |
| JBSbatServiceInterfaceMap | Class | Service interface map — A shared key-value data structure used across service methods to pass input and output data between processing layers. |
| JBSbatBusinessException | Class | Business exception — A checked exception wrapping a business logic error with an error code and parameterized message, thrown when data integrity is violated (e.g., missing detail contract). |
| JBSbatBusinessError | Class | Business error — A runtime exception used to signal non-recoverable business logic failures, thrown when a record exists but is in an invalid/unexpected state. |
| EKKB0210CE | Error Code | Error code indicating a missing database record in table `KK_T_SVC_KEI_UCWK` (service contract detail table not found). |
| EKKB0010CW | Error Code | Error code indicating a logged warning that processing is being skipped due to unexpected status. |