# Eo / Web / Webview / Kkw02410sf

## Overview

The **KKW02410SF** package handles femtocell option management — specifically the cancellation and recovery of femtocell options within the contract management system. When an operator navigates to this screen (typically from the optional service contract list), the module displays the current femtocell configuration and allows the operator to either cancel or reactivate the service. All business logic is delegated to backend services via a case-number-based invocation pattern.

## Key Classes and Interfaces

### KKW02410SFLogic

**File:** [`KKW02410SFLogic.java`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SFLogic.java)

The central business logic class for this module, extending [`JCCWebBusinessLogic`](source/koptWebFrontCommon/src/eo/web/webview/JCCWebBusinessLogic.java). It orchestrates the entire lifecycle of the femtocell option update screen.

#### Main Entry Point: `actionInit()`

This method initializes the screen display. The flow is:

1. Fetches screen context via `JCCWebCommon.getScreenInfo(this)`.
2. Retrieves the service form bean from the framework.
3. Calls `setHktgiBean()` to populate the bean with data inherited from the parent screen (the optional service contract list).
4. Calls `executeInitSvc()` to fetch the current femtocell configuration from the backend via service case `KKSV0577`.
5. Reads the `tran_div` (processing division) field to determine if the screen was entered for **cancellation** (`OP_TRAN_DIV_DSL`) or **recovery** (`OP_TRAN_DIV_KAIHK`).
6. Calls `setDataInit()` to set display values — for cancellation mode, the operational date becomes the end-use date and a notice label is set to "Femtocell Information Cancellation"; for recovery mode, it is set to "Femtocell Information Recovery".
7. Sets the next screen name (`KKW02410`) in the common info bean.
8. Logs the data bean state for debugging.

Returns `true` on success.

#### Data Population: `setHktgiBean()`

This private method copies data from the inherited customer contract list bean into the current screen's bean. Fields transferred include:

- Operation date (`use_ymd`)
- System ID (`sysid`)
- Service contract number (`svc_kei_no`)
- Error division (`ido_div`)
- Error reason code list and memo
- Optional service contract number (`op_svc_kei_no`)
- Processing division (`tran_div`)
- Application number (`mskm_no`) and detail number (`mskm_dtl_no`)

It iterates over the inherited error reason list, copying each reason code and memo into the current screen's error reason list bean.

#### Initial Service Call: `executeInitSvc()`

Invokes the backend service **KKSV0577** (femtocell option information inquiry) to fetch the current configuration. It uses [`KKSV0577_KKSV0577OPDBMapper`](source/koptWebB/src/eo/web/webview/mapping/KKSV0577_KKSV0577OPDBMapper.java) for both setting input parameters (option service contract agreement at `FUNC_CD_2` and inquiry at `FUNC_CD_1`) and retrieving results.

#### Confirmation: `actionFix()`

Triggered when the operator clicks the fix/confirm button. The method:

1. Reads the `tran_div` to determine the operation type.
2. If **cancellation** (`DSL`): calls `executeDslSvc()` and shows a "Femtocell option cancellation" message.
3. If **recovery** (`KAIHK`): calls `executeKaihkSvc()`, reads back the `rtn_msg_id`, and shows a "Femtocell option recovery" message.
4. On success (`rtn_msg_id` is empty), navigates to screen `KKW02411` and displays an info message.
5. On error (`rtn_msg_id` is populated), displays the error message — currently hardcoded as "Outside recovery period" with "Recovery" as the replacement text.

#### Cancellation Service: `executeDslSvc()`

Invokes service case **KKSV0578** (femtocell option cancellation confirmation). It:

1. Maps the option service cancellation CC, the SODCC, and the **femtocell error information registration CC** (added in v5.00 for ticket ST1-2013-0000397).
2. Clears the `rtn_msg_id`.
3. Calls `invokeService()` to execute the backend call.
4. Retrieves the cancellation result.

#### Recovery Service: `executeKaihkSvc()`

Invokes service case **KKSV0579** (femtocell option recovery). It:

1. Maps the option service recovery CC, SODCC, WORK mapping, and the femtocell error information registration CC (same as cancellation, added in v5.00).
2. Clears the `rtn_msg_id`.
3. Calls `invokeService()` to execute the backend call.
4. Retrieves the recovery result.

