# Eo / Web / Webview / Kkw14901sf

## Overview

The `KKW14901SF` module is the view logic for the **"Banpo-nashi Bango Jizen Tsuuchi Ichiran" (Proactive Notification for Unregistered Phone Numbers)** screen. It provides a search-and-display interface that lists proactive notification records, allowing operators to filter, sort, and navigate into detail/edit screens. It also launches background jobs for data extraction (data pull) and Yamato mail transmission. This module sits in the web layer of the contract management system and follows the standard X31/X33 web framework patterns used across the codebase.

## Key Classes and Interfaces

### [KKW14901SFLogic](source/koptWebB/src/eo/web/webview/KKW14901SF/KKW14901SFLogic.java) — Central View Logic

This is the core controller class for the screen, extending `JCCWebBusinessLogic`. It handles all user-facing actions: initial display, search, paging, sorting, data extraction, Yamato mail transmission, and navigation to child screens.

**Key methods:**

- **`actionInit()`** — Screen initialization entry point. It retrieves screen info, initializes search items, invokes the `KKSV0694` service to fetch the initial display data (a mapped query for the search condition screen), configures pulldown lists and checkbox selections, and conditionally enables or disables the "Back" button depending on the calling screen. After a search flag is detected, it also runs the search flow and maps results into the bean.

- **`actionSearch()`** — Executes a search against the proactive notification list. It copies search condition fields (SYSID, service contract number, date range, application number, customer name, send exclusion flag, "unsent" flag) into their `SEARCH_*` equivalents, resets sort fields, then delegates to `execSearch()`.

- **`actionPaging()`** — Handles pagination. It preserves the sort information but resets the selection fields and re-executes the search with the updated page position.

- **`actionSortAsc()` / `actionSortDesc()`** — Execute sort operations in ascending or descending order. Both set the sort field (`ORDER_TYPE`), then call `execSearch()`. They also clear the selection and receipt number to avoid stale state.

- **`actionClear()`** — Clears all search fields, resets pulldown and checkbox defaults, hides the list display area, and resets the list data.

- **`actionReHakkoCopy()`** — Re-issue (copy) mode. Validates that the selected row has a non-blank send timestamp (returning error `EKB0930_NW` if not), then transfers all context info to the detail screen (`KKW14902SF`) in re-issue mode.

- **`actionShokaiDtl()`** — View-only detail access. Transfers context info to `KKW14902SF` in inquiry mode (`SENHI_MODE_SHOKAI`).

- **`actionUpdDtl()`** — Edit mode detail access. Checks that the selected row has no send timestamp (returning error `EKB0930_NW` if already sent), then transfers context to `KKW14902SF` in update mode (`SENHI_MODE_UPD`).

- **`actionDchs()`** — Data extraction job. Invokes service `KKSV0696` (`EO22V0510J0` job ID) to run the proactive notification data extraction batch. Handles errors for "extraction batch in progress" and "send batch in progress."

- **`actionSend()`** — Yamato mail send job. Invokes service `KKSV0697` (`EO22V0110J0` job ID) to transmit unsent proactive notification records. Returns errors for "no unsent data," "extraction batch in progress," and "send batch in progress."

- **`actionYoksiAdd()`** — Navigation to the suppression number registration screen (`KKW14905SF`). Sets screen context and back-source mapping.

- **`actionBack()`** — Returns to the calling screen using the stored screen ID.

- **`execSearch(X31SDataBeanAccess bean)`** — Internal method that orchestrates a search. Validates that at least one search condition is provided (error `EKB0410_NW` if not), invokes `KKSV0695` service, maps results, and runs `afterSearch()`.

- **`afterSearch(X31SDataBeanAccess bean, HashMap<String, Object> outputMap)`** — Post-search processing. Checks for search error flags (zero results, over-max results, no data for current page), applies pagination data, sets `LIST_DISP_FLG` to true, restores the previously selected receipt number if it still exists in results, and alternates row styles between `odd` and `even`.

