# Business Logic — JBSbatKKSyuKeiStabunKikiStaAdd.executeKK_T_KAP_KEI_PKSELECT() [10 LOC]

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

## 1. Role

### JBSbatKKSyuKeiStabunKikiStaAdd.executeKK_T_KAP_KEI_PKSELECT()

This method performs a **Primary Key (PK) lookup** on the allocation contract table (`KK_T_KAP_KEI`) within the K-Opticom customer core system (eo customer core system / eo顧客基幹システム). Specifically, it retrieves an existing allocation contract record by its composite primary key consisting of the allocation contract number (`KAP_KEI_NO`) and the generation registration date/time (`GENE_ADD_DTM`). The method acts as a **delegation wrapper** — it maps the caller's simple `Object[]` parameters into a typed `JBSbatCommonDBInterface` result object suitable for use in downstream allocation contract creation logic. In the larger batch processing flow, it is invoked from the main `execute()` method when a subcontracted service contract (割込契約) has status `030` (Tiketsuke / 着付 — assigned contract status) but lacks a set allocation contract billing start date; in that scenario, the PK select fetches the current contract record so that a **new allocation contract entry** can be created with billing standard date incremented by one month. This method is the sole database read operation for the allocation contract entity within this batch service, and it follows the framework's standard `selectByPrimaryKeys` pattern for entity-safe, parameterized queries.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["executeKK_T_KAP_KEI_PKSELECT(whereParam)"])
    STEP1["Create JBSbatCommonDBInterface whereMap"]
    STEP2["whereMap.setValue(KAP_KEI_NO, whereParam[0])"]
    STEP3["whereMap.setValue(GENE_ADD_DTM, whereParam[1])"]
    STEP4["db_KK_T_KAP_KEI.selectByPrimaryKeys(whereMap)"]
    RETURN(["Return JBSbatCommonDBInterface result"])

    START --> STEP1
    STEP1 --> STEP2
    STEP2 --> STEP3
    STEP3 --> STEP4
    STEP4 --> RETURN
