# Eo / Web / Webview / Kkw02541sf

## Overview

This module implements the **band restriction inquiry screen** (`帯域制限照会画面`). It displays a list of band (帯域) information records associated with a service contract, allowing users to view details such as authentication IDs, usage months, advance notice dates, and implementation dates for each band. The module is part of the K-Opticom contract management system and follows the Fujitsu Futurity X31/X33 web framework conventions for data binding and GUI validation.

---

## Key Classes and Interfaces

### KKW02541SFLogic

**Path:** [`source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFLogic.java`](source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFLogic.java)

This is the main business logic class for the screen. It extends `JCCWebBusinessLogic` and orchestrates the initialization flow when a user opens the band restriction inquiry screen.

#### Key methods

- **`actionInit()`** (public, returns `boolean`)
  - Entry point for initial screen display.
  - Acquires screen information via `JCCWebCommon.getScreenInfo(this)`, then retrieves the service form bean.
  - Calls three private setup methods in sequence:
    1. `setHktgiBean()` — copies inherited data (service contract number) from the parent context into the main bean.
    2. `executeInitSvc()` — invokes the band information inquiry service (use case `KKSV0573`) to fetch the band list.
    3. `setNinshoID()` — processes each band row to construct display-friendly authentication IDs.
  - Sets the next screen name on the common info bean and dumps the DataBean state for logging.

- **`executeInitSvc(X31SDataBeanAccess[] paramBean)`** (private, returns `void`)
  - Executes the band information inquiry service using the use case ID `KKSV0573`.
  - Creates an `KKSV0573_KKSV0573OPDBMapper` to map between service items and DataBean items (both for input and output).
  - Calls `invokeService(paramMap, inputMap, outputMap)` to call the backend service, then maps the results back into the bean.

- **`setHktgiBean(X31SDataBeanAccess[] paramBean)`** (private, returns `void`)
  - Copies the service contract number (`svc_kei_no`) from the parent context into the main bean.
  - Contains commented-out code (v4.01, IT1-2012-0001210 fix) that previously copied sysid and svc_kei_no from an inherited contract list bean. This was simplified to read directly from the main bean.

- **`setNinshoID(X31SDataBeanAccess[] paramBean)`** (private, returns `void`)
  - Iterates over each band info row (`tik_list`) and constructs a display authentication ID.
  - For each row, it retrieves the `isp_ninsho_id` and `mltise_ninsho_id`. If `mltise_ninsho_id` is empty, the display ID is just `isp_ninsho_id`; otherwise, it concatenates them with a comma: `isp_ninsho_id,mltise_ninsho_id`.
  - Also sets alternating `row_style` values (`odd` / `even`) for CSS striping, added as part of the accessibility fix (v4.01).

---

### KKW02541SFChecker

**Path:** [`source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFChecker.java`](source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFChecker.java)

This class implements the `X31SGuiCheckBase` interface for GUI validation on this screen. It holds a reference to the business logic (`X31BBusinessLogic bl`) passed in via the constructor.

- **`checkMethod(X31SGuiCheckParam param, X31GUtilStockMessage errMsgStock)`** (returns `boolean`)
  - Currently a pass-through stub that always returns `true`.
  - Receives the `patternID` from the param but does not branch on it — no validation logic is implemented yet.
  - This is the intended extension point for adding field-level or business-rule validation on form submission.

---

### KKW02541SFBean

**Path:** [`source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFBean.java`](source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFBean.java)

