# Business Logic — JBSbatKKAdChgFinAddRun.addPrg() [80 LOC]

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

## 1. Role

### JBSbatKKAdChgFinAddRun.addPrg()

The `addPrg` method registers a new progress management record into the `KK_T_PRG` (Progress Management) table, which tracks the execution state of batch processing steps for a given service contract. This method serves as the batch-side entry point for recording that a specific service contract line (`svcKeiNo`) has reached a defined processing stage (`prgStat`) with an associated change classification (`00020` = service contract modification). It generates a new sequence-based process number (`PRG_NO`), queries the existing progress table for the contract line, captures the current system timestamp, and conditionally records a special notation when a contractor address change is in effect. The method follows a simple builder-then-insert pattern: it prepares all 33 field values into a parameter array, maps them to the database columns, and delegates the actual insert to `executeKK_T_PRG_PKINSERT`. If no valid service contract number is provided, it returns early without side effects, making it safe to call in loops or conditional chains.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addPrg params"])
    CHECK_BLANK["Is svcKeiNo blank?"]
    EARLY_RETURN(["Return early - no service contract number"])
    GEN_SEQ["Call JBSbatOracleSeqUtil.getFormatedNextSeq"]
    SEQ_DESC["Generate SEQ_PRG_NO sequence number"]
    EXEC_SELECT["Call executeKK_T_PRG_KK_SELECT_009"]
    SELECT_DESC["Query KK_T_PRG table"]
    FETCH_RECORD["Read db_KK_T_PRG.selectNext"]
    GET_TIMESTAMP["Call JBSbatDateUtil.getSystemDateTimeStamp"]
    CHK_CHG_FLAG["Is kshadChgUm equal to 1?"]
    SET_NOTATION["Set tokkiJikou1 special notation field"]
    GET_SYS_DATE["Call JCCBatCommon.getSysDateTimeStamp"]
    BUILD_ARRAY["Build setParam array 33 fields"]
    INSERT_RECORD["Call executeKK_T_PRG_PKINSERT"]
    DB_INSERT["Insert into KK_T_PRG table"]
    END_NODE(["Return Next"])

    START --> CHECK_BLANK
    CHECK_BLANK -->|true| EARLY_RETURN
    CHECK_BLANK -->|false| GEN_SEQ
    GEN_SEQ --> SEQ_DESC
    SEQ_DESC --> EXEC_SELECT
    EXEC_SELECT --> SELECT_DESC
    SELECT_DESC --> FETCH_RECORD
    FETCH_RECORD --> GET_TIMESTAMP
    GET_TIMESTAMP --> CHK_CHG_FLAG
    CHK_CHG_FLAG -->|"kshadChgUm 1"| SET_NOTATION
    CHK_CHG_FLAG -->|else| GET_SYS_DATE
    SET_NOTATION --> GET_SYS_DATE
    GET_SYS_DATE --> BUILD_ARRAY
    BUILD_ARRAY --> INSERT_RECORD
    INSERT_RECORD --> DB_INSERT
    DB_INSERT --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `svcKeiNo` | `String` | Service contract number (サービス契約番号) — the unique identifier for a service contract line item. Used as the primary key to query existing progress records and to link the new progress record to the correct service contract. If null or blank, the method returns early without any database operation. |
| 2 | `prgStat` | `String` | Processing status (進捗ステータス) — indicates the current stage of the batch job for this contract line. This value is written directly to the `PRG_STAT` column of the `KK_T_PRG` table and is used by downstream processes to determine which batch steps have been completed. |
| 3 | `kshadChgUm` | `String` | Contractor address change presence flag (契約者住所変更有無フラグ) — when set to `"1"`, it signals that a contractor's address has been modified, which triggers the population of the special notation field (`PRG_TKJK_1`) with the value `"処理区分：契約者情報変更"` (Processing Category: Contractor Information Change). For any other value or null, this field is left as null. |

**Instance fields / external state read:**

