# Eo / Web / Webview / Kkw02701sf

## Overview

The `KKW02701SF` module provides the **course history view logic** for the eo customer base system. It is a webview package that displays a list of a customer's subscription history records and supports cancellation workflows for both **eo net (internet)** and **eo TV** services. When a representative initiates a reservation cancellation, the module performs a series of cross-system validation checks — covering contractor linkages, smart device service status, router speed compatibility, and temporary fee refund confirmations — before forwarding the request to backend EJB services and navigating to the confirmation screen.

This module is one of the central webview components in the eo system, referenced by three external screen configuration XMLs (`WEBGAMEN_KKW027010PJP.xml`, `WEBGAMEN_KKW027020PJP.xml`, `WEBGAMEN_KKW027030PJP.xml`) and the business logic configuration `x31business_logic_KKW02701SF.xml`.

## Key Classes and Interfaces

### [KKW02701SFBean](source/koptWebB/src/eo/web/webview/KKW02701SF/KKW02701SFBean.java) — Main View Bean

This is the primary view backing bean for the course history screen. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface`, `X31CBaseBean`, and `Serializable`.

**Purpose:** Holds the screen-level form state and acts as a container for nested data bean lists. It is the top-level bean that the JSF page binds to.

**Key fields and their roles:**

| Field | Description |
|---|---|
| `course_rk_list_list` | `X33VDataTypeList` containing the course history table rows (each row is a `KKW02701SF02DBean`) |
| `hktgi_cust_kei_hktgi_list_list` | `X33VDataTypeList` containing customer contract continuation data (each row is a `KKW02701SF01DBean`) |
| `svc_cd` / `prc_grp_cd` | Service code and price group code for the current customer |
| `upd_dtm` / `unyo_dtm` / `unyo_ymd` | Update timestamp, operation timestamp, and operation date |
| `btn_ctrl_flg` / `plan_chg_flg` | Button control flags that determine which UI buttons are visible |
| `ctrl_button_flg` | Controls "back" button visibility (popup mode) |
| `mansion_flg` | Indicates whether the customer is in a mansion-type building |
| `svc_kei_stat` | Service contract status |
| `wrib_auto_aply_tg_gai_flg` | Auto-discount application target flag |
| `cp_disp_flg` | Course change fee reduction display flag |
| `koji_um_flg` | Work existence flag |
| `mskm_dtl_kojiak_no` | Detailed work case number |

**Constructor behavior:** The constructor initializes both data bean lists. `course_rk_list_list` is created as an empty `X33VDataTypeList`, and `hktgi_cust_kei_hktgi_list_list` is initialized with one pre-instantiated `KKW02701SF01DBean` entry.

**Key method — `getJsflist_typelist_course_rk_list()`:** Converts the `course_rk_list_list` into a list of `SelectItem` objects for JSF dropdown rendering, extracting the "course history list" value from each row.

### [KKW02701SF01DBean](source/koptWebB/src/eo/web/webview/KKW02701SF/KKW02701SF01DBean.java) — Customer Contract Data Bean

This bean holds per-row data for the **customer contract continuation list**. Each entry in `hktgi_cust_kei_hktgi_list_list` is an instance of this class.

**Purpose:** Carries all fields related to a single customer contract continuation record, including service codes, plan codes, reason codes for course changes, and mansion details. It follows the standard update/value/state triple pattern for each field (e.g., `hktgi_sysid_update`, `hktgi_sysid_value`, `hktgi_sysid_state`).

**Key data groups:**

1. **System identification fields** — `hktgi_sysid`, `hktgi_svc_kei_no`, `hktgi_ido_div` (course change division), `hktgi_ido_rsn_cd` (reason code), `hktgi_ido_rsn_memo` (reason memo)
2. **Optional service fields** — `hktgi_op_svc_kei_no` (optional service contract number), `hktgi_tran_div` (processing division)
3. **Mansion fields** — `hktgi_mskm_no` (reservation number), `hktgi_mskm_dtl_no` (detail number), `hktgi_tokutei_id_kmk_nm` (specified ID item name), `hktgi_tokutei_id_kmk_value` (specified ID item value)
4. **Service/price codes (before/after)** — `hktgi_svc_cd` / `hktgi_svc_cd_bf`, `hktgi_prc_grp_cd` / `hktgi_prc_grp_cd_bf`, `hktgi_prcs_cd` / `hktgi_prcs_cd_bf`, `hktgi_pplan_cd` / `hktgi_pplan_cd_bf`
5. **Other** — `hktgi_popup_mode` (popup mode indicator), `hktgi_wrib_auto_aply_tg_gai_flg`

**Key methods:**

- **`getHktgi_ido_rsn_cd_list()` / `setHktgi_ido_rsn_cd_list()`**: Holds the dropdown list of course change reason codes as an `X33VDataTypeList`.
- **`getJsflist_hktgi_ido_rsn_cd()`**: Converts the reason code list into `ArrayList<SelectItem>` for JSF rendering.
- **`getHktgi_op_svc_kei_no_list()` / `getJsflist_hktgi_op_svc_kei_no()`**: Similar dropdown conversion for optional service contract numbers.

Each field follows the consistent getter/setter pattern with `*_update`, `*_value`, and `*_state` suffixes for form binding.

### [KKW02701SF02DBean](source/koptWebB/src/eo/web/webview/KKW02701SF/KKW02701SF02DBean.java) — Course History Data Bean

This bean holds per-row data for the **course history list** (displayed in the main table). Each entry in `course_rk_list_list` is an instance of this class.

**Purpose:** Carries the display fields for a single course history record, including internal contract numbers, registration timestamps, reservation numbers, status indicators, and pricing changes. It also overrides `loadModelData()` and `storeModelData()` to support the `X31CBaseBean` persistence interface used by the framework.

**Key data groups:**

| Field | Description |
|---|---|
| `svc_kei_ucwk_no` | Service contract internal number |
| `gene_add_dtm` | Registration timestamp |
| `ido_rsv_no` | Reservation number for course changes |
| `mskm_dtl_no` | Reservation detail number |
| `stat` | Record status (with `enabled` flag) |
| `course_aply_ymd` | Course application date (with `enabled` flag) |
| `course_nm` | Course name (with `enabled` flag) |
| `mansion_id` / `mansion_nm` | Mansion identifier and name (with `enabled` flags) |
| `new_pcrs_cd` / `old_pcrs_cd` | New/old price course codes (added for TV support) |

**Important method — `loadModelData(String key, String subkey)`:** A large method (lines 436-581) that dispatches to the correct field based on the `key` and `subkey` combination. It returns the appropriate value from any field on the bean, enabling the framework to serialize/deserialize the bean state generically.

### [KKW02701SFLogic](source/koptWebB/src/eo/web/webview/KKW02701SF/KKW02701SFLogic.java) — Business Logic Controller

This is the core business logic class, extending `JCCWebBusinessLogic`. It orchestrates all user-facing operations on the course history screen.

**Purpose:** Handles screen initialization, course history search, reservation cancellation workflows, and all associated validation checks. It is the brain of the module, coordinating between the view beans, mapper classes, and backend EJB services.

**Public methods:**

| Method | Description |
|---|---|
| `init()` | Screen initialization — retrieves screen info and calls `searchCourseRk()` |
| `forwardRsvClCfm()` | **Reservation cancellation confirmation** — the primary cancellation entry point. Sets operation timestamps, invokes service, runs multiple validation checks, then navigates to KKW02702 |
| `forwardFix()` | **Update button processing** — processes updates and checks mobile course change cancellation; navigates to KKW02703 |
| `forwardBack()` | **Back button** — simply re-calls `searchCourseRk()` to refresh the list |
| `forwardIdoDivChoice()` | **Course change division select** — navigates to the customer contract continuation screen (KKW00145) with customer data |
| `forwardCustListShokai()` | **Customer list view button** — navigates to CKW00101 (customer overview) |
| `closeAply()` | **Close application button** — sets the discount flag, prepares screen info for KKW00128, and forwards to the model screen CCW00105 |
| `back()` | Generic back button — restores previous screen info |

**Private helper methods (service invocation setup):**

| Method | Description |
|---|---|
| `searchCourseRk()` | Searches and loads course history via `KKSV0394` mapper. Sets operation date, button control flags based on popup mode, and handles the discount auto-application flag display for eo net mansion-type customers. |
| `setInMsg()` | Routes to either `setKKSV0395()` (for eo net) or `setKKSV0396()` (for eo TV) based on the service code. |
| `setKKSV0395()` | Sets up input parameters for the **net reservation cancellation service** (use case KKSV0395). Configures 30+ data beans via the `KKSV0395` mapper. |
| `setKKSV0396()` | Sets up input parameters for the **TV reservation cancellation service** (use case KKSV0396). Configures 20+ data beans via the `KKSV0396` mapper. |

**Private helper methods (validation checks):**

| Method | Description |
|---|---|
| `isIcjkn()` | **Temporary fee refund check** — verifies work case status. Returns true if no work case exists, or if the work case status is not yet "completed" (200). Compares work case number with stored `mskm_dtl_kojiak_no`. |
| `isKktksvTkchuCheckResult()` | **Smart device service provision check** — for eo net, verifies if any smart device service has status "100" (in service). Blocks cancellation if found. |
| `isCouseRkRnkiCheckResult()` | **Course change linkage check** — for eo mobile3G, verifies business course change linkage date. |
| `isKkSonzaiCheckResult()` | **Crucible router existence check** — checks if a crucible (L0) indoor device type exists. |
| `isRouterSpeedCheckResult()` | **Router speed verification** — validates that the router hardware and speed code match the price course. Handles basic, basic-giga, old-wireless, new-wireless, and new-wireless-giga router types. |
| `isMobileCourseChgCheckResult()` | **Mobile course change cancellation check** — ensures only C27↔C28 (3G 7.2M) plan changes are allowed. |
| `isKojiRnkiCheckResult()` | **Work link confirmation** — for eo TV, checks if work cases exist with status 120 (registered) or 130 (accepted). |
| `isNetKojiRnkiCheckResult()` | **Work link confirmation** — for eo net, similar check with updated logic. |
| `isSptvStatCheckResult()` / `isErrCdCheckResult()` / `isCSOpCheckResult()` | **SmartTV linkage checks** — validates smart device integration status, error codes, and CS option work flags. |
| `setPopupValue()` | Determines whether to show "back" or "close" buttons based on the popup mode flag (empty/"0" = back button; "1"/"2" = close button). |
| `getHktgiDataMap()` | Extracts customer contract data from the service form bean into a HashMap for screen info passing. |

**Key constants defined:**

- `CUST_KEI_HKTGI_KEYS` — Array of customer contract field keys to extract during data serialization
- `KKTK_SVC_KEI_STAT_100` — Smart device service status "100" (in service)
- `TAKNKIKI_SBT_CD_L0` — Indoor device type code "L0" (Crucible)
- `PCRS_CD_A47` through `PCRS_CD_A99` — Price course codes for mansion type, global type, 5G/10G courses, Netflix plans, and eo net Simple plans
- `ROUTER_SPEED_SBT_CD_10` / `_20` — Router speed codes for 100M/1G
- `KOJIAK_SBT_PLAN_CHANGE` — Work type code "009" (plan change, replacement work)
- `KOJIAK_STAT_120` / `_130` / `_200` — Work case statuses (registered, accepted, completed)

### [KKW02701SFChecker](source/koptWebB/src/eo/web/webview/KKW02701SF/KKW02701SFChecker.java) — GUI Checker

Implements the `X31SGuiCheckBase` interface. The constructor receives the business logic class (`KKW02701SFLogic`) for reference.

**Purpose:** Serves as a hook point for GUI-level validation before business processing. Currently, `checkMethod()` always returns `true`, meaning no GUI-level validation rules are enforced at this time. This class is a placeholder for potential future input validation rules.

### [KKW02701SFConst](source/koptWebB/src/eo/web/webview/KKW02701SF/KKW02701SFConst.java) — Constants

A utility class with a private constructor (instantiation prevented). Contains `public static final String` constants used across the module.

**Key constants organized by purpose:**

| Category | Constants |
|---|---|
| List/Data keys | `COURSE_RK_LIST`, `HKTGI_CUST_KEI_HKTGI_LIST` |
| Control flags | `BTN_CTRL_FLG`, `PLAN_CHG_FLG`, `CTRL_BUTTON_FLG`, `WRIB_AUTO_APLY_TG_GAI_FLG`, `CP_DISP_FLG`, `MANSION_FLG`, `KOJI_UM_FLG` |
| Timestamps | `UPD_DTM`, `UNYO_DTM`, `UNYO_YMD` |
| Contract fields | `SVC_CD`, `PRC_GRP_CD`, `SVC_KEI_STAT` |
| Customer contract list fields | `HKTGI_SYSID_01` through `HKTGI_WRIB_AUTO_APLY_TG_GAI_FLG_01` (18 fields) |
| Course history list fields | `SVC_KEI_UCWK_NO_02` through `OLD_PCRS_CD_STATE` (21 fields) |

## How It Works

### Flow: Screen Initialization

```
User opens course history screen
  -> KKW02701SFLogic.init()
       -> JCCWebCommon.getScreenInfo(this)  // retrieve inherited screen data
       -> searchCourseRk()
            -> Set operation date on bean
            -> KKSV0394 mapper sets up service parameters
            -> invokeService("KKSV0394")  // backend call
            -> Mapper deserializes results into beans
            -> setPopupValue() determines button display
            -> Button control flag logic:
                 - eo net + non-mansion + service active + course change + CP target
                   -> BTN_CTRL=3, CTRL_BUTTON=3 (show discount flag)
                 - otherwise
                   -> BTN_CTRL=2, CTRL_BUTTON=1 (hide discount flag)
            -> setForwardInfo(KKW02701)
  -> Course history table rendered to user