- **`setParamAndSeniKKW14902(String seniMode)`** — Sets up screen inheritance context for navigation to the detail screen (`KKW14902SF`). Stores search context for the current screen and passes the selected row's receipt number and mode to the target screen. Also configures back-source IDs based on the mode.

- **`invokeService(String usecase_id, String operation_id, HashMap<String, Object> inputMap)`** — Generic service invocation helper. Sets up the `paramMap` with usecase and operation IDs, initializes the message result list, and delegates to the parent's `invokeService()`.

### [KKW14901SFBean](source/koptWebB/src/eo/web/webview/KKW14901SF/KKW14901SFBean.java) — Form Data Bean

This bean holds all form data for the screen. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface` and `X31CBaseBean`. Each field follows a standard four-property pattern: `_update`, `_value`, `_enabled`, and `_state` — representing field lifecycle state, the actual value, editability, and validation display state respectively.

**Key properties:**

| Property Group | Fields | Purpose |
|---|---|---|
| **Search conditions** | `sysid`, `svc_kei_no`, `data_chsht_year_from/mon_from/day_from`, `data_chsht_year_to/mon_to/day_to`, `mskmsho_no`, `cust_nm` | Search input fields for filtering the list |
| **Search results** | `search_sysid`, `search_svc_kei_no`, `search_data_chshtymd_from/to`, `search_mskmsho_no`, `search_cust_nm`, `search_send_jgi_flg`, `search_mi_send` | Mapped search conditions from the service |
| **List data** | `bmpnonnopretchi_list_list` | List of proactive notification records (type `X33VDataTypeList`), each row is a `KKW14901SF02DBean` |
| **Send exclusion** | `send_jgi_info_list` | Pulldown selection for send exclusion flag (type `X33VDataTypeList`), each row is a `KKW14901SF01DBean` |
| **Controls** | `mi_send` (boolean), `search_flg`, `list_disp_flg`, `bmpnonnopretchi_choice`, `rtn_btn_disp_flg` | Selection indicator, search flag, list display toggle, row selection, back-button visibility |
| **Sort** | `sort_num`, `order_num`, `order_type` | Sort configuration fields |
| **Details** | `kanuoreso_hakko_no` | Selected receipt number for navigation |

**Constructor behavior:** Initializes the `send_jgi_info_list` with one `KKW14901SF01DBean` instance and creates an empty `bmpnonnopretchi_list_list`.

### [KKW14901SF01DBean](source/koptWebB/src/eo/web/webview/KKW14901SF/KKW14901SF01DBean.java) — Send Exclusion Row Data

A listed data bean representing a single row in the "Send Exclusion Information" pulldown. It implements `X33VDataTypeBeanInterface` and `X33VListedBeanInterface`.

**Key properties:**

| Property | Type | Purpose |
|---|---|---|
| `cd_div_list_list` | `X33VDataTypeList` | List of send exclusion codes (string values) |
| `cd_div_nm_list_list` | `X33VDataTypeList` | List of send exclusion labels (display names) |
| `index` | `int` | Selected row index in the pulldown |

**Key methods:**

- **`getJsflist_cd_div_list()`** — Converts the `cd_div_list_list` into an `ArrayList<SelectItem>` for JSF rendering. Iterates through each element, extracts the string value, and creates a `SelectItem` with the index as value and the extracted string as label.

- **`getJsflist_cd_div_nm_list()`** — Same as above but for the `cd_div_nm_list_list` (display names).

- **`loadModelData(String key, String subkey)`** — Key-value based data access method. Handles the "Index" key (returning `index_value`, `index_enabled`, or `index_state`), the "Code List" key (returning values at a given index from `cd_div_list_list`), and the "Code Name List" key (returning values from `cd_div_nm_list_list`). Supports the wildcard `*` to return the list size.

- **`typeModelData(String key, String subkey)`** — Returns the `Class<?>` for a given key/subkey combination, enabling type-safe deserialization of the bean's data.

- **`addListDataInstance(String key)`** — Creates a new list element instance and returns its index.

- **`removeElementFromListData(String key, int index)`** — Removes an element at the given index.

- **`clearListDataInstance(String key)`** — Clears all elements in a list.

- **`listKoumokuIds()`** — Returns the list of property names for this bean, used by the framework for serialization/deserialization.

### [KKW14901SF02DBean](source/koptWebB/src/eo/web/webview/KKW14901SF/KKW14901SF02DBean.java) — List Row Detail Data

A listed data bean representing a single row in the proactive notification list. It implements `X33VDataTypeBeanInterface`, `X33VListedBeanInterface`, and `Serializable`.

**Key properties:**

| Property | Type | Purpose |
|---|---|---|
| `kanuoreso_hakko_no_value` | `String` | Receipt number (internal ID) for the record |
| `sysid_value` | `String` | System ID |
| `svc_kei_no_value` | `String` | Service contract number |
| `mskmsho_no_value` | `String` | Application number |
| `cust_nm_value` | `String` | Customer name (kanji) |
| `telno_1_value`, `telno_2_value` | `String` | Phone numbers 1 and 2 |
| `data_chsht_dtm_value` | `String` | Data extraction datetime |
| `send_dtm_value` | `String` | Send datetime (empty = not yet sent) |
| `upd_dtm_value` | `String` | Update datetime |
| `row_style_value` | `String` | CSS row style (`odd` or `even`) |

Each property follows the standard `_update` / `_value` / `_enabled` / `_state` four-part naming pattern.

**Key methods:**

- **`loadModelData(String key, String subkey)`** — Implements the key-value access pattern. Maps each property (e.g., "Receipt Number", "System ID", "Service Contract Number", "Phone No. 1", "Phone No. 2", "Data Extraction Date/Time", "Send Date/Time", "Update Date/Time", "Row Style") to its `_value`, `_enabled`, `_state`, or `_update` getter/setter based on the subkey. Also handles the wildcard `*` to return the row index.

- **`storeModelData(...)`** — Multiple overloads for setting property values via key-value access. The four-argument version (`key, subkey, in_value, isSetAsString`) supports typed storage with string conversion.

- **`typeModelData(String key, String subkey)`** — Returns the expected type for each property (e.g., `String.class` for values, `Boolean.class` for enabled flags).

### [KKW14901SFChecker](source/koptWebB/src/eo/web/webview/KKW14901SF/KKW14901SFChecker.java) — GUI Validation

Implements the `X31SGuiCheckBase` interface. Receives a reference to the business logic class (`KKW14901SFLogic`) via constructor injection. The `checkMethod(X31SGuiCheckParam param, X31GUtilStockMessage errMsgStock)` method currently returns `true` unconditionally, acting as a pass-through placeholder where no custom client-side or server-side GUI validation is needed.

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

A utility class holding all string constants used across the module. Key categories:

| Category | Constants |
|---|---|
| **Search fields** | `SYSID`, `SVC_KEI_NO`, `DATA_CHSHT_YEAR_FROM/MON_FROM/DAY_FROM`, `DATA_CHSHT_YEAR_TO/MON_TO/DAY_TO`, `MSKMSHO_NO`, `CUST_NM` |
| **Search result fields** | `SEARCH_SYSID`, `SEARCH_SVC_KEI_NO`, `SEARCH_DATA_CHSHTYMD_FROM`, `SEARCH_DATA_CHSHTYMD_TO`, `SEARCH_MSKMSHO_NO`, `SEARCH_CUST_NM`, `SEARCH_SEND_JGI_FLG`, `SEARCH_MI_SEND` |
| **List row fields** | `SYSID_02`, `SVC_KEI_NO_02`, `MSKMSHO_NO_02`, `CUST_NM_02`, `TELNO_1_02`, `TELNO_2_02`, `DATA_CHSHT_DTM_02`, `SEND_DTM_02`, `UPD_DTM_02`, `ROW_STYLE_02`, `KANUORESO_HAKKO_NO_02` |
| **Control flags** | `SEND_JGI_INFO`, `MI_SEND`, `SEND_JGI_CD`, `SORT_NUM`, `ORDER_NUM`, `ORDER_TYPE`, `SEARCH_FLG`, `LIST_DISP_FLG`, `BMPNONNOPRETCHI_CHOICE`, `BMPNONNOPRETCHI_LIST`, `RTN_BTN_DISP_FLG` |
| **Pulldown keys** | `INDEX_01`, `CD_DIV_LIST_01`, `CD_DIV_NM_LIST_01` |

## How It Works

### Main Flow: Initial Display

```mermaid
flowchart TD
    A["User accesses screen"] --> B["Controller calls actionInit()"]
    B --> C["getScreenInfo - retrieve screen metadata"]
    C --> D["clearSearchItem - reset search state"]
    D --> E["setBmpNonNoPreTchiReSearchCC - set up search condition connector"]
    E --> F["invokeService KKSV0694/KKSV0694OP"]
    F --> G["Map pulldown lists and checkbox selections"]
    G --> H["Set back-button visibility"]
    H --> I["Return to controller for rendering"]
