# Eo / Web / Webview / Kkw01037sf

## Overview

The `KKW01037SF` module is the **Introduction Information Inquiry** screen in the Fujitsu Futurity X31 web framework. It displays details about a referred/referral customer (被紹介者) and their associated service contracts — including service contract numbers, pricing group names, status, start dates, introduction codes, and coupon codes. It also shows the customer contract succession list (顧客契約引継リスト) with SYSID and service contract numbers. This is a read-only inquiry screen (no-edit) within the Contract Management System (契約管理システム).

The module follows the standard X33V + X31C multi-tier architecture: a top-level form bean (`KKW01037SFBean`) holds all screen data, two data-type beans (`KKW01037SF01DBean`, `KKW01037SF02DBean`) represent rows in repeatable list sections, a logic class (`KKW01037SFLogic`) orchestrates the initial display and service invocation, and a checker class (`KKW01037SFChecker`) provides GUI validation hooks.

---

## Key Classes and Interfaces

### KKW01037SFBean — Main Form Bean

**File:** [KKW01037SFBean.java](source/koptWebB/src/eo/web/webview/KKW01037SF/KKW01037SFBean.java)

**Role:** This is the primary data container for the entire screen. It extends `X33VViewBaseBean` and implements both `X33VListedBeanInterface` and `X31CBaseBean`. It holds header-level fields, two repeatable list data structures, and popup mode state.

**Key properties:**

| Property | Type | Purpose |
|----------|------|---------|
| `hktg_sysid` | String | Inherited SYSID from the calling screen (引き継ぎSYSID) |
| `hktg_svc_kei_no` | String | Inherited service contract number (引き継ぎサービス契約番号) |
| `hi_cust_nm` | String | Referrer contract name (被紹介者契約者名), initially disabled |
| `hi_telno` | String | Referrer phone number (被紹介者電話番号) |
| `hi_sysid` | String | Referrer SYSID (被紹介者SYSID) |
| `svc_kei_list_list` | `X33VDataTypeList` | Service contract list rows, each row is a `KKW01037SF01DBean` |
| `cust_kei_hktgi_list_list` | `X33VDataTypeList` | Customer contract succession list rows, each row is a `KKW01037SF02DBean` |
| `popup_mode` | String | Popup mode flag (ポップアップモード) |

**Key methods:**

- **`KKW01037SFBean()` (constructor)** — Initializes both list beans. `svc_kei_list_list` starts empty (capacity 0), while `cust_kei_hktgi_list_list` starts with 1 pre-allocated `KKW01037SF02DBean` instance. This is the one place where the list type beans are instantiated.

- **`getJsflist_typelist_svc_kei_list()`** — Converts the `svc_kei_list_list` into a `List<SelectItem>` for JSF dropdown display. Iterates over list elements and loads each row's "service contract list" value.

- **`getJsflist_typelist_cust_kei_hktgi_list()`** — Same pattern, but for the customer contract succession list.

- **`loadModelData(String key, String subkey)`** — The central data retrieval dispatcher. Uses a string-routing pattern with `/` as a separator to navigate into nested data. If the key starts with `//`, delegates to the parent class for common-info bean access. Otherwise, it dispatches to the appropriate property based on the key string (e.g., "引き継ぎSYSID", "被紹介者契約者名", etc.). For list keys ("サービス契約一覧リスト", "顧客契約引継リスト"), it parses the index and delegates to the inner bean's `loadModelData`.

- **`storeModelData(String key, String subkey, Object in_value, boolean isSetAsString)`** — The counterpart to `loadModelData`. Routes incoming data into the correct property based on the key/subkey pattern. For list elements, it resolves the index from the key string (e.g., "サービス契約一覧リスト/0/被紹介者お客さまSYSID") and calls the inner bean's `storeModelData`.

- **`listKoumokuIds(String key)`** — Returns the list of valid field keys. When called with `null`, returns all top-level keys. For list keys, delegates to `KKW01037SF01DBean.listKoumokuIds()` or `KKW01037SF02DBean.listKoumokuIds()`.

- **`addListDataInstance(String key)`** — Dynamically adds a new row to a repeatable list. For "サービス契約一覧リスト", creates a new `KKW01037SF01DBean`. For "顧客契約引継リスト", creates a new `KKW01037SF02DBean` (subject to a max element count check — the succession list has a configured maximum). Returns the new row's index.

