# Business Logic — JBSbatKKMiStcKikiInfStku.executeKktkSvcNo() [33 LOC]

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

## 1. Role

### JBSbatKKMiStcKikiInfStku.executeKktkSvcNo()

This method performs **equipment provision service contract number lookup processing** (機器提供サービス契約番号検索処理). It is the primary query entry point for retrieving active equipment provision service contracts in the K-Opticom customer base system. The method accepts a service contract number (`svc_no`) and service code (`svc_cd`), queries the equipment provision service contract table (`KK_T_KKTK_SVC_KEI`), and then validates that the contract's status is one of the three valid operational states: **Contracted** (`030`), **Contract Change in Progress** (`110`), or **Service in Progress** (`100`). If the contract is not found, or if its status is in any other state (e.g., Terminated, Suspended, Canceled), the method throws a `JBSbatBusinessError` after logging a business error with code `EKKB0010CW`. On successful validation, the method populates the output map (`out_map`) with the service contract number, the generation registration timestamp (`GENE_ADD_DTM`), and the indoor equipment model code (`TAKNKIKI_MODEL_CD`), and sets a transfer flag (`setOutFlg(true)`) to signal that data was successfully retrieved. The method follows a **routing + validation + data transfer** pattern, acting as a shared service utility called by higher-level batch/screen processing methods (e.g., `execute()`) that need to transfer or reference equipment provision service contract data to downstream processing.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["executeKktkSvcNo"])
    SEARCH["searchKktk(svc_no, svc_cd, err_val)"]
    CHECK_NULL{db_map != null?}
    CHECK_STAT{isSvcStat?<br/>030 or 110 or 100?}
    ERROR["Log error EKKB0010CW<br/>throw JBSbatBusinessError"]
    SET_SVC_NO["out_map.set(svc_no_key, svc_no)"]
    SET_GENE["out_map.set(gene_key, Rtrim)"]
    SET_MODEL["out_map.set(TAKNKIKI_MODEL_CD, Rtrim)"]
    SET_FLG["out_map.setOutFlg(true)"]
    RETURN["return out_map"]

    START --> SEARCH --> CHECK_NULL
    CHECK_NULL -->|Yes| CHECK_STAT
    CHECK_NULL -->|No| RETURN
    CHECK_STAT -->|Yes 030 110 100| SET_SVC_NO
    CHECK_STAT -->|No| ERROR
    SET_SVC_NO --> SET_GENE --> SET_MODEL --> SET_FLG --> RETURN
```

**Constant Resolution:**
- `JBSbatKKConst.SVC_KEI_STAT_CNC_ZM = "030"` — Status: Contracted (契約済)
- `JBSbatKKConst.SVC_KEI_STAT_SVCCHG_CHU = "110"` — Status: Contract Change in Progress (契約変更中)
- `JBSbatKKConst.SVC_KEI_STAT_SVCTK_CHU = "100"` — Status: Service in Progress (サービス提供中)

The method executes the following processing flow:

1. **Search** — Calls `searchKktk()` to query the equipment provision service contract table by `svc_no` and `svc_cd`.
2. **Null check** — If no record is found (`db_map == null`), skip processing and return the `out_map` as-is (no error is raised for missing records).
3. **Status validation** — If a record is found, call `isSvcStat()` to verify the contract status (`KKTK_SVC_KEI_STAT`) is one of the valid operational states (`030`, `110`, `100`).
4. **Error branch** — If the status is not in the valid set, construct an error message including the service contract number and the current status name, log it using `printBusinessErrorLog` with error code `EKKB0010CW`, and throw `JBSbatBusinessError`.
5. **Success branch** — If the status is valid, populate `out_map` with the service contract number, generation registration timestamp (right-trimmed), and indoor equipment model code (right-trimmed). Set the output flag to `true`.
6. **Return** — Return the `out_map` to the caller.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `svc_no` | `String` | Equipment provision service contract number — the unique identifier for an equipment provision service contract record to look up in the KK_T_KKTK_SVC_KEI table |
| 2 | `svc_cd` | `String` | Equipment provision service code — classifies the type of equipment provision service (e.g., FTTH, broadband, etc.), used as a secondary key in the contract search |
| 3 | `out_map` | `JBSbatServiceInterfaceMap` | Output information map — the destination data structure into which the method writes the retrieved contract number, generation timestamp, and equipment model code; also serves as the return value carrier |
| 4 | `svc_no_key` | `String` | Key name for the transfer destination equipment provision service contract number — the map key under which `svc_no` is stored in `out_map` for downstream consumers |
| 5 | `gene_key` | `String` | Key name for the transfer destination generation registration timestamp — the map key under which the `GENE_ADD_DTM` (record creation datetime, right-trimmed) is stored in `out_map` |
| 6 | `err_val` | `String` | Error log output phrase — a contextual label appended to the error message when status validation fails, used to identify which service contract number triggered the error in logs |

**External state read by the method:**
- No instance fields are directly read by this method. All dependencies are resolved through method calls (`searchKktk`, `isSvcStat`, `getStatNm`).

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JBSbatKKMiStcKikiInfStku.searchKktk` | - | `KK_T_KKTK_SVC_KEI` | Queries the equipment provision service contract table by service contract number and service code to retrieve the contract record |
| R | `JBSbatKKMiStcKikiInfStku.isSvcStat` | - | - (in-memory) | Validates the contract status field against valid operational statuses (`030`, `110`, `100`) |
| R | `JBSbatKKMiStcKikiInfStku.getStatNm` | - | - (in-memory) | Retrieves the human-readable status name for the current contract status, used in error logging |
| R | `JBSbatStringUtil.Rtrim` | - | - (in-memory) | Right-trims whitespace from string values — used on `GENE_ADD_DTM` and `TAKNKIKI_MODEL_CD` before writing to `out_map` |
| - | `JBSbatServiceInterfaceMap.set` | - | - (in-memory) | Writes data values into the output map by key — used for `svc_no_key`, `gene_key`, and `TAKNKIKI_MODEL_CD` |
| - | `JBSbatServiceInterfaceMap.setOutFlg` | - | - (in-memory) | Sets the output flag to `true` to signal successful data retrieval to downstream consumers |
| - | `super.logPrint.printBusinessErrorLog` | - | - (in-memory) | Logs a business-level error with code `EKKB0010CW` when the contract status is not valid; includes the error value and service contract number in the log message |
| - | `JBSbatBusinessError` constructor | - | - | Throws a business error exception to abort processing when contract status validation fails |