#### Navigation: `actionBack()` and `actionFin()`

Both set the next screen ID and name in the common info bean to return to the originating screen. `actionFin()` is called on final screen exit.

### KKW02410SFBean

**File:** [`KKW02410SFBean.java`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SFBean.java)

The main view bean for this screen. Extends `X33VViewBaseBean` and implements `X33VListedBeanInterface` and `X31CBaseBean`. It holds all the display fields for the femtocell option update form.

#### Field Groups

The bean's fields follow a consistent pattern of `_update`, `_value`, `_state`, and sometimes `_enabled` properties for each UI field. The fields are grouped by business domain:

**Business Operator Information:**
| Field | Purpose |
|-------|---------|
| `jigyosha_cd` | Business operator code (update/value/state + enabled) |
| `jigyosha_nm` | Business operator name (update/value/state + enabled) |
| `jigyosha_use_cd` | Business operator usage code (update/value/state + enabled) |

**Authentication Information:**
| Field | Purpose |
|-------|---------|
| `ninsyo_id` | Authentication ID (update/value/state + enabled) |
| `ninsyo_pwd` | Authentication password (update/value/state + enabled) |

**Service Period:**
| Field | Purpose |
|-------|---------|
| `use_staymd` | Use start date (update/value/state + enabled) |
| `use_endymd` | Use end date (update/value/state) |

**Identification & Contract:**
| Field | Purpose |
|-------|---------|
| `sysid` | System ID (update/value/state) |
| `svc_kei_no` | Service contract number (update/value/state) |
| `ido_div` | Error division (update/value/state) |
| `op_svc_kei_no` | Optional service contract number (update/value/state) |
| `tran_div` | Processing division — determines cancel vs. recovery (update/value/state) |
| `use_ymd` | Operational year-month-day (update/value/state) |
| `svc_kei_ucwk_no` | Service contract detail number (update/value/state) |
| `mskm_no` | Application number (update/value/state) |
| `mskm_dtl_no` | Application detail number (update/value/state) |

**Lists & Metadata:**
| Field | Purpose |
|-------|---------|
| `cust_kei_hktgi_list_list` | Customer contract inheritance list |
| `ido_rsn_list_list` | Error reason list |
| `rtn_msg_id` | Return message ID from backend (update/value/state) |
| `last_upd_dtm_op` | Last update datetime for optional service (update/value/state) |

#### List Helper Methods

- `getJsflist_typelist_cust_kei_hktgi_list()` — Iterates over the customer contract list and builds a `List<SelectItem>` for JSF dropdown rendering, using the "value" from each item's `loadModelData`.
- `getJsflist_typelist_ido_rsn_list()` — Same pattern for the error reason list.

### KKW02410SF01DBean

**File:** [`KKW02410SF01DBean.java`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SF01DBean.java)

A detail data bean used for the update-operation portion of the form. Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

#### Fields

This bean holds the subset of fields relevant to the detailed update view:

| Field | Purpose |
|-------|---------|
| `sysid` | System ID (update/value/state) |
| `svc_kei_no` | Service contract number (update/value/state) |
| `ido_div` | Error division (update/value/state) |
| `ido_rsn_cd_list` | List of error reason codes (`X33VDataTypeList`) |
| `ido_rsn_memo` | Error reason memo (update/value/state) |
| `op_svc_kei_no_list` | List of optional service contract numbers (`X33VDataTypeList`) |
| `tran_div` | Processing division (update/value/state) |
| `mskm_no` | Application number (update/value/state) |
| `mskm_dtl_no` | Application detail number (update/value/state) |
| `index` | Row index for list iteration |

#### List Management Methods

- `loadModelData(key, subkey)` — A reflective dispatcher that routes field reads based on the key/subkey combination. For simple string fields it delegates to the getter. For list fields (e.g., `ido_rsn_cd_list`), it handles index-based access including the `*` index which returns the list size.
- `storeModelData(...)` — Three overloads for setting data. The 4-parameter version handles `isSetAsString` for type coercion.
- `listKoumokuIds()` — Returns the list of field names (keys) for this bean's model.
- `typeModelData(key, subkey)` — Returns the `Class<?>` type for a given key/subkey, used by the framework for type-safe rendering.
- `addListDataInstance(key)`, `removeElementFromListData(key, index)`, `clearListDataInstance(key)` — Dynamic list management methods for adding, removing, and clearing list entries.

