# Eo / Web / Webview / Kka14201sf

## Overview

This module implements the **My Homepage Information Change** feature (`Myホームページ情報変更部品`). It provides a web-based interface that allows customers to view and modify the settings of their My Homepage — specifically the homepage storage capacity, the homepage access domain/account settings, and the WebID / access analysis options. It also handles service cancellation, recovery (reinstatement), and reservation cancellation for optional services tied to the My Homepage.

The module is reached from the **Optional Service Contract List** screen. It follows the standard X31/X33 web framework pattern: a main DataBean holds all screen fields, a business logic class orchestrates service invocations and validation, and several supporting beans handle list-type data structures (e.g., pulldown select items).

Starting from v18.00.00 (2015/09), this module was copied from the koptWebB project to koptWebA as part of a OneStop migration effort, meaning it exists in both web modules but the primary implementation resides in koptWebA.

---

## Key Classes and Interfaces

### [KKA14201SFLogic](source/koptWebA/src/eo/web/webview/KKA14201SF/KKA14201SFLogic.java)

The central business logic class, extending `JCCWebBusinessLogic`. This class handles the entire lifecycle of the My Homepage information change flow:

- **Initial display** — queries backend services to retrieve the customer's current My Homepage settings, maps results into the form bean, and renders the initial view.
- **Update processing** — validates changes, calls the "My Homepage Info Change Confirm" service (`KKSV0008`), and navigates to the confirmation screen.
- **Confirmation (fix) processing** — executes the actual change or cancellation registration by calling the appropriate backend service based on the operation type.
- **Cancellation / Recovery / Reservation Cancellation** — dedicated flows for each operation type, each invoking their own backend service.

#### Key methods

| Method | Purpose |
|---|---|
| `actionInit()` | Entry point for initial display. Sets up screen info, calls `setDataInit()` to prepare input, invokes the KKSV0007 (My HP Info Inquiry) service, then `storeGetDataInit()` to map service results into the bean. Handles billing eligibility determination for sub-optional services. |
| `actionUpdMyHPInfo()` | Update button processing. Determines whether the user is changing or cancelling (via `TRANDIV`), validates that URL is not being changed from present to absent, calls `setDataUpd()` or `setDataDsl()`, then invokes `KKSV0008` or `KKSV0009` respectively. Navigates to confirmation screen `KKW02505`. |
| `actionFixMyHPInfo()` | Confirmation (fix) button processing. Dispatches to the correct service based on operation type: `KKSV0008` (change), `KKSV0009` (cancellation), `KKSV0004` (recovery), or `KKSV0017` (reservation cancellation). Navigates to completion screen `KKW02506`. |
| `actionShusei()` | Edit button — returns to the change screen (`KKW02504`). |
| `actionBack()` | Back button — returns to the calling screen. |
| `actionFin()` | Completion button — returns to the calling screen. |
| `actionClear()` | Clear button — re-invokes `actionInit()` to reset the page. |
| `invokeService()` | Generic service invocation helper. Sets up input/output maps, calls `invokeService(paramMap, inputMap, outputMap)` from the parent class, and logs DataBean state before/after. |
| `setDataInit()` | Pre-service initialization. Sets operational date, price plan codes, service status codes, and copies transfer information (SYSID, service contract number, modification reason code, subscription number) from the customer contract transfer list. |
| `storeGetDataInit()` | Post-service initialization. Sets display fields from service results: homepage capacity, access analysis selection, modification type flags. Determines whether homepage capacity or access analysis sub-optional services are active. |
| `setDataUpd()` | Update DataBean setting. Validates that at least one field changed (homepage capacity, access analysis, or URL). Computes update type codes (chargeable/uncharged/unchanged) for each field. Sets submission metadata. Returns false if no changes detected. |
| `setDataDsl()` | Cancellation DataBean setting. Prepares cancellation-specific fields. |
| `setDataKaihk()` | Recovery DataBean setting. Sets up recovery operation parameters. |
| `setDataDslStp()` | Reservation cancellation DataBean setting. |
| `getUpd_kind_hp()` | Determines the change type for homepage capacity by comparing before/after capacity values against the free tier. Returns a code indicating whether the change involves becoming chargeable, becoming free, continuing as chargeable, or continuing as free. |
| `getUpd_kind_accs()` | Determines the change type for access analysis (active/inactive). |
| `getUpd_kind_url()` | Determines the change type for URL (changed/unchanged). |
| `setBtnVisibleAtTel()` / `setBtnVisibleAtNet()` / `setBtnVisibleAtTv()` | Button visibility control methods. Based on modification reason code (`IDO_DIV`), service code, and service contract status, determines which action buttons (view, add, change, cancel, recovery, reservation cancel, OP pack) are visible, active, or hidden. These methods exist for different service categories (telephone, network, TV). |
| `getNextScreenInfo()` | Returns the target screen ID, name, and end screen ID based on the action button and optional service code. Handles 20+ different service types, each with its own pair of confirmation/completion screens. |
| `getMsgRep()` | Retrieves replacement string arrays for message IDs returned by backend services. |
| `dslChk()` | Checks whether a sub-optional service contract status permits cancellation order submission. |
| `changeAccssBnsk()` | Maps access analysis values between OneStop format ("0"/"1") and display format ("1"/"0"). |
| `actionDslLetterSch()` | Navigation to the cancellation letter search screen. |
| `actionCasCard()` / `actionCloseCasCard()` | CAS Card button handling — opens/closes CAS card settings. |

