# Business Logic — JBSbatKKBndWdtOvrSendPstCrd.updateFtthTsrckJsk() [75 LOC]

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

## 1. Role

### JBSbatKKBndWdtOvrSendPstCrd.updateFtthTsrckJsk()

This method updates the **FTTH (Fiber To The Home) over-communication-volume records** in the `KK_T_FTTH_TSRCK_JSK` table. It is a batch-oriented service operation that writes the results of FTTH traffic monitoring into the over-usage history table, preparing downstream billing or domain-restriction workflows.

The method receives a service contract number (`svcKeiNo`) and a send classification code (`sendKbn`) that determines **which notification mode** applies. It resolves the financial service codes (payment service code `pcrsCd` and payment plan code `pplanCd`) for the given contract via a database query, then branches into three distinct processing paths:

- **SEND_KBN_JISHI ("2" — Actual Notification):** Records the previous month as the first over-usage notification date, writes domain-restriction-ready flags (`TIK_CTL_JSSI_ZM_FLG` = "1"), sets the domain-restriction implementation date, and populates both single ISP authentication ID and multi-selection ISP authentication ID fields. This path is used when the system is actually implementing a domain-restriction action for over-usage.
- **SEND_KBN_YOKOKU ("1" — Warning Notification):** Records the current operation date as the first over-usage notification date (i.e., this is the initial warning sent to the customer before restrictions are applied). It does NOT set any domain-restriction flags.
- **Default (any other value):** Treats the scenario as non-notification (e.g., routine monthly tracking). Records the previous month as the first over-usage notification date without any domain-restriction metadata.

The design pattern is a **routing/dispatch pattern** with conditional branching based on `sendKbn`. The method follows the standard K-Opticom batch CRUD template: query dependent data, prepare a set-map (values to update), prepare a where-map (matching criteria), acquire a row-level lock, execute the update, and validate row-count.

