# Eo / Web / Webview / Kkw22301sf

## Overview

This module implements the **Set Discount Registration screen** (セット割登録画面) — a web page where operators can search for customer contracts by service contract number, mineo receipt number, or electricity receipt number, then register, cancel, or mark as ineligible discount campaigns (セット割, i.e., bundled service discounts) tied to those contracts. It is part of the K-Opticom contract management system and follows the X31/X33 web framework pattern used across the `eo.web.webview` package.

The screen supports four primary actions:

- **Initial display** — loads customer contract lists, existing discount campaigns, and search target code tables.
- **Availability check** (可否チェック) — validates whether a campaign can be applied to the selected contract.
- **Registration** (登録) — registers a new discount campaign association.
- **Ineligibility** (照査NG) — marks a campaign as ineligible (e.g., for email mailing suppression).
- **Cancellation** (解除) — removes an existing campaign association.

---

## Key Classes and Interfaces

### [KKW22301SFLogic](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SFLogic.java)

**Role:** The central screen business logic class. Extends `JCCWebBusinessLogic` and orchestrates all screen operations — initial display, availability checks, registration, ineligibility, and cancellation.

This class is the entry point from the JSP view (`KKW223010PJP.jsp`) and the primary point where server-side service calls are invoked. It maps screen actions to specific EJB business operations via data mappers.

#### Key methods

| Method | Purpose |
|---|---|
| `actionInit()` | Initial screen display. Calls `KKSV0910` to fetch customer contract list, campaign list, search target code list, and service form info. Sets up pulldown lists and error messages. |
| `executeKhChk()` | Availability check button handler. Validates the search key format (mineo receipt = 10 digits, mineo phone = 11 or 14 digits, electricity receipt = 10 digits), then calls `KKSV0913` to check if a campaign can be applied. Activates or deactivates the Registration and Ineligibility buttons based on results. |
| `actionAdd()` | Registration button handler. Validates that the search target, search key, and campaign code haven't changed since the availability check (anti-tampering), then calls `KKSV0914` to register the campaign. On success, clears the form via `clearBean()`. |
| `actionShosaNg()` | Ineligibility (照査NG) button handler. Validates that at least one email send target (EO or mineo) is selected, then calls `KKSV0915` to mark the campaign as ineligible. |
| `actionRls()` | Cancellation (解除) button handler. Validates search key format, then checks that the entered campaign code matches an active campaign in the campaign list. Calls `KKSV0916` to cancel the registration. |
| `searchWribCampaignCdAjax()` | Ajax handler for fetching campaign names as the user types a campaign code. Uses `KKSV0912` (user master lookup) internally. Requires at least 8 characters in the campaign code. |
| `clearBean()` | Resets all set discount fields to default values and re-invokes `actionInit()` to return the form to its initial state. |

#### Service mappings

The logic class maps to six backend operations:

| Mapper | Use Case ID | Operation ID | Purpose |
|---|---|---|---|
| `KKSV0910` | `UCID_KKSV0910` | `OPID_KKSV0910OP` | Initial display — fetch all master data |
| `KKSV0912` | `UCID_KKSV0912` | `OPID_KKSV0912OP` | Campaign name lookup (Ajax) |
| `KKSV0913` | `UCID_KKSV0913` | `OPID_KKSV0913OP` | Availability check |
| `KKSV0914` | `UCID_KKSV0914` | `OPID_KKSV0914OP` | Registration |
| `KKSV0915` | `UCID_KKSV0915` | `OPID_KKSV0915OP` | Ineligibility |
| `KKSV0916` | `UCID_KKSV0916` | `OPID_KKSV0916OP` | Cancellation |

---

### [KKW22301SFBean](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SFBean.java)

**Role:** The main screen data bean (Service Form Bean). Extends `X33VViewBaseBean` and implements `X33VListedBeanInterface`, `X31CBaseBean`, and `Serializable`.

This bean holds the entire screen's state — search criteria, customer contract lists, campaign lists, and all set discount information fields. It is configured in `WEBGAMEN_KKW223010PJP.xml` and passed to the JSP view.

#### Major field groups