The class also has a **OneStop API path** (introduced in v18.00.00) that runs a parallel flow through:
1. `apiControl()` — top-level controller
2. `apiInit()` — OneStop API initialization
3. `singleChkForOneStop()` — OneStop single-field validation
4. `commonKnrnChkForOneStop()` — OneStop common related-field validation
5. `actionInit0()` / `actionInit()` — OneStop-aware initialization
6. `singleKnrnChkForOneStop()` / `knrnChkForOneStop()` — OneStop custom related validation
7. `actionUpdMyHPInfo()` — update confirmation (shared with standard path)
8. `apiTerminal()` — OneStop API cleanup

Validation error messages are accumulated in `warMsgMap`, `tkckErrMsgMap`, and `errMsgMap` for OneStop error reporting.

---

### [KKW02504SFBean](source/koptWebA/src/eo/web/webview/KKA14201SF/KKW02504SFBean.java)

The main form DataBean for this screen. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface` and `X31CBaseBean`. This is the primary data carrier between the view layer and the business logic layer.

It holds fields in three sets:
- **Update / Value / Enabled / State triplets** for each display field — this pattern allows the framework to bind each field to the view while tracking whether the user modified it, what its current value is, whether it is enabled, and any validation state.
- **List fields** (`X33VDataTypeList`) for multi-row data (code lists, name lists).
- **Derived display fields** that combine list data into `ArrayList<SelectItem>` for JSF rendering.

#### Key fields (representative)

| Field group | Purpose |
|---|---|
| `hpad_domain_*` | Homepage access domain (display + change information) |
| `hpad_account_*` | Homepage access account |
| `hp_capa_*` | Homepage capacity |
| `web_id_*` | WebID |
| `accss_bnsk_*` | Access analysis (active/inactive) |
| `use_staymd_*` / `use_endymd_*` | Service start/end dates |
| `chg_hpad_*` | Change information (domain/account) |
| `capa_*` / `add_capa_*` / `svctk_but_*` | Capacity-related fields including free/maximum/added capacity |
| `trandiv_*` | Processing category (update/cancel/recovery/reservation cancel) |
| `sysid_*` / `svc_kei_no_*` / `ido_div_*` | Transfer identifiers (SYSID, service contract number, modification reason) |
| `op_svc_kei_no_*` / `mskm_no_*` / `mskm_dtl_no_*` | Optional service contract number, subscription number, detail number |
| Sub-optional fields (0170/0440) | Homepage capacity and access analysis sub-optional contract details |

---

### [KKW02504SF01DBean](source/koptWebA/src/eo/web/webview/KKA14201SF/KKW02504SF01DBean.java)

A listed DataBean used for table/list item rendering. Implements `X33VDataTypeBeanInterface`, `X33VListedBeanInterface`, and `Serializable`.

Holds three list structures:
- `cd_div_list_list` — Code classification list
- `cd_div_nm_list_list` — Code name list
- `nm_list_list` — Name list

Provides methods for managing dynamic list data:
- `loadModelData()` / `storeModelData()` — Load and store data by key/subkey from the model layer.
- `typeModelData()` — Returns the Java type for a given field key, enabling dynamic type conversion.
- `addListDataInstance()` / `removeElementFromListData()` / `clearListDataInstance()` — Manage list item lifecycle (add/remove/clear).
- `listKoumokuIds()` — Returns all field name identifiers.

The `storeModelData()` method has an overloaded version accepting an `isSetAsString` flag that controls whether values are stored as strings — this is important because some fields must preserve their type across serialization boundaries.

---

### [KKW02504SF02DBean](source/koptWebA/src/eo/web/webview/KKA14201SF/KKW02504SF02DBean.java)

Another listed DataBean, similar to `KKW02504SF01DBean` but with fields specific to the detail view section. Holds:
- `ido_rsn_cd_list` — Modification reason code list
- `op_svc_kei_no_list` — Optional service contract number list

Each field has the standard update/value/state triplet pattern. Key fields include:
- `sysid_*`, `svc_kei_no_*`, `ido_div_*` — Transfer identifiers
- `mskm_no_*`, `mskm_dtl_no_*` — Subscription identifiers
- `tokutei_id_kmk_*` — Specified personal information mask name/value
- `ido_rsn_memo_*` — Modification reason memo

---

### [KKW02504SFConst](source/koptWebA/src/eo/web/webview/KKA14201SF/KKW02504SFConst.java)

A utility class containing **display label constants** for this screen's fields. All fields are human-readable Japanese labels (e.g., `HPAD_DOMAIN = "ホームページアクセスドメイン"`, `ACCSS_BNSK = "アクセス分析"`). The class has a private constructor to prevent instantiation — it exists purely as a namespace for constants.

Key constants:
- `HP_CAPA` / `WEB_ID` / `ACCSS_BNSK` / `USE_STAYMD` / `USE_ENDYMD` — Display labels for main fields
- `TRANDIV` — Processing category label
- `SYSID` / `SVC_KEI_NO` / `IDO_DIV` — Transfer identifier labels
- `SBOP_SVC_CD_0170` / `SBOP_SVC_CD_0440` — Sub-optional service code keys

---

### [KKW02504SFChecker](source/koptWebA/src/eo/web/webview/KKA14201SF/KKW02504SFChecker.java)

Implements the `X31SGuiCheckBase` interface. This is a GUI validation hook that receives a reference to the business logic class (`X31BBusinessLogic bl`) and a `X31SGuiCheckParam`. The `checkMethod()` dispatches on `patternID` to run validation based on the screen pattern.

Currently, this class is a **placeholder stub** — it always returns `true` (valid) without performing any validation. Actual validation is handled inline within `KKA14201SFLogic` methods and through the OneStop validation methods (`singleChkForOneStop()`, `commonKnrnChkForOneStop()`, etc.).

---

## How It Works

### Screen Flow

```mermaid
flowchart TD
    A["Optional Service<br/>Contract List Screen"] -->|"Navigate"| B["KKW02504<br/>Initial Display"]
    B -->|"Update Button"| C["KKW02505<br/>Confirmation"]
    B -->|"Cancel/Recover"| D["KKW02505<br/>Confirmation"]
    C -->|"Fix Button"| E["KKW02506<br/>Completion"]
    D -->|"Fix Button"| E
    C -->|"Edit Button"| B
    E -->|"Back/Finish"| A
    B -->|"Clear Button"| B
