# Eo / Web / Webview / Kkw03204sf

## Overview

This module implements the **050 Number Issuance Change** feature (`050番号発番変更部品`) within the Fujitsu Futurity X31/X33 web framework. It handles contract lifecycle operations for a 050-number telephone service — specifically **cancellation** (解除), **recovery** (回復), and **reservation cancellation** (予約取消消). The module is invoked from an Operations Service Contract Overview screen (`KKW032040`) and its confirmation/finalization screens (`KKW032050`, `KKW032060`).

A new team member should understand: this is a典型的 web MVC-style controller module. The logic class (`KKW03204SFLogic`) orchestrates screen initialization, data mapping to/from backend AP services, and navigation to subsequent screens. It uses the Futurity X31/X33 framework's data bean system, where a main screen bean (`KKW03204SFBean`) holds a collection of typed row beans (`*DBean` classes) that represent lists displayed on the UI (customer contract list, discontinuation reasons, aging info, etc.).

## Key Classes and Interfaces

### [KKW03204SFLogic](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SFLogic.java)

**Purpose:** The central controller for the 050 Number Issuance Change feature. It extends `JCCWebBusinessLogic` and implements all the action methods that the web framework invokes in response to user interactions on the screen.

**Why it matters:** This class is the brain of the module. Every user action (initial display, update confirmation, fix/commit, modify, back, finish, clear) routes through a method here. It decides which backend AP service to call, prepares input data, maps output results, and determines the next screen.

**Key methods:**

| Method | Purpose |
|---|---|
| `actionInit()` | Initial display processing. Fetches screen context from the parent screen's inherited data list, sets up the service form bean with service codes, calls the initial display service `KKSV0135`, and maps returned data to the screen bean. |
| `actionUpd_cfm()` | Update confirmation. Assembles the end date from year/month/day fields, calls the cancellation confirmation service `KKSV0136`, maps results, and navigates to the confirmation/finalization screen `KKW03205`. |
| `actionFix()` | Finalization (commit). Dispatches to one of three services based on the processing division (`trans_div`): cancellation (`KKSV0136`), recovery (`KKSV0162`), or reservation cancel (`KKSV0163`). Then navigates to the completion screen `KKW03206`. |
| `actionShusei()` | Modify — returns to the change screen (`KKW03204`). |
| `actionBack()` | Back — returns to the calling screen using the inherited screen ID. |
| `actionFin()` | Finish — returns to the calling screen and ends the session. |
| `actionClear()` | Clear — resets fields to cancellation defaults. |
| `doService()` | Private helper that invokes the AP server via `invokeService()` with the appropriate usecase/operation IDs. |
| `setDataInit()` | Private setup for initial display — reads inherited data from the parent screen's session bean, populates fields like system ID, service contract number, submission number, and the discontinuation reason list. |
| `setDataInit_Kaiyaku()` | Private setup specific to cancellation — pre-fills the end date with today's date and enables the cancellation action buttons. |
| `setDataDsl()` | Private setup for cancellation service input — sets the end date, service charge end date, and builds the aging info list. |
| `setDataKaihk()` | Private setup for recovery service input — sets the recovery date to today's date and builds the aging info list. |
| `setDataDslStp()` | Private setup for reservation cancel input — builds the aging info list. |
| `getMsgRep()` | Private helper that provides localized message substitutions for specific error codes (e.g., "suspended period", "future date" errors). |
| `setErrorMessageInfo()` | Private helper (added in OM-2015-0000564) that checks for SOD issuance errors returned by the AP service. |

**Important constants defined in this class:**

| Constant | Value | Meaning |
|---|---|---|
| `MSKM_SBT_CD_OPMK` | `"00026"` | Submission type code (Operations Service Submission) |
| `SVC_DLRE_CD_TUJYO` | `"01"` | Service termination reason code (Normal Termination) |
| `AGING_SBT_CD_TEL` | `"001"` | Aging type code (Telephone) |
| `PRG_STAT_CD` | `"5102"` | Progress status (Settings Complete) |
| `IDO_DIV_CD` | `"0031"` | Discontinuation division (Operations Settings) |
| `DSL_RSV` | `"1"` | Termination type (Reservation Termination) |
| `DSL_SOKU` | `"2"` | Termination type (Immediate Termination) |
| `OP_SVC_CD_050` | `"B029"` | Operations Service Code for 050 |

### [KKW03204SFBean](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SFBean.java)

