# Business Logic — JBSbatKKAdChgSmtvlRnki.changeTajgswkeiTgkeiSvcKeiNo() [17 LOC]

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

## 1. Role

### JBSbatKKAdChgSmtvlRnki.changeTajgswkeiTgkeiSvcKeiNo()

This method performs a **service contract number replacement for third-party discount eligible contracts** (他事業者割引契約対象契約のサービス契約番号を切替える). It is a core part of the Smart Balance synchronization link product (スマートバルー連係部品) that handles address changes between home and mobile lines. When a customer's service contract number changes during a smart balance migration — for example, when moving from an old third-party discount arrangement to a new KDDI service contract — this method manages the historical record transition for the `KK_T_TAJGSWKEI_TGKEI` (Third-Party Discount Eligible Contract Target Contract) table.

The method implements a **validity period management pattern** common in telecom billing systems. It reads the existing contract record using the original service data as lookup keys, then inserts two new historical records: an **application termination record** (setting the effective end date to the day before the operational date) and an **application start record** (setting the effective start date to the current operational date and the service contract number to the new value). This ensures a clean, auditable handoff from the old service contract number to the new one without data loss.

The method serves as a **delegation-based worker** called by the batch entry point `execute()`. It operates as a private utility within the `JBSbatKKAdChgSmtvlRnki` batch service class, which processes smart balance sync data for address change notifications to KDDI.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["changeTajgswkeiTgkeiSvcKeiNo params"])
    STEP1["Create whereMap JBSbatCommonDBInterface"]
    STEP2["Set TAJGS_WRIB_KEI_NO = tajgsWribKeiNo"]
    STEP3["Set TAJGSWKEI_TGKEI_NO = tajgswkeiTgkeiNo"]
    STEP4["Set GENE_ADD_DTM = geneAddDtm"]
    STEP5["selectByPrimaryKeys whereMap on KK_T_TAJGSWKEI_TGKEI"]
    COND{resultMap != null?}
    BRANCH_NULL["Skip no matching record"]
    BRANCH_NOTNULL["insertKK_T_TAJGSWKEI_TGKEI resultMap null"]
    BRANCH_NOTNULL2["insertKK_T_TAJGSWKEI_TGKEI resultMap svcKeiNo"]
    END_NODE(["Return / Next"])

    START --> STEP1
    STEP1 --> STEP2
    STEP2 --> STEP3
    STEP3 --> STEP4
    STEP4 --> STEP5
    STEP5 --> COND
    COND -->|true| BRANCH_NOTNULL
    COND -->|false| BRANCH_NULL
    BRANCH_NOTNULL --> BRANCH_NOTNULL2
    BRANCH_NOTNULL2 --> END_NODE
    BRANCH_NULL --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `tajgsWribKeiNo` | `String` | **Replacement-source third-party discount contract number** (切替元の他事業者割引契約番号) — the original contract number assigned to a customer who is eligible for a third-party discount. This serves as a primary lookup key to identify the specific contract record in `KK_T_TAJGSWKEI_TGKEI` that needs its service contract number replaced. |