### KKW02410SF02DBean

**File:** [`KKW02410SF02DBean.java`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SF02DBean.java)

A lighter-weight detail data bean focused on the error reason details portion of the form. Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

#### Fields

| Field | Purpose |
|-------|---------|
| `ido_rsn_cd` | Error reason code (update/value/state) |
| `ido_rsn_memo` | Error reason memo (update/value/state) |
| `index` | Row index for list iteration |

This bean has fewer fields than `KKW02410SF01DBean` and does not initialize any lists in its constructor. It follows the same `loadModelData`/`storeModelData`/`listKoumokuIds`/`typeModelData` pattern for framework integration.

### KKW02410SFChecker

**File:** [`KKW02410SFChecker.java`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SFChecker.java)

Implements the `X31SGuiCheckBase` interface. The constructor takes a reference to the business logic class (`KKW02410SFLogic`). Currently, the `checkMethod()` always returns `true`, meaning no GUI-level validation is enforced at the framework level. This class is a placeholder where custom client-side validation could be added if needed.

### KKW02410SFConst

**File:** [`KKW02410SFConst.java`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SFConst.java)

A utility class holding all string constants used across the module. It has a private constructor (instantiation-proof) and all fields are `public static final String`.

#### Key Constant Categories

**Screen Fields:**

| Constant | Value | Usage |
|----------|-------|-------|
| `JIGYOSHA_CD` | "事業者コード" | Business operator code |
| `JIGYOSHA_NM` | "事業者名" | Business operator name |
| `JIGYOSHA_USE_CD` | "事業者使用コード" | Business operator usage code |
| `NINSYO_ID` | "認証ID" | Authentication ID |
| `NINSYO_PWD` | "認証IDパスワード" | Authentication password |
| `USE_STAYMD` | "利用開始日" | Use start date |
| `USE_ENDYMD` | "利用終了日" | Use end date |
| `SYSID` | "SYSID" | System ID |
| `SVC_KEI_NO` | "サービス契約番号" | Service contract number |
| `IDO_DIV` | "異動区分" | Error/transfer division |
| `OP_SVC_KEI_NO` | "オプションサービス契約番号" | Optional service contract number |
| `TRAN_DIV` | "処理区分" | Processing division (DSL/KAIHK) |
| `USE_YMD` | "運用年月日" | Operational date |
| `SVC_KEI_UCWK_NO` | "サービス契約内訳番号" | Service contract detail number |
| `MSKM_NO` | "申込番号" | Application number |
| `MSKM_DTL_NO` | "申込明細番号" | Application detail number |
| `LAST_UPD_DTM_OP` | "最終更新年月日时分秒（オプションサービス契約）" | Last update timestamp |
| `RTN_MSG_ID` | "返却メッセージID" | Return message ID from backend |
| `PRG_TKJK_1` | "進捗特記事項１" | Progress note field 1 |

**List Keys:**

| Constant | Value | Usage |
|----------|-------|-------|
| `CUST_KEI_HKTGI_LIST` | "顧客契約引継リスト" | Customer contract list key |
| `IDO_RSN_LIST` | "異動理由リスト" | Error reason list key |

**Inherited Field Keys (from parent screen):**

| Constant | Value | Source |
|----------|-------|--------|
| `SYSID_01` | "SYSID" | Inherited from parent list |
| `SVC_KEI_NO_01` | "サービス契約番号" | Inherited from parent list |
| `IDO_DIV_01` | "異動区分" | Inherited from parent list |
| `IDO_RSN_CD_01` | "異動理由コード" | Inherited error code |
| `IDO_RSN_MEMO_01` | "異動理由メモ" | Inherited error memo |
| `OP_SVC_KEI_NO_01` | "オプションサービス契約番号" | Inherited optional service |
| `TRAN_DIV_01` | "処理区分" | Inherited processing division |
| `MSKM_NO_01` | "申込番号" | Inherited application number |

## How It Works