**Purpose:** The main screen data bean. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface` and `X31CBaseBean`. It holds approximately 80+ fields that represent every piece of data displayed on the 050 Number Issuance Change screen.

**Why it matters:** This is the bridge between the UI and the logic class. Every field on the screen (displayed or hidden) has a corresponding triple of properties in this bean: `_<field>_value` (the actual data), `_<field>_update` (update flag), and `_<field>_state` (enabled/disabled state). Some fields also have `_<field>_enabled` (Boolean) properties for fine-grained display control.

**Key data structures (typed list beans):**

| List Property | Row Bean Type | UI Meaning |
|---|---|---|
| `cust_kei_hktgi_list_list` | `KKW03204SF01DBean` | Customer Contract Inheritance List (table of contracts) |
| `ido_rsn_list_list` | `KKW03204SF02DBean` | Discontinuation Reason List |
| `aging_info_list_list` | `KKW03204SF03DBean` | Aging Information List |
| `op_svc_list_list` | `KKW03204SF04DBean` | Operations Service List |

**Notable fields:**

- `sys_id_value` / `sys_id_state`: System ID (identifier)
- `svc_kei_no_value` / `svc_kei_no_state`: Service Contract Number
- `op_svc_kei_no_value`: Operations Service Contract Number
- `ido_div_value`: Discontinuation Division (e.g., "0031" = Operations Settings)
- `mskm_no_value`: Submission Number
- `mskm_dtl_no_value`: Submission Detail Number
- `use_endymd_year_value` / `use_endymd_mon_value` / `use_endymd_day_value`: End Date (split into year/month/day components)
- `hradsi_050_no_value`: Output 050 Number
- `aging_sbt_cd_value`: Defaults to `"001"` (Telephone) in the constructor
- `mskm_sbt_cd_value`: Defaults to `"00026"` (Operations Service Submission)
- `dsl_view_enable_flg_value`: Boolean that controls whether the cancellation action buttons are visible

### [KKW03204SF01DBean](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SF01DBean.java)

**Purpose:** Row data bean for entries in the Customer Contract Inheritance List. Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

**Fields:** Each row represents a customer contract and carries identification and discontinuation reason data:

| Field Group | Purpose |
|---|---|
| `sysid_*`, `svc_kei_no_*`, `ido_div_*` | System ID, Service Contract Number, Discontinuation Division — inherited from parent |
| `tran_div_*` | Processing Division (cancellation / recovery / cancel reservation) |
| `mskm_no_*`, `mskm_dtl_no_*` | Submission Number and Detail Number |
| `tokutei_id_kmk_*` / `telno_jun_*` | Specific ID item fields and telephone number sequence (added for input support workflow in IT1-2013-0000328) |
| `ido_rsn_cd_list`, `op_svc_kei_no_list` | Data lists for dropdown selectors; `getJsflist_*()` methods convert these to `SelectItem` arrays for JSF rendering |

**Key methods:**
- `loadModelData(key, subkey)` — Dynamically returns field values by name. Supports the framework's reflection-based data binding.
- `storeModelData(key, subkey, in_value)` — Dynamically sets field values by name.
- `typeModelData(key, subkey)` — Returns the Java type (`Class<?>`) for a given field name.
- `listKoumokuIds()` — Returns a static list of all field names for this bean type.
- `getJsflist_ido_rsn_cd()` / `getJsflist_op_svc_kei_no()` — Convert typed list data to JSF `SelectItem` arrays for dropdown rendering.

### [KKW03204SF02DBean](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SF02DBean.java)

**Purpose:** Row data bean for entries in the Discontinuation Reason List. Each row represents a single discontinuation reason.

**Fields:**
| Field | Purpose |
|---|---|
| `ido_rsn_cd_*` | Discontinuation Reason Code |
| `ido_rsn_memo_*` | Discontinuation Reason Memo/notes |

This is a simple two-field row bean. It's used in the customer contract list section where each contract row can have associated discontinuation reasons.

### [KKW03204SF03DBean](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SF03DBean.java)

**Purpose:** Row data bean for entries in the Aging Information List.

**Fields:**
| Field | Purpose |
|---|---|
| `aging_sbt_cd_*` | Aging Type Code (e.g., `"001"` for Telephone) |
| `aging_tg_value_*` | Aging Target Value (the 050 number being processed) |

The logic class automatically creates one aging info row (type = Telephone) when performing cancellation, recovery, or reservation cancel operations. This aging data is passed to the backend AP services for audit/tracking purposes.

### [KKW03204SF04DBean](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SF04DBean.java)

**Purpose:** Row data bean for entries in the Operations Service List.

**Fields:**
| Field | Purpose |
|---|---|
| `rsv_psb_prd_*` | Reservation Possible Period |

This bean was added in TAI-2012-0000081 (2012/09/28) and is relatively minimal.

### [KKW03204SFChecker](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SFChecker.java)

**Purpose:** GUI validation class implementing `X31SGuiCheckBase`. Currently a placeholder — the `checkMethod()` always returns `true` and performs no validation.

**Why this exists:** The X31 framework expects a checker class for each screen to handle field-level and cross-field validation. In this case, the validation appears to be handled entirely by the backend AP service (KKSV0136) and the logic class itself, so this class is a no-op stub.

### [KKW03204SFConst](source/koptWebB/src/eo/web/webview/KKW03204SF/KKW03204SFConst.java)

**Purpose:** Constants class for screen identifiers, field labels, and service codes. All constants are `public static final String` fields.

**Key constant groups:**
- **Service codes:** `OP_SVC_CD_050 = "B029"`, `OP_SVC_CD` (Operations Service Code)
- **Field labels (Japanese):** `SYS_ID`, `SVC_KEI_NO`, `IDO_DIV`, `MSKM_NO`, `IDO_RSN_CD`, `AGING_INFO_LIST`, `AGING_SBT_CD`, `AGING_TG_VALUE`, etc.
- **Inherited list field keys:** `SYSID_01`, `SVC_KEI_NO_01`, `IDO_DIV_01`, `IDO_RSN_CD_01`, `TRAN_DIV_01`, `MSKM_NO_01`, `MSKM_DTL_NO_01`, `TOKUTEI_ID_KMK_NM_01`, `TOKUTEI_ID_KMK_VALUE_01`, `IDO_RSN_MEMO_01`, `TELNO_JUN_02`
- **Tab control codes:** `TEL_1_TAB_OP_IF_CTL_CD`, `TEL_2_TAB_OP_IF_CTL_CD` (added for tab-based operations workflow)

## How It Works

### Request Flow

```mermaid
flowchart TD
    subgraph Controller
        Logic["KKW03204SFLogic<br/>Main controller / business logic"]
    end
    subgraph Beans
        Bean["KKW03204SFBean<br/>Screen data bean<br/>~80 fields"]
        DBean01["KKW03204SF01DBean<br/>Customer contract list<br/>row data"]
        DBean02["KKW03204SF02DBean<br/>Discontinuation reason<br/>row data"]
        DBean03["KKW03204SF03DBean<br/>Aging info<br/>row data"]
        DBean04["KKW03204SF04DBean<br/>Reservation possible<br/>period row data"]
        Const["KKW03204SFConst<br/>Screen constants"]
        Checker["KKW03204SFChecker<br/>GUI validation<br/>(placeholder)"]
    end
    subgraph Mappers
        Mapper0135["KKSV0135 Mapper<br/>Initial display service"]
        Mapper0136["KKSV0136 Mapper<br/>Cancellation service"]
        Mapper0162["KKSV0162 Mapper<br/>Recovery service"]
        Mapper0163["KKSV0163 Mapper<br/>Reservation cancel service"]
    end

    Logic --> Bean
    Bean --> DBean01
    Bean --> DBean02
    Bean --> DBean04
    Bean --> Const
    Logic --> Mapper0135
    Logic --> Mapper0136
    Logic --> Mapper0162
    Logic --> Mapper0163
    Checker --> Logic
