# Eo / Web / Webview / Kka17201sf

## Overview

This module implements the view-layer business logic for the **eo Light TV Cable TV Guide Magazine Update Screen** (eo光テレビケーブルテレビガイド誌更新画面). It handles the full lifecycle of updating delivery address information and related settings for the eo Light TV guide magazine — supporting four modes: inquiry (照会), update (更新), dissolution/cancellation (解約), and reservation cancellation (予約取消). The module also includes a **Wanstop integration** (ワンストップ対応), which allows the screen's functionality to be called programmatically via an API by external systems (e.g., the STB1 Wanstop portal).

The package is organized as follows:

- `KKA17201SFLogic` — the central controller that processes all screen actions and API calls
- `KKW02522SFBean` — the main data access bean holding screen-level form state
- `KKW02522SF01DBean` / `KKW02522SF02DBean` — typed data beans for dropdown lists and customer contract details
- `KKW02522SFConst` / `KKW02301SFConst` — constant definitions for field names, control flags, and screen identifiers
- `KKW02522SFChecker` — GUI validation delegate

```
flowchart TD
    subgraph Controllers["Controller Layer"]
        KKA17201SFLogic["KKA17201SFLogic<br/>Main view logic class"]
    end

    subgraph DataBeans["Data Bean Layer"]
        KKW02522SFBean["KKW02522SFBean<br/>Screen data access bean"]
        KKW02522SF01DBean["KKW02522SF01DBean<br/>Dropdown/division data bean"]
        KKW02522SF02DBean["KKW02522SF02DBean<br/>Customer contract data bean"]
    end

    subgraph Constants["Constants"]
        KKW02522SFConst["KKW02522SFConst<br/>Screen constants"]
        KKW02301SFConst["KKW02301SFConst<br/>Reference screen constants"]
    end

    subgraph Validation["Validation"]
        KKW02522SFChecker["KKW02522SFChecker<br/>GUI validation"]
    end

    subgraph Mappers["DB Mappers"]
        KKSV0534["KKSV0534<br/>Initial load mapper"]
        KKSV0535["KKSV0535<br/>Copy mapper"]
        KKSV0820["KKSV0820<br/>Reference code mapper"]
    end

    KKA17201SFLogic --> KKW02522SFBean
    KKA17201SFLogic --> KKW02522SF01DBean
    KKA17201SFLogic --> KKW02522SF02DBean
    KKA17201SFLogic --> KKW02522SFConst
    KKA17201SFLogic --> KKW02301SFConst
    KKA17201SFLogic --> KKW02522SFChecker
    KKA17201SFLogic --> KKSV0534
    KKA17201SFLogic --> KKSV0535
    KKA17201SFLogic --> KKSV0820
```

## Key Classes and Interfaces

### `KKA17201SFLogic`

**File:** [KKA17201SFLogic.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKA17201SFLogic.java)

The central business logic controller for this screen. It extends `JCCWebBusinessLogic` and implements the X31 framework's web business logic pattern. This class orchestrates all user interactions and API requests.

#### Two Entry Points

1. **`init()`** — Standard web screen initialization (normal UI flow). Called when the user navigates to the screen from the menu or another screen.
2. **`apiControl()`** — Wanstop API entry point. Called by external systems via the Wanstop framework. It performs a full pipeline: API initialization → validation → business processing → confirmation → fix, all within a single API call.

#### Core Methods