- **`removeElementFromListData(String key, int index)`** — Removes a row from the specified list by index, with bounds checking.

- **`clearListDataInstance(String key)`** — Clears all rows from the specified list.

- **`typeModelData(String key, String subkey)`** — Returns the Java type for a given key/subkey combination. Used by the framework for type-safe data binding. Returns `String.class`, `Boolean.class`, or `int.class` depending on the property, or delegates to list beans for repeatable section fields.

---

### KKW01037SF01DBean — Service Contract List Row

**File:** [KKW01037SF01DBean.java](source/koptWebB/src/eo/web/webview/KKW01037SF/KKW01037SF01DBean.java)

**Role:** Represents a single row in the **Service Contract List** (サービス契約一覧リスト). Implements `X33VDataTypeBeanInterface`, `X33VListedBeanInterface`, and `Serializable`. Each instance holds one row's worth of referrer service contract data.

**Properties (each field has `update`, `value`, `enabled`, `state` variants):**

| Property Prefix | Japanese Name | Meaning |
|-----------------|---------------|---------|
| `hi_svc_kei_no` | 被紹介者お客さまID | Referrer customer SYSID |
| `hi_prc_grp_nm` | 被紹介者料金グループ名 | Referrer pricing group name |
| `hi_svc_kei_stat` | 被紹介者ステータス | Referrer service contract status |
| `hi_svc_sta_ymd` | 被紹介者サービス開始年月日 | Referrer service start date |
| `intr_cd` | 紹介コード | Introduction code |
| `coupon_cd` | クーポンコード | Coupon code (added in ANK-4416-00-00) |
| `sho_svc_kei_no` | 紹介者お客さまID | Introducer (referrer) customer SYSID |
| `sho_prc_grp_nm` | 紹介者料金グループ名 | Introducer pricing group name |
| `sho_sysid` | 紹介者SYSID | Introducer SYSID |
| `sho_cust_nm` | 紹介者契約者名 | Introducer contract name |

Each field uses the standard four-property pattern:
- `_<field>_update` — Change indicator (tells the framework whether the field was modified)
- `_<field>_value` — The actual data value
- `_<field>_enabled` — Whether the field is enabled for editing (typically `true` for most fields)
- `_<field>_state` — Display state (e.g., highlighting, read-only indicator)

**Key methods:**

- **`loadModelData(String key, String subkey)`** — Routes to the correct getter based on the key string. The `subkey` parameter determines what aspect of the field to return: `"value"` for the data, `"enable"` for the enabled flag, or `"state"` for display state.

- **`storeModelData(String key, String subkey, Object in_value, boolean isSetAsString)`** — Routes to the correct setter based on the key string and subkey. Mirrors `loadModelData` in its routing logic.

- **`listKoumokuIds()`** — Returns the list of all valid field keys for this bean (e.g., "被紹介者お客さまID", "紹介コード", etc.).

- **`typeModelData(String key, String subkey)`** — Returns the type of each field. String-typed fields return `String.class`, boolean fields return `Boolean.class`, and the index field returns `int.class`.

- **`getIndex()` / `setIndex(int)`** — Row index within the list.

---

### KKW01037SF02DBean — Customer Contract Succession List Row

**File:** [KKW01037SF02DBean.java](source/koptWebB/src/eo/web/webview/KKW01037SF/KKW01037SF02DBean.java)

**Role:** Represents a single row in the **Customer Contract Succession List** (顧客契約引継リスト). This is a simpler bean with only two data properties per row. It implements `X33VDataTypeBeanInterface`, `X33VListedBeanInterface`, and `Serializable`.

**Properties:**

| Property | Type | Purpose |
|----------|------|---------|
| `sysid` | String | SYSID of the succession record (SYSID) |
| `svc_kei_no` | String | Service contract number (サービス契約番号) |

Both properties follow the standard `_<field>_update` / `_<field>_value` / `_<field>_state` pattern (no `enabled` flag).

**Key methods:**

- **`loadModelData(String key, String subkey)`** — Routes to `getSysid_value()` / `getSvc_kei_no_value()` based on the key ("SYSID" or "サービス契約番号"), returning value or state based on subkey.

