# Eo / Web / Webview / Kkw02510sf

## Overview

The `KKW02510SF` package is the **multi-session update component** for the contract management system. It handles web-screen-based operations for modifying, cancelling, recovering, and reserving cancellation of multi-session (multiple concurrent session) subscriptions. Operators access this screen from the **Option Service Contract List** screen and perform lifecycle actions on a selected subscription — change option details, cancel a subscription, reactivate a cancelled one, or cancel a pending reservation. The module follows the standard X31 web framework pattern: a `Logic` class coordinates screen flow and service calls, `Bean` classes carry form and detail data between the view and the business layer, a `Checker` class provides a GUI validation hook, and a `Const` class holds field-name constants.

## Key Classes and Interfaces

### KKW02510SFLogic — Screen Coordination and Service Orchestration

[src: `source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFLogic.java`](source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFLogic.java)

This is the central class of the module. It extends `JCCWebBusinessLogic` and orchestrates the entire screen flow for multi-session subscription updates. Rather than containing business rules itself, it maps data to/from beans, calls backend services, and decides which screen to navigate to next.

**Action methods (public, called by the framework):**

| Method | Purpose | Key behavior |
|---|---|---|
| `actionInit()` | Initial display | Retrieves screen origin info, sets inherited data into the DataBean, calls the initial-display service (`KKSV0071`), maps results back to the bean, then validates that the operation type (update/cancel/recover/reservation-cancel) is actually valid for the current subscription status. If not, disables the update flag and shows an error. |
| `actionUpdCfm()` | "Update Confirmation" button on the edit screen | Dispatches to the correct update service based on `TRAN_DIV` (処理区分). For **update**, calls `KKSV0072` / `KKSV0072OP`; for **cancellation**, calls `KKSV0073` / `KKSV0073OP`. After the service call, checks for a return message ID. If empty, navigates to the confirmation screen (`KKW02511`); otherwise calls `displayGyomuErrorMsg()` to show the error on-screen. |
| `actionFix()` | "Confirm" button on the confirmation screen | Re-dispatches to the correct final update service with `FUNC_CD_1` (the "confirm" function code). The five supported services are: `KKSV0072` (update), `KKSV0073` (cancellation), `KKSV0074` (recovery), `KKSV0075` (reservation cancel). On success, navigates to the completion screen (`KKW02512`); on error, displays the error message. |
| `actionShusei()` | "Modify" button on the confirmation screen | Returns to the edit screen (`KKW02510`). |
| `actionBack()` | "Back" button | Returns to the calling screen (reads the original screen ID from shared form bean). |
| `actionFin()` | "Complete" button | Same as `actionBack()` — returns to the calling screen. |
| `actionClear()` | "Clear" button | Re-runs the initial display flow (`KKSV0071`). |

**Internal helper methods (private):**

- `doService(usecase_id, operation_id, inputMap, outputMap)` — Generic service invocation wrapper. Sets up the `TELEGRAM_INFO_USECASE_ID` and `TELEGRAM_INFO_OPERATION_ID` parameters, calls `invokeService()`, and returns a `X31CMessageResult`. If an AP-server error occurs, the error message object is returned (not null); on success, `null` is returned.

- `setHktgiBean(paramBean)` — Copies data from the caller screen's `cust_kei_hktgi_list` (customer contract continuation list) into this screen's DataBean. Extracts `SYSID`, service contract number, operation division, deviation division, deviation reason codes, option service contract number, application number, and application detail number. Also populates the "deviation reason list" from a separate data source.

- `setInitsrv(paramBean, inputMap)` — Prepares input for the initial-display service. Sets the operation date, operation timestamp, clears the return message ID, and sets flags based on `TRAN_DIV` (e.g., `UPD_MODE_FLG` for update mode, `NON_UPD_DSL_FLG` for display-only mode, `KAIHK_CNSL_FLG` for recovery/cancellation). Then calls the `KKSV0071` mapper for six mapping blocks.