It plays a central role in the **FTTH domain-restriction notification workflow** — specifically, the step that commits the monitoring results to the database after domain-restriction eligibility decisions have been made by upstream batch processes. The method is called directly by `JBSbatKKBndWdtOvrSendPstCrd.execute()`.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["updateFtthTsrckJsk svcKeiNo sendKbn"])
    SVC_QUERY["executeKK_T_SVC_KEI_KK_SELECT_180"]
    FETCH["db_KK_T_SVC_KEI.selectNext"]
    CHECK_RESULT{"resultMap null?"}
    SET_PCRS["pcrsCd from resultMap"]
    SET_PPLAN["pplanCd from resultMap"]
    SKIP_PCRS["pcrsCd/pplanCd remain null"]
    NENGETSU["getTargetNengetsu 0"]
    NEW_SET_MAP["setMap = new JBSbatCommonDBInterface"]
    CHECK_SEND{"sendKbn equals SEND_KBN_JISHI = 2"}
    CHECK_YOKOKU{"sendKbn equals SEND_KBN_YOKOKU = 1"}
    BRANCH_JISHI["Actual Notification Branch"]
    BRANCH_YOKOKU["Warning Notification Branch"]
    BRANCH_DEFAULT["Default Branch"]
    GET_FST_YMD_1["getLastMonthFtthFstYmd"]
    SET_FST_YMD_1["setMap.setValue FTTH_TSR_FST_CHOK_TCH_YMD ftthFstYmd"]
    SET_ZM_FLG["setMap.setValue TIK_CTL_JSSI_ZM_FLG 1"]
    SET_ZM_YMD["setMap.setValue TIK_CTL_JSSI_YMD super.opeDate"]
    GET_NINSHO["getNinshoId svcKeiNo"]
    SET_NINSHO["setMap.setValue ISP_NINSHO_ID ninshoId"]
    GET_MLT_NINSHO["getMltNinshoId svcKeiNo"]
    SET_MLT_NINSHO["setMap.setValue MLTISE_NINSHO_ID mltNinshoId"]
    SET_FST_YMD_2["setMap.setValue FTTH_TSR_FST_CHOK_TCH_YMD super.opeDate"]
    GET_FST_YMD_3["getLastMonthFtthFstYmd"]
    SET_FST_YMD_3["setMap.setValue FTTH_TSR_FST_CHOK_TCH_YMD ftthFstYmd"]
    NEW_WHERE["whereMap = new JBSbatCommonDBInterface"]
    SET_WHERE_SVC["whereMap.setValue SVC_KEI_NO svcKeiNo"]
    SET_WHERE_PCRS["whereMap.setValue PCRS_CD pcrsCd"]
    SET_WHERE_PPLAN["whereMap.setValue PPLAN_CD pplanCd"]
    SET_WHERE_NG["whereMap.setValue FTTH_TUSHIN_USE_YM nengetsu"]
    LOCK["lockFtthTsrckJsk svcKeiNo pcrsCd pplanCd"]
    UPDATE["executeKK_T_FTTH_TSRCK_JSK_PKUPDATE"]
    CHECK_CNT{"cnt >= 1?"}
    THROW["throw JBSbatBusinessError"]
    END_NODE(["Return Next"])

    START --> SVC_QUERY
    SVC_QUERY --> FETCH
    FETCH --> CHECK_RESULT
    CHECK_RESULT -->|true| SET_PCRS
    SET_PCRS --> SET_PPLAN
    SET_PPLAN --> NENGETSU
    CHECK_RESULT -->|false| SKIP_PCRS
    SKIP_PCRS --> NENGETSU
    NENGETSU --> NEW_SET_MAP
    NEW_SET_MAP --> CHECK_SEND
    CHECK_SEND -->|true| BRANCH_JISHI
    BRANCH_JISHI --> GET_FST_YMD_1
    GET_FST_YMD_1 --> SET_FST_YMD_1
    SET_FST_YMD_1 --> SET_ZM_FLG
    SET_ZM_FLG --> SET_ZM_YMD
    SET_ZM_YMD --> GET_NINSHO
    GET_NINSHO --> SET_NINSHO
    SET_NINSHO --> GET_MLT_NINSHO
    GET_MLT_NINSHO --> SET_MLT_NINSHO
    SET_MLT_NINSHO --> NEW_WHERE
    CHECK_SEND -->|false| CHECK_YOKOKU
    CHECK_YOKOKU -->|true| BRANCH_YOKOKU
    BRANCH_YOKOKU --> SET_FST_YMD_2
    SET_FST_YMD_2 --> NEW_WHERE
    CHECK_YOKOKU -->|false| BRANCH_DEFAULT
    BRANCH_DEFAULT --> GET_FST_YMD_3
    GET_FST_YMD_3 --> SET_FST_YMD_3
    SET_FST_YMD_3 --> NEW_WHERE
    NEW_WHERE --> SET_WHERE_SVC
    SET_WHERE_SVC --> SET_WHERE_PCRS
    SET_WHERE_PCRS --> SET_WHERE_PPLAN
    SET_WHERE_PPLAN --> SET_WHERE_NG
    SET_WHERE_NG --> LOCK
    LOCK --> UPDATE
    UPDATE --> CHECK_CNT
    CHECK_CNT -->|false| THROW
    CHECK_CNT -->|true| END_NODE
    THROW --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `svcKeiNo` | `String` | **Service Contract Number** — the unique identifier of the FTTH service subscription. Used as the primary matching key to locate the correct customer's FTTH over-usage records and to resolve dependent data (payment codes, ISP authentication IDs). |
| 2 | `sendKbn` | `String` | **Send Classification Code** — determines the notification mode for the FTTH over-usage update. Possible values (from constants): `"2"` = SEND_KBN_JISHI (Actual Notification — domain restriction is being implemented), `"1"` = SEND_KBN_YOKOKU (Warning Notification — initial warning sent before restrictions), any other value = Default (routine tracking without restriction flags). |