- **`storeModelData(String key, String subkey, Object in_value, boolean isSetAsString)`** — Routes to the corresponding setter.

- **`listKoumokuIds()`** — Returns `["SYSID", "サービス契約番号"]`.

- **`typeModelData(String key, String subkey)`** — Returns `String.class` for both fields.

- **`getIndex()` / `setIndex(int)`** — Row index within the list.

---

### KKW01037SFLogic — Business Logic

**File:** [KKW01037SFLogic.java](source/koptWebB/src/eo/web/webview/KKW01037SF/KKW01037SFLogic.java)

**Role:** Extends `JCCWebBusinessLogic` and contains the screen's business logic. Handles initial display (`actionInit`), back navigation (`actionBack`), data bean configuration (`setHktgiBean`), service invocation (`doService`), and data mapping (`setInitService`, `storeDataBeanInitService`).

**Key methods:**

- **`actionInit()`** — The entry point for the initial screen display. The flow is:
  1. Obtains the screen's form bean via `getServiceFormBean()`.
  2. Retrieves screen info from the previous screen via `JCCWebCommon.getScreenInfo(this)`.
  3. Sets the next screen name on the common info bean.
  4. Calls `setHktgiBean(bean)` to populate inherited fields (hktg_sysid, hktg_svc_kei_no, popup_mode) from the prior screen's `hktgi_cust_kei_hktgi_list` data bean array.
  5. Creates an input map and runs the top-level mapping via `setInitService()` — uses `KKSV0784_KKSV0784OPDBMapper` to map input data beans to the service's input map, with function code `JPCModelConstant.FUNC_CD_1` (紹介情報照会 = introduction information inquiry).
  6. Invokes the backend service `KKSV0784` with operation `KKSV0784` via `doService()`.
  7. After the service returns, calls `storeDataBeanInitService()` — uses the same mapper to map the service's output map back into the screen's data beans.
  8. Logs the final state of the data bean via `JSYwebLog.println(JSYwebLog.DataBean_Dump, ...)`.
  9. Returns `true` to indicate success.

- **`actionBack()`** — Handles the back navigation. Sets the next screen ID and name to `SCREEN_ID_KKW01021` / `SCREEN_NAME_KKW01021` on the common info bean, logs the data bean state, and returns `true`.

- **`setHktgiBean(X31SDataBeanAccess bean)`** — Configures the inherited fields. Retrieves the customer contract succession list array from the data bean access, gets the first element, and copies `hktgi_sysid` and `hktgi_svc_kei_no` into the screen's `hktg_sysid` and `hktg_svc_kei_no` properties. Also copies the popup mode.

- **`doService(String usecase_id, String operation_id, ...)`** — Internal service invocation helper. Sets up the parameter map with the usecase ID and operation ID, then calls `invokeService()` (from the parent class). Returns an `X31CMessageResult`.

- **`setInitService(X31SDataBeanAccess[] paramBean, HashMap<String, Object> inputMap)`** — Sets up the service input map. Creates a `KKSV0784_KKSV0784OPDBMapper` and calls `setIntrInfoCfmCC(paramBean, inputMap, JPCModelConstant.FUNC_CD_1)` to perform the top-level mapping from the data bean into the service input.

- **`storeDataBeanInitService(X31SDataBeanAccess[] paramBean, HashMap<String, Object> outputMap)`** — Maps the service output into the data beans. Creates a `KKSV0784_KKSV0784OPDBMapper` and calls `getIntrInfoCfmCC(paramBean, outputMap)` if the output map is not null.

---

### KKW01037SFChecker — GUI Validation

**File:** [KKW01037SFChecker.java](source/koptWebB/src/eo/web/webview/KKW01037SF/KKW01037SFChecker.java)

**Role:** Implements `X31SGuiCheckBase` to provide GUI-level validation hooks for the screen. Receives a reference to a `X31BBusinessLogic` (which will be `KKW01037SFLogic`) in its constructor.

**Key methods:**

- **`KKW01037SFChecker(X31BBusinessLogic bl)`** — Constructor. Stores the business logic reference for potential use in validation methods.

- **`checkMethod(X31SGuiCheckParam param, X31GUtilStockMessage errMsgStock)`** — The validation dispatch method. Currently always returns `true` (pass), meaning no validation errors are raised. The `param.patternID` is extracted but not used in the current implementation. This is a stub where custom validation logic can be added when the screen requires field-level checks.