```

### Detailed Processing Path

1. **Initial Display (`actionInit()`)**
   - Screen info is retrieved via `JCCWebCommon.getScreenInfo()`
   - `setDataInit()` populates the service form bean with operational date, price plan codes, and transfer information from the customer contract
   - A large `KKSV0007_KKSV0007OPDBMapper` is created to handle up-to-17 mapping operations for the inquiry service
   - `invokeService("KKSV0007", "KKSV0007OP")` calls the My Homepage Info Inquiry service
   - `storeGetDataInit()` maps results into the bean: homepage capacity, access analysis, modification types
   - If the sub-optional service status is "service in progress", a billing eligibility check is performed via `JKKWebCommon.jdgHiChrg()`
   - Button visibility is set via `setKbnButtonVisible()` based on the modification reason code
   - If the optional service contract list is present, a list search service is called (`searchList()`) and STB/op-pack info is populated

2. **Update Processing (`actionUpdMyHPInfo()`)**
   - The `TRANDIV` field determines if this is an update or cancellation
   - For updates: business rules check that URL is not being changed from present to absent, and that URL is required if the contract is post-construction
   - `setDataUpd()` validates at least one field changed and computes update type codes
   - `setMappedKKSV0008(FUNC_CD_2)` does a "check only" mapping, then the service is called
   - If no changes detected, an error message is displayed
   - Navigates to screen `KKW02505` (confirmation)

3. **Fix/Confirmation (`actionFixMyHPInfo()`)**
   - Dispatches by `TRANDIV`:
     - **Change**: `KKSV0008` with `FUNC_CD_1` (check + register), followed by navigation to `KKW02506`
     - **Cancel**: `KKSV0009` with `FUNC_CD_1`, `getOpsvckeiDslCC` mapping, navigates to `KKW02506`
     - **Recovery**: `KKSV0004` with recovery CC mapping and SOD emission, navigates to `KKW02506`
     - **Reservation Cancel**: `KKSV0017` with cancel CC, SOD emission, and form support info update, navigates to `KKW02506`
   - Return message ID from the service is processed via `getMsgRep()` for display

### Button Visibility Logic

Button visibility is controlled by a combination of:
- **Modification reason code** (`IDO_DIV`): new contract (`00001`), add service (`00002`), other modifications (`00031`), etc.
- **Service code** (`OP_SVC_CD`): identifies the optional service type (email, TV optional channel, mail list, etc.)
- **Service contract status**: service in progress (`100`), cancelled (`910`), cancelled pending (`920`)
- **Whether optional services exist** and whether they are in a cancellable state

The three methods `setBtnVisibleAtTel()`, `setBtnVisibleAtNet()`, and `setBtnVisibleAtTv()` handle button visibility for telephone, network, and TV service categories respectively. Each button has a visibility flag (`0` = hidden, `1` = visible).

---

## Data Model

### Field Pattern: `_update`, `_value`, `_state`, `_enabled`

Every display field in `KKW02504SFBean` follows a consistent naming convention:

| Suffix | Purpose |
|---|---|
| `_update` | Whether the field was modified by the user on this screen iteration |
| `_value` | The current data value |
| `_state` | Validation or display state (e.g., error indicators) |
| `_enabled` | Boolean flag for field enable/disable on the UI |

This pattern allows the X33 framework to distinguish between user modifications and server-populated values, enabling correct comparison logic (e.g., "was this field actually changed?").

### Data Flow

```mermaid
sequenceDiagram
    participant C as Customer
    participant W as Web Page
    participant L as KKA14201SFLogic
    participant S as Business Service
    participant B as KKW02504SFBean

    C->>W: Navigate to My HP page
    W->>L: actionInit()
    L->>L: setDataInit() - prepare input
    L->>S: invokeService KKSV0007
    S-->>L: Return My HP data
    L->>L: storeGetDataInit() - map results
    L->>B: populate display fields
    L-->>W: Return view
    W-->>C: Display My HP info

    C->>W: Click Update button
    W->>L: actionUpdMyHPInfo()
    L->>L: Determine trandiv (update vs cancel)
    L->>L: setDataUpd() or setDataDsl()
    alt Update path
        L->>S: invokeService KKSV0008
    else Cancel path
        L->>S: invokeService KKSV0009
    end
    S-->>L: Return confirmation result
    L-->>W: Navigate to confirmation screen KKW02505

    C->>W: Click Confirm button
    W->>L: actionFixMyHPInfo()
    alt Update confirm
        L->>S: invokeService KKSV0008 (register)
    else Cancel confirm
        L->>S: invokeService KKSV0009 (register)
    else Recovery confirm
        L->>S: invokeService KKSV0004
    else ResCancel confirm
        L->>S: invokeService KKSV0017
    end
    S-->>L: Return final result
    L-->>W: Navigate to completion screen KKW02506