| Method | Purpose |
|---|---|
| `apiControl()` | Wanstop API control method. Orchestrates the full update lifecycle in one call: initialization, single-item checks, common related checks, business logic processing, confirmation, and fix. On error, returns return code "99" (system error). |
| `apiInit()` | Parses the incoming XML request into a `requestMap`. Validates the `func_code` parameter (must be "1: update" or "2: reference"). Initializes message maps and warning lists. |
| `init()` | Standard screen initialization. Retrieves screen info, customer contract data, service form data, and calls the `KKSV0534` service to load contract details. Sets up button visibility flags based on the incoming transfer division (`tranDiv`). |
| `forwardUpdCfm()` | **Update confirmation button** processing. Edits input data for update mode, performs index synchronization on address info comboboxes, validates related data (dissolution mode requires end month check), invokes the update service (`execInvokeService`), and forwards to the confirmation screen (KKW02523). |
| `forwardFix()` | **Fix button** processing. Identical pre-processing to `forwardUpdCfm()` but invokes the service with `funcCode = "1"` (actual update) instead of "2" (reference). Sets a success message and forwards to the result screen (KKW02524). |
| `forwardOptSvcKeiList()` | **List inquiry button**. Transfers to the option service contract list screen (KKW02301) with relevant customer contract context data. |
| `copy()` | **Copy button**. Clears delivery address info, fetches combo box selection indices, then calls `KKSV0535` service to retrieve and copy address data from the primary registered address. |
| `openAdSch()` | **Address search button**. Launches the separate address search screen (ZMW10601), passing current partial address data (postal code prefix) as context. |
| `closeAdSch()` | **Address search return**. Receives address selection from ZMW10601 via shared screen info, populates the form with the selected address, and resolves address code-to-detail mapping for fields not in the address master. |
| `clear()` | **Clear button**. Resets all address fields, delivery name, guide magazine count, and re-initializes form state. |
| `usepcadDoitsuChange()` | **"Same as usage location" checkbox** toggle. When checked, clears the delivery address and re-initializes it from the primary address. |
| `back()` | **Back button**. Sets forward info to the originating screen and navigates back. |
| `singleChkForOneStop()` | Wanstop single-item validation. Validates every field in the incoming request map: format checks (half-width, length, character type), reference value checks (valid ranges for enums). Returns errors via `warnList`. |
| `commonKnrnChkForOneStop()` | Wanstop common-related validation. Calls the `KKSV0820` service to validate SYSID, service contract number, and user ID, and to fetch code type lists. |
| `senkoKnrnChkForOneStop()` | Wanstop advance related validation. Additional pre-processing checks before the main business logic. |
| `knrnChkForOneStop()` | Wanstop related validation after main processing. |
| `execInvokeService()` | Generic service invocation helper. Sets up parameter mappers, invokes a service with the given `funcCode`, handles errors, and processes results. |
| `setValueDispCtrlFlg()` | Sets all button visibility flags based on `tranDiv`. For example, "00: inquiry" shows only inquiry controls; "03: update" shows update/confirm/clear/modify buttons; "06: cancellation" shows confirm button only. |
| `clearSohusAdInfo()` | Clears all delivery address fields (postal code, address code, state/city/district, building name, room number, phone number). |
| `reInitSohusAdInfo()` | Restores the delivery address form to its initial state by copying the primary address values. |
| `getHktgiDataMap()` | Extracts customer contract data from the service form bean into a `HashMap` for passing between screens. |
| `hasErrOpSvcKeiStat()` | Checks option service contract state validity. Returns error `EKB1510` if update is not possible. |
| `hasErrTvGuideMskmCnt()` | Validates the guide magazine subscription count (must not be "0", must be within 1-99 range). |
| `warningChk()` | Performs warning checks on the output map data. |
| `halfToFull()` | Converts half-width digits to full-width digits. |

#### Transfer Division Values

The `tranDiv` parameter determines the screen mode and button layout:

| Value | Mode | Buttons Shown |
|---|---|---|
| "00" | Inquiry | Inquiry controls only |
| "03" | Update | Update, Confirm, Clear, Modify |
| "06" | Dissolution | Confirm button only |
| "04"/"05" | Reservation Cancel / Recovery | Return button |

### `KKW02522SFBean`

**File:** [KKW02522SFBean.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKW02522SFBean.java)

The main screen data access bean. Extends `X33VViewBaseBean` and implements both `X33VListedBeanInterface` and `X31CBaseBean`. Holds all form fields for the update screen, including:

- **Mode fields**: `tran_mode`, `stdardymd` (operation date), `stdardymd_dtm` (operation date-time stamp)
- **Control flags**: `upd_info_ctrl_flg`, `upd_cfm_btn_ctrl_flg`, `clr_btn_ctrl_flg`, `rev_btn_ctrl_flg`, `rtn_btn_ctrl_flg`
- **Date fields**: `use_staymd` (start date), `use_endymd` (end date), `use_endym` (end month shortcut), `chgykgtym` (change start month), `chg_staymd`
- **Address fields** (primary): `pcd1`/`pcd2` (postal code), `ad_cd1`-`ad_cd4` (address code), `state`, `city`, `oaztsu`, `azcho`, `bnchigo`, `adrttm`, `adrrm`, `telno`, `shs_nm`, `shs_kana`
- **Delivery address fields** (prefixed with `CHG_`): mirrored set for the guide magazine delivery destination
- **Guide magazine fields**: `tv_guide_mskm_cnt` (subscription count), `guidemg_shs_ksitei_flg` (separate delivery flag), `ad_info` (address selection combobox), `usepcad_doitsu` (same as usage location)
- **Customer contract data**: `hktgi_cust_kei_hktgi_list` (list), `hktgi_sysid`, `hktgi_svc_kei_no`, `hktgi_tran_div`, `hktgi_ido_div`, `hktgi_ido_rsn_cd`, `hktgi_op_svc_kei_no`, `hktgi_mskm_no`, `hktgi_mskm_dtl_no`
- **Derived fields**: `disp_pcd`, `disp_ad_cd` (display-format postal code and address code), `disp_use_staym`, `disp_use_endym`, `bk_use_endym`

Each field follows the X33 framework convention with `*_update`, `*_value`, `*_enabled`, `*_state` variants for fine-grained control over field state.

### `KKW02522SF01DBean`

**File:** [KKW02522SF01DBean.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKW02522SF01DBean.java)

A typed data bean for dropdown/division selections. Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface` with extensive `loadModelData`, `storeModelData`, `typeModelData`, `listKoumokuIds`, `addListDataInstance`, and `removeElementFromListData` methods. This is the framework's data type bean pattern that allows dynamic type-based data access.

Key fields:
- `cd_div_cd_update`, `cd_div_cd_value`, `cd_div_cd_enabled`, `cd_div_cd_state` — code division code
- `cd_div_nm_update`, `cd_div_nm_value`, `cd_div_nm_enabled`, `cd_div_nm_state` — code division name
- `select_index_update`, `select_index_value`, `select_index_enabled`, `select_index_state` — selection index
- `default_cd_list_list`, `cd_div_cd_list_list`, `cd_div_nm_list_list` — dropdown list data

### `KKW02522SF02DBean`

**File:** [KKW02522SF02DBean.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKW02522SF02DBean.java)

Another typed data bean that wraps customer contract transfer data. Fields map directly to the customer contract contract information (`HKTGI_` prefixed):

- `hktgi_sysid` — System ID
- `hktgi_svc_kei_no` — Service contract number
- `hktgi_ido_div` — Movement classification
- `hktgi_ido_rsn_cd` — Movement reason code
- `hktgi_ido_rsn_memo` — Movement reason memo
- `hktgi_op_svc_kei_no` — Option service contract number
- `hktgi_tran_div` — Transfer division
- `hktgi_mskm_no`, `hktgi_mskm_dtl_no` — Magazine subscription number and detail number
- `hktgi_tokutei_id_kmk_nm`, `hktgi_tokutei_id_kmk_value` — Identified ID key name/value (for personally identifiable information)

### `KKW02522SFChecker`

**File:** [KKW02522SFChecker.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKW02522SFChecker.java)

Implements `X31SGuiCheckBase` for GUI-level validation. The constructor receives the `KKA17201SFLogic` instance, and `checkMethod()` dispatches validation based on the input parameter. Uses the X31 framework's GUI check infrastructure to validate screen data before business processing.

### `KKW02522SFConst`

**File:** [KKW02522SFConst.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKW02522SFConst.java)

Static constant class defining all field names, control flags, and screen identifiers used by this module. Key groupings:

- **Screen IDs**: `SCREEN_ID_KKW02522` (update screen), `SCREEN_ID_KKW02523` (confirmation), `SCREEN_ID_KKW02524` (result)
- **Control flags**: `TRAN_MODE`, `UPD_INFO_CTRL_FLG`, `UPD_CFM_BTN_CTRL_FLG`, `CLR_BTN_CTRL_FLG`, `REV_BTN_CTRL_FLG`, `RTN_BTN_CTRL_FLG`
- **Address fields**: `PCD1`/`PCD2` (postal code), `AD_CD1`-`AD_CD4`, `STATE`, `CITY`, `OAZTSU`, `AZCHO`, `BNCHIGO`, `ADRTTM`, `ADRRM`, `TELNO`
- **Delivery address fields**: All prefixed with `CHG_` — e.g., `CHG_PCD1`, `CHG_AD_CD1`, `CHG_STATE`
- **Check fields**: Prefixed with `CHK_` — e.g., `CHK_PCD1`, `CHK_AD_CD1`

### `KKW02301SFConst`

**File:** [KKW02301SFConst.java](source/koptWebA/src/eo/web/webview/KKA17201SF/KKW02301SFConst.java)

Shared constants used by the option service list reference screen (KKW02301SF) that is navigated to from the update screen. Contains constants for customer contract items (`CUST_KEI_HKTGI_LIST`, `SYSID`, `SVC_KEI_NO`, `IDO_DIV`, `SVC_CD`), option service items (`OP_SVC_KEI_LIST`, `OP_SVC_KEI_SEL`), and display control flags.

## How It Works

### Screen Flow

```
flowchart TD
    subgraph Screens["Screens"]
        KKW02522["KKW02522<br/>Update screen"]
        KKW02523["KKW02523<br/>Update confirmation screen"]
        KKW02524["KKW02524<br/>Update result screen"]
        KKW02301["KKW02301<br/>Option service list screen"]
        ZMW10601["ZMW10601<br/>Address search screen"]
        CRW10601["CRW10601<br/>Wanstop screen"]
    end

    KKW02522 -->|"forwardUpdCfm"| KKW02523
    KKW02523 -->|"forwardFix"| KKW02524
    KKW02522 -->|"forwardOptSvcKeiList"| KKW02301
    KKW02522 -->|"openAdSch"| ZMW10601
    ZMW10601 -->|"closeAdSch"| KKW02522
    CRW10601 -->|"apiControl -> init"| KKW02522
    KKW02522 -->|"back"| CRW10601

    style KKW02522 fill:#f9f,stroke:#333
    style KKW02523 fill:#bbf,stroke:#333
    style KKW02524 fill:#bfb,stroke:#333