**How to classify:**
- **R** (Read): `searchKktk` reads from the equipment provision service contract table; `isSvcStat` and `getStatNm` perform in-memory validation; `Rtrim` operates on in-memory strings.
- No Create (C), Update (U), or Delete (D) operations — this method is purely a read-and-validate entry point.

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.
Terminal operations from this method: `setOutFlg` [-], `Rtrim` [-], `printBusinessErrorLog` [-], `Rtrim` [-], `getString` [R], `getString` [R], `getStatNm` [R], `isSvcStat` [R], `searchKktk` [R]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | `JBSbatKKMiStcKikiInfStku.execute` | `execute` -> `executeKktkSvcNo` | `searchKktk [R] KK_T_KKTK_SVC_KEI` |

## 6. Per-Branch Detail Blocks

**Block 1** — [ASSIGN] `db_map = searchKktk(...)` (L1014)

> Search the equipment provision service contract table and store the result in `db_map`.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `db_map = searchKktk(svc_no, svc_cd, err_val)` // Query KK_T_KKTK_SVC_KEI by service contract number and code [-> KK_T_KKTK_SVC_KEI [R]] |

**Block 2** — [IF] `null != db_map` (L1017)

> If a contract record is found, proceed with status validation. If not found, skip to return.

**Block 2.1** — [ELSE] `null == db_map` — implicit branch (L1017)