```

1. The controller dispatches to `actionInit()`.
2. Screen info is retrieved, search items are cleared, and the initial data mapping is prepared.
3. The `KKSV0694` service (usecase `KKSV0694`, operation `KKSV0694OP`) is invoked to populate search condition data.
4. Pulldown lists (e.g., send exclusion information) are mapped into the bean via `setPulldownList()`.
5. The back-button visibility flag is set based on the calling screen.
6. The action returns `true`, and the framework renders the initial screen.

### Search Flow

```mermaid
sequenceDiagram
    participant User
    participant Controller
    participant Logic as KKW14901SFLogic
    participant Bean as KKW14901SFBean
    participant Mapper as KKSV0695 Mapper
    participant APService as AP Service

    User->>Controller: Search action
    Controller->>Logic: actionSearch()
    Logic->>Bean: get search conditions
    Logic->>Bean: map to SEARCH_* fields
    Logic->>Mapper: setBmpNonNoPreTchiReSearchCC()
    Logic->>APService: invokeService KKSV0695
    APService-->>Mapper: result
    Logic->>Mapper: getBmpNonNoPreTchiReSearchCC()
    Mapper-->>Logic: populated list
    Logic->>Bean: set list data
    Logic->>Bean: setListDispFlg(true)
    Logic-->>Controller: true