| Group | Description |
|---|---|
| `cust_kei_hktgi_list_list` | Customer contract continuation list (holds `KKW22301SF01DBean` rows) |
| `campaign_icrn_list` | Active discount campaign list (holds `KKW22301SF02DBean` rows) |
| `search_trgt_info_list` | Search target code list (holds `KKW22301SF03DBean` rows) |
| `keisha_ad_cd_*` | Contractor address code |
| `kaisen_place_ad_cd_*` | Line location address code |
| `svc_kei_kaisen_ucwk_no_*` | Service contract line-internal line number |
| `search_trgt_*` / `search_key_*` | Search criteria (target + key) |
| `wrib_campaign_cd_*` / `wrib_campaign_cd_nm_*` | Input campaign code and its display name |
| `taihi_*` | Suppressed (退避) copies of search fields, used to detect form tampering between availability check and registration |
| `add_btn_kassei_ctrl_flg_*` / `shosa_ng_btn_kassei_ctrl_flg_*` | Button enable/disable flags |
| `eo_ml_send1` / `eo_ml_send2` / `mineo_ml_send1` / `mineo_ml_send2` | Email mailing targets (EO contract / mineo contract) |
| `svc_cd_*` | Service code (added for eo net × mineo set discount, ANK-3521-00-00) |

Each data field follows a consistent four-property pattern: `_update`, `_value`, `_enabled`, `_state` — controlling whether the field was modified, its current value, editability, and display state (e.g., error highlighting).

---

### [KKW22301SF01DBean](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SF01DBean.java)

**Role:** Row bean for the **Customer Contract Continuation List** (顧客契約引継リスト). Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

Each row represents a customer contract line and contains:

| Field | Description |
|---|---|
| `svc_kei_no` | Service contract number |
| `sysid` | SYSID |
| `seiky_kei_no` | Billing contract number |
| `index` | Row index |

Uses `loadModelData(key, subkey)` to map Japanese field names (e.g., "契約者住所コード") to actual properties, and `storeModelData()` to write values back. This enables the X33 framework's data binding to work with localized field names.

---

### [KKW22301SF02DBean](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SF02DBean.java)

**Role:** Row bean for the **Campaign List** (キャンペーン一覧). Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

Each row represents an active discount campaign with:

| Field | Description |
|---|---|
| `dsp_campaign_cd` | Display campaign code |
| `wrib_svc_nm` | Discount service name |
| `svc_sta_ymd` | Service start date |
| `svc_endymd` | Service end date |
| `mskm_ymd` | Application date |
| `knrn_svc_kei_no` | Related customer ID (added in ANK-3521-00-00) |
| `status_nm` | Status name (added in ANK-4195-00-00) |
| `wrib_staymd` | Discount start date (added in ANK-4195-00-00) |
| `wrib_endymd` | Discount end date (added in ANK-4195-00-00) |
| `wrib_shin_route_nm` | Set discount application route name (added in ANK-4195-00-00) |
| `wrib_trgt_div` | Set discount target division (added in ANK-4195-00-00) |
| `index` | Row index |

This is one of the most recently evolved beans due to the eo net × mineo set discount policy addition (ANK-4195-00-00, Jan 2022).

---

### [KKW22301SF03DBean](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SF03DBean.java)

**Role:** Row bean for the **Search Target List** (検索対象リスト). Implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

Each row represents a search target type (e.g., "mineo receipt number", "mineo phone number", "electricity receipt number") and contains:

| Field | Description |
|---|---|
| `index` | Row index (string, defaults to "0") |
| `cd_div_list_list` | Code list (list of `X33VDataTypeStringBean`) |
| `cd_div_nm_list_list` | Code name list |
| `nm_list_list` | Name list |

Includes list management methods: `addListDataInstance()`, `removeElementFromListData()`, and `clearListDataInstance()` for dynamically managing the search target rows.

---

### [KKW22301SFChecker](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SFChecker.java)

**Role:** GUI validation checker. Implements `X31SGuiCheckBase` and holds a reference to the `KKW22301SFLogic` business logic.

Currently, the `checkMethod()` implementation is minimal — it always returns `true`. The framework expects it to perform field-level GUI checks (e.g., format validation, required-field checks) before the screen logic processes the action. The `bl` field is set via constructor injection.

---

### [KKW22301SFConst](source/koptWebB/src/eo/web/webview/KKW22301SF/KKW22301SFConst.java)

**Role:** Constant definitions for all field names, labels, and UI identifiers used across the module.

Key constant categories:

- **Search criteria:** `SEARCH_TRGT`, `SEARCH_KEY`, `SEARCH_TRGT_INFO`
- **Campaign codes:** `WRIB_CAMPAIGN_CD`, `WRIB_CAMPAIGN_CD_NM`, `CAMPAIGN_ICRN`
- **Set discount info:** `WRIB_SVC_KEI_NO`, `WRIB_SYSID`, `WRIB_SEIKY_KEI_NO`, `WRIB_KEISHA_AD_CD`, `WRIB_KAISEN_PLACE_AD_CD`
- **Button control flags:** `ADD_BTN_KASSEI_CTRL_FLG`, `SHOSA_NG_BTN_KASSEI_CTRL_FLG`
- **Email mailing targets:** `EO_ML_SEND1`, `EO_ML_SEND2`, `MINEO_ML_SEND1`, `MINEO_ML_SEND2`
- **Suppression fields (退避):** `TAHI_SEARCH_TRGT`, `TAHI_SEARCH_KEY`, `TAHI_WRIB_CAMPAIGN_CD` — copies stored during availability check to detect form tampering
- **List row keys:** `SVC_KEI_NO_01`, `SYSID_01`, `SEIKY_KEI_NO_01` for 01DBean; `DSP_CAMPAIGN_CD_02`, etc. for 02DBean; `INDEX_03`, `CD_DIV_LIST_03` for 03DBean

---

## How It Works

### Typical user flow

```mermaid
flowchart TD
    A[User opens screen] --> B[actionInit]
    B --> C[Call KKSV0910 OP]
    C --> D[Populate customer contract list]
    C --> E[Populate search target code list]
    C --> F[Populate active campaign list]
    F --> G[Display screen with search form]
    G --> H[User selects search target & enters key]
    H --> I[User selects campaign code]
    I --> J[User clicks Availability Check]
    J --> K[executeKhChk]
    K --> L[Validate search key format]
    L --> M[Call KKSV0913 OP]
    M --> N{Result?}
    N -->|"OK"| O[Activate Registration btn]
    N -->|"ineligible"| P[Activate Ineligibility btn]
    N -->|"error"| Q[Show error message]
    O --> R[User clicks Registration]
    P --> S[User clicks Ineligibility]
    R --> T[actionAdd: Validate no tampering]
    T --> U[Call KKSV0914 OP]
    U --> V[Success message, clear form]
    S --> W[actionShosaNg: Validate email target]
    W --> X[Call KKSV0915 OP]
    X --> Y[Success message, clear form]
    Z[User opens screen again] --> AA[User finds existing campaign]
    AA --> AB[User clicks Cancellation]
    AB --> AC[actionRls: Verify campaign active]
    AC --> AD[Call KKSV0916 OP]
    AD --> AE[Success message, clear form]
```

### Detailed operation traces

#### 1. Initial Display (`actionInit`)

1. Retrieves the common info bean and service form bean from the request context.
2. Calls `JCCWebCommon.getScreenInfo()` to fetch screen configuration.
3. Creates `KKSV0910_KKSV0910OPDBMapper` and sets up input parameters via multiple mapper methods (`setKKSV091001SC` through `setKKSV091007CC`), including operation date and operation date-time stamp.
4. Invokes the service via `invokeService(paramMap, inputMap, outputMap)`.
5. Processes the output: checks for error code `KKSV091007CC` and sets appropriate error messages if the discount information retrieval failed.
6. Sets up pulldown lists via `JKKWebCommon.setPulldownList()` for search targets.
7. The campaign list construction (`editWribCampaignList`) was commented out in ANK-3521-00-00, suggesting the campaign list is now populated differently.
8. Stores the screen ID and name in the common info bean.

#### 2. Availability Check (`executeKhChk`)

1. Reads the search target row from the `SEARCH_TRGT_INFO` data bean array, extracting the selected target code and its display name.
2. Copies these values into the "suppression" fields (`TAHI_SEARCH_TRGT`, `TAHI_SEARCH_KEY`, `TAHI_WRIB_CAMPAIGN_CD`) — these serve as a cryptographic-style integrity check to ensure the user hasn't changed the search criteria between the availability check and registration.
3. Validates the search key format based on the selected target:
   - Code "1" (mineo receipt): exactly 10 digits
   - Code "2" (mineo phone): 11 or 14 digits (updated in ANK-4068-00-00 for the 14-digit format)
   - Code "3" (electricity receipt): exactly 10 digits