```

### Initial Display (`actionInit`)

1. **Screen info extraction:** Reads screen context (screen ID, operation date) via `JCCWebCommon.getScreenInfo()`.
2. **Service form setup:** Sets the Operations Service Code `B029` on the service form bean.
3. **Inherited data fetch:** Reads the Customer Contract Inheritance List from the parent screen's session data — including the System ID, Service Contract Number, Operations Service Contract Number, Discontinuation Division, and Processing Division.
4. **Discontinuation reason population:** Iterates through inherited discontinuation reason codes and copies them into the screen bean's `ido_rsn_list_list`.
5. **AP service call:** Invokes `KKSV0135` / `KKSV0136OP` (initial display service) via the mapper classes to fetch the complete set of fields (dates, contract details, aging info, etc.).
6. **Processing-division branching:** If the processing division is "cancellation" (`OP_TRAN_DIV_DSL`), pre-fills the end date with today's date. If it's "recovery" (`OP_TRAN_DIV_KAIHK`) or "cancel reservation" (`OP_TRAN_DIV_RSV_CL`), displays an informational message indicating which action the screen is processing.

### Update Confirmation (`actionUpd_cfm`)

1. **End date assembly:** Combines the year, month, and day fields into a single `YYYYMMDD` string and sets both `USE_ENDYMD` and `DSP_ENDYMD` on the bean.
2. **Mapper setup:** Configures `KKSV0136` mapper with function code `"2"` (check only — no registration).
3. **AP service call:** Invokes the cancellation confirmation service `KKSV0136` / `KKSV0136OP`.
4. **Result mapping:** Copies output data back to the bean.
5. **Error handling:** If the AP service returns an error message ID, displays it; otherwise navigates to the confirmation screen `KKW03205`.

### Finalization (`actionFix`)

This is the critical branching method. Based on the `trans_div` (processing division), it dispatches to one of three paths:

**Path 1 — Cancellation (`OP_TRAN_DIV_DSL`):**
- Prepares cancellation data (end date, service charge end date, aging info list).
- Maps input via `KKSV0136` with function code `"1"` (check + register).
- Calls `KKSV0136` / `KKSV0136OP`.
- Maps output via `KKSV0136` mapper.
- Checks for error message IDs; on success, navigates to `KKW03206`.

**Path 2 — Recovery (`OP_TRAN_DIV_KAIHK`):**
- Prepares recovery data (recovery date set to today, aging info list).
- Maps input via `KKSV0162` with function code `"1"`.
- Calls `KKSV0162` / `KKSV0162OP`.
- Checks for SOD issuance errors (added in OM-2015-0000564 to address cases where SOD was not issued during cancellation).
- Maps output and navigates to `KKW03206`.

**Path 3 — Reservation Cancel (`OP_TRAN_DIV_RSV_CL`):**
- Prepares reservation cancel data (aging info list).
- Maps input via `KKSV0163` with function code `"1"`.
- Calls `KKSV0163` / `KKSV0163OP`.
- Maps output and navigates to `KKW03206`.

### Historical Bug Fixes (notable)

| Version | Date | Issue |
|---|---|---|
| v4.00.00 | 2013/03/04 | Added registration of submission screen input support workflow data during preview |
| v20.00.00 | 2015/12/04 | Fixed: When a transferred telephone OP was cancelled after a number change, the SIP cancellation/deletion order was sent incorrectly |
| v23.00.00 | 2016/02/23 | Fixed: SOD was not issued when cancelling 050 OP |

## Data Model

The data model revolves around the **Futurity X33 data bean system**. The main bean (`KKW03204SFBean`) holds flat primitive fields for simple screen inputs and typed list beans for repeating row data.

### Flat Fields (on `KKW03204SFBean`)

Each screen field follows a naming pattern: `<fieldname>_value`, `<fieldname>_update`, `<fieldname>_state`, and sometimes `<fieldname>_enabled`.

```
<fieldname>_value   — the actual data value
<fieldname>_update  — update flag (set when the field is modified)
<fieldname>_state   — display state (e.g., "disabled", "readonly")
<fieldname>_enabled — Boolean visibility toggle
```

### Row Bean Hierarchy

```
KKW03204SFBean (main screen bean)
├── cust_kei_hktgi_list_list  → KKW03204SF01DBean[] (Customer Contract Inheritance List)
│   └── Each row: sysid, svc_kei_no, ido_div, ido_rsn_cd_list, op_svc_kei_no_list,
│                tran_div, mskm_no, mskm_dtl_no, tokutei_id_kmk_*, ido_rsn_memo, telno_jun
├── ido_rsn_list_list         → KKW03204SF02DBean[] (Discontinuation Reason List)
│   └── Each row: ido_rsn_cd, ido_rsn_memo
├── aging_info_list_list      → KKW03204SF03DBean[] (Aging Info List)
│   └── Each row: aging_sbt_cd, aging_tg_value
└── op_svc_list_list          → KKW03204SF04DBean[] (Operations Service List)
    └── Each row: rsv_psb_prd