| Source | Field | Business Description |
|--------|-------|---------------------|
| `commonItem` | `connection` | Database connection object used for sequence generation. Injected from the batch's connection pool. |
| `super` | `opeDate` | Operator date (操作日) — the batch execution date, concatenated with the time portion from `sysDate` to produce the full process timestamp (`PRG_DTM`). |
| `db_KK_T_PRG` | DB accessor | Entity accessor for the `KK_T_PRG` table, used for both SELECT (via `selectBySqlDefine` + `selectNext`) and INSERT (via `insertByPrimaryKeys`). |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JBSbatOracleSeqUtil.getFormatedNextSeq` | JBSbatOracleSeq | SEQ_PRG_NO | Generates the next sequential process number (12-digit format) from the database sequence `SEQ_PRG_NO`. |
| R | `JBSbatKKAdChgFinAddRun.executeKK_T_PRG_KK_SELECT_009` | JBSbatKKAdChgFinAddRun | KK_T_PRG | Executes SQL define `KK_T_PRG_KK_SELECT_009` to query the progress table for the given service contract number and change division code (`00020`). |
| R | `JBSbatCommonDBInterface.selectNext` | JBSbatCommonDBInterface | KK_T_PRG | Retrieves the next row from the result set of the previous SELECT query. |
| R | `JBSbatDateUtil.getSystemDateTimeStamp` | JBSbatDateUtil | - | Returns the current system date-time stamp as a string for the `IDO_DTM` (migration date-time) field. |
| R | `JCCBatCommon.getSysDateTimeStamp` | JCCBatCommon | - | Returns the current system date-time stamp used for constructing the `PRG_DTM` (process date-time) field. |
| C | `JBSbatKKAdChgFinAddRun.executeKK_T_PRG_PKINSERT` | JBSbatKKAdChgFinAddRun | KK_T_PRG | Maps 33 parameters to database columns and inserts a new record into the `KK_T_PRG` progress management table using primary key-based insert. |
| - | `JBSbatKKAdChgFinAddRun.isBlank` | JBSbatKKAdChgFinAddRun | - | Utility check to determine if `svcKeiNo` is null or blank for early-return guard. |

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 1 method.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Batch: `JBSbatKKAdChgFinAddRun` | `JBSbatKKAdChgFinAddRun.execute()` → `JBSbatKKAdChgFinAddRun.addPrg()` | `executeKK_T_PRG_KK_SELECT_009 [R] KK_T_PRG`, `getFormatedNextSeq [R] SEQ_PRG_NO`, `executeKK_T_PRG_PKINSERT [C] KK_T_PRG` |

## 6. Per-Branch Detail Blocks

**Block 1** — [IF] `(isBlank(svcKeiNo))` (L1377)

> Guard clause: if the service contract number is null or blank, return early without any processing. This prevents invalid database writes for incomplete data.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isBlank(svcKeiNo)` // Check if service contract number is null or empty |
| 2 | RETURN | `return;` // Early return if no valid contract number |

**Block 2** — [SET] `(Generate next sequence number)` (L1381)

> Generates a formatted next sequence number for the process number field (`PRG_NO`) from the `SEQ_PRG_NO` database sequence.

| # | Type | Code |
|---|------|------|
| 1 | SET | `nextPrgNo = JBSbatOracleSeqUtil.getFormatedNextSeq(commonItem.getConnection(), "SEQ_PRG_NO", "", 12)` // Generate 12-digit formatted process number from sequence |

**Block 3** — [CALL] `(Query existing progress record)` (L1383)

> Executes a SELECT query against the `KK_T_PRG` table to find an existing progress record for the service contract number with change division code `"00020"` (service contract modification). The result is stored in the DB accessor for later retrieval.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `executeKK_T_PRG_KK_SELECT_009(new String[]{svcKeiNo, "00020"})` // Query KK_T_PRG for existing progress: service contract number + change division |
| 2 | SET | `samePrgInfo = db_KK_T_PRG.selectNext()` // Fetch the next row from the result set |

**Block 4** — [SET] `(Capture system date-time stamp)` (L1388–L1392)

> Sets the migration date-time (`IDO_DTM`) field to the current system date-time stamp. Previously, this was conditional on whether an existing progress record had a prior migration date — per the OM-2013-0005318 modification, the date-time is now always taken from the system clock.

| # | Type | Code |
|---|------|------|
| 1 | SET | `idoDtm = JBSbatDateUtil.getSystemDateTimeStamp()` // OM-2013-0005318: Always get current system date-time stamp for IDO_DTM |

**Block 5** — [IF] `(kshadChgUm != null && "1".equals(kshadChgUm))` (L1395–L1398)

> Conditional special notation: if the contractor address change flag equals `"1"`, set the special notation field (`tokkiJikou1`, mapped to `PRG_TKJK_1`) to `"処理区分：契約者情報変更"` (Processing Category: Contractor Information Change). This notation is stored in the progress record to flag that the batch processing involves a contractor address change operation. (契約者住所変更の場合、特記事項1に補足を記入する。)

| # | Type | Code |
|---|------|------|
| 1 | SET | `tokkiJikou1 = null` // Initialize special notation field |
| 2 | IF | `kshadChgUm != null && "1".equals(kshadChgUm)` [Contractor address change flag = "1"] |
| 3 | SET | `tokkiJikou1 = "処理区分：契約者情報変更"` // "Processing Category: Contractor Information Change" — Set special notation for contractor address change |

**Block 6** — [SET] `(Capture batch operator date)` (L1400)

> Gets the system date-time stamp from `JCCBatCommon` for constructing the process date-time (`PRG_DTM`) field. Per the ST2-2013-0000896 modification, the full timestamp is built by concatenating `super.opeDate` (operator date) with the time portion extracted via `sysDate.substring(8)`.

| # | Type | Code |
|---|------|------|
| 1 | SET | `sysDate = JCCBatCommon.getSysDateTimeStamp()` // Get system date-time for process date-time construction |

**Block 7** — [SET] — [FOR] `(Build parameter array for insert)` (L1402–L1441)

> Constructs the `setParam` object array containing all 33 field values for the `KK_T_PRG` insert operation. Most fields are populated with `null`, while the key fields that carry meaningful values are:

| # | Type | Code |
|---|------|------|
| 1 | SET | `setParam[0] = nextPrgNo` // 進捗番号 (Process Number) — Generated sequence |
| 2 | SET | `setParam[5] = svcKeiNo` // サービス契約番号 (Service Contract Number) — Input parameter |
| 3 | SET | `setParam[13] = "00020"` // 異動区分 (Change Division) — Fixed value for service contract modification |
| 4 | SET | `setParam[14] = idoDtm` // 異動年月日時秒 (Migration Date-Time) — System date-time stamp |
| 5 | SET | `setParam[15] = prgStat` // 進捗ステータス (Progress Status) — Input parameter |
| 6 | SET | `setParam[16] = super.opeDate + sysDate.substring(8)` // 進捗年月日時秒 (Process Date-Time) — Operator date + time portion |
| 7 | SET | `setParam[18] = tokkiJikou1` // 進捗特記事項1 (Process Special Notation 1) — Contractor address change flag or null |
| 8 | SET | `setParam[1..4, 6..12, 17]` | null — Reserved/major item number, request contract number, payment method numbers, service detail numbers, optional service numbers, etc. |
| 9 | SET | `setParam[19..32]` | null — Process memo, special notation 2, add date-time, add operator, update date-time, update operator, delete date-time, delete operator, invalid flag, add operation date, add process ID, update operation date, update process ID, delete operation date, delete process ID |

**Block 8** — [CALL] `(Insert progress record)` (L1447)

> Delegates the database insert to `executeKK_T_PRG_PKINSERT`, which maps each of the 33 parameter values to the corresponding `KK_T_PRG` table column and executes the insert via `db_KK_T_PRG.insertByPrimaryKeys`.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `executeKK_T_PRG_PKINSERT(setParam)` // Insert new record into KK_T_PRG with all 33 mapped fields |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `svcKeiNo` | Field | Service contract number (サービス契約番号) — Unique identifier for a service contract line item in the telecom billing system. |
| `prgStat` | Field | Progress status (進捗ステータス) — Indicates the current processing stage of a batch job for a given service contract. |
| `kshadChgUm` | Field | Contractor address change presence flag (契約者住所変更有無フラグ) — When set to "1", indicates the batch processing involves a contractor address change, triggering a special notation in the progress record. |
| `nextPrgNo` | Field | Process number (進捗番号) — Unique sequence-generated identifier for each progress management record, stored in `PRG_NO`. |
| `idoDtm` | Field | Migration date-time (異動年月日時秒) — Timestamp of when the data was migrated/created in the progress table. |
| `tokkiJikou1` | Field | Special notation 1 (進捗特記事項1) — Optional remark field that captures special processing categories such as contractor information changes. Mapped to `PRG_TKJK_1` in the database. |
| `opeDate` | Field | Operator date (操作日) — The batch job execution date, held in the parent class and combined with the time portion to form the full process timestamp. |
| `KK_T_PRG` | DB Table | Progress Management Table (進捗管理テーブル) — Core batch tracking table that records each processing step's execution for service contract line items. Contains 33 columns tracking process numbers, dates, statuses, change divisions, operators, and audit fields. |
| `SEQ_PRG_NO` | DB Sequence | Oracle sequence used to generate unique 12-digit process numbers for new progress records. |
| `00020` | Code | Change division code (異動区分) — Fixed value representing "service contract modification" (サービス契約変更) in the `IDO_DIV` field of `KK_T_PRG`. |
| `KK_T_PRG_KK_SELECT_009` | SQL Define | SQL query definition used to select existing progress records from `KK_T_PRG` by service contract number and change division code. |
| KK_T_PRG_PKINSERT | Method | Internal insert method that maps the 33-parameter array to database columns and performs primary key-based insertion into `KK_T_PRG`. |
| `PRG_NO` | DB Column | Process number — The unique identifier for a progress management record, generated from the `SEQ_PRG_NO` sequence. |
| `PRG_STAT` | DB Column | Progress status — The current stage of batch processing for the associated service contract. |
| `PRG_DTM` | DB Column | Process date-time (進捗年月日時秒) — Full timestamp when the progress record was created, formed by concatenating operator date with the system time. |
| `PRG_TKJK_1` | DB Column | Special notation 1 (進捗特記事項1) — Holds human-readable remarks such as "Processing Category: Contractor Information Change" when a contractor address modification is detected. |
| `IDO_DIV` | DB Column | Change division (異動区分) — Classification code for the type of change being processed (e.g., `00020` for service contract modification). |
| `IDO_DTM` | DB Column | Migration date-time (異動年月日時秒) — The timestamp of when the migration data was created. |
| JBSbatOracleSeqUtil | Component | Oracle sequence utility class providing formatted sequence number generation for batch processing. |
| JBSbatDateUtil | Component | Batch date utility class providing system date-time stamp retrieval. |
| JCCBatCommon | Component | Common batch utility class providing system date-time stamp retrieval and other shared batch helpers. |
| 進捗管理 | Business term | Progress Management — The batch processing tracking system that records each step's execution state for telecom service contract line items. |
| 契約者住所変更 | Business term | Contractor Address Change — A specific type of service contract modification where the customer's registered address is updated, flagged via `kshadChgUm`. |