# Eo / Web / Webview / Scw00401sf

## Overview

The `SCW00401SF` package is a web view module for **telephone VLAN-ID registration** within the K-Opticom "eo Customer Backbone System" (eo顧客基幹システム). It provides the full lifecycle of VLAN-ID management: a user searches for matching service contracts by contract number, reviews the resulting VLAN-ID records, confirms the data, and either registers or modifies them. The package follows the X31/X33 web framework pattern used throughout the eo application, with a dedicated logic class, form bean, detail row bean, constant definitions, and a GUI checker.

Three screens are involved in the workflow:

- **SCW00401** — Search screen (enter contract number, display results)
- **SCW00402** — Confirmation screen (review data before registration)
- **SCW00403** — Completion screen (display success message after registration)

This module communicates with back-end services via two database mappers (`SCSV0004` for search, `SCSV0005` for registration), making it a thin web-layer orchestrator that handles validation, UI state management, and navigation.

## Key Classes and Interfaces

### [SCW00401SFLogic](source/koptWebB/src/eo/web/webview/SCW00401SF/SCW00401SFLogic.java)

**Purpose:** The central business logic class for VLAN-ID registration. It extends `JCCWebBusinessLogic` and orchestrates every user action on the three screens.

**Key methods:**

| Method | Description |
|---|---|
| `init()` | Initializes the screen. Clears the service contract number holding area and sets the next screen to SCW00401 (search). |
| `search()` | Handles the search button click. Validates the service contract number via `chkItemValue1()`, clears the data bean, calls the `SCSV0004` mapper to query matching contracts, and returns an error message if zero results are found (message `EKB0330__I`). |
| `confirmCreate()` | Handles the registration confirmation button. Retrieves the first row of the detail list, runs business validations via `chkItemValue2()` and `chkItemValue3()`, calls the `SCSV0005` mapper in check mode (`FUNC_CD_4`), then navigates to SCW00402 with an info message "VLAN-ID の登録". |
| `fix()` | Handles the determination (fix) button. Calls `SCSV0005` in actual registration mode (`FUNC_CD_3`) and navigates to SCW00403 with a completion message `EKB0380__I`. |
| `modify()` | Navigates back to SCW00401 to allow the user to make changes. |
| `complete()` | Clears the service contract number and the detail list, then returns to the initial search screen (SCW00401). |
| `chkItemValue1()` | Validates that the service contract number is not empty. |
| `chkItemValue2()` | Validates business rules for registration: the contract must be for "eo光電話" (`eo_tel_flg = "1"`), and the SOD business collaboration status must not be in a "waiting" state (either `WAIT_RES` or `WAIT_FIN`). |
| `chkItemValue3()` | Validates that the telephone VLAN-ID field is not empty. |
| `clearDatabean()` | Private helper that clears the detail list array and adds a fresh empty row. |
| `setNextScreen()` | Private helper that sets the next screen ID and name in the common info bean. |

**Design notes:**
- Uses `invokeService()` from the parent `JCCWebBusinessLogic` to call back-end services `SCSV0004` and `SCSV0005`.
- Messages are set via `JCCWebCommon.setMessageInfo()` with standard message codes from `JPCOnlineMessageConstant`.
- Screen navigation is driven by `setNextScreen()` which writes to the `CommonInfoCF` common info bean.

### [SCW00401SFBean](source/koptWebB/src/eo/web/webview/SCW00401SF/SCW00401SFBean.java)

**Purpose:** The main form bean that carries all screen-level data between the UI and the logic layer. It implements `X33VViewBaseBean`, `X33VListedBeanInterface`, and `X31CBaseBean`, making it compatible with the X33 view framework and the X31 data bean access pattern.

**Important fields (grouped by purpose):**

**Search parameters:**
- `search_type_*` — Search processing parameter (update/value/enable/state)
- `max_search_num_*` — Maximum search result count
- `display_num_*` — Display item count per page
- `display_page_num_*` — Current display page number
- `total_search_num_*` — Total search result count
- `total_page_num_*` — Total page count
- `search_err_flg_*` — Search error flag