- `storeDataBeanInitsrv(paramBean, outputMap)` — Maps service output back into the DataBean using the `KKSV0071` mapper, then processes per-operation-division logic. Notable behaviors:
  - For **update**: copies `SVC_END_YMD` to the "use end date" field.
  - For **display-only** and **recovery**: same mapping.
  - For **cancellation**: splits the operation date into year/month/day parts for the "use end date" fields.
  - Always enables the `CHG_KAHI_FLG` (update state changeable flag).

- `setChgesrv()` / `storeDataBeanChgesrv()` — Input/output mapping for the update service (`KKSV0072`). The set method also writes a progress indicator text ("マルチセッション情報 + 変更") to `PRG_TKJK_1`.

- `setDslsrv()` / `storeDataBeanDslsrv()` — Input/output mapping for the cancellation service (`KKSV0073`). On the "update confirmation" call (identified by `FUNC_CD_2`), concatenates the year/month/day fields into `USE_ENDYMD`, clears `RTN_MSG_ID`, and writes progress indicator text. The "confirm" call (`FUNC_CD_1`) simply maps output.

- `setKaihksrv()` / `storeDataBeanKaihksrv()` — For recovery (`KKSV0074`). Sets the recovery date to the current operation date. Writes progress indicator text. Also retrieves discount service change messages via `getWrisvcMsg()`.

- `setRsvclsrv()` / `storeDataBeanRsvclsrv()` — For reservation cancellation (`KKSV0075`). Clears return message ID, writes progress indicator text, and includes a cancel SOD issuance mapping block. Also retrieves discount service change messages.

- `displayGyomuErrorMsg(rtn_msgId, trans_div)` — Displays error messages returned by services. Handles specific message codes with contextual parameter substitution (e.g., `EKB0690_NW` for past dates in cancellation, `EKB5440_JW` for outside recovery period, `EKB5420_JW` for reservation cancellation not allowed). Added a safety check (OM-2016-0002076) so messages display even when no parameter substitution is configured.

- `getWrisvcMsg(func_code, outputMap)` — Extracts discount service change messages from the `WrisvcAutoAplyCC` output block and stores them in the session for display to the user.

### KKW02510SFBean — Main Form Data Bean

[src: `source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFBean.java`](source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFBean.java)