```

### Backend Data Exchange

The module exchanges data with AP services through `HashMap<String, Object>` input/output maps. Key service interactions:

| Service | Usecase | Operation | Direction | Purpose |
|---|---|---|---|---|
| KKSV0135 | KKSV0136OP | Initial display | Read | Fetch service data, customer contract list, aging info |
| KKSV0136 | KKSV0136OP | Cancellation | Write | Perform cancellation confirmation or finalization |
| KKSV0162 | KKSV0162OP | Recovery | Write | Perform recovery operation |
| KKSV0163 | KKSV0163OP | Cancel Reservation | Write | Cancel a previously reserved cancellation |

## Dependencies and Integration

### Internal Dependencies

This module depends on the following packages and classes:

| Dependency | Role |
|---|---|
| `eo.web.webview.JCCWebBusinessLogic` | Base class for all web business logic controllers |
| `eo.web.webview.common.JCCWebCommon` | Shared utilities (screen info, date handling, message display) |
| `eo.web.webview.common.JKKCommonConst` | Common constants (session keys, screen IDs, division codes) |
| `eo.web.webview.common.JKKScreenConst` | Screen ID/name constants |
| `eo.web.webview.CommonInfoCF.CommonInfoCFConst` | Common info flow bean constants |
| `eo.common.constant.JPCModelConstant` | Model function codes |
| `eo.common.constant.JPCOnlineMessageConstant` | Message ID constants |
| `eo.web.webview.mapping.KKSV0135_KKSV0135OPDBMapper` | Data mapper for initial display service |
| `eo.web.webview.mapping.KKSV0136_KKSV0136OPDBMapper` | Data mapper for cancellation service |
| `eo.web.webview.mapping.KKSV0162_KKSV0162OPDBMapper` | Data mapper for recovery service |
| `eo.web.webview.mapping.KKSV0163_KKSV0163OPDBMapper` | Data mapper for reservation cancel service |

### Inbound Dependencies (who calls this module)

| XML Config | References |
|---|---|
| `WEBGAMEN_KKA164010PJP.xml` | `KKW03204SFBean` |
| `WEBGAMEN_KKW032040PJP.xml` | `KKW03204SFBean`, `KKW03204SFLogic` |
| `WEBGAMEN_KKW032050PJP.xml` | `KKW03204SFBean`, `KKW03204SFLogic` |
| `WEBGAMEN_KKW032060PJP.xml` | `KKW03204SFBean`, `KKW03204SFLogic` |
| `x31business_logic_KKW03204SF.xml` | `KKW03204SFLogic` |

### Cross-screen flow

The module participates in a three-screen flow:

```
KKW03204 (Initial/Change screen)
  → [Update Confirmation] → KKW03205 (Confirmation screen)
    → [Fix] → KKW03206 (Completion screen)