> No contract record found. Skip all processing and return `out_map` unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return out_map` // Return without modification when no record found |

**Block 2.2** — [IF] `!isSvcStat(db_map, KKTK_SVC_KEI_STAT)` (L1025)

> [KKTK_SVC_KEI_STAT = "KKTK_SVC_KEI_STAT"] — Check if the contract status is NOT one of the valid statuses. Valid statuses per `isSvcStat` are `SVC_KEI_STAT_CNC_ZM="030"` (Contracted / 契約済), `SVC_KEI_STAT_SVCCHG_CHU="110"` (Contract Change in Progress / 契約変更中), and `SVC_KEI_STAT_SVCTK_CHU="100"` (Service in Progress / サービス提供中).

> If the status is NOT 030, 110, or 100, log an error and throw a business exception.

| # | Type | Code |
|---|------|------|
| 1 | SET | `value = "機器提供サービス契約番号(" + err_val + ")：" + svc_no + " " + getStatNm(db_map, KKTK_SVC_KEI_STAT)` // Build error message with service contract number and current status name [-> EKKB0010CW error format] |
| 2 | EXEC | `super.logPrint.printBusinessErrorLog(JPCBatchMessageConstant.EKKB0010CW, new String[]{value})` // Log business error [-> EKKB0010CW] |
| 3 | EXEC | `throw new JBSbatBusinessError()` // Abort processing with business error |

**Block 2.3** — [ELSE] Status IS valid (030 / 110 / 100) (L1031)

> The contract status is valid. Populate `out_map` with the retrieved data and set the output flag.

| # | Type | Code |
|---|------|------|
| 1 | SET | `out_map.set(svc_no_key, svc_no)` // Store service contract number into out_map under the transfer key |
| 2 | SET | `out_map.set(gene_key, JBSbatStringUtil.Rtrim(db_map.getString(GENE_ADD_DTM)))` // Store right-trimmed generation registration datetime [-> GENE_ADD_DTM = "GENE_ADD_DTM" (generation registration year/month/day/hour/minute/second / 世代登録年月日時分秒)] |
| 3 | SET | `out_map.set(TAKNKIKI_MODEL_CD, JBSbatStringUtil.Rtrim(db_map.getString(TAKNKIKI_MODEL_CD)))` // Store right-trimmed indoor equipment model code [-> TAKNKIKI_MODEL_CD = "TAKNKIKI_MODEL_CD" (indoor equipment model code / 屋内機器型式コード)] |
| 4 | EXEC | `out_map.setOutFlg(true)` // Set output flag to true to signal successful retrieval |

**Block 3** — [RETURN] (L1038)

> Return the populated `out_map` to the caller regardless of which branch was taken.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return out_map` // Return output map with or without data |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| 機器提供サービス契約 (Kiki Teikyou Service Keiyaku) | Japanese field | Equipment Provision Service Contract — a contract record linking a customer to equipment (e.g., STB, ONT) provided by K-Opticom for service delivery |
| `KK_T_KKTK_SVC_KEI` | Database table | Equipment Provision Service Contract table — stores contract-level data including status, service codes, timestamps, and equipment model information |
| `KKTK_SVC_KEI_NO` | Field | Equipment Provision Service Contract Number — the unique identifier for a service contract record |
| `KKTK_SVC_KEI_STAT` | Field | Equipment Provision Service Contract Status — the current state of the contract (e.g., Contracted, Service in Progress, Terminated) |
| `KKTK_SVC_CD` | Field | Equipment Provision Service Code — classifies the type of equipment provision service |
| `GENE_ADD_DTM` | Field | Generation Registration Year/Month/Day/Hour/Minute/Second — the timestamp when the record was originally registered in the system (世代登録年月日時分秒) |
| `TAKNKIKI_MODEL_CD` | Field | Indoor Equipment Model Code — the model code of the customer premises equipment (e.g., STB, ONT) installed for the service (屋内機器型式コード) |
| `SVC_KEI_STAT_CNC_ZM = "030"` | Constant | Status: Contracted (契約済) — the contract has been concluded and is active |
| `SVC_KEI_STAT_SVCCHG_CHU = "110"` | Constant | Status: Contract Change in Progress (契約変更中) — a modification to the contract is currently being processed |
| `SVC_KEI_STAT_SVCTK_CHU = "100"` | Constant | Status: Service in Progress (サービス提供中) — the service is actively being delivered to the customer |
| `EKKB0010CW` | Error code | Business error message code — logged when a contract record is found but its status is not one of the valid operational states |
| `JBSbatBusinessError` | Exception | Business error exception — thrown to abort processing when business rules are violated (e.g., invalid contract status) |
| `out_map` | Parameter | Output information map — a key-value data structure that carries processed results to downstream components |
| `svc_no_key` | Parameter | Transfer destination service contract number key — the map key name for storing the service contract number in the output |
| `gene_key` | Parameter | Transfer destination generation timestamp key — the map key name for storing the record creation timestamp in the output |
| `err_val` | Parameter | Error log output phrase — contextual identifier appended to error messages for traceability |
| `Rtrim` | Utility | Right-trim — strips trailing whitespace from string values to ensure clean data in the output map |
| `setOutFlg(true)` | Operation | Output flag setter — signals to downstream consumers that data was successfully retrieved and available in `out_map` |
| `searchKktk` | Method | Equipment provision service contract search — queries the `KK_T_KKTK_SVC_KEI` table and returns a `JBSbatCommonDBInterface` result map |
| `isSvcStat` | Method | Service status validation — checks whether the contract status is one of the allowed operational states (030, 110, 100) |
| `getStatNm` | Method | Status name lookup — retrieves the human-readable name for a given contract status code, used in error messages |