The root data bean for the screen. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface`, `X31CBaseBean`, and `Serializable`. This is the primary bridge between the view layer (JSF pages) and the business logic layer.

#### Top-level properties

| Property | Type | Purpose |
|---|---|---|
| `tik_list_list` | `X33VDataTypeList` | Dynamic list of band info rows (`KKW02541SF01DBean`). Growable at runtime. |
| `svc_kei_no_value` | `String` | Service contract number (display value). |
| `svc_kei_no_state` | `String` | Display state for the service contract number. |
| `cust_kei_hktgi_list_list` | `X33VDataTypeList` | Customer contract inheritance list (`KKW02541SF02DBean`). Fixed to 1 element. |

#### Key methods

- **Constructor** — Initializes both `X33VDataTypeList` objects. `tik_list_list` starts empty (elements added dynamically). `cust_kei_hktgi_list_list` is initialized with exactly one `KKW02541SF02DBean` element.

- **`getJsflist_typelist_tik_list()`** — Builds an `ArrayList<SelectItem>` from the `tik_list_list` for dropdown rendering. Each item's value is taken from the band row's `帯域情報リスト` key.

- **`getJsflist_typelist_cust_kei_hktgi_list()`** — Similar dropdown builder for the customer contract inheritance list.

- **`loadModelData(String key, String subkey)`** — Central data retrieval dispatcher. Supports dot-path syntax:
  - `帯域情報リスト/0/ISP認証ID` → gets field `isp_ninsho_id_value` from index 0 of the band list.
  - `サービス契約番号/value` → returns `svc_kei_no_value`.
  - `顧客契約引継リスト/*` → returns the count of rows in the contract inheritance list.
  - `//` prefix → delegates to common info bean processing.

- **`storeModelData(String key, String subkey, Object in_value, boolean isSetAsString)`** — The inverse of `loadModelData`. Routes set operations to the correct nested bean based on the key path. Supports the `isSetAsString` flag for Long-type properties.

- **`addListDataInstance(String key)`** — Dynamically adds a row to a repeat list. For `帯域情報リスト`, creates a new `KKW02541SF01DBean`. For `顧客契約引継リスト`, creates a new `KKW02541SF02DBean` (subject to max element count).

- **`removeElementFromListData(String key, int index)`** — Removes an element at the given index from the specified list.

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

- **`typeModelData(String key, String subkey)`** — Returns the `Class<?>` type for a given property path, enabling the framework to perform type-safe data binding.

---

### KKW02541SF01DBean

**Path:** [`source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SF01DBean.java`](source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SF01DBean.java)

A data-type bean representing a **single row** in the band information list (`tik_list`). It implements `X33VDataTypeBeanInterface`, `X33VListedBeanInterface`, and `Serializable`. This is the core entity for the screen's main data grid.

#### Fields (each row)

| Field name (key) | Java property | Type | Description |
|---|---|---|---|
| `ISP認証ID` | `isp_ninsho_id_value` | `String` | ISP-specific authentication ID |
| マルチセッショニング用認証ID | `mltise_ninsho_id_value` | `String` | Multi-session authentication ID |
| 表示用認証ID | `ninsho_id_value` | `String` | Combined display authentication ID (computed by `setNinshoID()`) |
| 利用月 | `riyo_ym_value` | `String` | Usage month (YYYYMM format) |
| 事前警告日 | `yokoku_ymd_value` | `String` | Advance notice date |
| 帯域制限実施日 | `jishi_ymd_value` | `String` | Band restriction implementation date |
| 行スタイル | `row_style_value` | `String` | CSS row style (`odd` or `even` for alternating row colors) |

Each of the first six fields also has:
- `*_update` — update flag (String)
- `*_enabled` — enabled state (Boolean, default `false`)
- `*_state` — display state (String)

There is also a simple `index` (int) field for row positioning.

#### Key methods

- **`loadModelData(String key, String subkey)`** — Routes reads to the correct field. The `subkey` parameter determines what to return: `value` → the field value, `enable` → the `*_enabled` flag, `state` → the `*_state` field.

- **`storeModelData(String key, String subkey, Object in_value)`** — Routes writes to the correct field using the same key/subkey convention.

- **`listKoumokuIds()`** (static) — Returns a list of all field keys defined on this bean: `ISP認証ID`, `マルチセッショニング用認証ID`, `表示用認証ID`, `利用月`, `事前警告日`, `帯域制限実施日`, `行スタイル`.

- **`typeModelData(String key, String subkey)`** — Returns `String.class` for value/state subkeys and `Boolean.class` for the enable subkey.

---

### KKW02541SF02DBean

**Path:** [`source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SF02DBean.java`](source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SF02DBean.java)

A data-type bean representing a **customer contract inheritance row** (`cust_kei_hktgi_list`). This bean handles supplementary data associated with a customer contract, including transfer/divergence details.

#### Fields

| Field name (key) | Java property | Type | Description |
|---|---|---|---|
| `SYSID` | `sysid_value` | `String` | System ID |
| `サービス契約番号` | `svc_kei_no_value` | `String` | Service contract number |
| `異動区分` | `ido_div_value` | `String` | Transfer/divergence category |
| `異動理由コード` | `ido_rsn_cd_list` | `X33VDataTypeList` | Divergence reason code list (dynamic) |
| `異動理由メモ` | `ido_rsn_memo_value` | `String` | Divergence reason memo |
| `オプションサービス契約番号` | `op_svc_kei_no_list` | `X33VDataTypeList` | Optional service contract number list (dynamic) |
| `処理区分` | `tran_div_value` | `String` | Processing category |
| `申込番号` | `mskm_no_value` | `String` | Application number |
| `申込明細番号` | `mskm_dtl_no_value` | `String` | Application detail number |

The `*_state` fields (but not `*_enabled` flags) are present for all String fields, and each also has a `*_update` flag.

#### Key methods

- **`loadModelData` / `storeModelData`** — Routes data access by key name. For the two list fields (`ido_rsn_cd_list` and `op_svc_kei_no_list`), the key uses an index suffix: `異動理由コード/0` accesses element 0.

- **`getJsflist_ido_rsn_cd()`** / **`getJsflist_op_svc_kei_no()`** — Build dropdown `SelectItem` lists from the nested string lists.

- **`addListDataInstance` / `removeElementFromListData` / `clearListDataInstance`** — Manage the nested list fields (`異動理由コード` and `オプションサービス契約番号`).

---

### KKW02541SFConst

**Path:** [`source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFConst.java`](source/koptWebB/src/eo/web/webview/KKW02541SF/KKW02541SFConst.java)

A utility class holding string constants used across the module. It has a private constructor (utility class pattern). These constants provide Japanese-language display labels that serve as the lookup keys in the `loadModelData` / `storeModelData` routing logic.

Key constants include:
- `TIK_LIST` — "帯域情報リスト" (band information list)
- `SVC_KEI_NO` — "サービス契約番号" (service contract number)
- `CUST_KEI_HKTGI_LIST` — "顧客契約引継リスト" (customer contract inheritance list)
- `ISP_NINSHO_ID_01` — "ISP認証ID"
- `MLTISE_NINSHO_ID_01` — "マルチセッショニング用認証ID"
- `NINSHO_ID_01` — "表示用認証ID"
- `RIYO_YM_01` — "利用月"
- `YOKOKU_YMD_01` — "事前警告日"
- `JISHI_YMD_01` — "帯域制限実施日"
- `ROW_STYLE_01` — "行スタイル"
- `IDO_DIV_02`, `IDO_RSN_CD_02`, `IDO_RSN_MEMO_02` — divergence-related keys
- `TRAN_DIV_02`, `MSKM_NO_02`, `MSKM_DTL_NO_02` — processing/application keys

---

## How It Works

### Initial screen display flow

```
User opens screen
    │
    ▼
KKW02541SFLogic.actionInit()
    │
    ├── JCCWebCommon.getScreenInfo(this)    → acquire screen metadata
    ├── setHktgiBean(paramBean)              → copy svc_kei_no from parent context
    │
    ├── executeInitSvc(paramBean)
    │       │
    │       ├── Create KKSV0573_KKSV0573OPDBMapper
    │       ├── map service items → DataBean items (input)
    │       ├── invokeService(…, "KKSV0573") → call backend service
    │       └── map service results → DataBean items (output)
    │
    ├── setNinshoID(paramBean)
    │       │
    │       ├── For each row in tik_list:
    │       │   - Read isp_ninsho_id and mltise_ninsho_id
    │       │   - Compute ninsho_id (concatenated or single)
    │       │   - Set row_style (odd/even for CSS striping)
    │       │
    ├── Set NEXT_SCREEN_NAME on common info bean
    └── dumpDatabean() for logging
```

1. **`actionInit()`** is invoked by the framework as the screen initialization handler.
2. **`setHktgiBean()`** extracts the service contract number from the inherited context and stores it in the bean for display.
3. **`executeInitSvc()`** calls the backend service `KKSV0573` to fetch the band information list. The mapper converts between service response format and the DataBean format used by this screen.
4. **`setNinshoID()`** post-processes the returned rows to create user-friendly authentication IDs and alternating row styles.

### Data flow pattern

The module follows a standard X31/X33 MVC pattern:

1. The framework creates a `KKW02541SFBean` and passes it through `X31SDataBeanAccess` wrappers.
2. `KKW02541SFLogic` manipulates the bean through `sendMessageString()` calls, which internally route to `loadModelData`/`storeModelData` by key name and subkey.
3. The `KKSV0573_KKSV0573OPDBMapper` handles mapping between the service's business data format and the DataBean format.
4. The bean is then passed to the JSF view for rendering, where data-binding expressions access fields through the same key/subkey routing.
5. On form submission, values flow back through `storeModelData` into the bean, where they can be processed by validation or business logic.

### Authentication ID composition

A notable design decision in `setNinshoID()`: when both `isp_ninsho_id` and `mltise_ninsho_id` are present, they are joined with a comma (`,`) into the `ninsho_id` display field. If only the ISP ID is present, it is used as-is. This allows the display to show multiple authentication context identifiers without cluttering the UI with extra columns.

---

## Data Model

The data model is hierarchical:

```
KKW02541SFBean (root)
├── tik_list_list (X33VDataTypeList)
│   └── [] × KKW02541SF01DBean (band info row)
│       ├── isp_ninsho_id_value / enabled / state / update
│       ├── mltise_ninsho_id_value / enabled / state / update
│       ├── ninsho_id_value / enabled / state / update
│       ├── riyo_ym_value / enabled / state / update
│       ├── yokoku_ymd_value / enabled / state / update
│       ├── jishi_ymd_value / enabled / state / update
│       ├── row_style_value / state / update
│       └── index (int)
├── svc_kei_no_value / state / update
├── cust_kei_hktgi_list_list (X33VDataTypeList, fixed size 1)
│   └── 1 × KKW02541SF02DBean (contract inheritance row)
│       ├── sysid_value / state / update
│       ├── svc_kei_no_value / state / update
│       ├── ido_div_value / state / update
│       ├── ido_rsn_cd_list (X33VDataTypeList, dynamic)
│       │   └── [] × String (divergence reason codes)
│       ├── ido_rsn_memo_value / state / update
│       ├── op_svc_kei_no_list (X33VDataTypeList, dynamic)
│       │   └── [] × String (optional service contract numbers)
│       ├── tran_div_value / state / update
│       ├── mskm_no_value / state / update
│       └── mskm_dtl_no_value / state / update
└── index (int)
```

Each repeated row bean (01DBean / 02DBean) carries a consistent four-field pattern per property: `*_value` (the actual data), `*_enabled` (Boolean for field enablement), `*_state` (String for UI state), and `*_update` (String for update tracking). The row style field uses only `value` and `state` (no enable flag).

---

## Dependencies and Integration

### Inbound dependencies (who uses this module)

| XML Config | Classes Used |
|---|---|
| `WEBGAMEN_KKW025410PJP.xml` | `KKW02541SFBean`, `KKW02541SFLogic` |
| `x31business_logic_KKW02541SF.xml` | `KKW02541SFLogic` |

These XML configs wire the beans and logic into the X31 framework's navigation and service layers.

### Outbound dependencies (what this module uses)

| Category | Classes/Modules |
|---|---|
| **Framework** | `JCCWebBusinessLogic`, `X31CBaseBean`, `X31SGuiCheckBase`, `X33VViewBaseBean`, `X33VListedBeanInterface` |
| **Business service** | `KKSV0573_KKSV0573OPDBMapper` — maps the KKSV0573 use case service calls |
| **Common** | `JCCWebCommon`, `JPCModelConstant`, `CommonInfoCFConst`, `JKKScreenConst` |
| **Parent modules** | `eo.business.common`, `eo.business.service`, `eo.common.constant`, `eo.common.util`, `eo.ejb.cbs.mainproc`, `eo.ejb.common.edit` |
| **Sibling modules** | `eo.web.webview.KKA17201SF`, `KKW00127SF`, `FUW00162SF`, `SCW00101SF`, `KKA17101SF`, `KKA17401SF`, `FUW09905SF`, `commonOneStop`, `mapping`, `common` |

---

## Mermaid Diagram — Class Relationships

```mermaid
flowchart TD
    A["KKW02541SFLogic<br/>Business Logic"] -->|"uses"| B["KKW02541SFChecker<br/>GUI Validation"]
    A -->|"uses"| C["KKW02541SFBean<br/>Root Data Bean"]
    A -->|"calls"| D["KKSV0573OPDBMapper<br/>Service Mapper"]
    C -->|"contains"| E["tik_list<br/>X33VDataTypeList<KKW02541SF01DBean>"]
    C -->|"contains"| F["cust_kei_hktgi_list<br/>X33VDataTypeList<KKW02541SF02DBean>"]
    E -->|"element type"| G["KKW02541SF01DBean<br/>Band Info Row"]
    F -->|"element type"| H["KKW02541SF02DBean<br/>Contract History Row"]
    G -->|"fields"| I["isp_ninsho_id<br/>mltise_ninsho_id<br/>ninsho_id<br/>riyo_ym<br/>yokoku_ymd<br/>jishi_ymd<br/>row_style"]
    H -->|"fields"| J["sysid<br/>svc_kei_no<br/>ido_div<br/>ido_rsn_cd<br/>ido_rsn_memo<br/>op_svc_kei_no<br/>tran_div<br/>mskm_no<br/>mskm_dtl_no"]
```

---

## Notes for Developers

### Framework conventions

- **Key-based data binding**: All field access goes through `loadModelData` / `storeModelData` using Japanese-language string keys and subkey suffixes (`value`, `enable`, `state`). Do not directly access bean fields from the view layer; always use these routing methods.

- **Path syntax**: Nested list access uses slash-separated paths: `帯域情報リスト/2/ISP認証ID/value` accesses the ISP auth ID on row 2. The special key `*` returns the list element count.

- **Common info prefix**: Keys starting with `//` are delegated to the parent class's common info bean processing, not handled locally.

### Validation

The `KKW02541SFChecker` class is a current stub that always returns `true`. If you need to add field validation or business-rule checks on form submission, implement the routing logic in `checkMethod()` based on `param.patternID`.

### List management

- `tik_list` (band info rows) is dynamically sized — rows are added/removed by the service response. Use `addListDataInstance("帯域情報リスト")` to append rows.
- `cust_kei_hktgi_list` (contract inheritance) is fixed to 1 element by default. Attempting to add beyond the max will throw an `X33SException`.

### Row styling

The `row_style` field is set automatically in `setNinshoID()` based on row index parity (`i % 2`). This is used for CSS alternating row colors (odd/even striping), added as part of an accessibility fix. Do not override this field manually.

### Version history notes

- **v4.01 (2012/10/03, IT1-2012-0001210)**: Simplified the service contract number copy logic in `setHktgiBean()` and added row-style computation. The previous approach of extracting from a parent contract inheritance list was removed.

### No child modules

This package has no sub-packages or child wiki pages. All logic for this screen resides in these six source files.