# Business Logic — KKW00128SF01DBean.addListDataInstance() [32 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKA16601SF.KKW00128SF01DBean` |
| Layer | Data Bean (Webview / Presentation-tier data container) |
| Module | `KKA16601SF` (Package: `eo.web.webview.KKA16601SF`) |

## 1. Role

### KKW00128SF01DBean.addListDataInstance()

The `addListDataInstance` method is a factory-style dispatcher that dynamically creates and manages typed list instances for array-type UI form fields within the K-Opticom service contract screen (KKA16601SF). This screen is a web-based data entry interface for managing service contracts, and the method serves as the central mechanism for initializing per-row data instances in the data bean's collection fields. It implements the **dispatch (switch-by-key) design pattern**, routing incoming string keys to dedicated branch logic that constructs the appropriate `X33VDataTypeList`-backed item instances. The two supported branches handle "Migration Reason Code" (異動理由コード, field ID: `ido_rsn_cd`) — used to record the reason for service migration changes — and "Option Service Contract Number" (オプションサービス契約番号, field ID: `op_svc_kei_no`) — used to track optional add-on service contract identifiers. This method plays the role of a **shared data bean utility** called by the presentation layer when users dynamically add new rows to repeatable array sections on the screen. If the requested key is unknown or null, it returns -1 to signal that no recognized list item type corresponds to the given key.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance(key)"])
    CHECK_NULL{"key == null"}
    BRANCH_1{"key.equals(異動理由コード)"}
    NULL_CHECK_1{"ido_rsn_cd_list == null"}
    CREATE_LIST_1["ido_rsn_cd_list = new X33VDataTypeList()"]
    ADD_RSN["create tmpBean + add to list"]
    BRANCH_2{"key.equals(オプションサービス契約番号)"}
    NULL_CHECK_2{"op_svc_kei_no_list == null"}
    CREATE_LIST_2["op_svc_kei_no_list = new X33VDataTypeList()"]
    ADD_OPT["create tmpBean + add to list"]
    NOT_FOUND["return -1"]
    RETURN_RSN["return index (size-1)"]
    RETURN_OPT["return index (size-1)"]
    END_NODE(["Return / Next"])

    START --> CHECK_NULL
    CHECK_NULL -->|true| NOT_FOUND
    CHECK_NULL -->|false| BRANCH_1
    BRANCH_1 -->|true| NULL_CHECK_1
    BRANCH_1 -->|false| BRANCH_2
    NULL_CHECK_1 -->|true| CREATE_LIST_1
    NULL_CHECK_1 -->|false| ADD_RSN
    CREATE_LIST_1 --> ADD_RSN
    ADD_RSN --> RETURN_RSN
    BRANCH_2 -->|true| NULL_CHECK_2
    BRANCH_2 -->|false| NOT_FOUND
    NULL_CHECK_2 -->|true| CREATE_LIST_2
    NULL_CHECK_2 -->|false| ADD_OPT
    CREATE_LIST_2 --> ADD_OPT
    ADD_OPT --> RETURN_OPT
    RETURN_RSN --> END_NODE
    RETURN_OPT --> END_NODE
    NOT_FOUND --> END_NODE