```

### Flow: Reservation Cancellation

This is the primary business operation — a representative cancels a customer's reservation.

```
User clicks "Reservation Cancellation Confirmation" button
  -> KKW02701SFLogic.forwardRsvClCfm()
       -> Set operation timestamp and date
       -> setInMsg() -> dispatches based on service code:
            - eo net -> setKKSV0395() (30+ input mappings)
            - eo TV  -> setKKSV0396() (20+ input mappings)
       -> invokeService() (KKSV0395 or KKSV0396 use case)
       -> Check kikiOpRsvFlg -> error EKBF750 if active
       -> SmartTV checks (ANK-4592):
            - isSptvStatCheckResult() -> error EKBG220
            - isErrCdCheckResult() -> error EKB5440
            - isCSOpCheckResult() -> error EKBG200
       -> Service-specific checks:
            - eo TV / eo net -> isKojiRnkiCheckResult() -> error EKBA160
            - eo mobile3G -> isCouseRkRnkiCheckResult() -> error EKB9460
                              isKkSonzaiCheckResult() -> error EKB9470
            - eo net -> isKktksvTkchuCheckResult() -> error EKB5950
                         isIcjkn() -> error EKB5960
                         isRouterSpeedCheckResult() -> error EKB8820
                         isFatRouterExchangeCheckResult() -> error EKBF290
       -> setCourseRk() — filter list to reservation-only entries
       -> Set message EKB0370 ("cancellation")
       -> Navigate to KKW02702 (cancellation confirmation)
