# Eo / Web / Webview / Scw00301sf

## Overview

The `SCW00301SF` package handles **telephone VLAN-ID issuance registration** — the process by which a customer service operator submits a request to allocate a VLAN ID for an eo optical telephone contract. When a customer subscribes to the eo光電話 (eo optical telephone) service, a VLAN ID must be issued by the external SOD (Service Orchestration Data) system. This webview logic module orchestrates the entire user-facing workflow: searching for a service contract by its contract number, validating the VLAN-ID issuance request against SOD status constraints, confirming the details on a review screen, and finally submitting the issuance request to the backend service layer.

This module is part of the **eo customer backbone system** (eo顧客基幹システム) and sits at the intersection of the X31 web framework, the business service layer (use case `SCSV0005`), and the SOD integration points.

---

## Key Classes

### [SCW00301SFLogic](source/koptWebB/src/eo/web/webview/SCW00301SF/SCW00301SFLogic.java)

**Purpose:** This is the sole class in the `SCW00301SF` subpackage. It extends `JCCWebBusinessLogic` (the framework's base business logic class) and acts as the central controller for the VLAN-ID issuance registration screens. Every user action on the screens — search, confirm, fix (confirm and register), modify, and complete — funnels through one of its methods.

#### Method Summary

##### `init()`

Initializes the screen on first load. It clears any residual service contract number in the data bean and sets the navigation target to the search screen (`SCW00301`). This method is idempotent and always returns `true` unless an exception occurs.

##### `search()`

Handles the **search button** press. It validates the user-entered service contract number via `chkItemValue1()`, clears the result data bean, preserves the entered contract number in a display-hold field, then invokes the search service (`SCSV0004` use case). If zero results are found, it displays error message `EKB0330__I`. On success, it re-displays the same screen (`SCW00301`) with the fetched results populated in a list.

##### `confirmCreate()`

Handles the **register confirmation** button press. It extracts the VLAN list items from the data bean, runs detailed validation via `chkItemValue2()` (which checks the contract is an eo optical telephone service, that the SOD status allows submission, and that a job ticket number is present), then calls the pre-check service (`SCSV0005` use case with function code `FUNC_CD_6`). If the pre-check passes, it sets a success message and navigates to the confirmation screen (`SCW00302`).

##### `fix()`

Handles the **fix (confirm and submit)** button press. This is the final submission step. It invokes the registration service (`SCSV0005` use case with function code `FUNC_CD_5`), which persists the VLAN-ID issuance request. On success, it sets a completion message and navigates to the result screen (`SCW00303`).

##### `modify()`

Handles the **modify** button press from the confirmation screen. It simply navigates the user back to the original search screen (`SCW00301`) so they can correct their input. No business logic beyond screen transition.

##### `complete()`

Handles the **complete** button press from the result screen. It clears the service contract number fields, clears the data bean arrays, and navigates back to the search screen (`SCW00301`). This is a clean-up-and-return operation.

#### Private Helper Methods

##### `clearDatabean()`

Resets the data bean array for the VLAN list items (`ESC0021A010CBSMSG1LIST`) by clearing the array and adding a fresh empty entry. This ensures subsequent searches start with a clean slate.

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

A utility that sets the next-screen navigation metadata on the common info bean. Also logs the navigation target for debugging.

##### `chkItemValue1(X31SDataBeanAccess bean)`

Validates that the service contract number is present and non-empty. Returns `false` with message `EKB0010_TW` if missing.

##### `chkItemValue2(X31SDataBeanAccess bean)`

This is the most complex validation in the class. It enforces several business rules before a VLAN-ID issuance request can be submitted:

1. **Service type check** — The contract must be an eo optical telephone service (`EO_TEL_FLG_01` must equal `"1"`). Otherwise, error `EKB0780_KW` is returned.
2. **SOD status check** — The SOD status (`TEL_VLAN_ORDER_STAT_01`) must not be in any of the following states, all of which block issuance:
   - **Send waiting** (`SOD_STAT_SND_WAIT` = `"001"`) — the prior request has been sent but not yet acknowledged.
   - **ACK waiting** (`SOD_STAT_ACK_WAIT` = `"002"`) — awaiting a response.
   - **ACK abnormal** (`SOD_STAT_ACK_ABNORMAL` = `"005"`) — the prior response was an error.
   - **Re-send requested** (`SOD_STAT_REAPPLY` = `"007"`) — the SOD system requested a re-send.
3. **SOD business integration status check** — The SOD work rank status (`SOD_WORK_RNKI_STAT_01`) must not be:
   - **Integration waiting, SOD ACK pending** (`SOD_RNKI_STAT_WAIT_RES` = `"002"`)
   - **Integration waiting, SOD ACK received** (`SOD_RNKI_STAT_WAIT_FIN` = `"003"`)
4. **Job ticket number check** — The request job ticket number (`REQ_JI_KJAK_NO_01`) must be non-empty; otherwise error `EKB0930_NW` is returned.

If all checks pass, the method returns `true` and the request proceeds to the confirmation screen.

---

## How It Works

### End-to-End Request Flow

Below is the typical user journey through the VLAN-ID issuance registration screens:

```mermaid
sequenceDiagram
    participant User as "User"
    participant Web as "SCW00301SFLogic"
    participant SearchSvc as "SCSV0004 Service"
    participant PreCheckSvc as "SCSV0005 Pre-check"
    participant RegSvc as "SCSV0005 Registration"
    participant Bean as "DataBean"

    User->>Web: Init screen
    Web->>Bean: Clear service contract number
    Web-->>User: Show search screen SCW00301

    User->>Web: Search by contract number
    Web->>Bean: Validate input
    Web->>Bean: Clear databean
    Web->>SearchSvc: Invoke SCSV0004 search
    SearchSvc-->>Bean: Return results
    alt No results
        Web-->>User: Error EKB0330
    else Results found
        Web-->>User: Show results screen SCW00301
    end

    User->>Web: Confirm creation
    Web->>Bean: Get VLAN list items
    Web->>Bean: Validate VLAN items
    Web->>PreCheckSvc: Invoke SCSV0005 pre-check
    alt Pre-check fails
        Web-->>User: Error message
    else Pre-check passes
        Web-->>User: Show confirmation screen SCW00302
    end

    User->>Web: Fix (confirm)
    Web->>RegSvc: Invoke SCSV0005 registration
    RegSvc-->>Bean: Persist VLAN-ID request
    Web-->>User: Show completion screen SCW00303

    User->>Web: Modify
    Web-->>User: Back to SCW00301

    User->>Web: Complete
    Web->>Bean: Clear beans
    Web-->>User: Back to SCW00301
```

### Key Design Patterns and Decisions

- **Service delegation via mappers.** Each business operation (search, pre-check, registration) delegates to a dedicated mapper (`SCSV0004_SCSV0004OPDBMapper` or `SCSV0005_SCSV0005OPDBMapper`) which constructs the input/output parameter maps and calls `invokeService()`. This keeps the logic class free of service invocation details.

- **Pre-check before final submission.** The `confirmCreate()` method performs a pre-check against `SCSV0005` (function code `FUNC_CD_6`) before reaching `fix()`, which calls the same service with function code `FUNC_CD_5` for actual registration. This two-phase approach gives the user a review screen to catch issues before they are persisted.

- **SOD state machine enforcement.** The `chkItemValue2()` method implements a state guard: the VLAN-ID issuance request can only be submitted when the SOD system is in a clean/idle state. All intermediate or error states (waiting for response, abnormal response, re-send requested) block the operation and display descriptive error messages. This prevents duplicate or conflicting requests to the SOD integration.

- **Message-centric error handling.** Error and success messages are centralized through `JCCWebCommon.setMessageInfo()` using message codes from `JPCOnlineMessageConstant`. Parameters can be interpolated into messages (e.g., the operation name in `EKB0370__I`).

- **Screen state via common info bean.** Screen navigation metadata (next screen ID and name) is stored in the common info data bean, not in local variables. This follows the X31 framework convention of using shared bean state for screen routing.

---

## Data Model

This module works exclusively with the X31 framework's data bean access pattern (`X31SDataBeanAccess`). Key data fields and arrays used:

| Field / Array Key | Purpose |
|---|---|
| `KEY_SVC_KEI_NO` | Service contract number — user's primary search input |
| `KEY_SVC_KEI_NO_HOJI` | Display-hold copy of the service contract number (preserved across postbacks) |
| `ESC0021A010CBSMSG1LIST` | Array of VLAN list items returned by the search service; each entry is a `DataBeanAccess` |
| `EO_TEL_FLG_01` | Flag indicating whether the service is eo optical telephone (`"1"` = yes) |
| `TEL_VLAN_ORDER_STAT_01` | SOD status for the telephone VLAN order |
| `SOD_WORK_RNKI_STAT_01` | SOD business integration status |
| `REQ_JI_KJAK_NO_01` | Request job ticket number — required for the issuance request |

The data bean also carries the `NEXT_SCREEN_ID` and `NEXT_SCREEN_NAME` fields on the common info bean for screen routing.

---

## Dependencies and Integration

### Inbound (What uses this module)

The following XML configuration files reference `SCW00301SFLogic`:

| XML Config | Description |
|---|---|
| `x31business_logic_SCW00301SF.xml` | Business logic routing for the search/confirmation screens |
| `WEBGAMEN_SCW003010PJP.xml` | Screen configuration for the search screen |
| `WEBGAMEN_SCW003020PJP.xml` | Screen configuration for the confirmation screen |
| `WEBGAMEN_SCW003030PJP.xml` | Screen configuration for the result screen |

### Outbound (What this module calls)

```mermaid
flowchart TD
    subgraph Package["eo.web.webview.SCW00301SF"]
        Logic["SCW00301SFLogic"]
    end

    subgraph Framework["X31 Framework"]
        BusinessLogic["JCCWebBusinessLogic"]
        DataBean["X31SDataBeanAccess"]
        MessageResult["X31CMessageResult"]
    end

    subgraph Services["Business Services"]
        SCSV0004["SCSV0004_SCSV0004OPDBMapper
Service: SCSV0004
Search"]
        SCSV0005["SCSV0005_SCSV0005OPDBMapper
Service: SCSV0005
Pre-check + Register"]
    end

    subgraph Constants["Constants"]
        ScreenConst["JSCScreenConst
Screen IDs / names"]
        ModelConst["JPCModelConstant
Function codes, search error flags"]
        OnlineMsg["JPCOnlineMessageConstant
Message codes"]
        StrConstant["JSCStrConstant
SOD status strings"]
        CommonInfoCFConst["CommonInfoCFConst
Common info keys"]
        SCW00401SFConst["SCW00401SFConst
Service contract keys"]
    end

    subgraph Utilities["Utilities"]
        WebCommon["JCCWebCommon
Message setting, search error detection"]
        CommonUtil["JSCCommonUtil
Parameter validation"]
    end

    Logic --> BusinessLogic
    Logic --> DataBean
    Logic --> MessageResult
    BusinessLogic --> DataBean
    Logic --> SCSV0004
    Logic --> SCSV0005
    Logic --> ScreenConst
    Logic --> ModelConst
    Logic --> OnlineMsg
    Logic --> StrConstant
    Logic --> CommonInfoCFConst
    Logic --> SCW00401SFConst
    Logic --> WebCommon
    Logic --> CommonUtil
```

- **Business services:** The module delegates to two use cases:
  - **SCSV0004** — Service search. Fetches contract details by service contract number.
  - **SCSV0005** — VLAN-ID issuance registration. Called twice: once for pre-check (function code 6) and once for actual registration (function code 5).

- **Constants packages:** Several constant classes are used:
  - `JSCScreenConst` — Screen IDs and names (`SCREEN_ID_SCW00301`, `SCREEN_NAME_SCW00301`, etc.)
  - `JPCModelConstant` — Function codes (`FUNC_CD_1`, `FUNC_CD_5`, `FUNC_CD_6`), search error flags
  - `JPCOnlineMessageConstant` — Message codes for all user-facing errors and confirmations
  - `JSCStrConstant` — SOD status code strings (`SOD_STAT_SND_WAIT`, `SOD_STAT_ACK_WAIT`, etc.)
  - `CommonInfoCFConst` — Common info bean field keys (`NEXT_SCREEN_ID`, `NEXT_SCREEN_NAME`)
  - `SCW00401SFConst` — Service contract number field keys

---

## Notes for Developers

- **Extending this module:** If you need to add a new screen state or modify the VLAN-ID workflow, start by understanding the SOD status constraints in `chkItemValue2()`. Adding a new SOD state that should block submission requires updating both the constant in `JSCStrConstant` and the condition in this method.

- **Screen navigation:** All screen transitions go through `setNextScreen()`, which writes to the common info bean. Do not hard-code navigation in other places — the X31 framework reads these fields to determine the next JSP.

- **Data bean lifecycle:** The `clearDatabean()` method is called before each search to reset the result list. The list array is cleared and re-initialized with a single empty entry. If you add new list-based fields to the screen, ensure they are also handled in `clearDatabean()`.

- **Error message codes:** New error messages should follow the naming convention of existing codes in `JPCOnlineMessageConstant`. The message IDs follow patterns like `EKB0010_TW` (type + number + severity indicator) and `EKB1040_JW` (integration warning).

- **SOD integration is asynchronous.** The SOD system operates asynchronously — a request is sent, then the system waits for a response. The status checks in `chkItemValue2()` prevent the user from submitting a duplicate request while the prior one is still in flight (send waiting, ACK waiting, etc.). This is critical because the SOD status transitions to `SOD_STAT_ACK_NORMAL` (`"004"`) or `SOD_STAT_REAPPLIED` (`"006"`) only after the external system responds.

- **Thread safety:** The logic class does not maintain instance state beyond the data bean reference (which is request-scoped via the framework). Each method call operates independently on the current request's data bean.