```

The `trans_div` field (Processing Division) is inherited from the parent screen (`KKA16401`) to determine whether the operation is cancellation, recovery, or reservation cancel. This same `trans_div` controls both the initial display branching and the `actionFix()` dispatch logic.

## Notes for Developers

### Checker class is a placeholder

`KKW03204SFChecker.checkMethod()` always returns `true` and performs no validation. All validation logic is pushed to the backend AP service (`KKSV0136`). If you need to add client-side validation, this class is the extension point.

### Processing Division drives all behavior

The `trans_div` field is the single most important state variable. It determines:
- Which fields are pre-filled during `actionInit()`
- Which AP service is called during `actionFix()`
- What informational messages are shown during initialization
- How error messages are localized via `getMsgRep()`

### Aging info is auto-generated

Every write operation (cancellation, recovery, reservation cancel) automatically creates one aging info row with type code `"001"` (Telephone) and the target 050 number as the target value. This is done in `setDataDsl()`, `setDataKaihk()`, and `setDataDslStp()`.

### SOD error handling was added late

The `setErrorMessageInfo()` method was added in version 23.00.00 (OM-2016-0000002) to handle cases where the AP service returns an SOD (System Operations Database) issuance error. This checks `chk_kbn = "1"` in the mapper output map and displays message `EKBE020_KW`. When investigating unexpected behavior in cancellation/recovery flows, check whether SOD issuance is properly configured.

### The date fields use a split year/month/day pattern

The end date is stored as three separate fields (`use_endymd_year`, `use_endymd_mon`, `use_endymd_day`) in the bean, but assembled into a single `YYYYMMDD` string when sent to the AP service via `USE_ENDYMD`. The display fields (`DSP_ENDYMD`) are separate and may use different data sources (e.g., the reservation cancel service data for the display end date, as added in IT2-2013-0000223).

### Framework conventions

- All beans implement `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`, which requires `loadModelData()`, `storeModelData()`, `typeModelData()`, and `listKoumokuIds()` methods.
- The `*DBean` classes use string-based field lookups via `loadModelData()` / `storeModelData()` rather than direct field access. This is the framework's reflection-based data binding pattern.
- The `KKW03204SFBean` constructor initializes all list beans. The customer contract list and operations service list each initialize with capacity 1; the discontinuation reason and aging info lists start empty.