```

### List Data Model

The listed beans (`KKW02504SF01DBean`, `KKW02504SF02DBean`) use `X33VDataTypeList` for dynamic list data:
- `cd_div_list_list` — Code classification (e.g., homepage capacity codes)
- `cd_div_nm_list_list` — Code names corresponding to classifications
- `nm_list_list` — Full display names
- `ido_rsn_cd_list` — Modification reason codes
- `op_svc_kei_no_list` — Optional service contract numbers

The `Jsflist*` methods (e.g., `getJsflist_cd_div_list()`) convert `X33VDataTypeList` data into `ArrayList<SelectItem>` for JSF pulldown rendering.

---

## Dependencies and Integration

### XML Configuration References

| XML Config | Classes Referenced |
|---|---|
| `WEBGAMEN_KKA142010PJP.xml` | `KKA14201SFLogic`, `KKW02504SFBean` |
| `x31business_logic_KKA14201SF.xml` | `KKA14201SFLogic` |
| `WEBGAMEN_KKW025040PJP.xml` | `KKW02504SFBean` |
| `WEBGAMEN_KKW025050PJP.xml` | `KKW02504SFBean` |
| `WEBGAMEN_KKW025060PJP.xml` | `KKW02504SFBean` |

### Backend Services Used

| Service ID | Operation | Purpose | Mapper Class |
|---|---|---|---|
| `KKSV0007` | `KKSV0007OP` | My Homepage Info Inquiry | `KKSV0007_KKSV0007OPDBMapper` |
| `KKSV0008` | `KKSV0008OP` | My Homepage Info Change Confirm/Register | `KKSV0008_KKSV0008OPDBMapper` |
| `KKSV0009` | `KKSV0009OP` | My Homepage Cancellation Confirm/Register | `KKSV0009_KKSV0009OPDBMapper` |
| `KKSV0004` | `KKSV0004OP` | My Homepage Recovery | `KKSV0004_KKSV0004OPDBMapper` |
| `KKSV0017` | `KKSV0017OP` | My Homepage Reservation Cancel | `KKSV0017_KKSV0017OPDBMapper` |

Additional mappers referenced (likely for OneStop or extended functionality):
- `KKSV0042`, `KKSV0043`, `KKSV0061`, `KKSV0062`, `KKSV0463`, `KKSV0551`, `KKSV0793`, `KKSV0820`

### Framework Dependencies

- **X31 Framework**: `JCCWebBusinessLogic`, `X31SDataBeanAccess`, `X31SGuiCheckBase`, `X31CWebConst`, `X31CMessageResult`
- **X33 Framework**: `X33VViewBaseBean`, `X33VListedBeanInterface`, `X33VDataTypeList`, `X33VDataTypeBeanInterface`
- **OneStop Common**: `JCCWebCommon`, `JKKWebCommon`, `JKKCommonConst`, `JKKScreenConst`, `OneStopDataBeanAccess`, `JKKOneStopApiCommonUtil`
- **Common Utilities**: `JPCModelConstant`, `JPCOnlineMessageConstant`, `JPCUtilCommon`, `CommonInfoCFConst`
- **Validation**: `HalfCharCheck`, `LengthCheck`, `MixCharCheck` (from `com.fujitsu.futurity.model.common.check`)
- **Logging**: `JSYwebLog`, `JCMAPLConstMgr`

### Module Relationships

```mermaid
flowchart TD
    A["KKW02504SFBean<br/>Main form DataBean"] --> B["KKA14201SFLogic<br/>Business logic core"]
    A --> C["KKW02504SF01DBean<br/>Pulldown list item model"]
    A --> D["KKW02504SF02DBean<br/>Detail item model"]
    A --> E["KKW02504SFConst<br/>Display label constants"]
    A --> F["KKW02504SFChecker<br/>GUI validation hook"]

    B --> G["KKSV0007<br/>My HP inquiry service"]
    B --> H["KKSV0008<br/>My HP change confirm service"]
    B --> I["KKSV0009<br/>My HP cancellation confirm service"]
    B --> J["KKSV0004<br/>My HP recovery service"]
    B --> K["KKSV0017<br/>My HP reservation cancel service"]

    L["WEBGAMEN_KKA142010PJP.xml<br/>Calls KKA14201SFLogic"] --> B
    M["x31business_logic_KKA14201SF.xml<br/>Calls KKA14201SFLogic"] --> B
    N["WEBGAMEN_KKW025040PJP.xml<br/>Uses KKW02504SFBean"] --> A
    O["WEBGAMEN_KKW025050PJP.xml<br/>Uses KKW02504SFBean"] --> A
    P["WEBGAMEN_KKW025060PJP.xml<br/>Uses KKW02504SFBean"] --> A