```

**Description:**
The method follows a linear, no-branch processing pattern:

1. **Create a `JBSbatCommonDBInterface` instance** named `whereMap` — this serves as the parameter container for the PK-based database query.
2. **Set the first PK field** — `KAP_KEI_NO` (allocation contract number) is set from `whereParam[0]`. This uniquely identifies the allocation contract within the system.
3. **Set the second PK field** — `GENE_ADD_DTM` (generation registration date/time) is set from `whereParam[1]`. This disambiguates the specific record version when the same contract number has multiple historical entries.
4. **Execute the PK select** — `db_KK_T_KAP_KEI.selectByPrimaryKeys(whereMap)` performs the database query against the `KK_T_KAP_KEI` table, returning a `JBSbatCommonDBInterface` with the matching record's data.
5. **Return the result** — The fetched record data is returned directly to the caller.

There are **no conditional branches**, loops, or error-handling blocks within this method. All conditional logic resides in the caller (`execute()`), which determines when this method is invoked based on allocation contract status checks.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `whereParam` | `Object[]` | An array containing exactly 2 elements: the primary key values for the allocation contract lookup. Element `[0]` is the allocation contract number (`KAP_KEI_NO`) — a unique identifier for a specific allocation contract line item. Element `[1]` is the generation registration date/time (`GENE_ADD_DTM`) — the timestamp when the contract record was originally created in the system, used to distinguish between multiple versions of the same contract number. The values are derived from the allocation contract information returned by the service component (CC) during the main processing flow, specifically after a subcontracted service contract (割込契約) is identified with status `030` (Tiketsuke / 着付) and no billing start date. |

**Instance fields read by this method:**
- `db_KK_T_KAP_KEI` — A `JBSbatSQLAccess` instance configured for the `KK_T_KAP_KEI` (Allocation Contract) table. Initialized in the `initial()` method of the parent service class.

## 4. CRUD Operations / Called Services

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

No separate CRUD table operations other than the single PK select below.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `db_KK_T_KAP_KEI.selectByPrimaryKeys(whereMap)` | — | `KK_T_KAP_KEI` | Primary Key select — retrieves the allocation contract record matching the composite key `(KAP_KEI_NO, GENE_ADD_DTM)`. Returns all fields of the contract record as a `JBSbatCommonDBInterface` object for downstream use. |

**Classification rationale:**
- The method name `selectByPrimaryKeys` clearly indicates a **Read (R)** operation.
- The entity/DB table is `KK_T_KAP_KEI` (Allocation Contract table), resolved from the instance field name `db_KK_T_KAP_KEI` which is configured with the table name constant `D_TBL_NAME_KK_T_KAP_KEI = "KK_T_KAP_KEI"` in the class header.
- No service component (SC) code is present in the method call — this is a direct database access through the `JBSbatSQLAccess` framework wrapper.

## 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: `selectByPrimaryKeys` [R] `KK_T_KAP_KEI`

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Batch: JBSbatKKSyuKeiStabunKikiStaAdd.execute() | `execute(inMap)` -> `executeKK_T_KAP_KEI_PKSELECT(param)` | `selectByPrimaryKeys [R] KK_T_KAP_KEI` |

**Caller details:**
- `JBSbatKKSyuKeiStabunKikiStaAdd.execute(JBSbatServiceInterfaceMap inMap)` — the main business processing method of this batch service. It calls `executeKK_T_KAP_KEI_PKSELECT()` with a 2-element `String[]` array containing the allocation contract number and generation registration date/time. The call occurs inside a conditional branch that checks whether the subcontracted service contract status is `030` (Tiketsuke / 着付 — assigned contract status per `JBSbatKKConst.KAP_KEI_STAT_TIKT`) and the billing start date is unset.

## 6. Per-Branch Detail Blocks

**Block 1** — [NEW] `(Create whereMap)` (L518)

> Instantiate a new `JBSbatCommonDBInterface` object to serve as the parameter container for the PK-based database query.

| # | Type | Code |
|---|------|------|
| 1 | SET | `whereMap = new JBSbatCommonDBInterface()` // Create parameter map container |

**Block 2** — [EXEC] `(Set KAP_KEI_NO PK field)` (L519)

> Set the first primary key field — allocation contract number — into the parameter map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `whereMap.setValue("KAP_KEI_NO", whereParam[0])` // Set allocation contract number [-> KAP_KEI_NO] |

**Block 3** — [EXEC] `(Set GENE_ADD_DTM PK field)` (L520)

> Set the second primary key field — generation registration date/time — into the parameter map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `whereMap.setValue("GENE_ADD_DTM", whereParam[1])` // Set generation registration date/time [-> GENE_ADD_DTM] |

**Block 4** — [CALL] `(Execute PK select)` (L523)

> Invoke the database framework's PK select method against the `KK_T_KAP_KEI` table. Returns a `JBSbatCommonDBInterface` containing the fetched record's data, or `null` if no matching record is found.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `db_KK_T_KAP_KEI.selectByPrimaryKeys(whereMap)` // PK-based DB read -> returns JBSbatCommonDBInterface |
| 2 | RETURN | `return db_KK_T_KAP_KEI.selectByPrimaryKeys(whereMap)` // Return fetched record or null |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `KAP_KEI_NO` | Field | Allocation contract number — unique identifier for a subcontracted/allocating contract line item within the service contract hierarchy. The prefix "KAP" derives from "割込" (wari-komi — allocation/subcontracting). |
| `GENE_ADD_DTM` | Field | Generation registration date/time — the system timestamp when an allocation contract record was originally created. Used as part of the composite primary key to distinguish between multiple historical versions of the same contract number. |
| `KK_T_KAP_KEI` | Table | Allocation Contract (割込契約) master table — stores detailed records of allocation/subcontracted service contracts including contract status, plan codes, billing dates, and penalty information. |
| `KAP_KEI_STAT` | Field | Allocation contract status — indicates the current state of an allocation contract. Value `030` (Tiketsuke / 着付) means the contract is in "assigned" status, indicating it has been linked to a parent service contract. |
| `KAP_KEI_CHRG_STDARD_YMD` | Field | Allocation contract billing standard year/month/day — the reference date from which allocation billing cycles are calculated. |
| `KAP_KEI_CHRG_STAYMD` | Field | Allocation contract billing start year/month/day — the actual date when billing commences for the allocation contract. |
| Tiketsuke (着付) | Business term | A Japanese accounting/business term meaning "assigned" or "attached" — in this context, it denotes an allocation contract that has been successfully linked to a parent service contract but whose billing has not yet been initiated. |
| `JBSbatCommonDBInterface` | Class | Framework interface for database query result objects — a structured map holding key-value pairs representing columns from the queried database record. |
| `JBSbatSQLAccess` | Class | Framework class providing database access abstraction — wraps SQL execution for a specific table and provides methods like `selectByPrimaryKeys`. |
| `selectByPrimaryKeys` | Method | Framework method that performs a PK-based SELECT query using the key-value pairs in the passed `JBSbatCommonDBInterface` parameter object. |
| Batch service | Concept | A K-Opticom internal batch processing framework (`JBSbatBusinessService`) for deferred, bulk operations on customer core data. |
| 割込契約 (Warikomi Keiyaku) | Business term | Allocation contract — a subsidiary contract line item that represents a portion of a main service contract, used for itemized billing and service tracking in the telecom service fulfillment domain. |
| `KAP_PLAN_CD` | Field | Allocation plan code — the billing/contract plan type associated with the allocation contract. |
| `KKTK_SVC_KEI_NO` | Field | Equipment provision service contract number — the service contract number for equipment (terminal) provisioning services within the allocation contract. |
| `ADD_JI_KIKI_CHG_NO` | Field | Registration-time equipment change number — the equipment change request number associated at the time of allocation contract creation. |
| `MSKM_DTL_NO` | Field | Details specification number — a unique identifier for the detailed service specification/plan selected. |
| `IDO_DIV` | Field | Movement classification — indicates the type of service change or transfer (e.g., new installation, transfer, modification). |
| `RSV_APLY_YMD` | Field | Reservation application year/month/day — the date when the service reservation was applied. |
| `RSV_CL_YMD` | Field | Reservation cancellation year/month/day — the date when a service reservation was cancelled. |
| `RSV_APLY_CD` | Field | Reservation application code — the classification code for the reservation type. |
| `KAP_IKT_SIKY_SWCH_YM` | Field | Allocation unified billing switch year/month — the month when allocation was switched to unified billing. |
| `KAP_KEI_CNC_YMD` | Field | Allocation contract conclusion year/month/day — the date the allocation contract was formally concluded/agreed. |
| `KAP_SEIKY_ENDYMD` | Field | Allocation billing end year/month/day — the date when allocation billing concludes. |
| `KAP_KEI_DSL_YMD` | Field | Allocation contract termination year/month/day — the date the allocation contract was terminated. |
| `PNLTY_HASSEI_CD` | Field | Penalty occurrence code — the code indicating whether and what type of penalty (liquidated damages) was triggered. |
| `KAP_KEI_CANCEL_YMD` | Field | Allocation contract cancellation year/month/day — the date the allocation contract was cancelled. |
| `KAP_SEIKY_STA_YM` | Field | Allocation billing start year/month — the month when allocation billing began. |
| `KAP_PAY_ZAN_CNT` | Field | Allocation remaining payment count — the number of remaining installment payments for the allocation contract. |
| `KAP_SEIKY_ZUMI_CNT` | Field | Allocation billed payment count — the number of allocation billing installments already completed. |
| `KAP_SEIKY_ZUMI_AMNT` | Field | Allocation billed amount — the cumulative amount already billed for the allocation contract. |
| `TNMT_BUY_TCHISHO_OPUT_SKCD` | Field | Terminal purchase notice output distinction code — controls whether a terminal purchase notification is output. |
| `TNMT_BUY_UK_TNTSHA_NM` | Field | Terminal purchase responsible party name — the name of the entity responsible for terminal purchase receipt. |
| `PRMOP_REKEIJI_WRBHIAPL_FLG` | Field | Premium option renewal discount non-applicable flag — indicates whether a renewal discount for premium options is not applicable. |
| `HKTGI_MOTO_KAP_KEI_NO` | Field | Inherited original allocation contract number — the source allocation contract number when this contract is a continuation/inheritance of a previous one. |
| `MK_FLG_YK` | Field | Invalid flag — yes/no flag (Y/N) indicating whether the record is marked as invalid (deleted/voided). |