### Typical Screen Flow

```mermaid
flowchart TD
    A["Operator arrives from
Optional Service Contract List"] --> B["actionInit()"]
    B --> C["getScreenInfo
retrieve context"]
    C --> D["setHktgiBean
populate from
inherited bean"]
    D --> E["executeInitSvc
KKSV0577 service
inquire femtocell info"]
    E --> F{"Check tran_div
value"}
    F -->|"DSL - Cancel"| G["Display 'Femtocell
Option Cancellation'"]
    F -->|"KAIHK - Recovery"| H["Display 'Femtocell
Option Recovery'"]
    G --> I["Render screen to user"]
    H --> I
    I --> J{"Operator clicks Fix/Confirm"}
    J -->|"Cancel"| K["actionFix -> executeDslSvc
KKSV0578: cancellation
KKSV0578 sets SODCC
KKSV0578 sets fmtcel IdoInfAddCC"]
    J -->|"Recover"| L["actionFix -> executeKaihkSvc
KKSV0579: recovery
KKSV0579 sets SODCC
KKSV0579 sets WORK
KKSV0579 sets fmtcel IdoInfAddCC"]
    K --> M{"rtn_msg_id empty?"}
    L --> M
    M -->|"Yes"| N["Navigate to KKW02411
Display info message"]
    M -->|"No"| O["Display error message
with replacement text"]
```

### Cancellation Flow (tran_div = DSL)

1. **`actionFix()`** reads `tran_div` and detects `OP_TRAN_DIV_DSL`.
2. Calls **`executeDslSvc()`** which:
   - Sets up service case `KKSV0578`.
   - Maps the option service cancellation CC (`setOpSvcKeiDslCC`).
   - Maps the SODCC (`setJKKHakkoSODCC`).
   - Maps the femtocell error information registration CC (`setFmtcelIdoInfAddCC`) — added in v5.00.
   - Clears the return message ID.
   - Calls `invokeService()` with the mapped input.
   - Retrieves the cancellation result via `getOpSvcKeiDslCC()`.
3. If the backend returns successfully (empty `rtn_msg_id`), navigates to screen `KKW02411`.

### Recovery Flow (tran_div = KAIHK)

1. **`actionFix()`** reads `tran_div` and detects `OP_TRAN_DIV_KAIHK`.
2. Calls **`executeKaihkSvc()`** which:
   - Sets up service case `KKSV0579`.
   - Maps the option service recovery CC (`setOpSvcKeiKaihkCC`).
   - Maps the SODCC (`setJKKHakkoSODCC`).
   - Maps the WORK (`setKKSV0009WORK`).
   - Maps the femtocell error information registration CC (`setFmtcelIdoInfAddCC`).
   - Clears the return message ID.
   - Calls `invokeService()`.
   - Retrieves the result via `getOpSvcKeiKaihkCC()`.
3. The `rtn_msg_id` from the service is read back. If non-empty, an error message is shown (currently the replacement text "Outside recovery period" is hardcoded).

## Data Model

The module operates on three layers of data beans:

### Layer 1: KKW02410SFBean (Main Form Bean)

Holds all fields that appear on the main screen. Each field has:
- **`*_update`** — Update/change indicator flag.
- **`*_value`** — The actual data value displayed or submitted.
- **`*_state`** — Display state (e.g., normal, error, disabled).
- **`*_enabled`** (for some fields) — Boolean controlling UI editability.

Two list-type fields hold collections:
- `cust_kei_hktgi_list_list` — The inherited customer contract list from the parent screen.
- `ido_rsn_list_list` — The error reason codes and memos.

### Layer 2: KKW02410SF01DBean / KKW02410SF02DBean (Detail Beans)

These are sub-beans used for rendering and editing specific sections of the form. They use the key/subkey reflection model: `loadModelData("field_name", "value")` and `storeModelData("field_name", "value", data)`.

### Layer 3: Framework Beans (X31SDataBeanAccess)

The logic layer uses `X31SDataBeanAccess` objects to communicate field data through the framework's message-passing system (`sendMessageString`, `sendMessage`). Service cases are invoked via `invokeService()` with HashMap-based parameter maps.

## Dependencies and Integration

### Backend Services