**Instance fields / external state read:**
| Field | Description |
|-------|-------------|
| `super.opeDate` | The operation date inherited from the parent `JBSbatBusinessService` class. Used as the implementation date for domain-restriction fields and as a default value in warning notifications. |
| `db_KK_T_SVC_KEI` | Database access object for the `KK_T_SVC_KEI` (Service Contract) table. Used to query payment codes for the service contract. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `executeKK_T_SVC_KEI_KK_SELECT_180` | EKK0005A040SC (inferred) | `KK_T_SVC_KEI` | Read service contract payment codes (PCRS_CD, PPLAN_CD) for the given service contract number and operation date |
| R | `db_KK_T_SVC_KEI.selectNext` | EKK0005A040SC (inferred) | `KK_T_SVC_KEI` | Fetch the next result row from the service contract query result set |
| R | `getTargetNengetsu` | - | - | Retrieve the target year-month (processing period) for FTTH over-usage tracking; called with parameter `0` |
| R | `getLastMonthFtthFstYmd` | - | - | Compute and return the previous month's first date — used as the "first over-usage notification date" in actual/default notification branches |
| R | `getNinshoId` | - | - | Retrieve the ISP authentication ID for the given service contract number (single-ISP scenario) |
| R | `getMltNinshoId` | - | - | Retrieve the multi-selection ISP authentication ID for the given service contract number (multi-ISP scenario) |
| U | `executeKK_T_FTTH_TSRCK_JSK_PKUPDATE` | EKK0005A041SC (inferred) | `KK_T_FTTH_TSRCK_JSK` | Update the FTTH over-usage history record matched by the where-map primary keys with the set-map values |
| - | `lockFtthTsrckJsk` | - | - | Row-level lock on the FTTH over-usage record for the given service contract and payment codes, preventing concurrent modifications |
| - | `JBSbatCommonDBInterface.setValue` | - | - | Internal map data structure — used to populate set-map and where-map field values |

### How to classify:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `executeKK_T_SVC_KEI_KK_SELECT_180` | EKK0005A040SC | `KK_T_SVC_KEI` | Query service contract to retrieve the payment service code (PCRS_CD) and payment plan code (PPLAN_CD) for the target service contract number |
| R | `db_KK_T_SVC_KEI.selectNext` | EKK0005A040SC | `KK_T_SVC_KEI` | Fetch the next row from the open service contract query cursor |
| R | `getTargetNengetsu` | - | - | Determine the target year-month for FTTH processing; called with `0` to derive from the operation date |
| R | `getLastMonthFtthFstYmd` | - | - | Calculate the first day of the previous month as the "FTTH first over-usage notification date" |
| R | `getNinshoId` | - | - | Look up the ISP authentication ID for a customer's service contract (single-ISP use case) |
| R | `getMltNinshoId` | - | - | Look up the multi-selection ISP authentication ID for a customer's service contract (multi-ISP use case) |
| U | `executeKK_T_FTTH_TSRCK_JSK_PKUPDATE` | EKK0005A041SC | `KK_T_FTTH_TSRCK_JSK` | Perform a primary-key-based update on the FTTH over-usage history table with computed values and matching criteria |
| - | `lockFtthTsrckJsk` | - | `KK_T_FTTH_TSRCK_JSK` | Acquire a pessimistic row-level lock on the FTTH over-usage record before update |
| - | `JBSbatCommonDBInterface.setValue` | - | - | Populate map entries with field names and values for set-map (update values) and where-map (search conditions) |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Batch: JBSbatKKBndWdtOvrSendPstCrd | `execute()` -> `updateFtthTsrckJsk(svcKeiNo, sendKbn)` | `executeKK_T_FTTH_TSRCK_JSK_PKUPDATE [U] KK_T_FTTH_TSRCK_JSK` |

**Trace:**
This method is called exclusively by `JBSbatKKBndWdtOvrSendPstCrd.execute()`, which is the batch processing entry point for the domain-restriction over-usage notification batch job. The batch iterates over FTTH service contracts requiring notification and invokes `updateFtthTsrckJsk` for each contract with the appropriate `sendKbn` classification.

The method's terminal operations are:
- `executeKK_T_FTTH_TSRCK_JSK_PKUPDATE` [U] `KK_T_FTTH_TSRCK_JSK` — the primary write operation that commits the FTTH over-usage record update.
- `lockFtthTsrckJsk` [-] `KK_T_FTTH_TSRCK_JSK` — row-level locking for concurrency control before the update.
- Multiple `setValue` calls [-] — internal data preparation for the set-map and where-map structures.

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] Service Contract Query (L537)

> Queries the service contract table to retrieve payment codes for the given service contract number.

| # | Type | Code |
|---|------|------|
| 1 | SET | `svcKeiParam = {svcKeiNo, super.opeDate}` // Array containing service contract number and operation date |
| 2 | CALL | `executeKK_T_SVC_KEI_KK_SELECT_180(svcKeiParam)` // Query KK_T_SVC_KEI for payment codes |
| 3 | CALL | `resultMap = db_KK_T_SVC_KEI.selectNext()` // Fetch next result row from query cursor |

