# Business Logic — JBSbatKKKjFinClDataInTrn.updateSvcKeiUcwk() [50 LOC]

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

## 1. Role

### JBSbatKKKjFinClDataInTrn.updateSvcKeiUcwk()

This method performs the **update processing for a service contract line-item detail record** (サービス契約内訳 — *Service Contract Breakdown), specifically for either a **new addition** (新規分) or **cancellation** (解約分) entry. It is part of a financial data import batch that ingests and reconciles service contract details into K-Opticom's telecom billing system.

The method follows a **pessimistic locking** design pattern: it first acquires an exclusive row-level lock on the target table using a `SELECT ... FOR UPDATE WAIT` query, ensuring no other concurrent batch thread can modify the same service contract line-item during the update. If the record exists under lock, it sets two business fields — a reservation application code (setting the status to "reservation in progress", 予約手続中) and an invalidation flag (setting the mark flag to "invalid", 無効) — then delegates the actual SQL `UPDATE` to a dedicated helper method. If the record is not found, it raises a business exception (`EKKB0210CE`) indicating a "record not found" error for the service contract line-item.

Its role in the larger system is as a **shared private helper** called by the parent method `JBSbatKKKjFinClDataInTrn.execute()`, which orchestrates the broader financial data import batch. This method handles one specific line-item update within a larger batch iteration loop, typically processing records row-by-row from an import file.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["updateSvcKeiUcwk params"])
    INIT["Initialize: map, where_map, value, param"]
    WHERE_SET["Set where_map with SVC_KEI_UCWK_NO and GENE_ADD_DTM"]
    LOCK["selectByPrimaryKeysForUpdateWait where_map"]
    COND{map is not null}
    TRUE_BRANCH["Allocate value[2] and param[2] arrays"]
    SET_VALUES["Set value and param with resolved constants"]
    DEBUG_CHK{"DEBUG log level enabled?"}
    LOG["printDebugLog param and value details"]
    UPDATE["executeKK_T_SVC_KEI_UCWK_PKUPDATE value, param"]
    FALSE_BRANCH["throw JBSbatBusinessException EKKB0210CE"]
    END_NODE(["Return"])

    START --> INIT
    INIT --> WHERE_SET
    WHERE_SET --> LOCK
    LOCK --> COND
    COND -->|true| TRUE_BRANCH
    TRUE_BRANCH --> SET_VALUES
    SET_VALUES --> DEBUG_CHK
    DEBUG_CHK -->|true| LOG
    DEBUG_CHK -->|false| UPDATE
    LOG --> UPDATE
    UPDATE --> END_NODE
    COND -->|false| FALSE_BRANCH
    FALSE_BRANCH --> END_NODE