```

### Standard UI Flow (init → confirm → fix)

1. **`init()` is called** when the user first loads the screen (or returns from another screen).
   - Retrieves screen info and customer contract data from the shared form bean.
   - Copies SYSID, service contract number, movement classification, movement reason code, option service number, and transfer division from the customer contract list.
   - Calls `KKSV0534` service to load the specific contract's magazine subscription details.
   - Determines the mode (inquiry/update/dissolution/RSV cancel) based on `tranDiv` and sets button visibility flags.
   - For update mode: sets "change start month" default to "next month", enables the change section.
   - For dissolution mode: sets "end month" default to "this month", hides the change section.

2. **User modifies the delivery address** — either by:
   - Manual entry (postal code lookup → address code auto-fill)
   - Using the address search dialog (`openAdSch` → `ZMW10601` → `closeAdSch`)
   - Checking "Same as usage location" (`usepcadDoitsuChange`)
   - Pressing Copy (`copy`) to copy the primary address

3. **User presses "Update Confirmation" button** → `forwardUpdCfm()`:
   - Edits values for update mode (`editValueForUpd`)
   - Syncs the address info combobox selection index
   - If dissolution mode: validates the end month (`isRelation`)
   - Invokes the service (`execInvokeService`) with `funcCode = "2"` (reference)
   - Edits values for display (`editValueForDisp`)
   - Forwards to the confirmation screen (KKW02523)

4. **User confirms on confirmation screen** → `forwardFix()`:
   - Same validation as step 3 but calls `execInvokeService` with `funcCode = "1"` (actual update)
   - Sets the success message: `EKB4390` "eo Light TV guide magazine information has been updated"
   - Forwards to the result screen (KKW02524)

### Wanstop API Flow (apiControl)

When called via the Wanstop API, the entire flow happens in a single method call:

1. **`apiInit()`**: Parse incoming XML → `requestMap`. Validate `func_code`. Initialize message maps.
2. **`singleChkForOneStop()`**: Validate every field in the request map (format, length, reference values).
3. **`commonKnrnChkForOneStop()`**: Call `KKSV0820` service for SYSID/contract/user validation.
4. **`overwriteDataBeanForInit()`**: Copy request data into the data bean.
5. **`senkoKnrnChkForOneStop()`**: Advance related checks.
6. **`init()`**: Screen initialization (load contract details via `KKSV0534`).
7. **`msgChk()`**: Check for accumulated messages/errors.
8. **`overwriteDataBean()`**: Final data bean write.
9. **`knrnChkForOneStop()`**: Post-processing related checks.
10. **`forwardUpdCfm()`**: Process update confirmation.
11. **`msgChk()`**: Check messages again.
12. If `funcCode = "1"` (update): **`forwardFix()`** — execute the actual update.
13. **`apiTerminal("00")`**: Return success ("00") or error ("99") code.

### Business Rules

- **Guide magazine subscription count**: Must be between 1 and 99. Cannot be 0 (error `E5017`).
- **Separate delivery flag**: "1" = specified separately, "0" = same as usage location.
- **Change start month**: "01" = immediate, "02" = next month, "03" = month after.
- **End month**: "1" = this month, "2" = next month.
- **Submission type code**: "00027" = change (変更), "00005" = cancellation (解約).
- **Inquiry mode**: All fields are read-only; the user can only view data and navigate to related screens.
- **Update mode**: The user can modify delivery address, guide magazine count, change start month, and end month.
- **Dissolution mode**: The end month must be validated, and the change section is hidden.

## Data Model

The data flows through several layers of beans:

```
+------------------------+
|   X31SDataBeanAccess   |  ← Shared framework bean for screen communication
+------------------------+
         |
         | contains
         v