```

**Processing flow:**

1. **Null guard** (L1595): If `key` is null, immediately return -1 — no processing proceeds. This is a defensive guard against invalid invocation.
2. **Branch: Migration Reason Code** (L1601): If `key` equals `"異動理由コード"` (Migration Reason Code), the method prepares the `ido_rsn_cd_list` collection for storing reason codes. If the list is null (first use), it instantiates a new `X33VDataTypeList`. Then it creates a new `X33VDataTypeStringBean` instance (which represents a String-type form field) and adds it to the list. Returns the index of the newly added element.
3. **Branch: Option Service Contract Number** (L1611): If `key` equals `"オプションサービス契約番号"` (Option Service Contract Number), the method prepares the `op_svc_kei_no_list` collection. Same null-check-and-instantiate pattern. Creates a `X33VDataTypeStringBean`, adds it, and returns the index.
4. **Fallback** (L1623): If `key` matches none of the known branch strings, return -1 to indicate no recognized list item type.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The field name (item label) that identifies which array-type list instance to create. It acts as a discriminator that routes processing to the correct dedicated list field. Valid values are `"異動理由コード"` (Migration Reason Code — used to record why a service is being migrated/changed) and `"オプションサービス契約番号"` (Option Service Contract Number — used to track optional add-on service contract identifiers). Unknown or null values result in -1 being returned. |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `ido_rsn_cd_list` | `X33VDataTypeList` | The list collection storing migration reason code entries. Null-checked before first use to lazy-initialize. |
| `op_svc_kei_no_list` | `X33VDataTypeList` | The list collection storing option service contract number entries. Null-checked before first use to lazy-initialize. |

## 4. CRUD Operations / Called Services

This method performs **no database operations, no service component (SC) calls, and no CBS (Common Business Service) invocations**. It operates entirely within the data bean layer using only in-memory list operations:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| — | (none) | — | — | No data persistence operations. All work is performed in-memory via `X33VDataTypeList` and `X33VDataTypeStringBean` instantiation and list `add()` calls. This method does not read from or write to any database table. |

## 5. Dependency Trace

This method is a **leaf data bean utility** — it is not directly invoked by any other class within the `KKA16601SF` module or the broader codebase as a direct caller. Instead, it is **overridden** by multiple subclasses across different web view modules (FUW series) that extend the parent bean to add their own type-specific branches, calling `super.addListDataInstance(key)` as a fallback within their own overrides.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | (No direct callers found) | This method is not called directly by any other class. It is overridden by subclasses and invoked via polymorphism from the presentation layer through data bean access patterns (e.g., `bean.addListDataInstance(key)`). | — |
| 2 | FUW subclasses (e.g., FUW00901SFBean, FUW00907SFBean, FUW00917SFBean, FUW00919SFBean, etc.) | `SubclassBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW00128SF01DBean.addListDataInstance(key)` | — (falls through to no-op when key not recognized in subclass) |

**Notes:**
- The FUW series screens (FUW00901SF, FUW00907SF, FUW00917SF, FUW00919SF, FUW00926SF, etc.) override this method in their own bean classes and delegate unrecognized keys to `super.addListDataInstance(key)`, inheriting this method's behavior.
- KKW00128SF12DBean also overrides this method independently within the same module.

## 6. Per-Branch Detail Blocks

**Block 1** — [IF] `(key == null)` (L1595)

> Null guard: If the key parameter is null, return -1 immediately. No further processing is performed.

| # | Type | Code |
|---|------|------|
| 1 | CHECK | `key == null` |
| 2 | RETURN | `return -1;` // Return -1 when key is null |

**Block 2** — [ELSE-IF] `(key.equals("異動理由コード"))` [IDO_RSN_CD_LIST_KEY="異動理由コード"] (L1601)

> Branch: Create a list instance for "Migration Reason Code" — the field used to record the reason for service migration changes. The comment notes: "各繰り返し項目の固定要素数指定への処理を行う" (Handle fixed element count specification for repeatable items). The field ID for this item is `ido_rsn_cd`.

| # | Type | Code |
|---|------|------|
| 1 | CHECK | `key.equals("異動理由コード")` // Check if key matches migration reason code |
| 2 | [IF Block 2.1] | — |

**Block 2.1** — [IF] `(ido_rsn_cd_list == null)` (L1603)

> Lazy initialization: If the reason code list has not yet been created, instantiate a new empty list.

| # | Type | Code |
|---|------|------|
| 1 | SET | `ido_rsn_cd_list = new X33VDataTypeList();` // Generate new empty instance when list is null |

| # | Type | Code |
|---|------|------|
| 2 | [ELSE branch, L1607] | — |

| # | Type | Code |
|---|------|------|
| 3 | EXEC | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Create data type bean instance for the specified data type |
| 4 | CALL | `ido_rsn_cd_list.add(tmpBean);` // Add bean to list |
| 5 | RETURN | `return ido_rsn_cd_list.size() - 1;` // Return the index of the added element |

**Block 3** — [ELSE-IF] `(key.equals("オプションサービス契約番号"))` [OP_SVC_KEY="オプションサービス契約番号"] (L1611)

> Branch: Create a list instance for "Option Service Contract Number" — used to track optional add-on service contract identifiers. The field ID for this item is `op_svc_kei_no`. Same structural pattern as Block 2.

| # | Type | Code |
|---|------|------|
| 1 | CHECK | `key.equals("オプションサービス契約番号")` // Check if key matches option service contract number |
| 2 | [IF Block 3.1] | — |

**Block 3.1** — [IF] `(op_svc_kei_no_list == null)` (L1613)

> Lazy initialization: If the option service contract number list has not yet been created, instantiate a new empty list.

| # | Type | Code |
|---|------|------|
| 1 | SET | `op_svc_kei_no_list = new X33VDataTypeList();` // Generate new empty instance when list is null |

| # | Type | Code |
|---|------|------|
| 2 | [ELSE branch, L1617] | — |

| # | Type | Code |
|---|------|------|
| 3 | EXEC | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Create data type bean instance for the specified data type |
| 4 | CALL | `op_svc_kei_no_list.add(tmpBean);` // Add bean to list |
| 5 | RETURN | `return op_svc_kei_no_list.size() - 1;` // Return the index of the added element |

**Block 4** — [FALLBACK] — (L1623)

> Final return: No recognized key matched. Return -1 to signal that no applicable list item type exists for the given key.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // Return -1 when no matching item exists |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `ido_rsn_cd` | Field | Migration reason code — internal tracking field that stores the reason why a service is being migrated or changed. Used in the repeatable array section "異動理由コード" (Migration Reason Code). |
| `ido_rsn_cd_list` | Field | Migration reason code list — the X33VDataTypeList collection storing individual `X33VDataTypeStringBean` entries for migration reasons. |
| `op_svc_kei_no` | Field | Option service contract number — field ID for the optional add-on service contract identifier used in repeatable array sections. |
| `op_svc_kei_no_list` | Field | Option service contract number list — the X33VDataTypeList collection storing individual entries for option service contracts. |
| `X33VDataTypeList` | Type | X33V framework list type — a dynamic collection used in the X33 web framework to manage repeatable array sections in form screens. |
| `X33VDataTypeStringBean` | Type | String data type bean — a typed wrapper for String values in the X33V data framework. Each instance represents a single cell/row in a repeatable form array. |
| `X31CWebConst` | Type | X31C Web Constants framework — shared constants utility class in the X31C web framework for standard data bean field names. |
| `X33VListedBeanInterface` | Interface | Listed bean interface — marks a data bean as supporting list/array data operations (iteration, indexed access). |
| `X33VDataTypeBeanInterface` | Interface | Data type bean interface — marks a bean as a typed data container in the X33V framework. |
| 異動理由コード | Field Name (Japanese) | Migration Reason Code — the Japanese field label displayed in the UI, identifying the list item type for recording migration reasons. |
| オプションサービス契約番号 | Field Name (Japanese) | Option Service Contract Number — the Japanese field label displayed in the UI, identifying the list item type for optional service contracts. |
| リスト項目 | Term (Japanese) | List item — refers to entries within a repeatable array section of a form screen. |
| 繰り返し項目 | Term (Japanese) | Repeatable item — items that can appear multiple times in a tabular/repeat section of a screen. |
| KKA16601SF | Screen Module | The screen module identifier for the service contract screen (Web Client tool-generated). |
| ANK-2693-00-00 | Change Request | Change request for ordering system support (STEP2) — added external system code field in 2015-12-11. |