```

### Flow: Course Change Division Selection

```
User selects a course change division option
  -> forwardIdoDivChoice()
       -> Get screen info for KKW00145
       -> If null, call getHktgiDataMap() to populate customer contract data
       -> setScreenInfo(KKW00145, dataMap)
       -> Navigate to KKW00145
```

### Flow: Close Application

```
User clicks "Close Application" button
  -> closeAply()
       -> Get common info bean
       -> Check WRIB_AUTO_APLY_TG_GAI_FLG:
            - true -> set to "1" (not a discount target)
            - false -> set to "0" (is a discount target)
       -> GetHktgiDataMap() for screen data
       -> setScreenInfo(KKW00128, dataMap)
       -> Set next screen to CCW00105 (model screen)
```

## Data Model

The module uses a three-layer bean hierarchy that maps to the FJS (Fujitsu Java System) X33/X31 framework:

```
KKW02701SFBean (form-level)
  |-- course_rk_list_list  [X33VDataTypeList<KKW02701SF02DBean>]
  |       |-- 0: KKW02701SF02DBean (course history row 1)
  |       |-- 1: KKW02701SF02DBean (course history row 2)
  |       ...
  |-- hktgi_cust_kei_hktgi_list_list  [X33VDataTypeList<KKW02701SF01DBean>]
          |-- 0: KKW02701SF01DBean (customer contract row 1)
          |-- 1: KKW02701SF01DBean (customer contract row 2)
          ...