+------------------------+
|   KKW02522SFBean       |  ← Main screen bean (X33VViewBaseBean)
|   - tran_mode          |     Holds all form fields with update/value/enabled/state
|   - delivery_address   |     properties for each field.
|   - guide_mskm_cnt     |
|   - hktgi_* fields     |
+------------------------+
         |
         | contains (as typed sub-beans)
         v
+------------------------+     +-------------------------+
| KKW02522SF01DBean      |     | KKW02522SF02DBean       |
| - dropdown items       |     | - customer contract     |
| - code divisions       |     |   data (SYSID, etc.)    |
+------------------------+     +-------------------------+
```

### Key data relationships

- **Customer Contract** (`CUST_KEI_HKTGI_LIST`) → **Delivery Address** (`AD_INFO`): The primary address stored in the customer contract is used as the default for the guide magazine delivery address.
- **Delivery Address fields** (2 sets): The screen maintains both a primary address set (from the customer record) and a delivery address set (prefixed with `CHG_`) which can differ if the user specifies a separate delivery destination.
- **Guide Magazine Count** → **Option Service Check**: The subscription count is validated against option service contract status. If the count is "0" or the option service state check fails, an error is returned.

## Dependencies and Integration

### Outbound Dependencies

| Dependency | Purpose |
|---|---|
| `eo.ejb.common` | Common EJB utilities |
| `eo.business.service` | Business service layer |
| `eo.ejb.cbs.mainproc` | Core business processing |
| `eo.web.webview.KKA17601SF` | Related web screens |
| `eo.web.webview.SCW00101SF` | Reference screens |
| `eo.web.webview.CommonInfoCF` | Shared screen info constants |
| `eo.web.webview.KKW05001SF` | Related screens |
| `eo.web.webview.FUW00162SF` | Related screens |
| `eo.web.webview.KKA17101SF` | Related screens |
| `eo.web.webview.KKW00127SF` | Related screens |
| `eo.common.constant` | Framework constants |
| `eo.common.util` | Framework utilities |
| `eo.web.webview.common` | Common web utilities |
| `eo.web.webview.mapping.KKSV0534*` | Service mapper for initial load |
| `eo.web.webview.mapping.KKSV0535*` | Service mapper for copy |
| `eo.web.webview.mapping.KKSV0820*` | Service mapper for reference codes |
| `eo.web.webview.mapping.KKSV0042*` through `KKSV0551*` | Various service mappers |
| `com.fujitsu.futurity.bp.custom.common` | Fujitsu BP custom utilities |
| `eo.web.webview.FUW09905SF` | Related screens |
| `eo.business.common` | Business common |
| `eo.web.webview.KKW00127SF` | Reference screens |
| `eo.web.webview.mapping` | Database mapper layer |

### Inbound References

The module is used by the following consumers:

| Consumer | Type |
|---|---|
| `WEBGAMEN_KKA172010PJP.xml` | Configuration referencing `KKA17201SFLogic` and `KKW02522SFBean` |
| `x31business_logic_KKA17201SF.xml` | Business logic configuration for `KKA17201SFLogic` |
| `KKA172010PJP.jsp` | JSP view referencing `KKW02522SFBean` |
| `KKW025220PJP.jsp` | JSP view referencing `KKW02522SFBean` |
| `KKW025230PJP.jsp` | Confirmation screen JSP referencing `KKW02522SFBean` |
| `WEBGAMEN_KKW025220PJP.xml` | Screen configuration |
| `WEBGAMEN_KKW025230PJP.xml` | Confirmation screen configuration |
| `WEBGAMEN_KKW025240PJP.xml` | Result screen configuration |

## Notes for Developers

### Extension Points

- **Adding new fields**: Follow the X33 convention of `*_update`, `*_value`, `*_enabled`, `*_state` property groups in `KKW02522SFBean`. Ensure corresponding entries in `KKW02522SF01DBean` if the field is used in dropdown lists.
- **Adding validation**: Add a new field check in `singleChkForOneStop()` following the pattern of checking `requestMap.containsKey()` → format validation → length validation → reference value validation.
- **Adding a new service mapper**: Import the mapper class, create an instance, call `set*CC()` for input mapping, invoke via `invokeService()`, then call `get*CC()` for output mapping.
- **Button visibility**: Modify `setValueDispCtrlFlg()` to add new screen modes. Each `tranDiv` value maps to a different set of visible buttons and mode.

### Gotchas

- **Wanstop vs. Standard**: The Wanstop API (`apiControl`) handles the entire update lifecycle in one call, while the standard UI flow (`init` → `forwardUpdCfm` → `forwardFix`) is split across three user interactions. Don't mix these flows.
- **funcCode distinction**: `funcCode = "1"` triggers actual updates; `funcCode = "2"` is reference-only. This flag determines whether `forwardFix` is called after `forwardUpdCfm`.
- **Address resolution**: When the address search dialog returns, `executeMoveAdBnchigo()` resolves address codes to finer-grained detail fields (chome, block, building name) for items not present in the address master. If this resolution fails, the fields will remain empty.
- **Address validation warnings**: The module tracks address validation status at warning level (`WA` status) for the bottom-level address field. Error codes `EKK0381C050` and `EKK0381D010` map to either warning `W0001` (for `WA` status) or error `E5019` (for `EA` status).
- **Clear semantics**: `clear()` only clears the delivery address fields (not the primary address) and resets the guide magazine count and change start month. The "Same as usage location" flag is preserved from the original value.
- **Thread safety**: The logic class stores state in instance fields (e.g., `warMsgMap`, `funcCode`, `svcCd`). Ensure each HTTP request gets its own instance. The X31 framework typically handles this via request-scoped beans.
- **Half-width vs. full-width**: The `halfToFull()` utility is used for display formatting of numeric data. Input validation always expects half-width characters.

### Screen Constants Reference

| Constant | Value | Purpose |
|---|---|---|
| `IF_ID` | `"KKIFE297"` | Service interface ID for Wanstop |
| `MSKM_HNK` | `"00027"` | Change (変更) submission type |
| `MSKM_KY` | `"00005"` | Cancellation (解約) submission type |
| `KSITEI_FLG_1` | `"1"` | Separate delivery specified |
| `KSITEI_FLG_2` | `"0"` | Same as usage location |
| `TV_GUIDE_MSKM_CNT_ZERO` | `"0"` | Zero subscription count (error condition) |
| `HASH_KEY_UPD_CC` | `"EohTvGuideUpdCC"` | Hash map key for update contract data |