**Key contract:**
- `key_svc_kei_no_*` — KDDI service contract number (search key)
- `key_svc_kei_no_hoji_*` — KDDI service contract number holding (persisted across screens)

**Detail list:**
- `esc0021a010cbsmsg1list_list` — An `X33VDataTypeList` containing `SCW00401SF01DBean` rows. This represents the telephone VLAN-ID order list.

**Key methods:**
- **Constructor** — Initializes the `esc0021a010cbsmsg1list_list` with one empty `SCW00401SF01DBean` row.
- **`getJsflist_typelist_esc0021a010cbsmsg1list()`** — Returns an `ArrayList<SelectItem>` for rendering a dropdown/selection list from the detail bean rows.
- **`loadModelData(key, subkey)`** — Route-based data access method. Parses the key string (e.g., "表示件数" -> value/enable/state) and delegates to the appropriate getter. Supports `//` prefix for common info bean data. Handles the "all fields" `*/` wildcard pattern to return list size.
- **`storeModelData(...)`** — Mutating counterpart to `loadModelData`. Supports the same key routing plus an `isSetAsString` flag for Long-type fields.

### [SCW00401SF01DBean](source/koptWebB/src/eo/web/webview/SCW00401SF/SCW00401SF01DBean.java)

**Purpose:** The detail row bean for each entry in the telephone VLAN-ID order list. Every row displayed on the search/confirmation screens is an instance of this bean.

**Properties (each has `_update`, `_value`, `_enabled`, `_state` variants):**

| Field | Description |
|---|---|
| `sysid_*` | Contract number (契約者番号) |
| `cust_nm_*` | Contract name (契約者名) |
| `keisha_telno_*` | Contractor phone number (契約者電話番号) |
| `tel_vlan_id_*` | Telephone VLAN-ID (電話用VLAN-ID) — **key editable field** |
| `bas_host_id_*` | RAS host ID (RAS-ホストID) |
| `eo_tel_flg_*` | eo telephone flag (eo電話フラグ) — `"1"` means eo light phone contract |
| `sod_work_rnki_stat_*` | SOD business collaboration status (SOD業務連携ステータス) |
| `svc_cd_*` | Service code (サービスコード) |
| `svc_cd_nm_*` | Service code name (サービスコード名) |
| `svc_kei_stat_*` | Service contract status (サービス契約ステータス) |
| `svc_kei_stat_nm_*` | Service contract status name (サービス契約ステータス名) |
| `tel_vlan_order_stat_*` | Telephone VLAN order status (電話用VLAN-IDオ达斯ステータス) |
| `req_ji_mskmsho_no_*` | Request submission form number (依頼時申込書番号) |
| `req_ji_kjak_no_*` | Request work case number (依頼時工事件番号) |
| `index` | Row index within the list |

Each field follows the standard 4-part pattern:
- `_update` — Edit mode indicator
- `_value` — Current data value
- `_enabled` — Whether the field is editable on the UI
- `_state` — Visual state for rendering (e.g., error, warning)

**Key methods:**
- **`loadModelData(key, subkey)`** — Route-based data access that maps Japanese field names (e.g., "契約者番号", "電話用VLAN-ID") to the corresponding getter based on the subkey (`"value"`, `"enable"`, `"state"`).
- **`storeModelData(...)`** — Mutating counterpart for `loadModelData`, with three overloaded signatures for convenience.
- **`listKoumokuIds()`** — Returns an `ArrayList<String>` of all field names in this bean.
- **`typeModelData(key, subkey)`** — Returns the `Class<?>` type for a given field/subkey combination (used by the framework for type-safe binding).

### [SCW00401SFConst](source/koptWebB/src/eo/web/webview/SCW00401SF/SCW00401SFConst.java)

**Purpose:** A utility class holding all string constant keys used across the `SCW00401SF` module. It has a private constructor (instantiation is not allowed) and exposes only `public static final String` fields.