| 2 | `tajgswkeiTgkeiNo` | `String` | **Replacement-source third-party discount eligible contract target contract number** (切替元の他事業者割引契約対象契約番号) — the secondary contract identifier that, together with the discount contract number, uniquely identifies the contract record being modified. |
| 3 | `geneAddDtm` | `String` | **Replacement-source generation registration date/time** (切替元の世代登録年月日時分秒) — the timestamp of the original record's creation/generation. This acts as a third part of the composite primary key used to locate the exact historical record in the versioned contract table. |
| 4 | `svcKeiNo` | `String` | **Replacement-target service contract number** (切替先のサービス契約番号) — the new service contract number to assign to the newly created start-of-effective-period record. If `null` is passed (as in the first `insertKK_T_TAJGSWKEI_TGKEI` call), it signals that this is an application termination record rather than a new active contract. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JBSbatSQLAccess.selectByPrimaryKeys` | - | `KK_T_TAJGSWKEI_TGKEI` | Reads the existing third-party discount eligible contract target contract record using the composite primary key (TAJGS_WRIB_KEI_NO, TAJGSWKEI_TGKEI_NO, GENE_ADD_DTM) to find the record that needs its service contract number replaced. |
| C | `insertKK_T_TAJGSWKEI_TGKEI` | - | `KK_T_TAJGSWKEI_TGKEI` | Inserts a new record to mark the application termination (適用終了). Passes `null` as the new service contract number and sets the effective end date to the day before the operational date (opeDate - 1). |
| C | `insertKK_T_TAJGSWKEI_TGKEI` | - | `KK_T_TAJGSWKEI_TGKEI` | Inserts a new record to mark the application start (適用開始). Passes the new service contract number (svcKeiNo) and generates a new contract target contract number via sequence `SEQ_TAJGSWKEI_TGKEI_NO`. Sets the effective start date to the operational date and end date to the maximum date value. |
| - | `JDKStructuredMap.setValue` | JDKStructuredMap | - | Calls `setValue` on `JBSbatCommonDBInterface` (which extends JDKStructuredMap) to set lookup keys on `whereMap` and fields on `insertMap`. |
| - | `JBSbatDateUtil.adjustDate` | - | - | Called by `insertKK_T_TAJGSWKEI_TGKEI` to compute the termination effective date: sets the end date to the day before the operational date. |
| - | `JBSbatDateUtil.getSystemDateTimeStamp` | - | - | Called by `insertKK_T_TAJGSWKEI_TGKEI` to generate the system timestamp for GENE_ADD_DTM of new records. |
| - | `JBSbatOracleSeqUtil.getFormatedNextSeq` | - | - | Called by `insertKK_T_TAJGSWKEI_TGKEI` when svcKeiNo is provided; generates a new formatted sequence number for TAJGSWKEI_TGKEI_NO from the `SEQ_TAJGSWKEI_TGKEI_NO` Oracle sequence (15-digit format). |

**CRUD Analysis Summary:**

This method performs a **read-then-write** pattern on the `KK_T_TAJGSWKEI_TGKEI` table:
- **1 Read (R)**: Looks up the existing record to verify it exists before processing.
- **2 Creates (C)**: Inserts two new records to manage the validity period transition — one marking the end of the old service contract's validity, and one starting the new service contract's validity.
- **0 Updates (U)**: No in-place updates; instead, it uses a soft-transition pattern where old records are not modified but new records are inserted to represent the state change.
- **0 Deletes (D)**: No records are deleted; historical data is preserved through the period management approach.

## 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: `insertKK_T_TAJGSWKEI_TGKEI` [C], `insertKK_T_TAJGSWKEI_TGKEI` [C], `selectByPrimaryKeys` [R].

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Batch: JBSbatKKAdChgSmtvlRnki.execute() | `execute()` → `changeTajgswkeiTgkeiSvcKeiNo(tajgsWribKeiNo, tajgswkeiTgkeiNo, geneAddDtm, itnsSvcKeiNo)` | `selectByPrimaryKeys [R] KK_T_TAJGSWKEI_TGKEI`, `insertKK_T_TAJGSWKEI_TGKEI [C] KK_T_TAJGSWKEI_TGKEI` (x2) |

The method is called from the batch's main `execute()` method (line 247 of `JBSbatKKAdChgSmtvlRnki.java`), which processes smart balance synchronization data during address change operations. The caller iterates through data and invokes this method when handling net contract cancellations or new contracts (ネットが解約／新規の場合). The terminal operations resolve to CRUD operations on the `KK_T_TAJGSWKEI_TGKEI` table, which stores third-party discount eligible contract target contract records.

## 6. Per-Branch Detail Blocks

### Block 1 — SET (variable initialization) (L622)

> Creates the search condition map (whereMap) for the primary key lookup.

| # | Type | Code |
|---|------|------|
| 1 | SET | `whereMap = new JBSbatCommonDBInterface();` // Instantiate search condition map (切替元レコードを検索) |

### Block 2 — SET (set search condition values) (L624-626)

> Sets the three-part composite primary key values on the `whereMap` to identify the exact record to look up.

| # | Type | Code |
|---|------|------|
| 1 | SET | `whereMap.setValue("TAJGS_WRIB_KEI_NO", tajgsWribKeiNo);` // Set third-party discount contract number (切替元の他事業者割引契約番号) |
| 2 | SET | `whereMap.setValue("TAJGSWKEI_TGKEI_NO", tajgswkeiTgkeiNo);` // Set third-party discount eligible contract target contract number (切替元の他事業者割引契約対象契約番号) |
| 3 | SET | `whereMap.setValue("GENE_ADD_DTM", geneAddDtm);` // Set generation registration timestamp (切替元の世代登録年月日時分秒) |

### Block 3 — CALL (primary key lookup) (L628)

> Performs the database query to find the existing contract record using the composite primary key.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `resultMap = db_KK_T_TAJGSWKEI_TGKEI.selectByPrimaryKeys(whereMap);` // Query KK_T_TAJGSWKEI_TGKEI by primary key (切替元レコードを検索) |

### Block 4 — IF (conditional branch: record found) (L629)

> Checks whether the target record was found. If null, the method returns early with no action — this handles the case where the contract record does not exist (possibly already processed or deleted).

| # | Type | Code |
|---|------|------|
| 1 | IF | `if (resultMap != null)` { record exists |

### Block 4.1 — CALL (application termination record insert) (L630)

> Inserts a record marking the end of the old service contract's validity period. Passes `null` as the new service contract number to signal termination.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `insertKK_T_TAJGSWKEI_TGKEI(resultMap, null);` // Insert application termination record (適用終了のレコードを追加). newSvcKeiNo=null signals end of validity. |

### Block 4.2 — CALL (application start record insert) (L631)

> Inserts a record marking the start of the new service contract's validity period. Passes the replacement-target service contract number.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `insertKK_T_TAJGSWKEI_TGKEI(resultMap, svcKeiNo);` // Insert application start record (適用開始のレコードを追加). Uses the new service contract number. |

### Block 4.3 — RETURN (end of method) (L633)

> Returns void — processing complete.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `}` // Close if block, method end |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `KK_T_TAJGSWKEI_TGKEI` | Table | Third-Party Discount Eligible Contract Target Contract table — stores records for contracts eligible for third-party discounts, including the service contract number and validity period management. |
| `TAJGS_WRIB_KEI_NO` | Field | Third-party discount contract number (他事業者割引契約番号) — the original discount contract identifier. |
| `TAJGSWKEI_TGKEI_NO` | Field | Third-party discount eligible contract target contract number (他事業者割引契約対象契約番号) — the secondary contract identifier within the discount eligibility framework. |
| `GENE_ADD_DTM` | Field | Generation registration date/time (世代登録年月日時分秒) — the timestamp when a record was originally generated/created; used as a versioning key in the contract table. |
| `SVC_KEI_NO` | Field | Service contract number (サービス契約番号) — the primary identifier for a customer's service contract. |
| `TAJGSWKEI_TGKEI_TSTAYMD` | Field | Application start date (適用開始日) — the date from which a contract record becomes effective. |
| `TAJGSWKEI_TGKEI_TENDYMD` | Field | Application end date (適用終了日) — the date until which a contract record remains valid. |
| `ADD_DTM` / `ADD_OPEACNT` | Field | Registration timestamp / registered operator account (登録日時 / 登録操作アカウント) — audit fields tracking who and when a record was created. |
| `UPD_DTM` / `UPD_OPEACNT` | Field | Update timestamp / updated operator account (更新日時 / 更新操作アカウント) — audit fields tracking modifications. |
| `DEL_DTM` / `DEL_OPEACNT` | Field | Deletion timestamp / deleted operator account (削除日時 / 削除操作アカウント) — audit fields tracking deletion. |
| `MAX_DATE` | Constant | Maximum date value (日付の最大値) — typically '9999-12-31', used as the open-ended end date for active records. |
| `opeDate` | Field | Operational date (運用日) — the batch processing date used as the reference point for validity period calculations. |
| `SEQ_TAJGSWKEI_TGKEI_NO` | Sequence | Oracle sequence for generating new third-party discount eligible contract target contract numbers (他事業者割引契約対象契約番号シーケンス番号). |
| `smart balance` (スマートバルー) | Product | KDDI's bundled service plan that combines fixed-line and mobile services, enabling synchronized address changes between home and mobile lines. |
| `JBSbatCommonDBInterface` | Class | Framework interface for building database query/update parameter maps (Extends JDKStructuredMap, used throughout batch services as a key-value container for DB operations). |
| `JBSbatSQLAccess` | Class | Framework class providing database access methods including `selectByPrimaryKeys`, `insertByPrimaryKeys`, and `selectNext`. |
| `JBSbatDateUtil` | Class | Framework utility for date manipulation operations (`adjustDate` for date arithmetic, `getSystemDateTimeStamp` for current timestamp). |
| `JBSbatOracleSeqUtil` | Class | Framework utility for Oracle sequence operations (`getFormatedNextSeq` for generating formatted sequence numbers). |
| Third-Party Discount (他事業者割引) | Business term | A discount pricing arrangement where customers receive reduced rates for services when transitioning from or in combination with services from other telecommunications carriers. |
| Application Termination (適用終了) | Business term | The state marking the end of a contract record's validity period, typically set to the day before the operational date when a replacement record takes effect. |
| Application Start (適用開始) | Business term | The state marking the beginning of a contract record's validity period, set to the operational date when a new service contract takes effect. |