```

1. User submits the search form.
2. `actionSearch()` copies all search input fields to their `SEARCH_*` equivalents (e.g., `DATA_CHSHT_YEAR_FROM` + `MON_FROM` + `DAY_FROM` → `SEARCH_DATA_CHSHTYMD_FROM`).
3. `execSearch()` is called, which first checks if any search conditions were provided. If not, it returns an error message.
4. The `KKSV0695` service is invoked with the search conditions.
5. Results are mapped back into the bean via the mapper's `getBmpNonNoPreTchiReSearchCC()`.
6. `afterSearch()` validates search results (zero results, over-max limit), configures pagination, sets the list display flag, and alternates row styles.

### Navigation to Detail Screen

1. User selects a row from the list (`BMPNONNOPRETCHI_CHOICE` holds the index).
2. The user clicks a detail action button (Re-issue, View Detail, or Edit).
3. The corresponding `actionReHakkoCopy()`, `actionShokaiDtl()`, or `actionUpdDtl()` method is called.
4. `setParamAndSeniKKW14902(seniMode)` is invoked:
   - Retrieves the selected row's receipt number (`kanuoreso_no`).
   - Builds `dataMapMe` (current screen context — all search conditions) and `dataMapNext` (next screen context — mode and receipt number).
   - Sets screen info for both the current and target screens.
   - Configures back-source screen IDs.
5. The framework renders the target screen (`KKW14902SF`).

### Data Extraction / Yamato Send Jobs

Both `actionDchs()` and `actionSend()` follow a similar pattern:

1. Prepare the mapper and input map.
2. Set up service connectors via mapper `setKKSV*SC()` methods.
3. Invoke the respective AP service (`KKSV0696` for data extraction, `KKSV0697` for Yamato send).
4. Evaluate the result using `getKKSV0696Result()` or `getKKSV0697Result()`.
5. Display an appropriate message based on the result code (success, extraction batch in progress, send batch in progress, no unsent data).

## Data Model

The module uses a layered bean architecture typical of the X31/X33 framework:

```mermaid
flowchart LR
    A["KKW14901SFBean<br/>(Form Bean)"] --> B["send_jgi_info_list"]
    A --> C["bmpnonnopretchi_list_list"]
    B --> D["KKW14901SF01DBean<br/>(Pulldown row)"]
    C --> E["KKW14901SF02DBean<br/>(List row)"]
    D --> F["cd_div_list_list<br/>/cd_div_nm_list_list"]
    E --> G["Row properties:<br/>kanuoreso_hakko_no, sysid,<br/>svc_kei_no, mskmsho_no,<br/>cust_nm, telno_1/2,<br/>data_chsht_dtm, send_dtm,<br/>upd_dtm, row_style"]