```

**Each row bean** follows the `*_update` / `*_value` / `*_state` pattern:
- `*_update` — tracks whether the field was modified by the user (used for optimistic locking / dirty tracking)
- `*_value` — the actual data value displayed or submitted
- `*_state` — visual state for the UI (e.g., enabled, required, error)

Some fields also have an `*_enabled` (Boolean) counterpart for conditional UI rendering.

**Screen data passing** uses `HashMap<String, Object>` through `JCCWebCommon.setScreenInfo()` and `getScreenInfo()`, storing data under screen IDs like `KKW00145`, `KKW00128`, etc. The `getHktgiDataMap()` method handles the conversion from data bean arrays to hash maps, with special handling for variable-length fields.

## Dependencies and Integration

### Module dependencies
The module imports from the following packages:

| Package | Role |
|---|---|
| `eo.business.common` | Business common utilities |
| `eo.business.service` | Business service layer |
| `eo.common.constant` / `eo.common.util` | Shared constants and utilities (string, date) |
| `eo.ejb.common` / `eo.ejb.common.entity` / `eo.ejb.common.itemrelation` / `eo.ejb.common.edit` | EJB entity and edit beans for data access |
| `eo.ejb.cbs.mainproc` | CBS (central business system) main processing |
| `eo.web.webview` | Common webview base classes |
| `eo.web.webview.CommonInfoCF` | Common info carrier framework |
| `eo.web.webview.common` / `eo.web.webview.commonOneStop` | Shared webview utilities |
| `eo.web.webview.mapping` | Data mappers (KKSV0394, KKSV0395, KKSV0396) |
| `eo.web.webview.KKA17101SF` / `KKA17201SF` / `KKA17401SF` / `KKW00127SF` / `FUW00162SF` / `SCW00101SF` | Related screen modules |

### Inbound relationships
The module is consumed by these external configurations:

- `WEBGAMEN_KKW027010PJP.xml` — references `KKW02701SFBean` and `KKW02701SFLogic` (main course history screen)
- `WEBGAMEN_KKW027020PJP.xml` — references `KKW02701SFBean` and `KKW02701SFLogic` (cancellation confirmation screen)
- `WEBGAMEN_KKW027030PJP.xml` — references `KKW02701SFBean` and `KKW02701SFLogic` (update processing screen)
- `x31business_logic_KKW02701SF.xml` — wires `KKW02701SFLogic` into the business logic framework

### Backend service integration
The module communicates with three backend use cases through mapper classes:

| Use Case | Mapper Class | Purpose |
|---|---|---|
| KKSV0394 | `KKSV0394_KKSV0394OPDBMapper` | Course history search |
| KKSV0395 | `KKSV0395_KKSV0395OPDBMapper` | Net reservation cancellation |
| KKSV0396 | `KKSV0396_KKSV0396OPDBMapper` | TV reservation cancellation |

Each mapper generates dozens of input/output data bean mappings via methods like `setKKSV039501SC()`, `getKKSV039401CC()`, etc.

## Notes for Developers

### Architecture pattern
This module follows the **Page Controller + Form Bean + Business Logic** pattern typical of the Fujurity X31/X33 framework. The `KKW02701SFBean` binds to the JSF page, `KKW02701SFLogic` handles all business processing, and the `01DBean`/`02DBean` classes handle table row data.

### Field naming convention
All form fields use the `*_update` / `*_value` / `*_state` triple:
- When a user modifies a field, `*_update` is set to mark it as dirty
- `*_value` holds the current value
- `*_state` controls UI rendering (e.g., `"0"` = enabled, `"1"` = disabled)

This pattern is critical for optimistic locking and UI state management. Do not skip the `*_update` field when modifying a value.

### Service-specific logic
The cancellation flow diverges based on `svc_cd`:
- **`SVC_CD_NET` (eo net)**: Uses KKSV0395 service and requires router speed checks, smart device checks, and temporary fee refund checks
- **`SVC_CD_TV` (eo TV)**: Uses KKSV0396 service and requires work link confirmation

Adding support for a new service type requires adding a new `setKKSV...()` method and branching in `setInMsg()`, plus any relevant validation methods.

### Recent additions worth noting
- **Netflix plans (v51-v52)**: Added price course codes A93-A96 for 5G/10G Netflix plans
- **eo net Simple plan (v71)**: Added A97 and A99 course codes
- **SmartTV/suppa linkage (v71/ANK-4592)**: Three new checks (`isSptvStatCheckResult`, `isErrCdCheckResult`, `isCSOpCheckResult`) added to the cancellation flow
- **Multi-function router exchange check (v41)**: Added `isFatRouterExchangeCheckResult()` for 10G router speed validation
- **Fiber optic mansion course update (v73)**: Added A74 course code for 10G fiber optic mansion plans

### Bean initialization caveat
Both `01DBean` and `02DBean` constructors create their data bean lists in the parent `KKW02701SFBean` constructor. If you need to add new list fields, remember to initialize them in the bean constructor as well.

### The Checker is currently a no-op
`KKW02701SFChecker.checkMethod()` returns `true` unconditionally. If you need to add GUI-level validation (e.g., field format checks before calling the business logic), implement the logic here before `invokeService()` is called.

### Screen navigation
Screen IDs are defined in `JKKScreenConst` and `JCKScreenConst`. The module navigates between:
- `KKW02701` (main screen) ← `searchCourseRk()`
- `KKW02702` (cancellation confirmation) ← `forwardRsvClCfm()`
- `KKW02703` (update screen) ← `forwardFix()`
- `KKW00145` (contract continuation) ← `forwardIdoDivChoice()`
- `KKW00128` (close application data) ← `closeAply()`
- `CKW00101` (customer list) ← `forwardCustListShokai()`
- `CCW00105` (model screen) ← `closeAply()`

### Diagram — Module Architecture

```mermaid
flowchart TD
    A["KKW02701SFBean<br/>Main View Bean"] --> B["KKW02701SF01DBean<br/>Customer Contract Data"]
    A --> C["KKW02701SF02DBean<br/>Course History Data"]
    A --> D["KKW02701SFLogic<br/>Business Logic"]
    D --> E["KKW02701SFChecker<br/>GUI Checker"]
    D --> F["KKW02701SFConst<br/>Constants"]
    D --> G["KKSV0394 Mapper<br/>Course History Search"]
    D --> H["KKSV0395 Mapper<br/>Net Cancellation"]
    D --> I["KKSV0396 Mapper<br/>TV Cancellation"]
    subgraph Services
        G
        H
        I
    end