**Key constants:**

| Constant | Value | Used for |
|---|---|---|
| `KEY_SVC_KEI_NO` | "KDDIサービス契約番号" | Main search key |
| `KEY_SVC_KEI_NO_HOJI` | "KDDIサービス契約番号保持" | Cross-screen persistence |
| `ESC0021A010CBSMSG1LIST` | "電話用VLAN-IDオダ一覧" | Detail list key |
| `SYSID_01` | "契約者番号" | Row bean field key |
| `CUST_NM_01` | "契約者名" | Row bean field key |
| `TEL_VLAN_ID_01` | "電話用VLAN-ID" | The core editable field |
| `EO_TEL_FLG_01` | "eo電話フラグ" | Validation flag |
| `SOD_WORK_RNKI_STAT_01` | "SOD業務連携ステータス" | Validation field |

All other constants follow the same pattern, providing readable Japanese names for each row bean property.

### [SCW00401SFChecker](source/koptWebB/src/eo/web/webview/SCW00401SF/SCW00401SFChecker.java)

**Purpose:** Implements `X31SGuiCheckBase` to define GUI-level validation rules. Currently a **placeholder** — its `checkMethod()` always returns `true` without performing any checks. All business validation is handled within `SCW00401SFLogic`'s `chkItemValue*()` methods instead.

The checker holds a reference to the business logic class (`X31BBusinessLogic bl`) but does not use it in the current implementation.

## How It Works

### End-to-end workflow

```mermaid
flowchart TD
    UI["Web UI"] --> Logic["SCW00401SFLogic"]
    Logic --> Bean["SCW00401SFBean"]
    Bean --> DBean["SCW00401SF01DBean"]
    Bean --> DataList["X33VDataTypeList"]
    DataList --> DBean
    Logic --> Mapper1["SCSV0004 Mapper"]
    Logic --> Mapper2["SCSV0005 Mapper"]
    Mapper1 --> Service1["SCSV0004 SC Service"]
    Mapper2 --> Service2["SCSV0005 SC Service"]
    Logic --> Checker["SCW00401SFChecker"]
    Logic --> Const["SCW00401SFConst"]
```

### Step-by-step: Register a VLAN-ID

1. **Screen initialization** (`init()`)
   - The user navigates to SCW00401. The logic class clears the contract number holding area and directs the UI to the search screen.

2. **Search** (`search()`)
   - The user enters a KDDI service contract number and clicks the search button.
   - `chkItemValue1()` validates the contract number is non-empty.
   - `clearDatabean()` resets the detail list.
   - The contract number is stored in `KEY_SVC_KEI_NO_HOJI` for cross-screen persistence.
   - `SCSV0004_SCSV0004OPDBMapper` is called with use case `SCSV0004` to query matching contracts.
   - If zero results are found (`SEARCH_ERR_FLG_ZERO`), message `EKB0330__I` is displayed and the screen does not advance.
   - Otherwise, the data is populated into the bean and the screen stays on SCW00401 (showing results).

3. **Confirmation** (`confirmCreate()`)
   - The user clicks the registration confirmation button.
   - `chkItemValue2()` runs two business validations:
     - The `eo_tel_flg` must equal `"1"` (eo light phone contract).
     - The `sod_work_rnki_stat` must not be in a waiting state (both `WAIT_RES` and `WAIT_FIN` are blocked).
   - `chkItemValue3()` validates that the telephone VLAN-ID field is non-empty.
   - `SCSV0005_SCSV0005OPDBMapper` is called with `FUNC_CD_4` (pre-registration check mode).
   - On success, an info message "VLAN-ID の登録" is set and the screen advances to SCW00402 (confirmation screen).

4. **Determination** (`fix()`)
   - The user clicks the fix (確定) button on SCW00402.
   - `SCSV0005_SCSV0005OPDBMapper` is called with `FUNC_CD_3` (actual registration).
   - On success, message `EKB0380__I` is displayed and the screen advances to SCW00403 (completion screen).