4. Calls `KKSV0913_KKSV0913OPDBMapper` with the operation date-time stamp.
5. Based on the result:
   - `RSLT_CD_1` with `RSLT_SYSTEM_CD_000` → registration possible (activate Registration button, deactivate Ineligibility)
   - Normal result but not `RSLT_CD_1` → registration not possible (deactivate Registration, activate Ineligibility)
   - System error `RSLT_SYSTEM_CD_500` → same as above, with different message
   - Other errors → both buttons deactivated, system error message

#### 3. Registration (`actionAdd`)

1. Reads and stores the current search criteria into the suppression fields (consistent with `executeKhChk`).
2. Validates that the suppression values match the current input — if any mismatch occurred, the Registration button is deactivated and a "re-enter" error is shown for each mismatched field.
3. If the campaign code is empty, clears the campaign name field.
4. Calls `KKSV0914_KKSV0914OPDBMapper` to register.
5. On success (`RSLT_CD_0`): shows "registered" message. On system error: shows "registration failed". On other errors: shows system error message.
6. Calls `clearBean()` to reset all form fields.

#### 4. Ineligibility (`actionShosaNg`)

1. Validates that at least one email mailing target (`eo_ml_send1` or `mineo_ml_send1`) is checked.
2. Performs the same suppression field tampering check as registration.
3. Calls `KKSV0915_KKSV0915OPDBMapper` to mark the campaign as ineligible.
4. On result code `E01`: shows error message. Otherwise: success.
5. Calls `clearBean()`.

#### 5. Cancellation (`actionRls`)

1. Validates the search key format (same rules as availability check).
2. Performs a related-campaign check: iterates through the displayed `campaign_icrn_list` and verifies the entered campaign code matches an active campaign.
3. Calls `KKSV0916_KKSV0916OPDBMapper` to cancel.
4. On success: shows "cancelled" message. On system error: shows "cancellation failed". Otherwise: system error.
5. Calls `clearBean()`.

---

## Data Model

### Screen-level data flow

```mermaid
flowchart TD
    JSP["KKW223010PJP.jsp"] -->|"reads/writes"| Bean["KKW22301SFBean<br/>(Service Form Bean)"]
    Bean -->|"contains list of"| Row01["KKW22301SF01DBean<br/>(Contract rows)"]
    Bean -->|"contains list of"| Row02["KKW22301SF02DBean<br/>(Campaign rows)"]
    Bean -->|"contains list of"| Row03["KKW22301SF03DBean<br/>(Search target rows)"]
    Bean -->|"uses"| Logic["KKW22301SFLogic<br/>(Business Logic)"]
    Logic -->|"uses"| Const["KKW22301SFConst<br/>(Field keys)"]
    Logic -->|"maps to"| Mapper1["KKSV0910<br/>OPDBMapper"]
    Logic -->|"maps to"| Mapper2["KKSV0913<br/>OPDBMapper"]
    Logic -->|"maps to"| Mapper3["KKSV0914<br/>OPDBMapper"]
    Logic -->|"maps to"| Mapper4["KKSV0915<br/>OPDBMapper"]
    Logic -->|"maps to"| Mapper5["KKSV0916<br/>OPDBMapper"]
    Logic -->|"maps to"| Mapper6["KKSV0912<br/>OPDBMapper"]
```

### Bean field pattern

Every data field in the beans follows a four-property convention:

| Property | Type | Purpose |
|---|---|---|
| `*_update` | String | Tracks whether the field was modified during the current request |
| `*_value` | String / Boolean | Current value of the field |
| `*_enabled` | Boolean | Whether the field is editable on the screen |
| `*_state` | String | Display state (e.g., error indicators) |

This pattern allows the view layer to control field interactivity and display without server-side logic.

### List data beans

Three list-type fields on the main bean hold collections of typed row beans:

- `cust_kei_hktgi_list_list` → `ArrayList<KKW22301SF01DBean>` — populated with 1 initial row on construction
- `campaign_icrn_list` → `ArrayList<KKW22301SF02DBean>` — populated dynamically from service results
- `search_trgt_info_list` → `ArrayList<KKW22301SF03DBean>` — populated with 1 initial row on construction

---

## Dependencies and Integration

### Outbound dependencies

The module depends on these packages:

| Package | Purpose |
|---|---|
| `eo.ejb.cbs.mainproc` | Backend business operations (via mappers) |
| `eo.web.webview.KKA17601SF`, `KKA14701SF`, etc. | Other web view modules (likely called via screen navigation) |
| `eo.web.webview.mapping.*` | Data mappers for KKSV0910 through KKSV0916 operations |
| `eo.common.constant` | System constants (`JPCModelConstant`, `JPCOnlineMessageConstant`) |
| `eo.web.webview.common` | Shared utilities (`JCCWebCommon`, `JKKWebCommon`, `CommonInfoCFConst`) |
| `eo.business.common` | Business common utilities |
| `com.fujitsu.futurity.bp.custom.common` | Framework custom classes |

### Framework integration

- **Web framework:** Fujitsu's X31/X33 web framework (`com.fujitsu.futurity.web.x31`, `x33`)
- **Inheritance:** `KKW22301SFLogic` extends `JCCWebBusinessLogic`, which extends `X31BBusinessLogic`
- **Bean framework:** `KKW22301SFBean` extends `X33VViewBaseBean`, implementing `X33VListedBeanInterface` and `X31CBaseBean`
- **GUI checking:** `KKW22301SFChecker` implements `X31SGuiCheckBase`
- **Service invocation:** All backend calls go through `invokeService()` inherited from the base logic class

### Configuration files

| XML Config | References |
|---|---|
| `WEBGAMEN_KKW223010PJP.xml` | `KKW22301SFBean`, `KKW22301SFLogic` |
| `x31business_logic_KKW22301SF.xml` | `KKW22301SFLogic` |

---

## Notes for Developers

### Key constants to remember

- **Screen ID:** `JKKScreenConst.SCREEN_ID_KKW22301`
- **UCID:** `JKKCommonConst.UCID_KKSV0910` (and corresponding 0913–0916 for each action)
- **Operation date:** Retrieved via `JCCWebCommon.getOpeDate()` — used for KKSV0910 initial display
- **Operation date-time stamp:** Retrieved via `JCCWebCommon.getOpeDateTimeStamp()` — used for KKSV0913, KKSV0914, KKSV0916

### Search key validation rules

| Search target code | Field name | Length |
|---|---|---|
| `1` | mineo receipt number (mineo受領番号) | 10 digits |
| `2` | mineo phone number (mineo電話番号) | 11 or 14 digits |
| `3` | electricity receipt number (電気受領番号) | 10 digits |

### Button lifecycle

- By default, both the **Registration** and **Ineligibility** buttons are active.
- After a successful availability check returning `RSLT_CD_1`: Registration activates, Ineligibility deactivates.
- After a non-positive availability check: Registration deactivates, Ineligibility activates.
- After cancellation or registration: `clearBean()` resets both buttons to active.

### Anti-tampering mechanism

The module copies search criteria into "suppression" (退避) fields during `executeKhChk()`. Before registration or ineligibility actions, it compares these copies against the current values. If they differ, it means the user modified the form after the availability check — the action is rejected with a "re-enter" error. This prevents race conditions where the availability check result no longer applies to the submitted data.

### Version history highlights

- **v38.00.00 (Jun 2018):** Initial creation — ANK-3436-00-00 mineo set discount
- **v38.00.04 (Jul 2018):** IT1-2018-0000126
- **v38.00.05 (Aug 2018):** ST-2018-0000031 — fixed display of set discount info for already-cancelled campaigns
- **v40.00.00 (Dec 2018):** ANK-3521-00-00 — added set discount reference function, added service code field
- **v54.00.00 (Oct 2021):** ANK-4068-00-00 — IBUKI: 14-digit number support (updated phone number validation to accept 14 digits)
- **ANK-4195-00-00 (Jan 2022):** eo net × mineo set discount policy start — added new fields to 02DBean for discount start/end dates, status name, application route, and target division

### Extension points

- **Adding new search targets:** Update the validation logic in `executeKhChk()` and `actionRls()` to handle the new target code. Add entries to the search target code table.
- **Adding new campaign fields:** Add four-property sets (`*_update`, `*_value`, `*_enabled`, `*_state`) to `KKW22301SFBean` and `KKW22301SF02DBean`, and add corresponding constants to `KKW22301SFConst`.
- **New backend operation:** Create a new mapper class following the `KKSV09XX` naming convention, add a new method in `KKW22301SFLogic`, and wire up the UCID/OPID in the operation map.