---

### KKW01037SFConst — Constant Definitions

**File:** [KKW01037SFConst.java](source/koptWebB/src/eo/web/webview/KKW01037SF/KKW01037SFConst.java)

**Role:** Provides string constants used as keys to route data between beans, mappers, and the service. These constants represent Japanese field names and are used throughout the `loadModelData` / `storeModelData` / `typeModelData` methods of the bean classes.

**Key constants:**

| Constant | Value |
|----------|-------|
| `HKTG_SYSID` | "引き継ぎSYSID" |
| `HKTG_SVC_KEI_NO` | "引き継ぎお客さまID" |
| `HI_CUST_NM` | "被紹介者契約者名" |
| `HI_TELNO` | "被紹介者電話番号" |
| `HI_SYSID` | "被紹介者SYSID" |
| `SVC_KEI_LIST` | "サービス契約一覧リスト" |
| `CUST_KEI_HKTGI_LIST` | "顧客契約引継リスト" |
| `POPUP_MODE` | "ポップアップモード" |
| `HI_SVC_KEI_NO_01` | "被紹介者お客さまID" |
| `HI_PRC_GRP_NM_01` | "被紹介者料金グループ名" |
| `HI_SVC_KEI_STAT_01` | "被紹介者ステータス" |
| `HI_SVC_STA_YMD_01` | "被紹介者サービス開始年月日" |
| `INTR_CD_01` | "紹介コード" |
| `COUPON_CD_01` | "クーポンコード" |
| `SHO_SVC_KEI_NO_01` | "紹介者お客さまID" |
| `SHO_PRC_GRP_NM_01` | "紹介者料金グループ名" |
| `SHO_SYSID_01` | "紹介者SYSID" |
| `SHO_CUST_NM_01` | "紹介者契約者名" |
| `SYSID_02` | "SYSID" |
| `SVC_KEI_NO_02` | "サービス契約番号" |

---

## How It Works

### Initial Display Flow

When a user navigates to this screen, the following sequence occurs:

```mermaid
sequenceDiagram
    participant JSP as WEBGAMEN_KKW010370PJP.jsp
    participant LOGIC as KKW01037SFLogic
    participant BEAN as KKW01037SFBean
    participant MAPPER as KKSV0784_KKSV0784OPDBMapper
    participant SERVICE as KKSV0784 Usecase
    participant CHECKER as KKW01037SFChecker

    Note over JSP, BEAN: Initial Display Flow (actionInit)

    JSP->>LOGIC: actionInit()
    LOGIC->>LOGIC: getScreenInfo()
    LOGIC->>LOGIC: setHktgiBean(bean)
    LOGIC->>MAPPER: setIntrInfoCfmCC(paramBean, inputMap)
    LOGIC->>SERVICE: doService("KKSV0784", "KKSV0784", inputMap, outputMap)
    SERVICE-->>LOGIC: outputMap
    LOGIC->>MAPPER: getIntrInfoCfmCC(paramBean, outputMap)
    MAPPER-->>BEAN: populate bean fields
    LOGIC->>JSP: return true, forward to JSP
```

1. **The JSP (`WEBGAMEN_KKW010370PJP.jsp`)** triggers the action, which creates a `KKW01037SFLogic` instance.

2. **`actionInit()`** is called:
   - Screen information from the previous screen is retrieved via `JCCWebCommon.getScreenInfo(this)`.
   - The common info bean is updated with the next screen name.
   - `setHktgiBean()` copies inherited fields (SYSID, service contract number, popup mode) from the prior screen's data bean array into the current screen's bean.

3. **Service input mapping** uses `KKSV0784_KKSV0784OPDBMapper.setIntrInfoCfmCC()` to populate the input map from the data beans, with function code `FUNC_CD_1`.

4. **Backend service invocation** calls usecase `KKSV0784` / operation `KKSV0784` via `doService()`. This is where the actual data retrieval from the database layer occurs (handled by the backend service infrastructure).

5. **Service output mapping** uses `KKSV0784_KKSV0784OPDBMapper.getIntrInfoCfmCC()` to populate the screen's data beans from the service output map.