5. **Completion** (`complete()`)
   - The user clicks the complete button on SCW00403.
   - The service contract number and holding area are cleared.
   - `clearDatabean()` resets the detail list.
   - The screen returns to SCW00401 (search screen).

6. **Modify** (`modify()`)
   - At any point before completion, the user can click the modify (修正) button to return to SCW00401 and edit the data.

### Data flow through the beans

```
                    +------------------+
                    |  SCW00401SFBean  |
                    |  (form / screen) |
                    +--------+---------+
                             |
              esc0021a010cbsmsg1list_list
                             |
                    +--------v---------+
                    | X33VDataTypeList |
                    +--------+---------+
                             | contains
                             v
              +---------------------------+
              | SCW00401SF01DBean (xN)   |
              | (detail row per VLAN-ID)  |
              +---------------------------+
              | sysid_value               |
              | cust_nm_value             |
              | tel_vlan_id_value (edit)  |
              | eo_tel_flg_value          |
              | sod_work_rnki_stat_value  |
              | svc_cd_value              |
              | ...                       |
              +---------------------------+
```

The framework binds UI fields to bean properties via the `loadModelData` / `storeModelData` methods, which route based on the field name (Japanese label) and subkey (`"value"`, `"enable"`, `"state"`).

## Data Model

### Search criteria

| Field | Type | Editable | Source |
|---|---|---|---|
| Service contract number (`KEY_SVC_KEI_NO`) | String | Yes (input) | User enters on search screen |
| Search processing parameter (`search_type`) | String | Yes | User selects search type |
| Maximum search count (`max_search_num`) | String | Yes | User sets page size |

### Result list (each row = `SCW00401SF01DBean`)

| Field | Description | Editable |
|---|---|---|
| Contract number (`sysid`) | Unique contract identifier | No (read-only) |
| Contract name (`cust_nm`) | Name of the contractor | No (read-only) |
| Contractor phone (`keisha_telno`) | Phone number | No (read-only) |
| Telephone VLAN-ID (`tel_vlan_id`) | **The VLAN-ID to register** | Yes (the core editable field) |
| RAS host ID (`bas_host_id`) | Network host identifier | No (read-only) |
| eo telephone flag (`eo_tel_flg`) | `"1"` = eo light phone contract | No (read-only) |
| SOD work status (`sod_work_rnki_stat`) | External collaboration status | No (read-only) |
| Service code / name (`svc_cd` / `svc_cd_nm`) | Service identifier | No (read-only) |
| Contract status / name (`svc_kei_stat`) | Current status | No (read-only) |
| Order status (`tel_vlan_order_stat`) | VLAN order status | No (read-only) |
| Request submission form number (`req_ji_mskmsho_no`) | Form reference | No (read-only) |
| Request work case number (`req_ji_kjak_no`) | Case reference | No (read-only) |

All non-key fields on the detail row have read-only `_value` accessors. Only `tel_vlan_id` is the field the user actually modifies. The `_enabled` flags control UI editability, and `_state` flags control rendering state (e.g., error highlighting).

## Dependencies and Integration

### Inbound (who uses this module)

| XML Config | Classes Used |
|---|---|
| `WEBGAMEN_SCW003010PJP.xml` | `SCW00401SFBean` |
| `WEBGAMEN_SCW003020PJP.xml` | `SCW00401SFBean` |
| `WEBGAMEN_SCW003030PJP.xml` | `SCW00401SFBean` |
| `WEBGAMEN_SCW004010PJP.xml` | `SCW00401SFBean`, `SCW00401SFLogic` |
| `WEBGAMEN_SCW004020PJP.xml` | `SCW00401SFBean`, `SCW00401SFLogic` |
| `WEBGAMEN_SCW004030PJP.xml` | `SCW00401SFBean`, `SCW00401SFLogic` |
| `x31business_logic_SCW00401SF.xml` | `SCW00401SFLogic` |