```

- **`KKW14901SFBean`** is the top-level form bean containing both the search condition fields and the result lists.
- **`bmpnonnopretchi_list_list`** holds `X33VDataTypeList` entries of type `KKW14901SF02DBean`, one per row in the search results.
- **`send_jgi_info_list`** holds `X33VDataTypeList` entries of type `KKW14901SF01DBean`, representing the send exclusion pulldown options.
- Each **`KKW14901SF02DBean`** row contains all fields needed for display in the list (receipt number, system ID, customer info, dates, row style).

### Property Pattern

Every field in the beans follows the `_update` / `_value` / `_enabled` / `_state` convention:

| Suffix | Meaning |
|---|---|
| `_update` | Field lifecycle/update state flag (framework-managed) |
| `_value` | The actual data value |
| `_enabled` | Whether the field is editable (`Boolean`) |
| `_state` | Validation/display state (e.g., error styling) |

This pattern is used consistently across all three bean classes.

## Dependencies and Integration

### Inbound Dependencies (who uses this module)

- **`WEBGAMEN_KKW149010PJP.xml`** — The web page mapping config that references `KKW14901SFBean` and `KKW14901SFLogic`, wiring them to the HTTP request handler.
- **`x31business_logic_KKW14901SF.xml`** — The business logic configuration referencing `KKW14901SFLogic`.

### Service Integrations

The module invokes four AP services through mapper classes:

| Service | Operation | Mapper | Purpose |
|---|---|---|---|
| `KKSV0694` | `KKSV0694OP` | `KKSV0694_KKSV0694OPDBMapper` | Initial display — maps search condition data |
| `KKSV0695` | `KKSV0695OP` | `KKSV0695_KKSV0695OPDBMapper` | Search — retrieves proactive notification records |
| `KKSV0696` | `KKSV0696OP` | `KKSV0696_KKSV0696OPDBMapper` | Data extraction — launches batch job `EO22V0510J0` |
| `KKSV0697` | `KKSV0697OP` | `KKSV0697_KKSV0697OPDBMapper` | Yamato send — launches batch job `EO22V0110J0` |

### Cross-Module Relationships

This module connects to several other screens:

| Module | Relationship |
|---|---|
| `KKW14902SF` | Navigates to/from the proactive notification detail screen (view, edit, re-issue modes) |
| `KKW14905SF` | Navigates to the suppression number registration screen |
| `KKA14901SF` | Related module in the same feature family |
| `KKA17401SF`, `KKA14401SF`, `KKA17201SF`, `KKA14201SF`, `KKA14701SF` | Related screens in the broader notification system |
| `CommonInfoCF` | Shared common info bean for cross-screen navigation |
| `FUW09905SF`, `FUW00162SF` | Shared service modules |
| `SCW00101SF` | Shared common utilities |
| `commonOneStop` | One-stop common module |
| `eo.business.common`, `eo.business.service` | Business layer services |
| `eo.ejb.cbs.mainproc`, `eo.ejb.common.edit` | EJB layer services |
| `eo.common.constant` | Shared constant definitions |
| `eo.web.webview.common` | Shared web view utilities |

### Framework Dependencies

- **X31/X33 Framework** (`com.fujitsu.futurity.web.x31.*`, `com.fujitsu.futurity.web.x33.*`) — Core web framework for bean management, GUI validation, and screen flow.
- **`JCCWebBusinessLogic`** — Abstract base class providing common web logic functionality (service invocation, screen info management, message handling).
- **`JSYwebLog`** (`com.fujitsu.futurity.common`) — Logging utility for data bean dumps and debug messages.

## Notes for Developers

### Bean Architecture

All beans follow the X33 data type pattern with key-value based access via `loadModelData()` and `storeModelData()`. When adding new fields:

1. Add the `_update`, `_value`, `_enabled`, `_state` properties to the bean class.
2. Add corresponding getter/setter methods.
3. Update `loadModelData()` to handle the new field's key.
4. Update `storeModelData()` for value storage.
5. Update `typeModelData()` for type resolution.
6. Update `listKoumokuIds()` to include the new field name.

### Screen Navigation

When navigating to another screen via `setParamAndSeniKKW14902()`:
- Always call `JCCWebCommon.setScreenInfo()` for both the current screen and target screen.
- Always call `JCCWebCommon.setScreenId()` to configure back-source mapping.
- The `commoninfoBean.NEXT_SCREEN_ID` must be set before returning from the action.

### Error Handling

The module uses `JCCWebCommon.setMessageInfo()` with specific message constant keys:
- `EKB0930_NW` — General warning/error (parameterized with context strings)
- `EKB0410_NW` — No search condition entered
- `EKB0330__I` — Zero search results
- `EKB0340__I` — Over maximum search limit
- `EKB0350__I` — No data on current page
- `EKB7950__I` — Informational success messages

### Search Validation

The `isSearchInput()` method concatenates all search fields and checks if the result is blank. This is the gate that prevents empty searches. Adding a new search field requires updating this method to include the new field.

### Row Styling

List rows are styled with alternating `odd` and `even` CSS classes (`ROW_STYLE_ODD` / `ROW_STYLE_EVEN`). This is set in `afterSearch()` by iterating through the result list and assigning styles based on index parity.

### Background Jobs

Data extraction (`actionDchs`) and Yamato send (`actionSend`) launch asynchronous batch jobs. The services return result codes that indicate success or specific batch-in-progress states. The UI provides user feedback but does not wait for job completion.

### v4.01 Screen Flow Change

In v4.01 (2012/10/05), back-button display logic was added. If the screen is accessed from the menu (`SCREEN_ID_ZMW06901`) or from a null/empty source, the back button is hidden. Otherwise, it is shown. This is controlled by the `RTN_BTN_DISP_FLG` constant.

### Diagram: Module Structure

```mermaid
flowchart TD
    A["KKW14901SFLogic<br/>View Logic"] --> B["KKW14901SFBean<br/>Form Bean"]
    A --> C["KKW14901SFChecker<br/>GUI Validation"]
    A --> D["KKW14901SFConst<br/>Constants"]
    A --> E["KKW14901SF01DBean<br/>List Row Data"]
    A --> F["KKW14901SF02DBean<br/>Detail Row Data"]
    B --> E
    A --> G["KKSV0694<br/>Initial Display Service"]
    A --> H["KKSV0695<br/>Search Service"]
    A --> I["KKSV0696<br/>Data Extraction Service"]
    A --> J["KKSV0697<br/>Yamato Send Service"]
    A --> K["KKW14902SF<br/>Detail Screen"]
    A --> L["KKW14905SF<br/>Yokisu Registration"]
    style A fill:#e1f5ff
    style G fill:#fff4e6
    style H fill:#fff4e6
    style I fill:#fff4e6
    style J fill:#fff4e6
    style K fill:#ffe6e6
    style L fill:#ffe6e6
```