# SCW00401SFLogic

## Purpose

`SCW00401SFLogic` is the web presentation-layer logic class that handles VLAN-ID registration in an enterprise service management system. It orchestrates a multi-step user workflow: a developer searches for a service contract by its number, confirms VLAN-ID registration details against an EO optical phone contract, executes the registration via backend services, and then either corrects the data or completes the process. This class sits between the web screen layer and the business service layer, acting as the central orchestrator for the VLAN-ID registration feature.

## Design

`SCW00401SFLogic` extends `JCCWebBusinessLogic`, which provides base web business logic utilities such as `getServiceFormBean()`, `getCommonInfoBean()`, `invokeService()`, and `setNextScreen()`. The class follows a **screen flow controller** pattern — it is invoked by XML-based screen definitions (see Relationships section below) to handle specific user actions (button presses) on the VLAN-ID registration screens.

The class operates on a `X31SDataBeanAccess` data bean (retrieved via `getServiceFormBean()`), which carries form data between screens. Screen transitions are managed by setting the `NEXT_SCREEN_ID` and `NEXT_SCREEN_NAME` fields on the common info bean via `setNextScreen()`.

Backend service calls are dispatched via `invokeService()` with a `paramMap` containing a `USECASE_ID` that maps to specific stored procedure or business logic endpoints:

- **SCSV0004** — Search for service contracts (used by `search()`)
- **SCSV0005** — Register VLAN-ID data (used by `confirmCreate()` and `fix()`)

The `FUNC_CD` parameter passed to the mapper (`FUNC_CD_3` for registration, `FUNC_CD_4` for pre-registration check) differentiates the operation mode within the shared use case.

## Key Methods

### `public boolean init() throws Exception`

Initializes the screen for VLAN-ID registration. It clears the "service contract number preservation" field (`KEY_SVC_KEI_NO_HOJI`) to ensure a fresh search state, then transitions to the initial screen (`SCREEN_ID_SCW00401`). This method is typically called when the user first opens the VLAN-ID registration screen.

Returns `true` to indicate successful initialization.

### `public boolean search() throws Exception`

Handles the search button press. This is the primary entry point for looking up a service contract by its number. The flow is:

1. Validates the input via `chkItemValue1()`, which checks that the service contract number (`KEY_SVC_KEI_NO`) is a valid (non-empty, non-null) parameter.
2. Clears the data bean via `clearDatabean()` to remove any previous search results.
3. Persists the entered service contract number into the preservation field (`KEY_SVC_KEI_NO_HOJI`) so it survives screen transitions.
4. Invokes the backend service `SCSV0004` via `SCSV0004_SCSV0004OPDBMapper` with function code `FUNC_CD_1` (search mode).
5. If the service returns no results (`SEARCH_ERR_FLG_ZERO`), displays error `EKB0330` ("no search results found") and returns `false`.
6. On success, remains on the same screen (`SCREEN_ID_SCW00401`) to display the search results.

Returns `true` on success (results displayed), `false` on validation failure or service error.

### `public boolean confirmCreate() throws Exception`

Handles the registration confirmation button press. This method initiates a **pre-registration check** against the backend before confirming. The flow:

1. Extracts the first item from the list data bean (`ESC0021A010CBSMSG1LIST`).
2. Runs item validation via `chkItemValue2()` and `chkItemValue3()`:
   - `chkItemValue2` verifies the contract is an **EO optical phone contract** (`EO_TEL_FLG_01` must equal `"1"`) and that the SOD business integration status is not in a "waiting" state (`SOD_WORK_RNKI_STAT_01` must not be `WAIT_RES` or `WAIT_FIN`).
   - `chkItemValue3` verifies the **telephone VLAN-ID** (`TEL_VLAN_ID_01`) is a valid parameter.
3. Invokes backend service `SCSV0005` via `SCSV0005_SCSV0005OPDBMapper` with function code `FUNC_CD_4` (pre-registration check mode).
4. On success, sets the success message "VLAN-ID registration" (`EKB0370`) and transitions to the confirmation screen (`SCREEN_ID_SCW00402`).
5. On failure (validation error or service error), displays the error message and remains on the current screen.

Returns `true` on success, `false` on validation failure or service error.

### `public boolean fix() throws Exception`

Handles the confirmation (execute registration) button press. This method performs the **actual VLAN-ID registration** against the backend. The flow:

1. Extracts the first item from the list data bean.
2. Invokes backend service `SCSV0005` via `SCSV0005_SCSV0005OPDBMapper` with function code `FUNC_CD_3` (registration mode).
3. On success, sets the success message "VLAN-ID registration completed" (`EKB0380`) and transitions to the completion screen (`SCREEN_ID_SCW00403`).
4. On failure, displays the error message and remains on the confirmation screen.

Returns `true` on success, `false` on error.

### `public boolean modify() throws Exception`

Handles the correction button press on the confirmation screen. This is a simple method — it just transitions back to the search screen (`SCREEN_ID_SCW00401`), allowing the user to review and edit the registration data. Returns `true`.

### `public boolean complete() throws Exception`

Handles the completion button press on the completion screen. It clears the service contract number fields (`KEY_SVC_KEI_NO` and `KEY_SVC_KEI_NO_HOJI`), clears the data bean, and transitions back to the initial screen (`SCREEN_ID_SCW00401`). This effectively resets the screen for a new operation. Returns `true`.

### `private void clearDatabean() throws Exception`

Clears and reinitializes the list data bean (`ESC0021A010CBSMSG1LIST`). It calls `clearArray()` to remove all rows, then `addDataBean()` to add an empty row as the new base. This prepares the form for new search results.

### `private void setNextScreen(String nextScreenId, String nextScreenName)`

Sets the screen transition destination by writing `NEXT_SCREEN_ID` and `NEXT_SCREEN_NAME` fields on the common info bean (`getCommonInfoBean()`). Also emits a debug log entry. This is the internal mechanism by which all screen transitions are performed.

### `private boolean chkItemValue1(X31SDataBeanAccess bean) throws Exception`

Validates the **service contract number** (`KEY_SVC_KEI_NO`). Checks that the value is a valid parameter (non-null, non-empty, non-whitespace) using `JSCCommonUtil.isValidParameter()`. If invalid, displays error `EKB0010` ("input error") for the field "サービス契約番号" (service contract number) and returns `false`. Returns `true` if valid.

### `private boolean chkItemValue2(X31SDataBeanAccess bean) throws Exception`

Validates the **contract type and SOD integration status** before registration. Checks two conditions:

1. **EO optical phone contract flag** (`EO_TEL_FLG_01`) must equal `"1"`. If not, displays error `EKB0780` indicating that registration is only available for EO optical phone contracts.
2. **SOD business integration status** (`SOD_WORK_RNKI_STAT_01`) must not be in a "waiting" state. Both `SOD_RNKI_STAT_WAIT_RES` (waiting for SOD response, not yet) and `SOD_RNKI_STAT_WAIT_FIN` (waiting for SOD response, completed) states block registration, displaying error `EKB1040` ("record status: business integration waiting [SOD response pending / SOD response received]") for "VLAN-ID registration".

Returns `true` if all checks pass, `false` otherwise.

### `private boolean chkItemValue3(X31SDataBeanAccess bean) throws Exception`

Validates the **telephone VLAN-ID** (`TEL_VLAN_ID_01`). Uses `JSCCommonUtil.isValidParameter()` to ensure it is non-null, non-empty, and non-whitespace. If invalid, displays error `EKB0010` for the field "電話用VLAN-ID" (VLAN-ID for telephone) and returns `false`. Returns `true` if valid.

## Relationships

### Who uses this class

Four XML configuration files reference `SCW00401SFLogic`, wiring it as the logic class for different screen/portal configurations in the web framework:

```mermaid
flowchart TD
    XML1["x31business_logic_SCW00401SF.xml
(Screen XML config)"]
    XML2["WEBGAMEN_SCW004010PJP.xml
(Portlet 01)"]
    XML3["WEBGAMEN_SCW004020PJP.xml
(Portlet 02)"]
    XML4["WEBGAMEN_SCW004030PJP.xml
(Portlet 03)"]
    LOGIC["SCW00401SFLogic
VLAN-ID Registration Logic"]
    PARENT["JCCWebBusinessLogic
Base web business logic"]

    XML1 -->|references| LOGIC
    XML2 -->|references| LOGIC
    XML3 -->|references| LOGIC
    XML4 -->|references| LOGIC
    LOGIC -->|extends| PARENT
```

The portlet XML files (SCW004010PJP, SCW004020PJP, SCW004030PJP) correspond to the three screens in the workflow — search, confirmation, and completion — each binding the same `SCW00401SFLogic` class to handle their button actions.