This is the screen-level form bean. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface`, `X31CBaseBean`, and `Serializable`. It holds all fields displayed on the multi-session update screen plus control flags.

**Key data fields (grouped by purpose):**

| Group | Fields | Description |
|---|---|---|
| Operation date | `unyo_ymd`, `unyo_dtm` | Current operation date and timestamp |
| Customer/contract | `cust_kei_hktgi_list_list`, `sysid`, `svc_kei_no` | Customer contract continuation list (row-based) with SYSID and service contract number |
| Transaction info | `ido_div`, `ido_rsn_list_list`, `op_svc_kei_no`, `tran_div`, `mskm_no`, `mskm_dtl_no` | Deviation division, deviation reason list, option service contract number, operation division, application number, application detail number |
| Pricing & plan | `prc_grp_cd`, `pcrs_cd`, `pplan_cd` | Price group code, price code, price plan code |
| Authentication | `ninsho_id`, `shk_pwd`, `pwd_init_flg`, `mltise_ninsho_id`, `mltise_ninsho_id_pwd`, `mltise_shk_ninsho_id_pwd`, `kotei_ip_ad` | Authentication ID, initial password, password initialization flag, multi-session auth fields, fixed IP address |
| Service dates | `svc_sta_ymd`, `svc_end_ymd`, `svc_chrg_endymd`, `kaihk_ymd`, `use_endymd`, `use_staymd` | Service start/end dates, service charge end date, recovery date, use end date, use start date |
| Flags | `non_upd_dsl_flg`, `upd_mode_flg`, `kaihk_cnsl_flg`, `kotei_gip_op_on_flg`, `pwd_init_flg_ctrl`, `chg_kahi_flg` | Cannot update/cancel flag, update mode flag, recovery/cancel display flag, fixed global IP option flag, password init flag (control), update state changeable flag |
| Session | `cur_session_cnt`, `chg_session_cnt`, `session_uppl`, `session_dwnl`, `rsv_uppl_prd` | Current session count, changed session count, session upper limit, update-possible session lower limit, reservation upper limit days |
| Return/error | `rtn_msg_id` | Return message ID from service calls |

**Constructor:** Creates the `cust_kei_hktgi_list_list` with one pre-initialized row containing a `KKW02510SF01DBean` instance.

**`getJsflist_typelist_cust_kei_hktgi_list()`** — Converts the customer contract list into an `ArrayList<SelectItem>` for JSF rendering, using Japanese labels ("顧客契約引継リスト").

### KKW02510SF01DBean — Detail Data Bean (List Row)

[src: `source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SF01DBean.java`](source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SF01DBean.java)

Represents a single row in the customer contract continuation list. Implements `X33VDataTypeBeanInterface`, `X33VListedBeanInterface`, and `Serializable`. Each row has three state properties per field (`_update`, `_value`, `_state`) following the X31 convention for edit tracking.

**Fields per row:**

- `sysid` / `svc_kei_no` / `ido_div` — Core identification fields
- `ido_rsn_cd_list` / `ido_rsn_memo` — Deviation reason codes and memo
- `op_svc_kei_no_list` — Option service contract number list
- `tran_div` / `mskm_no` / `mskm_dtl_no` — Transaction and application numbers
- `index` — Row position

**`loadModelData(key, subkey)`** — Dynamic field access. Given a field name (in Japanese) and a subkey ("value", "state", or a list index), it looks up the appropriate property. For list-type fields (`ido_rsn_cd_list`, `op_svc_kei_no_list`), if the subkey is `"*"`, it returns the list size. For list access with an index, it returns the value at that index from the list.

**`storeModelData()`** (multiple overloads) — Reverse of `loadModelData`, sets values on the bean dynamically.

**`addListDataInstance(key)` / `removeElementFromListData(key, index)` / `clearListDataInstance(key)`** — List management helpers for dynamically growing/shrinking the reason-code and option-service lists.

**`listKoumokuIds()` / `typeModelData()`** — Introspection methods that return a list of all field names and their Java types, used by the framework for data binding.

### KKW02510SF02DBean — Secondary Detail Data Bean

[src: `source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SF02DBean.java`](source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SF02DBean.java)

A smaller detail bean for secondary list data. Contains only `ido_rsn_cd` (deviation reason code), `ido_rsn_memo` (deviation reason memo), and `index`. Uses the same pattern of update/value/state triplets and implements the same interfaces as `KKW02510SF01DBean`.

### KKW02510SFChecker — GUI Validation Hook

[src: `source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFChecker.java`](source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFChecker.java)

Implements `X31SGuiCheckBase` and holds a reference to the business logic (`X31BBusinessLogic`). The constructor receives the `KKW02510SFLogic` instance.

The `checkMethod(param, errMsgStock)` method currently receives the check pattern ID and returns `true` (pass) unconditionally — no validation logic is implemented here. The actual validation is handled by:
1. The X31 framework's field-level validation (defined in the screen definition XML).
2. The status-based checks inside `actionInit()` that validate whether the operation is allowed for the current subscription state before enabling the update flag.

This is a placeholder for future GUI-level validation if needed.

### KKW02510SFConst — Field Name Constants

[src: `source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFConst.java`](source/koptWebB/src/eo/web/webview/KKW02510SF/KKW02510SFConst.java)

Utility class with a private constructor. All fields are `public static final String` constants. Every value is a Japanese label that the X31 framework uses as a key to access fields on the DataBean via `sendMessageString()`, `sendMessageBoolean()`, etc.

The constants cover roughly 50+ field names organized into these categories:
- **Operation date/time**: `UNYO_YMD`, `UNYO_DTM`
- **Customer/contract**: `CUST_KEI_HKTGI_LIST`, `SYSID`, `SVC_KEI_NO`, `IDO_DIV`, `IDO_RSN_LIST`
- **Transaction info**: `TRAN_DIV`, `MSKM_NO`, `MSKM_DTL_NO`
- **Pricing**: `PCRS_CD`, `PPLAN_CD`, `PRC_GRP_CD`
- **Authentication**: `NINSHO_ID`, `SHK_PWD`, `PWD_INIT_FLG`, `MLTISE_NINSHO_ID`, `MLTISE_NINSHO_ID_PWD`, `MLTISE_SHK_NINSHO_ID_PWD`, `KOTEI_IP_AD`
- **Service dates**: `SVC_STA_YMD`, `SVC_END_YMD`, `SVC_CHRG_ENDYMD`, `KAIHK_YMD`, `USE_ENDYMD`, `USE_STAYMD`
- **Session management**: `CUR_SESSION_CNT`, `CHG_SESSION_CNT`, `SESSION_UPPL`, `SESSION_DWNL`, `RSV_UPPL_PRD`
- **Control flags**: `NON_UPD_DSL_FLG`, `UPD_MODE_FLG`, `KAIHK_CNSL_FLG`, `KOTEI_GIP_OP_ON_FLG`, `PWD_INIT_FLG_CTRL`, `RTN_MSG_ID`, `CHG_KAHI_FLG`
- **Progress indicator**: `PRG_TKJK_1`

## How It Works

### Request Flow

The module follows the standard X31 web framework layered architecture:

- The **web screen** sends form submissions to `KKW02510SFLogic` based on the action type button the user clicks.
- The **Logic** class coordinates all processing: it reads data from the `KKW02510SFBean` (the form bean), maps it through DataMapper classes, invokes backend services, maps results back, and determines the next screen to navigate to.
- **DataBean** classes (`KKW02510SFBean`, `KKW02510SF01DBean`, `KKW02510SF02DBean`) carry data between the view and the logic layer.
- The **Checker** class provides a framework hook for additional GUI validation (currently unused).
- The **Const** class provides the field name keys that the framework uses for dynamic bean access.

```mermaid
flowchart LR
    WEB["Web Screen KKSV02510"] --> LOGIC["KKW02510SFLogic"]
    LOGIC --> BEAN["KKW02510SFBean"]
    LOGIC --> C01["KKW02510SF01DBean"]
    LOGIC --> C02["KKW02510SF02DBean"]
    LOGIC --> CHECKER["KKW02510SFChecker"]
    LOGIC --> CONST["KKW02510SFConst"]
    LOGIC --> MAP01["KKSV0071 Mapper (Initial Display)"]
    LOGIC --> MAP02["KKSV0072 Mapper (Update)"]
    LOGIC --> MAP03["KKSV0073 Mapper (Cancellation)"]
    LOGIC --> MAP04["KKSV0074 Mapper (Recovery)"]
    LOGIC --> MAP05["KKSV0075 Mapper (Reservation Cancel)"]
    LOGIC --> SVC["Backend Service Layer"]