**Block 2** — [IF] Extract Payment Codes from Result Map (L543)

> Conditionally extracts payment service code and payment plan code from the query result. If no result is found (resultMap is null), these fields remain null.

| # | Type | Code |
|---|------|------|
| 1 | SET | `pcrsCd = resultMap.getString(JBSbatKK_T_SVC_KEI.PCRS_CD)` // Payment service code |
| 2 | SET | `pplanCd = resultMap.getString(JBSbatKK_T_SVC_KEI.PPLAN_CD)` // Payment plan code |

**Block 3** — [ELSE] Null Result Path (L543, else branch — implicit)

> When resultMap is null, pcrsCd and pplanCd remain null. Processing continues with null payment codes.

| # | Type | Code |
|---|------|------|
| 1 | SET | `pcrsCd` remains `null` // No service contract row found |
| 2 | SET | `pplanCd` remains `null` // No service contract row found |

**Block 4** — [SET] Get Target Year-Month (L550)

> Determines the target year-month for FTTH over-usage tracking.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `nengetsu = getTargetNengetsu(0)` // Target year-month derived from operation date |
| 2 | SET | `setMap = new JBSbatCommonDBInterface()` // Create the set-map for update values |

**Block 5** — [IF] SEND_KBN_JISHI = "2" (Actual Notification Branch) (L554)

> Condition: `SEND_KBN_JISHI.equals(sendKbn)` where `SEND_KBN_JISHI = "2"`. This branch handles the case where FTTH over-usage notification is an actual implementation notification — meaning domain restriction is being put into effect for the customer.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `ftthFstYmd = getLastMonthFtthFstYmd(svcKeiNo, pcrsCd, pplanCd)` // Previous month's first date as the first over-usage notification date |
| 2 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.FTTH_TSR_FST_CHOK_TCH_YMD, ftthFstYmd)` // Write first over-usage notification date |
| 3 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.TIK_CTL_JSSI_ZM_FLG, "1")` // Set domain-restriction-ready flag to "1" — this customer is now eligible for domain restriction |
| 4 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.TIK_CTL_JSSI_YMD, super.opeDate)` // Write domain-restriction implementation date (current operation date) |
| 5 | CALL | `ninshoId = getNinshoId(svcKeiNo)` // Retrieve ISP authentication ID for single-ISP customers |
| 6 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.ISP_NINSHO_ID, ninshoId)` // Write single-ISP authentication ID |
| 7 | CALL | `mltNinshoId = getMltNinshoId(svcKeiNo)` // Retrieve multi-selection ISP authentication ID |
| 8 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.MLTISE_NINSHO_ID, mltNinshoId)` // Write multi-ISP authentication ID |

**Block 6** — [ELSE-IF] SEND_KBN_YOKOKU = "1" (Warning Notification Branch) (L568)

> Condition: `SEND_KBN_YOKOKU.equals(sendKbn)` where `SEND_KBN_YOKOKU = "1"`. This branch handles warning notification — the initial customer notification that over-usage has been detected, but domain restriction has not yet been implemented.

| # | Type | Code |
|---|------|------|
| 1 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.FTTH_TSR_FST_CHOK_TCH_YMD, super.opeDate)` // Current operation date as first over-usage notification date (warning sent now) |

**Block 7** — [ELSE] Default Branch (L574)

> Condition: `sendKbn` is neither "1" nor "2". This branch handles non-notification scenarios (e.g., routine monthly over-usage tracking without any customer notification).

| # | Type | Code |
|---|------|------|
| 1 | CALL | `ftthFstYmd = getLastMonthFtthFstYmd(svcKeiNo, pcrsCd, pplanCd)` // Previous month's first date as first over-usage notification date |
| 2 | SET | `setMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.FTTH_TSR_FST_CHOK_TCH_YMD, ftthFstYmd)` // Write first over-usage notification date |

**Block 8** — [SET] Build Where-Map (L581)

> Constructs the WHERE clause conditions for the update — matching the FTTH over-usage record by all four primary key fields.