### Outbound dependencies

```mermaid
flowchart TD
    LOGIC["SCW00401SFLogic"]
    PARENT["JCCWebBusinessLogic
(Base class)"]
    MAPPER1["SCSV0004_SCSV0004OPDBMapper
Search mapper"]
    MAPPER2["SCSV0005_SCSV0005OPDBMapper
Register mapper"]
    DATABEAN["X31SDataBeanAccess
Form data bean"]
    COMMON["JCCWebCommon
Utility class"]

    LOGIC --> PARENT
    LOGIC --> MAPPER1
    LOGIC --> MAPPER2
    LOGIC --> DATABEAN
    LOGIC --> COMMON
```

The class depends on:
- **`JCCWebBusinessLogic`** — the parent class providing core infrastructure (`invokeService()`, `getServiceFormBean()`, `getCommonInfoBean()`).
- **`SCSV0004_SCSV0004OPDBMapper`** — maps data between the form bean and the search service `SCSV0004`.
- **`SCSV0005_SCSV0005OPDBMapper`** — maps data between the form bean and the registration service `SCSV0005`.
- **`JCCWebCommon`** — static utility for setting messages and checking search error flags.
- **`X31SDataBeanAccess`** — the data bean structure carrying form data across screen transitions.

## Usage Example

A typical user flow for VLAN-ID registration follows this sequence:

1. **`init()`** is called when the screen loads — clears preserved contract number, navigates to the search screen.
2. User enters a service contract number and clicks search — **`search()`** validates the input, calls `SCSV0004` backend, and displays results.
3. If search succeeds, the user reviews the VLAN-ID details and clicks confirm — **`confirmCreate()`** validates the EO contract flag and SOD status, calls `SCSV0005` for pre-registration check, and navigates to the confirmation screen.
4. On the confirmation screen, the user can either:
   - Click confirm — **`fix()`** calls `SCSV0005` for actual registration, navigates to completion screen.
   - Click correction — **`modify()`** navigates back to the search screen.
5. On the completion screen, the user clicks complete — **`complete()`** clears all data and navigates back to the search screen.

## Notes for Developers

- **Thread safety** — This class is not thread-safe. It operates on instance fields inherited from `JCCWebBusinessLogic` (the data beans, common info bean) and is expected to be instantiated per-request by the web framework.
- **Error handling** — All public methods throw `Exception` and return `boolean`. `true` indicates success and `false` indicates failure (validation error or service error). Errors are communicated through `JCCWebCommon.setMessageInfo()`, which sets messages on the data bean for display on the UI.
- **Screen transitions** — All navigation goes through `setNextScreen()`, which writes to the common info bean. This is a central mechanism — if you add new screens, ensure the corresponding `SCREEN_ID_*` and `SCREEN_NAME_*` constants are defined.
- **Data bean lifecycle** — `clearDatabean()` clears the list and adds one empty row. This means the list always has at least one row available after any operation. Be aware of this when checking for empty lists.
- **Validation cascading** — `confirmCreate()` calls both `chkItemValue2` and `chkItemValue3`. Validation stops at the first failure (short-circuit `||`), so `chkItemValue3` never runs if `chkItemValue2` fails.
- **SOD status blocking** — Both "waiting for response (not yet)" and "waiting for response (received)" states block registration. Only fully completed or not-yet-triggered SOD statuses allow registration. This suggests the system requires the SOD integration to be outside of an in-progress state.
- **Hard-coded use case IDs** — The use case IDs `"SCSV0004"` (search) and `"SCSV0005"` (register) are hardcoded as string literals. Changes to the backend service names will require updates in this class.
- **Japanese messages** — Error messages (e.g., `MSG_REGISTER_VLAN_ID = "VLAN-IDの登録"`) and field labels are embedded in Japanese. The constants class `SCW00401SFConst` likely holds screen IDs and names. The error codes (`EKB0010`, `EKB0330`, `EKB0370`, `EKB0380`, `EKB0780`, `EKB0930`, `EKB1040`) are imported from `JPCOnlineMessageConstant` and resolved to user-facing messages by the framework.
- **Commented-out code** — `chkItemValue3` contains commented-out code for validating "依頼時工事案件番号" (request work project case number). This may indicate a previously planned but not-yet-implemented feature.