```

### Step-by-Step: Initial Display

1. `actionInit()` is called by the framework when the screen is first opened.
2. Screen origin info is retrieved via `JCCWebCommon.getScreenInfo()`.
3. `setHktgiBean()` copies data from the caller screen's contract list into this screen's DataBean (SYSID, contract number, operation division, etc.).
4. `setInitsrv()` prepares the service input: operation date, timestamp, control flags (depending on operation type), and maps DataBean fields into the service input `HashMap` via the `KKSV0071` mapper.
5. `doService("KKSV0071", "KKSV0071OP", ...)` invokes the backend service.
6. `storeDataBeanInitsrv()` maps the service output back into the DataBean using the `KKSV0071` mapper, enables the update flag, and populates session-related fields.
7. Status-based validation runs: if the operation division is "update" but the option service contract status is not one of (preparation, contract completion, service provision), an error is shown and the update flag is disabled. Similar checks exist for cancellation, recovery, and reservation cancellation.
8. The screen is rendered with all data populated.

### Step-by-Step: Update Confirmation

1. `actionUpdCfm()` is called when the user clicks "Update Confirmation" on the edit screen.
2. The operation division (`TRAN_DIV`) determines which service to call:
   - **Cancellations (`OP_TRAN_DIV_DSL`)** → calls `setDslsrv()` to prepare input, then `doService("KKSV0073", "KKSV0073OP")` to execute.
   - **Updates (`OP_TRAN_DIV_CHGE`)** → sets `PWD_INIT_FLG_CTRL` from `PWD_INIT_FLG` (forwarding the password initialization toggle), calls `setChgesrv()` to prepare input, then `doService("KKSV0072", "KKSV0072OP")`.
3. After the service call, the return message ID is checked. If it's empty, the screen navigates to the confirmation screen (`KKW02511`). If not empty, `displayGyomuErrorMsg()` shows the error.

### Step-by-Step: Final Confirm

1. `actionFix()` is called when the user clicks "Confirm" on the confirmation screen.
2. The operation division determines which service to call, all with `FUNC_CD_1`:
   - **Update** → `KKSV0072` / `KKSV0072OP`
   - **Cancellation** → `KKSV0073` / `KKSV0073OP`
   - **Recovery** → `KKSV0074` / `KKSV0074OP`
   - **Reservation Cancel** → `KKSV0075` / `KKSV0075OP`
3. On success, navigates to the completion screen (`KKW02512`). On error, shows the error.

### Service Mapping Pattern

Each service has a companion DataMapper (e.g., `KKSV0071_KKSV0071OPDBMapper`) that handles the field-to-field mapping between the DataBean and the service input/output. The Logic class instantiates the mapper and calls specific mapping methods:

| Service | Mapper | Purpose |
|---|---|---|
| KKSV0071 | KKSV0071_KKSV0071OPDBMapper | Initial display |
| KKSV0072 | KKSV0072_KKSV0072OPDBMapper | Update |
| KKSV0073 | KKSV0073_KKSV0073OPDBMapper | Cancellation |
| KKSV0074 | KKSV0074_KKSV0074OPDBMapper | Recovery |
| KKSV0075 | KKSV0075_KKSV0075OPDBMapper | Reservation cancel |

Each mapper provides a `set*SC()` method for input mapping and a `get*SC()` method for output mapping, plus specialized methods like `setOpsvckeiDslCC` (for the cancellation-specific block) or `setOpsvckeiKaihkCC` (for the recovery-specific block).

## Data Model

The data model is driven by the DataBean classes and follows a three-tier hierarchy:

1. **`KKW02510SFBean`** — The top-level form bean. Contains scalar fields for operation metadata, control flags, and session information, plus list-type fields for multi-row data.
2. **`KKW02510SF01DBean`** — A list row representing a single customer contract continuation entry. Each row contains identification fields (`sysid`, `svc_kei_no`), deviation information (`ido_div`, `ido_rsn_cd_list`), and application details (`mskm_no`, `mskm_dtl_no`). The list fields (`ido_rsn_cd_list`, `op_svc_kei_no_list`) hold strings and can grow dynamically.
3. **`KKW02510SF02DBean`** — A secondary list row for deviation reason data, containing only a reason code and memo.

Each scalar field on the detail beans has a triplet of properties:
- `*_update` — Tracks whether the field has been modified by the user.
- `*_value` — The current field value.
- `*_state` — The display/edit state (e.g., enabled, disabled, read-only).

The main bean also has a `cust_kei_hktgi_list_list` field of type `X33VDataTypeList` containing `KKW02510SF01DBean` instances, supporting multiple contract rows on a single screen.

## Dependencies and Integration

### Outbound Dependencies

The module depends on several other modules for cross-cutting concerns:

| Dependency | Usage |
|---|---|
| `eo.web.webview.mapping.KKSV007*_Mapper` | Data mapping for each of the 5 backend services |
| `eo.web.webview.JCCWebBusinessLogic` | Base class providing `invokeService()`, `getServiceFormBean()`, `getCommonInfoBean()` |
| `eo.web.webview.common.JCCWebCommon` | Utility for screen info retrieval, operation date, message display |
| `eo.web.webview.common.JKKCommonConst` | Shared constants for operation division codes and status codes |
| `eo.web.webview.common.JKKScreenConst` | Screen ID constants (`KKW02510`, `KKW02511`, `KKW02512`) |
| `eo.web.webview.common.JKKSetSessionMessage` | Session-based message storage for discount service messages |
| `eo.web.webview.CommonInfoCF.CommonInfoCFConst` | Shared form bean field names |
| `eo.common.constant.JPCModelConstant` | Function code constants (`FUNC_CD_1`, `FUNC_CD_2`) |
| `eo.common.constant.JPCOnlineMessageConstant` | Error/info message ID constants |
| `eo.web.webview.mapping.*OPDBMapper` | Database mapping layer for the 5 services |

### Inbound Dependencies (who uses this module)

| XML Config | Classes Referenced |
|---|---|
| `WEBGAMEN_KKW025100PJP.xml` | `KKW02510SFBean`, `KKW02510SFLogic` |
| `WEBGAMEN_KKW025110PJP.xml` | `KKW02510SFBean`, `KKW02510SFLogic` |
| `WEBGAMEN_KKW025120PJP.xml` | `KKW02510SFBean`, `KKW02510SFLogic` |
| `x31business_logic_KKW02510SF.xml` | `KKW02510SFLogic` |

Three screen configuration files reference this module:
- **KKW02510** — The edit screen (initial display + update form)
- **KKW02511** — The confirmation screen
- **KKW02512** — The completion screen

Additionally, the `WEBGAMEN_KKA144010PJP.xml` config references `KKW02510SFBean`, suggesting this module is launched from the option service contract list screen (`KKA14401`).

## Notes for Developers

### Operation Division Codes
The module uses `JKKCommonConst` constants to distinguish between four operation types. All flow decisions in `actionInit()`, `actionUpdCfm()`, and `actionFix()` branch on these:

- `OP_TRAN_DIV_CHGE` — Update (option service change)
- `OP_TRAN_DIV_DSL` — Cancellation
- `OP_TRAN_DIV_KAIHK` — Recovery (re-activate cancelled subscription)
- `OP_TRAN_DIV_RSV_CL` — Reservation cancellation (cancel a pending reservation)
- `OP_TRAN_DIV_SHOKAI` — Display-only (read-only mode)

### Subscription Status Checks
On initial display, the module validates whether each operation is actually allowed for the current subscription state (`op_svc_kei_stat`). For example:
- **Update** is only allowed if status is 020 (preparation), 030 (contract completion), or 100 (service provision).
- **Cancellation** requires status 030, 100, or 210 (suspended/interrupted).
- **Recovery** is only shown when status is 910 (cancelled).
- **Reservation Cancel** allows status 010 (received), 020, 030, or 100.

If the status doesn't match, the update flag is disabled and an error message is displayed.

### Password Initialization
For update operations, a password initialization flag (`PWD_INIT_FLG`) is read from the bean and forwarded to the service as `PWD_INIT_FLG_CTRL`. This flag controls whether the multi-session authentication credentials are being changed as part of the update.

### Discount Service Messages
When option services are updated or recovered, discount services may auto-apply. The `getWrisvcMsg()` method extracts discount change messages from the service output and stores them in the session via `JKKSetSessionMessage`. These are displayed to the user as informational messages after confirmation.

### Thread Safety
The bean classes use instance variables without synchronization. In the X31 web framework, beans are typically instantiated per-request, so thread safety is not a concern. However, avoid storing request-scoped data in static fields of bean classes.

### Extending with New Operations
To add a new operation type:
1. Define a new `OP_TRAN_DIV_*` constant in the appropriate `JKKCommonConst` (if not already present).
2. Add the corresponding `KKSV007X` service call and mapper.
3. Add `setOpsvckeiXxxCC()` and `getOpsvckeiXxxCC()` methods to the service input mapping pattern (follow the existing `setDslsrv()` / `storeDataBeanDslsrv()` pattern).
4. Add the action and status validation logic in `actionInit()`, `actionUpdCfm()`, and `actionFix()`.
5. Add screen configurations for any new confirmation/completion screens.