# Business Logic — JBSbatKKKDDIAnkenIktTrkm.getAgntCd() [33 LOC]

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

## 1. Role

### JBSbatKKKDDIAnkenIktTrkm.getAgntCd()

This method retrieves the **dealer (agent) code and name** from the dealer master table (`KK_M_AGNT`) based on the **receiving store code** (`ukTenCd`). In the K-Opticom business domain, a "dealer" (代理店, *dairiten*) is an authorized business partner that handles customer-facing operations for the telecom service provider — essentially a franchise or authorized agent store. The method acts as a **data lookup service** within the reference (introduction ticket / 紹介票, *shokaihyo*) batch processing pipeline: it is called by `isCheckKKIFE217()` during validation of the KKIFE217 reference ticket form, ensuring that the store code being processed belongs to a valid, active dealer in the system. It implements a **read-only query pattern**: it constructs a WHERE clause parameter array, delegates to the table-specific select method (`executeKK_M_AGNT_KK_SELECT_001`), fetches the result via `db_KK_M_AGNT.selectNext()`, and returns the agent code and agent name as a `String[]`. If no matching dealer record exists, the method does not throw an exception; instead it records a **warning** (登録（不備）, *touroku (fubi)* — "Registration (Deficiency)") in the warning result list, sets the warning flag (`isCheckWarFlg = true`), and returns `null`, allowing the caller to continue processing while flagging the missing dealer for later review.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["getAgntCd(ukTenCd, intrHyoKanriNo)"])
    START --> SET["Set whereParamAgnt[4]"]
    SET --> S0["whereParamAgnt[0] = ukTenCd<br/>(Receiving Store Code)"]
    S0 --> S1["whereParamAgnt[1] = commonItem.getOpeDate()<br/>(Billing Effective Date)"]
    S1 --> S2["whereParamAgnt[2] = commonItem.getOpeDate()<br/>(Agent Valid Start Date)"]
    S2 --> S3["whereParamAgnt[3] = commonItem.getOpeDate()<br/>(Agent Valid End Date)"]
    S3 --> EXEC["executeKK_M_AGNT_KK_SELECT_001(whereParamAgnt)"]
    EXEC --> SELECT["db_KK_M_AGNT.selectNext()<br/>--mapAgnt"]
    SELECT --> COND{mapAgnt == null?<br/>(Record not found)}
    COND -->|Yes| MSG["getMessage(EKKB0720KW,<br/>\"Agent Master\")"]
    MSG --> WAR["warMapList.add(setKDDITrkmRsltDataList(<br/>WAR, UK_TEN_CD, ukTenCd, msg, intrHyoKanriNo))"]
    WAR --> WARFLG["isCheckWarFlg = true"]
    WARFLG --> RETNULL["return null"]
    COND -->|No| RET["return [mapAgnt.getString(AGNT_CD),<br/>mapAgnt.getString(AGNT_NM)]"]
    RET --> END(["Return Agent Info<br/>(Code, Name)"])