```

### Constant Resolution

| Constant | Value | Business Meaning |
|----------|-------|------------------|
| `JBSbatKKConst.RSV_APLY_CD_TTDK` | `"1"` | Reservation Application Code — "Reservation in Progress" (予約手続中) |
| `JBSbatKKConst.MK_FLG_MK` | `"1"` | Invalidation Flag — "Invalid" (無効) |

The original source code shows that prior to v20.00.00, these values were hardcoded as `"1"` for both fields. The refactor replaced them with named constants for maintainability, while the actual business values remain unchanged.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `svcKeiUcwkNo1_151` | `String` | **Service Contract Line-Item Number** — The unique primary key identifier for a service contract breakdown record (T_SVC_KEI_UCWK table). Used both as the lookup key for pessimistic locking and as the WHERE clause value in the subsequent UPDATE statement. Each record in this table represents a single line-item within a service contract (e.g., a specific service type under a customer's contract). |
| 2 | `geneAddDtm1_151` | `String` | **Generation Registration Date-Time** — The timestamp (year/month/day/hour/minute/second) attached to the record's creation/generation. Used as the second part of the composite primary key for pessimistic locking, ensuring that the exact version of the record is locked and updated. |

**External/Instance fields read:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `db_KK_T_SVC_KEI_UCWK` | `JBSbatCommonDBInterface` | Database access interface for the `T_SVC_KEI_UCWK` (Service Contract Line-Item) table. Provides `selectByPrimaryKeysForUpdateWait` and `updateByPrimaryKeys` methods. |
| `super.logPrint` | `JBSbatLogUtil` (inherited) | Logging utility inherited from parent class. Used to check debug log level and output debug messages. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `db_KK_T_SVC_KEI_UCWK.selectByPrimaryKeysForUpdateWait` | - | `T_SVC_KEI_UCWK` | Pessimistic lock read — performs a `SELECT ... FOR UPDATE WAIT` on the service contract line-item table using the composite primary key (SVC_KEI_UCWK_NO, GENE_ADD_DTM). Locks the row exclusively so no other transaction can modify it until this transaction completes. |
| U | `executeKK_T_SVC_KEI_UCWK_PKUPDATE` | - | `T_SVC_KEI_UCWK` | Delegates the actual UPDATE operation. Sets `RSV_APLY_CD` (Reservation Application Code) and `MK_FLG` (Invalidation Flag) by primary key, updating the service contract line-item record to "reservation in progress" status with the invalidation flag set. |
| - | `JBSbatCommonDBInterface.setValue` | - | - | Internal data structure population for mapping key-value pairs used in WHERE and SET clauses. |
| - | `super.logPrint.chkLogLevel` | - | - | Checks whether DEBUG-level logging is enabled. |
| - | `super.logPrint.printDebugLog` | - | - | Outputs four debug log lines with parameter and value details when DEBUG logging is active. |

### Internal CRUD summary

| CRUD | Method | Entity / DB | Operation Description |
|------|--------|-------------|----------------------|
| R | `selectByPrimaryKeysForUpdateWait` | `T_SVC_KEI_UCWK` | Pessimistic lock-read by composite primary key to prevent concurrent modification |
| U | `executeKK_T_SVC_KEI_UCWK_PKUPDATE` | `T_SVC_KEI_UCWK` | Update reservation application code and invalidation flag by primary key |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Batch: `JBSbatKKKjFinClDataInTrn` | `execute()` -> `updateSvcKeiUcwk(svcKeiUcwkNo1_151, geneAddDtm1_151)` | `executeKK_T_SVC_KEI_UCWK_PKUPDATE [U] T_SVC_KEI_UCWK` |

**Call chain detail:**

The only direct caller is the `execute()` method within `JBSbatKKKjFinClDataInTrn` itself. This method is called during the batch's main processing loop when processing service contract line-item records (specifically for new additions or cancellations). The batch iterates over import data, and for each relevant line-item, invokes `updateSvcKeiUcwk` to lock and update the corresponding database record.

**Terminal operations from this method:**

- `selectByPrimaryKeysForUpdateWait` — Read (R) on `T_SVC_KEI_UCWK` with row-level exclusive lock
- `executeKK_T_SVC_KEI_UCWK_PKUPDATE` — Update (U) on `T_SVC_KEI_UCWK` setting `RSV_APLY_CD` and `MK_FLG`

## 6. Per-Branch Detail Blocks

**Block 1** — [VARIABLE DECLARATION] (L1896)

> Initialize local variables for database interface maps and string arrays.

| # | Type | Code |
|---|------|------|
| 1 | SET | `map = new JBSbatCommonDBInterface()` [Create map holder] |
| 2 | SET | `where_map = new JBSbatCommonDBInterface()` [Create WHERE clause map] |
| 3 | SET | `value = null` [Result array — null initially] |
| 4 | SET | `param = null` [Parameter array — null initially] |

**Block 2** — [SET] (L1903-L1904)

> Build the WHERE clause map using the composite primary key fields.

| # | Type | Code |
|---|------|------|
| 1 | SET | `where_map.setValue(SVC_KEI_UCWK_NO, svcKeiUcwkNo1_151)` [Set primary key: service contract line-item number] |
| 2 | SET | `where_map.setValue(GENE_ADD_DTM, geneAddDtm1_151)` [Set primary key: generation date-time] |

**Block 3** — [CALL] (L1907)

> Perform pessimistic lock read on the target record. The comment states: 排他検索を行います (Perform exclusive search / lock).

| # | Type | Code |
|---|------|------|
| 1 | CALL | `map = db_KK_T_SVC_KEI_UCWK.selectByPrimaryKeysForUpdateWait(where_map)` [Lock-read T_SVC_KEI_UCWK by PK; returns null if not found] |

**Block 4** — [IF] `(map != null)` — Record Found (L1909)

> The record exists under lock. Proceed with update preparation.

**Block 4.1** — [SET] Array Allocation (L1911-L1912)

> Allocate the value (SET clause) and param (WHERE clause) arrays for the update.

| # | Type | Code |
|---|------|------|
| 1 | SET | `value = new String[2]` [Arrays for UPDATE SET values] |
| 2 | SET | `param = new String[2]` [Arrays for UPDATE WHERE values] |

**Block 4.2** — [SET] Constant Resolution (L1917-L1918)

> Assign business constants to the SET clause values. Comment: v20.00.00 変更開始 (Change start). These were previously hardcoded as `"1"`.

| # | Type | Code |
|---|------|------|
| 1 | SET | `value[0] = JBSbatKKConst.RSV_APLY_CD_TTDK` [-> `RSV_APLY_CD_TTDK = "1"` (Reservation in Progress / 予約手続中)] |
| 2 | SET | `value[1] = JBSbatKKConst.MK_FLG_MK` [-> `MK_FLG_MK = "1"` (Invalid / 無効)] |

**Block 4.3** — [SET] Parameter population (L1921-L1922)

> Populate the WHERE clause parameters with the original PK values for the UPDATE statement.

| # | Type | Code |
|---|------|------|
| 1 | SET | `param[0] = svcKeiUcwkNo1_151` [サービス契約内訳番号１ — Service contract line-item number 1] |
| 2 | SET | `param[1] = geneAddDtm1_151` [世代登録年月日時分秒１ — Generation registration year/month/day/hour/minute/second 1] |

**Block 4.4** — [IF] `(super.logPrint.chkLogLevel(JBSbatLogUtil.MODE_DEBUG))` (L1925)

> Comment: ログレベルがデバッグモードの場合 (If log level is debug mode). Output four debug log entries.

**Block 4.4.1** — [EXEC] Debug Logging (L1927-L1930)

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `super.logPrint.printDebugLog("param(サービス契約内訳番号): " + param[0])` |
| 2 | EXEC | `super.logPrint.printDebugLog("param(世代登録年月日時分秒): " + param[1])` |
| 3 | EXEC | `super.logPrint.printDebugLog("value(予約適用コード（予約手続中）): " + value[0])` |
| 4 | EXEC | `super.logPrint.printDebugLog("value(無効フラグ（無効）): " + value[1])` |

**Block 4.5** — [CALL] Actual DB Update (L1933)

> Delegate to the private helper that performs the SQL UPDATE by primary key.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `executeKK_T_SVC_KEI_UCWK_PKUPDATE(value, param)` [Executes `UPDATE T_SVC_KEI_UCWK SET RSV_APLY_CD=?, MK_FLG=? WHERE SVC_KEI_UCWK_NO=? AND GENE_ADD_DTM=?`] |

**Block 5** — [ELSE] — Record Not Found (L1935-L1939)

> Comment: 排他エラーの場合 (In case of exclusive error). The pessimistic lock-read returned null, meaning no record matched the composite primary key.

**Block 5.1** — [THROW] Business Exception (L1937-L1938)

> Comment: 該当レコードなしのエラー (Record-not-found error).

| # | Type | Code |
|---|------|------|
| 1 | THROW | `throw new JBSbatBusinessException(JPCBatchMessageConstant.EKKB0210CE, new String[]{"サービス契約内訳", "サービス契約内訳番号１" + svcKeiUcwkNo1_151})` [Business exception with error code EKKB0210CE and context: entity name + key value] |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `svc_kei_ucwk_no` | Field | Service Contract Line-Item Number — Unique identifier for a service contract breakdown/detail record within the telecom billing system. |
| `gene_add_dtm` | Field | Generation Registration Date-Time — Timestamp indicating when the record was created/generated in the system. Part of the composite primary key. |
| `RSV_APLY_CD` | Field | Reservation Application Code — Indicates the reservation application status of a service contract line-item. |
| `RSV_APLY_CD_TTDK` | Constant | Reservation in Progress (予約手続中) — Code `"1"`, meaning the service contract reservation is pending processing. |
| `MK_FLG` | Field | Invalidation Flag — Boolean-style flag indicating whether the record is valid or invalid. |
| `MK_FLG_MK` | Constant | Invalid (無効) — Code `"1"`, meaning the record is flagged as invalid. |
| `MK_FLG_YK` | Constant | Valid (有効) — Code `"0"`, meaning the record is valid (not present in this method's logic but defined in the constant file). |
| `T_SVC_KEI_UCWK` | Table | Service Contract Line-Item table — Stores the breakdown/detail records of service contracts (e.g., individual services under a customer's contract). |
| `selectByPrimaryKeysForUpdateWait` | Method | Pessimistic lock read — Performs a `SELECT ... FOR UPDATE WAIT` query, acquiring an exclusive row-level lock on matching records. |
| `JBSbatBusinessException` | Class | Business exception class for domain-specific errors in the batch service layer. |
| `EKKB0210CE` | Constant | Error code for "record not found" business exception, including entity name and key value in its message. |
| `JBSbatKKConst` | Class | Batch-level constant definitions class containing reservation codes, flags, and other domain-specific string constants. |
| `JBSbatKK_T_SVC_KEI_UCWK` | Class | Table column name constants for the T_SVC_KEI_UCWK entity (e.g., `SVC_KEI_UCWK_NO`, `GENE_ADD_DTM`). |
| 予約手続中 | Japanese term | Reservation in progress — Service contract reservation is being processed, awaiting final application. |
| 無効 | Japanese term | Invalid — Flag indicating the record should be treated as invalid/deactivated. |
| サービス契約内訳 | Japanese term | Service Contract Breakdown/Line-Item — Individual detail record within a service contract (e.g., a specific service type). |
| 世代登録時分秒 | Japanese term | Generation registration date-time — The precise timestamp when the record was generated/registered. |
| 排他制御 | Japanese term | Exclusive control / pessimistic locking — Database mechanism to prevent concurrent modification of the same record. |
| 排他検索 | Japanese term | Exclusive search — SELECT ... FOR UPDATE query to acquire an exclusive row lock. |