The module is wired into the X31/X33 framework via XML configs: three for the screens (SCW00401, SCW00402, SCW00403) and one for the business logic routing.

### Outbound (what this module calls)

| Dependency | Purpose |
|---|---|
| `SCSV0004_SCSV0004OPDBMapper` | Search/match service contracts by contract number |
| `SCSV0005_SCSV0005OPDBMapper` | Register VLAN-ID (called in both check and actual modes) |
| `JCCWebBusinessLogic` | Parent class providing `invokeService()`, `getServiceFormBean()`, etc. |
| `JCCWebCommon` | Common message-setting and utility helpers |
| `JSCCommonUtil` | Parameter validation (`isValidParameter()`) |
| `JPCOnlineMessageConstant` | Standard message codes (`EKB0010_TW`, `EKB0330__I`, `EKB0370__I`, `EKB0380__I`, `EKB0780_KW`, `EKB1040_JW`) |
| `JPCModelConstant` | Model constants (`FUNC_CD_3`, `FUNC_CD_4`, `SEARCH_ERR_FLG_ZERO`, etc.) |
| `CommonInfoCFConst` | Common info screen constants (`NEXT_SCREEN_ID`, `NEXT_SCREEN_NAME`, `ESC0021A010CBSMSG1LIST`) |
| `JSCScreenConst` | Screen ID/name constants (`SCREEN_ID_SCW00401`, etc.) |
| `JSCStrConstant` | String constants (`SOD_RNKI_STAT_WAIT_RES`, `SOD_RNKI_STAT_WAIT_FIN`) |

### Related packages

The module depends on various common and business packages (`eo.common.util`, `eo.business.common`, `eo.business.service`, `eo.web.webview.common`, etc.) through its imports, all of which are standard infrastructure for the eo web application.

## Notes for Developers

1. **Checker class is a placeholder.** `SCW00401SFChecker` always returns `true` and does nothing. All validation logic lives in the `chkItemValue*()` methods of `SCW00401SFLogic`. If you need to add GUI-level validation, either implement it in the checker or in the logic class.

2. **Business validation for SOD status is specific.** Registration is blocked if the SOD work collaboration status is in either "waiting for response" (`WAIT_RES`) or "waiting for completion" (`WAIT_FIN`) state. This prevents registering VLAN-IDs for contracts that are still in pending SOD workflows.

3. **eo light phone contract is mandatory.** The `eo_tel_flg` must equal `"1"` (string, not integer) for registration to proceed. This is enforced in `chkItemValue2()`.

4. **Only VLAN-ID is editable.** Among all the fields in the detail row, only `tel_vlan_id` is the field the user actually modifies. All other fields are displayed as read-only reference data returned from the search.

5. **Service contract number persists across screens.** The value entered on the search screen is stored in `KEY_SVC_KEI_NO_HOJI` and is not cleared until the user clicks the complete button. This allows the user to navigate back and forth without losing the search key.

6. **Zero-result search is a user-visible error.** When the search returns zero records, message `EKB0330__I` is displayed and the screen does not advance. The bean is cleared before the search, so stale data is never displayed.

7. **The `//` prefix in `loadModelData` is for common info bean access.** If a key starts with `//`, the request is delegated to the parent class's `loadCommonInfoData()` method. This is used to read data from the common information area (e.g., user session data).

8. **Mapper use case IDs.** Search uses `SCSV0004`; registration uses `SCSV0005`. The mapper's `setSCSV000501SC()` method takes a function code that determines whether it's a check (`FUNC_CD_4`) or actual registration (`FUNC_CD_3`).

9. **All bean fields follow the _update / _value / _enabled / _state pattern.** This is a convention of the X33/X31 framework. When adding new fields, maintain this 4-field pattern for consistency.

10. **The detail list always starts with one empty row.** The constructor initializes `esc0021a010cbsmsg1list_list` with exactly one `SCW00401SF01DBean` instance. After a search, the list is cleared and repopulated with actual data rows. The `clearDatabean()` method clears the list and adds back one empty row.