```

**Processing narrative:**
1. The method constructs a 4-element WHERE parameter array (`whereParamAgnt`) for querying the dealer master table. The first element is the receiving store code (`ukTenCd`), and the remaining three elements all use the current operation date (`commonItem.getOpeDate()`) to filter by billing effective date, agent valid start date, and agent valid end date respectively.
2. It delegates to `executeKK_M_AGNT_KK_SELECT_001` which executes the SQL key `KK_SELECT_001` against the `KK_M_AGNT` database table.
3. The result is fetched via `db_KK_M_AGNT.selectNext()` into `mapAgnt`.
4. If `mapAgnt` is `null` (no matching dealer record found), it generates a warning message, records it in the warning result list (`warMapList`) with the status `KDDI_TRKM_RSLT_VAL_WAR = "登録（不備）"`, sets the warning flag, and returns `null`.
5. If a record is found, it returns a `String[]` containing the dealer code (`AGNT_CD`) and dealer name (`AGNT_NM`).

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `ukTenCd` | `String` | **Receiving Store Code** (受付店コード, *uketsuke-ten code*) — The unique identifier of the store location where the service order/introduction ticket was initially received. This value is used as the primary lookup key to find the corresponding dealer record in the `KK_M_AGNT` master table. It is also echoed into the warning result record when no matching dealer is found. |
| 2 | `intrHyoKanriNo` | `String` | **Introduction Ticket Management Number** (紹介票管理番号, *shokaihyo kanri-bango*) — The unique management/tracking number assigned to the introduction ticket (紹介票, *shokaihyo*) in the K-Opticom reference system. This number is propagated to the warning result list for traceability, enabling operators to identify which specific ticket triggered the dealer-not-found warning. |

**Instance fields read:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `commonItem` | Object with `getOpeDate()` | Provides the current operation date (業務日, *gyoumu-bi*) used as the effective date for the dealer master lookup — the same date is applied to billing effective date, valid start date, and valid end date conditions. |
| `db_KK_M_AGNT` | `JBSbatCommonDBInterface` | Database accessor for the dealer master table (`KK_M_AGNT`). Used to fetch the query result via `selectNext()`. |
| `warMapList` | List/DataStructure | Warning result list. Stores warning records when a dealer is not found, using `setKDDITrkmRsltDataList`. |
| `isCheckWarFlg` | `boolean` | Warning flag. Set to `true` when a dealer record is not found, signaling to the caller that a warning was generated. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `executeKK_M_AGNT_KK_SELECT_001(Object[])` | KK_M_AGNT | `KK_M_AGNT` | Executes SQL key `KK_SELECT_001` to select the dealer master record matching the WHERE clause (store code + date range). |
| R | `db_KK_M_AGNT.selectNext()` | KK_M_AGNT | `KK_M_AGNT` | Fetches the next result row from the SQL query executed by `executeKK_M_AGNT_KK_SELECT_001`. |
| R | `JBSbatLogPrintControl.getMessage(String, String[])` | JBSbatLogPrintControl | - | Retrieves the localized warning message text for key `EKKB0720KW` with "代理店マスタ" (Agent Master) as a substitution parameter. |
| R | `JBSbatLogPrintControl.getMessage(JPCBatchMessageConstant)` | JBSbatLogPrintControl | - | Retrieves localized message texts for various validation keys (used by caller `isCheckKKIFE217`). |
| R | `JBSbatInterface.getMessage` | JBSbatInterface | - | Generic message retrieval utility. |
| R | `JBSbatFUCaseFileRnkData.getString` | JBSbatFUCaseFileRnkData | - | Retrieves string values from case file rank data maps. |
| R | `JBSbatFUMoveNaviData.getString` | JBSbatFUMoveNaviData | - | Retrieves string values from navigation move data maps. |
| R | `JBSbatZMAdDataSet.getString` | JBSbatZMAdDataSet | - | Retrieves string values from ZM address data set maps. |
| R | `JCCBPCommon.getOpeDate` | JCCBPCommon | - | Returns the current operation date. |
| R | `JFUEoTvCngAddStbCC.getOpeDate` | JFUEoTvCngAddStbCC | - | Returns the operation date. |
| R | `JKKCreditAddCC.getOpeDate` | JKKCreditAddCC | - | Returns the operation date. |
| R | `JFUHikkosiNaviRelAddCC.getOpeDate` | JFUHikkosiNaviRelAddCC | - | Returns the operation date. |
| R | `JESC0101B010TPMA.getString` | JESC0101B010TPMA | - | Retrieves string values from ESC data maps. |
| R | `JESC0101B020TPMA.getString` | JESC0101B020TPMA | - | Retrieves string values from ESC data maps. |
| R | `JCCModelCommon.getOpeDate` | JCCModelCommon | - | Returns the operation date. |
| R | `JCCMessageCache.getMessage` | JCCMessageCache | - | Retrieves cached message texts. |
| - | `JBSbatKKKDDIAnkenIktTrkm.setKDDITrkmRsltDataList(...)` | JBSbatKKKDDIAnkenIktTrkm | - | Sets a KDDI reference result data list entry with status code, field name, value, message, and ticket number. |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Batch: `isCheckKKIFE217` (JBSbatKKKDDIAnkenIktTrkm, L665) | `JBSbatKKKDDIAnkenIktTrkm.isCheckKKIFE217` -> `getAgntCd(ukTenCd, intrHyoKanriNo)` | `executeKK_M_AGNT_KK_SELECT_001 [R] KK_M_AGNT` |

**Caller context:** `isCheckKKIFE217` is a validation method in the same class (`JBSbatKKKDDIAnkenIktTrkm`) that performs single-item checks on the KKIFE217 reference ticket form. It calls `getAgntCd` to verify that the dealer associated with the receiving store code exists in the dealer master table. This method itself is invoked from the main batch processing flow (line 260) during the processing of K-Opticom reference ticket data.

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] `(L1823)` Prepare WHERE parameter array for dealer table query

> Sets up a 4-element Object array that defines the WHERE clause for querying the dealer master table (`KK_M_AGNT`).

| # | Type | Code |
|---|------|------|
| 1 | SET | `Object[] whereParamAgnt = new Object[4];` // Prepare WHERE clause parameter array |
| 2 | SET | `whereParamAgnt[0] = ukTenCd;` // Dealer Code — Receving store code lookup key |
| 3 | SET | `whereParamAgnt[1] = commonItem.getOpeDate();` // Billing Effective Date (予約適応年月日) |
| 4 | SET | `whereParamAgnt[2] = commonItem.getOpeDate();` // Agent Valid Start Date (代理店適用開始年月日) |
| 5 | SET | `whereParamAgnt[3] = commonItem.getOpeDate();` // Agent Valid End Date (代理店適用終了年月日) |

**Block 2** — [EXEC] `(L1837)` Execute dealer table SQL query

> Delegates to the table-specific select method that builds bound variables and executes `KK_SELECT_001` SQL key against the `KK_M_AGNT` table.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `executeKK_M_AGNT_KK_SELECT_001(whereParamAgnt);` // Execute SQL key KK_SELECT_001 against KK_M_AGNT table |

**Block 3** — [EXEC] `(L1839)` Fetch result row from query

> Fetches the next row from the query result set into `mapAgnt` using `db_KK_M_AGNT.selectNext()`.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `JBSbatCommonDBInterface mapAgnt = db_KK_M_AGNT.selectNext();` // Get next dealer record from result set |

**Block 4** — [IF] `(mapAgnt == null)` `[Record not found]` (L1841)

> Checks if the dealer record was found. When no matching dealer exists for the given store code, this branch records a warning and returns null.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `String msg = JBSbatLogPrintControl.getMessage(EKKB0720KW, new String[]{"代理店マスタ"});` // Get warning message with "Agent Master" substitution |
| 2 | EXEC | `warMapList.add(setKDDITrkmRsltDataList(KDDI_TRKM_RSLT_VAL_WAR, KDDI_UK_TEN_CD, ukTenCd, msg, intrHyoKanriNo));` // Add warning: status="登録（不備）", field="受付店コード", value=ukTenCd, msg, ticketNo=intrHyoKanriNo |
| 3 | SET | `isCheckWarFlg = true;` // Set warning flag for caller |
| 4 | RETURN | `return null;` // No dealer found — return null to caller |

**Block 5** — [ELSE / Fall-through] `(mapAgnt != null)` `[Record found]` (L1854)

> When a matching dealer record exists, returns an array containing the dealer code and dealer name.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return new String[]{mapAgnt.getString(JBSbatKK_M_AGNT.AGNT_CD), mapAgnt.getString(JBSbatKK_M_AGNT.AGNT_NM)};` // Return [Dealer Code, Dealer Name] |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `ukTenCd` | Field | Receiving Store Code (受付店コード, *uketsuke-ten code*) — The unique identifier of the store location where the service order or introduction ticket was initially received. |
| `intrHyoKanriNo` | Field | Introduction Ticket Management Number (紹介票管理番号, *shokaihyo kanri-bango*) — The unique tracking number for a reference/introduction ticket in the K-Opticom system. |
| `AGNT_CD` | Field | Dealer/Agent Code (代理店コード) — The unique identifier of a dealer (authorized business partner) in the dealer master table. |
| `AGNT_NM` | Field | Dealer/Agent Name (代理店名) — The registered name of a dealer in the dealer master table. |
| `KK_M_AGNT` | Entity | Dealer Master Table (代理店マスタ) — The master table storing dealer information including code, name, type, valid date ranges, and hierarchical parent-dealer relationships. |
| `KK_SELECT_001` | SQL Key | SQL definition key for the dealer master lookup query, selecting records by store code and date range. |
| `EKKB0720KW` | Message Key | Message key for the dealer-not-found warning: "代理店マスタ" (Agent Master) — used when a dealer record does not exist for the given store code. |
| `KDDI_TRKM_RSLT_VAL_WAR` | Constant | "登録（不備）" (Touroku (fubi)) — Registration (Deficiency). Warning status value indicating an incomplete or non-fatal issue. |
| `KDDI_UK_TEN_CD` | Constant | "受付店コード" (Uketsuke-ten code) — Field name for the receiving store code in result reports. |
| `warMapList` | Instance Field | Warning result list that accumulates warning-level issues during batch processing. |
| `isCheckWarFlg` | Instance Field | Warning flag set to `true` when any warning-level issue is detected during processing. |
| `commonItem` | Instance Field | Common item holder providing the current operation date (`getOpeDate()`) used for date-based master table lookups. |
| `db_KK_M_AGNT` | Instance Field | Database accessor interface for the `KK_M_AGNT` (Dealer Master) table. |
| `dairiten` (代理店) | Business term | Dealer/Authorized Agent — A franchise or authorized business partner in the K-Opticom telecom system that handles customer-facing operations. |
| `shokaihyo` (紹介票) | Business term | Introduction Ticket — A reference/ticket document used in the K-Opticom system to track and manage service requests. |
| `gyoumu-bi` (業務日) | Business term | Business/Operation Date — The current operational date used as the effective date for validating master records. |
| `JBSbatKKIFE217` | Class/Entity | KKIFE217 — A service ticket/form entity class (代理店情報変更, *dairiten jouhou henkou* — Dealer Information Change) processed during the reference ticket validation flow. |
| `MSKM_DTM` | Field | Submission Date/Time (申請日時) — The date/time when the ticket/form was submitted. Used in KKIFE217 validation. |
| `MSKM_DTM` | Constant | "申請" (Shinsei) — "Application" — field label in result reports. |
| `isCheckErrFlg` | Instance Field | Error flag set to `true` when a validation error (as opposed to warning) is detected. |
| `isCheckFlg` | Instance Field | Overall check flag — `true` if all validation checks pass (no errors). |