6. **The JSP renders** the populated bean data to the user.

### Back Navigation Flow

```mermaid
sequenceDiagram
    participant JSP as WEBGAMEN_KKW010370PJP.jsp
    participant LOGIC as KKW01037SFLogic
    participant COMINF as CommonInfoBean

    JSP->>LOGIC: actionBack()
    LOGIC->>COMINF: set NEXT_SCREEN_ID = KKW01021
    LOGIC->>COMINF: set NEXT_SCREEN_NAME = KKW01021
    LOGIC->>JSP: return true, navigate back
```

### Screen Layout Structure

The screen is organized into two main list sections plus header fields:

**Header (non-repeatable):**
- Inherited SYSID and service contract number (read from prior screen)
- Referrer contract name, phone number, SYSID
- Popup mode indicator

**Repeatable List 1 — Service Contract List (サービス契約一覧リスト):**
Each row contains:
- Referrer customer SYSID (`hi_svc_kei_no`)
- Referrer pricing group name (`hi_prc_grp_nm`)
- Referrer status (`hi_svc_kei_stat`)
- Referrer service start date (`hi_svc_sta_ymd`)
- Introduction code (`intr_cd`)
- Coupon code (`coupon_cd`) — added in ANK-4416-00-00
- Introducer customer SYSID (`sho_svc_kei_no`)
- Introducer pricing group name (`sho_prc_grp_nm`)
- Introducer SYSID (`sho_sysid`)
- Introducer contract name (`sho_cust_nm`)

**Repeatable List 2 — Customer Contract Succession List (顧客契約引継リスト):**
Each row contains:
- SYSID (`sysid`)
- Service contract number (`svc_kei_no`)

---

## Data Model

The data model follows a hierarchical structure with the main form bean at the top and two typed list beans as children:

```mermaid
flowchart TD
    A["KKW01037SFBean
(Main Form Bean)"] -->|"holds list of"| B["KKW01037SF01DBean
(Service Contract Row)"]
    A -->|"holds list of"| C["KKW01037SF02DBean
(Succession Row)"]
    A -->|"contains"| D["hktg_sysid: String
hktg_svc_kei_no: String"]
    A -->|"contains"| E["hi_cust_nm: String
hi_telno: String
hi_sysid: String"]
    A -->|"contains"| F["popup_mode: String"]
    A -->|"contains"| G["svc_kei_list_list
X33VDataTypeList"]
    A -->|"contains"| H["cust_kei_hktgi_list_list
X33VDataTypeList"]
    B -->|"fields: "| I["hi_svc_kei_no
hi_prc_grp_nm
hi_svc_kei_stat
hi_svc_sta_ymd
intr_cd
coupon_cd
sho_svc_kei_no
sho_prc_grp_nm
sho_sysid
sho_cust_nm
(index)"]
    C -->|"fields: "| J["sysid
svc_kei_no
(index)"]
```

Each property in the data beans follows a four-part pattern:
- **`<field>_value`** — The actual data held by the field
- **`<field>_update`** — A flag indicating whether this field's value has been modified since last load
- **`<field>_enabled`** — Boolean indicating if the field is editable on the UI
- **`<field>_state`** — A string indicating the display state (e.g., read-only highlight, error state)

The list data beans (`KKW01037SF01DBean`, `KKW01037SF02DBean`) are stored inside `X33VDataTypeList` containers, which the X33V framework handles for iteration, addition, removal, and type-safe access.

---

## Dependencies and Integration

### Inbound (what uses this module)

| Consumer | Uses |
|----------|------|
| `WEBGAMEN_KKW010370PJP.jsp` | `KKW01037SF01DBean`, `KKW01037SFBean` |
| `WEBGAMEN_KKW010370PJP.xml` | `KKW01037SFBean`, `KKW01037SFLogic` |
| `x31business_logic_KKW01037SF.xml` | `KKW01037SFLogic` |

### Outbound (what this module depends on)

**Internal packages:**
- `eo.web.webview.KKW00127SF` — Referenced screen module
- `eo.web.webview.FUW09905SF` — Referenced screen module
- `eo.web.webview.KKA17401SF` — Referenced screen module
- `eo.web.webview.KKA17601SF` — Referenced screen module
- `eo.web.webview.KKA17101SF` — Referenced screen module
- `eo.web.webview.FUW00162SF` — Referenced screen module
- `eo.web.webview.CommonInfoCF` — Common info bean constants
- `eo.web.webview.commonOneStop` — One-stop screen module
- `eo.web.webview.mapping` — Data mappers (specifically `KKSV0784_KKSV0784OPDBMapper`)