```

### Diagram — Cancellation Request Flow

```mermaid
flowchart TD
    Start["User clicks<br/>Cancel Button"] --> GetSvc["Get service code<br/>(svc_cd)"]
    GetSvc --> CheckNet{"eo net?"}
    CheckNet -->|Yes| KKSV0395["Call KKSV0395<br/>service"]
    CheckNet -->|No| KKSV0396["Call KKSV0396<br/>service"]
    KKSV0395 --> SmartTVCheck["SmartTV / Error / CS checks"]
    KKSV0396 --> SmartTVCheck
    SmartTVCheck --> KikiCheck{"kikiOpRsvFlg<br/>= 1?"}
    KikiCheck -->|Yes| Err1["Error: EKBF750"]
    KikiCheck -->|No| SvcCheck{"Service<br/>type?"}
    SvcCheck -->|TV| TVCheck["Work link check<br/>isKojiRnkiCheckResult"]
    SvcCheck -->|Net| NetChecks["Device service check<br/>Router speed check<br/>Fee refund check<br/>Multi-func router check"]
    SvcCheck -->|Mobile3G| MobileCheck["Course change check<br/>Crucible check"]
    TVCheck --> Filter["Filter course list<br/>setCourseRk()"]
    NetChecks --> Filter
    MobileCheck --> Filter
    Filter --> Navigate["Navigate to KKW02702"]
    Err1 --> End["End"]
    Navigate --> End
```