The module invokes three distinct backend service cases:

| Service Case | Purpose | Mapped By |
|-------------|---------|-----------|
| **KKSV0577** | Femtocell option info inquiry (initial load) | [`KKSV0577_KKSV0577OPDBMapper`](source/koptWebB/src/eo/web/webview/mapping/KKSV0577_KKSV0577OPDBMapper.java) |
| **KKSV0578** | Femtocell option cancellation confirmation | [`KKSV0578_KKSV0578OPDBMapper`](source/koptWebB/src/eo/web/webview/mapping/KKSV0578_KKSV0578OPDBMapper.java) |
| **KKSV0579** | Femtocell option recovery | [`KKSV0579_KKSV0579OPDBMapper`](source/koptWebB/src/eo/web/webview/mapping/KKSV0579_KKSV0579OPDBMapper.java) |

All three share common mappings: SODCC and femtocell error info registration CC (via KKSV0578 mapper), with KKSV0579 additionally mapping a WORK case.

### Inbound Dependencies

Two XML configuration files reference this module's classes:

- `WEBGAMEN_KKW024100PJP.xml` — Uses `KKW02410SFBean` and `KKW02410SFLogic`.
- `WEBGAMEN_KKW024110PJP.xml` — Uses `KKW02410SFBean` and `KKW02410SFLogic` (the destination screen after fix).
- `x31business_logic_KKW02410SF.xml` — Declares the business logic configuration for `KKW02410SFLogic`.

### Framework Dependencies

- **Fujitsu Futurity X31/X33 Framework** — The entire module relies on this framework for bean lifecycle, GUI validation, and service invocation.
- **JSF (JavaServer Faces)** — Used for UI rendering, evidenced by `SelectItem` imports.
- **JCCWebBusinessLogic** — The parent class providing common web business logic patterns.

## Notes for Developers

### Processing Division (tran_div)

The `tran_div` field is the key control parameter for this module. It is set from the parent screen and never changed on this screen:

- `OP_TRAN_DIV_DSL` (cancel) — triggers the cancellation flow with `KKSV0578`.
- `OP_TRAN_DIV_KAIHK` (recovery) — triggers the recovery flow with `KKSV0579`.

The screen title ("Femtocell option Cancellation" vs "Femtocell option Recovery") is derived from this value.

### Screen Navigation

- **Entry:** From the optional service contract list screen.
- **Fix success:** Navigates to screen `KKW02411` (`SCREEN_NAME_KKW02411`).
- **Fix failure:** Stays on the current screen with an error message.
- **Back/Finish:** Returns to the originating screen ID.

### Error Handling

Currently, the error message replacement for recovery errors is hardcoded:

```java
String[] str = {"Outside recovery period", "Recovery"};
```

The original message substitution logic (`getMsgRep`) was removed in v4.01. If the backend returns an `rtn_msg_id`, the screen displays it using `JCCWebCommon.setMessageInfo()` — either directly or with the hardcoded replacement.

### Changelog Highlights

| Version | Date | Change |
|---------|------|--------|
| v4.00 | 2012/06/11 | Initial creation |
| v4.01 | 2012/10/07 | Quality review: removed unused code (SbtCd constant, message replacement logic) |
| v4.02 | 2012/11/05 | Progress note item editing support (ANK-1223-00-00) |
| v5.00 | 2013/02/22 | Added femtocell error information registration CC mapping (ST1-2013-0000397) |

### Bean Field Naming Convention

Each field follows a uniform naming pattern with `*_update`, `*_value`, `*_state` (and sometimes `*_enabled`) properties. The suffix convention:

- `*_update` — Change flag for the field.
- `*_value` — Current data value.
- `*_state` — UI state indicator.
- `*_enabled` — Editability flag (Boolean, only for operator/auth fields).

### Constants Pattern

All field keys are defined in [`KKW02410SFConst`](source/koptWebB/src/eo/web/webview/KKW02410SF/KKW02410SFConst.java) using Japanese strings as keys. The "01" suffixed constants (`SYSID_01`, etc.) reference the field keys from the **inherited** parent screen bean, while the non-suffixed versions are for the current screen's bean. Be careful not to confuse these two sets when adding new fields.