**Framework classes:**
- `eo.web.webview.JCCWebBusinessLogic` — Parent class of `KKW01037SFLogic`
- `eo.web.webview.common.JCCWebCommon` — Screen info utility
- `eo.web.webview.common.JKKCommonConst` — Shared screen constants
- `eo.web.webview.common.JKKScreenConst` — Screen ID/name constants
- `com.fujitsu.futurity.web.x31` — X31C framework (data beans, GUI check, utilities)
- `com.fujitsu.futurity.web.x33` — X33V framework (view beans, data types, lists)
- `com.fujitsu.futurity.common.JSYwebLog` — Logging utility
- `eo.common.constant.JPCModelConstant` — Function code constants
- `eo.business.common` — Business common classes
- `eo.business.service` — Business service layer

---

## Notes for Developers

### Screen ID Navigation
The back button navigates to screen `KKW01021` (`SCREEN_ID_KKW01021` / `SCREEN_NAME_KKW01021`). This is hardcoded in `actionBack()` within `KKW01037SFLogic`.

### Inherited Data Source
The screen receives its initial context (hktg_sysid, hktg_svc_kei_no, popup_mode) from the calling screen's `hktgi_cust_kei_hktgi_list` data bean array — specifically the first element. This means the caller is responsible for pre-populating this list before navigation.

### Service Contract
The backend service is `KKSV0784` / `KKSV0784` with function code `FUNC_CD_1`. Any changes to the service interface require corresponding updates in the `KKSV0784_KKSV0784OPDBMapper` used by both `setInitService()` and `storeDataBeanInitService()`.

### GUI Validation
`KKW01037SFChecker.checkMethod()` currently returns `true` unconditionally. To add field-level validation, implement routing on `param.patternID` inside this method and use `errMsgStock` for custom error messages.

### Adding New List Fields
To add a new field to the service contract list:
1. Add the four properties (`_<field>_update`, `_<field>_value`, `_<field>_enabled`, `_<field>_state`) to `KKW01037SF01DBean`.
2. Add a constant in `KKW01037SFConst`.
3. Add routing in `KKW01037SF01DBean.loadModelData()`, `storeModelData()`, and `typeModelData()`.
4. Add the key in `KKW01037SF01DBean.listKoumokuIds()`.
5. Update `KKW01037SFBean.loadModelData()`, `storeModelData()`, and `typeModelData()` for the list element routing.

### Coupon Code Addition (ANK-4416-00-00)
The `coupon_cd` field was added to `KKW01037SF01DBean` and `KKW01037SFConst` as part of the ANK-4416-00-00 change to support simultaneous entry of introduction codes and partner-company entry codes. This serves as a template for similar field additions.

### Data Bean Logging
The logic class logs the full data bean state (`dumpDatabean()`) at both the end of `actionInit()` and `actionBack()`. This is useful for debugging data mapping issues but should not be removed — it is part of the standard X31C screen logging pattern.

### List Management
The `svc_kei_list_list` (service contract list) has no maximum element count — rows can be added or removed freely. The `cust_kei_hktgi_list_list` (customer contract succession list) has a configured maximum (`maxElementCnt`), and adding beyond it throws `ERRS_CANNOT_ADD_REPEATITEM`. Check the list bean's configuration if you need to adjust this limit.

### Framework Pattern
This module follows the standard X31C/X33V pattern:
- **Data routing** is done via string-key dispatch in `loadModelData` / `storeModelData` / `typeModelData`, not via reflection or annotation-based binding. Changes to field names require updating all three methods in both the main bean and the list beans.
- **List management** uses the X33V `X33VDataTypeList` infrastructure with typed inner beans.
- **Service invocation** is through the Futurity `invokeService()` pattern with explicit `usecase_id` / `operation_id` parameters.
- **Mapping** between screen beans and service maps is handled by auto-generated mapper classes (`KKSV0784_KKSV0784OPDBMapper`) created fresh per operation.