| # | Type | Code |
|---|------|------|
| 1 | SET | `whereMap = new JBSbatCommonDBInterface()` // Create the where-map for update criteria |
| 2 | SET | `whereMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.SVC_KEI_NO, svcKeiNo)` // Match by service contract number |
| 3 | SET | `whereMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.PCRS_CD, pcrsCd)` // Match by payment service code |
| 4 | SET | `whereMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.PPLAN_CD, pplanCd)` // Match by payment plan code |
| 5 | SET | `whereMap.setValue(JBSbatKK_T_FTTH_TSRCK_JSK.FTTH_TUSHIN_USE_YM, nengetsu)` // Match by FTTH communication usage year-month |

**Block 9** — [EXEC] Row-Level Lock (L594)

> Acquires a pessimistic lock on the target FTTH over-usage record to prevent concurrent modifications.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `lockFtthTsrckJsk(svcKeiNo, pcrsCd, pplanCd)` // Lock the FTTH over-usage record for exclusive update |

**Block 10** — [EXEC] Execute Update (L599)

> Performs the actual database update of the FTTH over-usage history record.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `cnt = executeKK_T_FTTH_TSRCK_JSK_PKUPDATE(setMap, whereMap)` // Update the FTTH over-usage record |

**Block 11** — [IF] Row Count Validation (L601)

> Validates that the update affected exactly one row. If no rows were updated, throws a business error.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `throw new JBSbatBusinessError()` // Thrown when `cnt < 1` — indicates the target record was not found or could not be updated |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `svcKeiNo` | Field | Service Contract Number — unique identifier for an FTTH service subscription contract in the customer base |
| `sendKbn` | Field | Send Classification Code — determines whether the update represents an actual notification ("2"), warning notification ("1"), or routine tracking (other values) |
| `pcrsCd` | Field | Payment Service Code — code identifying the type of financial service associated with the contract (e.g., FTTH broadband) |
| `pplanCd` | Field | Payment Plan Code — code identifying the specific billing plan for the service contract |
| `nengetsu` | Field | Year-Month (usage period) — the target billing month for FTTH over-usage tracking |
| `ftthFstYmd` | Field | FTTH First Over-Usage Notification Date (Year/Month/Day) — the date when the customer was first notified of over-usage |
| `ninshoId` | Field | ISP Authentication ID — the customer's ISP login credentials identifier for single-ISP service contracts |
| `mltNinshoId` | Field | Multi-selection ISP Authentication ID — the customer's ISP authentication identifier for multi-ISP bundled service contracts |
| SEND_KBN_JISHI | Constant | "2" — Actual Notification send classification. Indicates domain restriction is being implemented |
| SEND_KBN_YOKOKU | Constant | "1" — Warning Notification send classification. Indicates an initial over-usage warning has been sent |
| SEND_KBN_NONE | Constant | "0" — No send classification. No notification is being processed |
| FTTH | Business term | Fiber To The Home — fiber-optic broadband internet service provided by K-Opticom |
| KK_T_SVC_KEI | DB Table | Service Contract table — stores customer service contract information including payment codes |
| KK_T_FTTH_TSRCK_JSK | DB Table | FTTH Over-Usage History table — stores records of FTTH communication volume overages, used for domain-restriction decisions |
| TIK_CTL_JSSI_ZM_FLG | Field | Domain Restriction Implementation Ready Flag — when set to "1", indicates the customer is eligible for domain restriction enforcement |
| TIK_CTL_JSSI_YMD | Field | Domain Restriction Implementation Date — the date when domain restriction is scheduled or executed |
| ISP_NINSHO_ID | Field | ISP Authentication ID — customer's internet service provider authentication identifier |
| MLTISE_NINSHO_ID | Field | Multi-selection ISP Authentication ID — customer's ISP authentication ID for multi-ISP bundled service plans |
| JBSbatBusinessError | Exception | K-Opticom batch business error — thrown when a business rule is violated (e.g., zero rows updated) |
| JBSbatCommonDBInterface | Class | Key-value data structure used to build set-maps (UPDATE values) and where-maps (UPDATE conditions) |
| JBSbatBusinessService | Class | Parent class providing common batch processing infrastructure including opeDate and common item handling |
| SET_KBN_JISHI | Comment | 実施通知 — Actual notification; the live implementation of a domain-restriction measure |
| SET_KBN_YOKOKU | Comment | 警告通知 — Warning notification; the initial alert sent to a customer before domain restriction |
| opeDate | Field | Operation date — the current processing date of the batch job, inherited from parent class |