```

---

## Notes for Developers

### OneStop Migration

This module has a dual code path — the standard web flow and the OneStop API flow. The OneStop code was introduced in v18.00.00 when the module was copied from koptWebB to koptWebA. The OneStop path uses static message maps (`warMsgMap`, `tkckErrMsgMap`, `errMsgMap`, `sifErrMap`) shared across the session rather than per-instance state. Be careful not to mix the two paths — the OneStop methods use `OneStopDataBeanAccess` types while the standard path uses `X31SDataBeanAccess`.

### Validation

The `KKW02504SFChecker` class is currently a stub that does nothing. All validation happens inside `KKA14201SFLogic` methods:
- Single-field validation: `singleChkForOneStop()` and related methods
- Related-field validation: `commonKnrnChkForOneStop()`, `singleKnrnChkForOneStop()`, `knrnChkForOneStop()`
- Custom business rules (e.g., URL cannot go from present to absent) in `actionUpdMyHPInfo()`

### Modification Type Determination

The module computes three independent modification type codes:
- **Homepage capacity** (`UPD_KIND_HP`): 5 states — becoming chargeable, becoming free, continuing chargeable, continuing free, or unchanged
- **Access analysis** (`UPD_KIND_ACCS`): 3 states — chargeable, free, or unchanged
- **URL** (`UPD_KIND_URL`): changed or unchanged

These codes are used by the backend services to determine pricing impact.

### Screen Navigation

The `getNextScreenInfo()` method is a large dispatch table (500+ lines) mapping action button IDs and optional service codes to confirmation and completion screen IDs. Each optional service type (email, TV channel, mail list, etc.) has its own pair of screens. When adding a new optional service, this method must be updated with the new screen ID pair.

### DataBean Serialization

The listed beans implement custom `loadModelData()` and `storeModelData()` methods for type-aware serialization. The `storeModelData(key, subkey, value, isSetAsString)` overload is critical — when `isSetAsString` is `false`, the value's original Java type is preserved during serialization. Incorrect use of this flag can cause type conversion errors downstream.

### Error Message Handling

Service return codes are processed through `getMsgRep(trandiv, rtn_msg_id)` which looks up replacement strings for message formatting. If no replacement strings are found, the raw message ID is displayed directly. This pattern is used consistently across `actionUpdMyHPInfo()` and `actionFixMyHPInfo()`.

### Key Business Rules

- **URL cannot be deleted**: If the homepage access domain/account is currently set, it cannot be changed to empty. Message `EKB0010_TW` is displayed.
- **Post-construction URL is required**: After construction, if the service contract status is "pending" (`010`), a URL must be set. Message `EKB1040_JW` is displayed if not.
- **No changes = no submission**: `setDataUpd()` returns `false` if the homepage capacity, access analysis, and URL have all remained unchanged. Message `EKB5370_NW` is displayed.
- **Cancellation eligibility**: `dslChk()` checks whether the optional service contract status allows a cancellation order to be submitted.

### Constants to Know

| Constant | Meaning |
|---|---|
| `MSKM_SBT_CD_OPMK` | Subscription type code for optional subscription |
| `SVC_DLRE_CD_TUJYO` | Service cancellation reason code (normal cancellation) |
| `SVC_KEI_STAT_TEIKYO` | Service contract status "in progress" (100) |
| `SVC_KEI_STAT_DSL` | Service contract status "cancelled" (910) |
| `SVC_KEI_STAT_CANCEL` | Service contract status "cancellation pending" (920) |
| `SBOP_SVC_CD_HP` | Sub-optional service code for homepage capacity |
| `SBOP_SVC_CD_ACCS` | Sub-optional service code for access analysis |
| `AGING_SBT_CD_URL` / `AGING_SBT_CD_WEBID` | Entry type codes: URL / WebID |
| `DSL_RSV` / `DSL_SOKU` | Cancellation type: scheduled / immediate |