# SCW00301SFLogic

## Purpose

`SCW00301SFLogic` is the business logic controller for the **telephone VLAN-ID issuance request registration** workflow within the K-Opticom eo customer backbone system. It orchestrates the complete lifecycle of a customer's request to register and issue a VLAN-ID for their telephone service — from initial screen display, through search, confirmation, and final registration, all the way to completion. This class sits at the heart of a 4-step screen flow (SCW00301 -> SCW00302 -> SCW00303) and is referenced by 4 other configuration modules.

## Design

This class follows the **Web Command (Form Controller)** pattern commonly used in the Fujitsu Futurity X31 web framework. It acts as a mediator between the view layer (screens SCW00301/302/303) and the backend business services (`SCSV0004` for search, `SCSV0005` for registration), using Data Transfer Object mappers (`SCSV0004OPDBMapper`, `SCSV0005OPDBMapper`) to serialize/deserialize data beans. Each public method corresponds to a single screen action (button press), performing input validation, invoking a backend service via `invokeService()`, handling error conditions, and directing the user to the next screen.

The class extends `JCCWebBusinessLogic`, inheriting common web-layer capabilities such as `getServiceFormBean()`, `getCommonInfoBean()`, and `invokeService()`.

### Architecture diagram

```mermaid
flowchart TD
    subgraph XML_Config["XML Configuration Layer"]
        XML1["x31business_logic_SCW00301SF.xml"]
        XML2["WEBGAMEN_SCW003010PJP.xml"]
        XML3["WEBGAMEN_SCW003020PJP.xml"]
        XML4["WEBGAMEN_SCW003030PJP.xml"]
    end

    XML1 --> SCW00301SFLogic
    XML2 --> SCW00301SFLogic
    XML3 --> SCW00301SFLogic
    XML4 --> SCW00301SFLogic

    SCW00301SFLogic --> JCCWebBusinessLogic

    SCW00301SFLogic --> SCSV0004["SCSV0004_SCSV0004OPDBMapper"]
    SCW00301SFLogic --> SCSV0005["SCSV0005_SCSV0005OPDBMapper"]
```

## Key Methods

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

Initializes the screen session. This is the entry point when a user first accesses the VLAN-ID registration screen. It retrieves the service form bean, **clears the service contract number hold field** (`KEY_SVC_KEI_NO_HOJI`) to ensure a clean state, and then sets the next screen to the initial search screen (`SCREEN_ID_SCW00301`). Always returns `true`.

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

Handles the search button press. This is the most complex method in the class and performs the primary data retrieval operation:

1. **Input validation** — calls `chkItemValue1()` to verify the service contract number is provided and valid.
2. **Data bean clearing** — calls `clearDatabean()` to reset the result array before fetching new data.
3. **Contract number preservation** — saves the user-entered service contract number into the hold field so it persists across the search round-trip.
4. **Backend service invocation** — builds a parameter map with use case ID `SCSV0004`, uses the `SCSV0004OPDBMapper` to map the form bean into the input map, and calls `invokeService()` to fetch matching records.
5. **Error handling** — if the service returns a message result directly, displays it and returns `true`. If the result indicates zero records (`SEARCH_ERR_FLG_ZERO`), displays error `EKB0330` and returns `false`.
6. **Screen flow** — on success, remains on the same screen ID (`SCW00301`) with the search results populated.

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

Handles the "register confirmation" button press. This performs a **pre-check** against the backend service without committing the registration:

1. Extracts the first element from the `ESC0021A010CBSMSG1LIST` data bean array (the list of VLAN-ID registration items).
2. **Item validation** — calls `chkItemValue2()` (detailed below) to verify the request is eligible for registration.
3. **Service pre-check** — invokes backend use case `SCSV0005` via `SCSV0005OPDBMapper` with function code `FUNC_CD_6` (pre-check mode). If the service returns an error message, displays it and returns `false`.
4. **Screen transition** — on success, sets an informational message "VLAN-ID issuance request registration" and navigates to `SCREEN_ID_SCW00302` (the confirmation screen).

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

Handles the "confirm/finalize" button press. This is the method that **actually registers** the VLAN-ID issuance request with the backend:

1. Uses the same `SCSV0005OPDBMapper` as `confirmCreate()`, but with function code `FUNC_CD_5` (registration mode, as opposed to `FUNC_CD_6` for pre-check).
2. Invokes `invokeService()` with the mapped input data.
3. On success, sets the completion message "VLAN-ID issuance request registration" and navigates to `SCREEN_ID_SCW00303` (the completion/confirmation screen).
4. On failure, displays the error from the service and stays on the confirmation screen.

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

A simple pass-through that navigates back to the initial search screen (`SCREEN_ID_SCW00301`). Called when the user clicks "modify" from the completion screen, allowing them to go back and change their request. Always returns `true`.

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

Handles the "complete/close" button press. Cleans up the session state by clearing both the service contract number (`KEY_SVC_KEI_NO`) and its hold field (`KEY_SVC_KEI_NO_HOJI`), clears the data bean, and navigates back to the initial search screen. This is typically the last action a user takes.

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

Input validation method used exclusively by `search()`. Verifies that the **service contract number** field is populated and non-blank using `JSCCommonUtil.isValidParameter()`. If the value is empty or null, displays error message `EKB0010` (with parameter "service contract number") and returns `false`.

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

The most validation-intensive method in the class, used by `confirmCreate()` before allowing a registration pre-check. Performs **four categories** of validation:

1. **eo光電話 contract check** — verifies the `EO_TEL_FLG_01` flag is set to `"1"`. If not, displays error `EKB0780` stating that registration processing is only available for eo light telephone contracts.

2. **SOD status checks** — examines the `TEL_VLAN_ORDER_STAT_01` field (SOD = Service Order? integration status) and rejects the request in four states:
   - `SND_WAIT` (waiting to send)
   - `ACK_WAIT` (waiting for acknowledgment)
   - `ACK_ABNORMAL` (acknowledgment abnormal)
   - `REAPPLY` (resubmission required)
   
   Each state produces a localized error message `EKB1040` with the specific status name.

3. **SOD business integration status** — checks `SOD_WORK_RNKI_STAT_01` for two additional blocked states:
   - `WAIT_RES` (waiting for SOD response, not yet received)
   - `WAIT_FIN` (waiting for SOD response, received but not yet processed)

4. **Required job number check** — verifies that `REQ_JI_KJAK_NO_01` (request time engineering project number) is populated. If empty or null, displays error `EKB0930` stating the number could not be obtained.

Returns `true` only if all four validation categories pass.

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

Utility method that clears and reinitializes the result data bean array (`ESC0021A010CBSMSG1LIST`). It clears the array contents and adds a fresh empty `DataBean` element to prepare for receiving search results or completing the form.

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

Helper method that sets the navigation target in the common info bean by writing `NEXT_SCREEN_ID` and `NEXT_SCREEN_NAME` fields. This is how the X31 framework determines which screen to render next. Also logs the navigation destination at debug level.

## Relationships

### Upstream (Who uses this class)

Four XML configuration files reference `SCW00301SFLogic`, wiring it into the X31 web framework:

| XML Config File | Role |
|---|---|
| `x31business_logic_SCW00301SF.xml` | Maps screen SCW00301 (search screen) to this logic class |
| `WEBGAMEN_SCW003010PJP.xml` | Screen navigation config for SCW00301 (entry/search) |
| `WEBGAMEN_SCW003020PJP.xml` | Screen navigation config for SCW00302 (confirmation) |
| `WEBGAMEN_SCW003030PJP.xml` | Screen navigation config for SCW00303 (completion) |

### Downstream (Dependencies)

```mermaid
classDiagram
    class SCW00301SFLogic {
        -String MSG_REGISTER_VLAN_ID
        +boolean init()
        +boolean search()
        +boolean confirmCreate()
        +boolean fix()
        +boolean modify()
        +boolean complete()
        -void clearDatabean()
        -void setNextScreen(String, String)
        -boolean chkItemValue1(DataBean)
        -boolean chkItemValue2(DataBean)
    }
    class JCCWebBusinessLogic {
        +X31SDataBeanAccess getServiceFormBean()
        +X31SDataBeanAccess getCommonInfoBean()
        +X31CMessageResult invokeService(Map, Map, Map)
    }
    class SCSV0004_SCSV0004OPDBMapper {
        +setSCSV000401SC(DataBean[], Map, int)
        +getSCSV000401SC(DataBean[], Map)
    }
    class SCSV0005_SCSV0005OPDBMapper {
        +setSCSV000501SC(DataBean[], Map, int)
    }
    class X31SDataBeanAccess {
        +sendMessageString(String, String, String)
        +getDataBeanArray(String)
    }

    SCW00301SFLogic --|> JCCWebBusinessLogic
    SCW00301SFLogic --> SCSV0004_SCSV0004OPDBMapper
    SCW00301SFLogic --> SCSV0005_SCSV0005OPDBMapper
    SCW00301SFLogic --> X31SDataBeanAccess
```

The class depends on `JCCWebBusinessLogic` for core web framework capabilities (bean access, service invocation, screen navigation). It uses two mapper classes — `SCSV0004OPDBMapper` (for search, use case `SCSV0004`) and `SCSV0005OPDBMapper` (for registration, use case `SCSV0005`) — to bridge between the X31 data bean model and the backend service input/output maps.

## Usage Example

The typical user flow through this logic class follows a **4-screen wizard pattern**:

```
  init()           search()         confirmCreate()    fix()
  [SCW00301] -->   [SCW00301] -->   [SCW00302] -->     [SCW00303]
  Search Screen     Search Results    Confirmation      Completion
                    with results      Screen            Screen
```

1. User accesses the screen → `init()` is called, clearing state and showing the search screen.
2. User enters a contract number and clicks search → `search()` validates the input, fetches matching records from `SCSV0004`, and displays results.
3. User clicks "register confirmation" → `confirmCreate()` validates eligibility (including SOD status checks via `chkItemValue2()`) and shows the confirmation screen.
4. User clicks "confirm" → `fix()` performs the actual registration via `SCSV0005` and shows the completion screen.
5. From completion, the user can either click "modify" (calls `modify()` to return to step 1) or "complete" (calls `complete()` to clean up and reset).

## Notes for Developers

- **Thread safety** — The class holds no mutable instance state beyond what is inherited from `JCCWebBusinessLogic`. Each method creates local `HashMap` instances for parameter/input/output maps, suggesting it is safe for concurrent use within a single session context. However, the X31 framework typically instantiates one logic class per request, so this is likely not a concern in practice.

- **Validation gate** — `chkItemValue2()` is the critical gatekeeper for the registration workflow. If the SOD (service order) status is anything other than "ready", the user cannot proceed. This includes states like `SND_WAIT`, `ACK_WAIT`, `ACK_ABNORMAL`, `REAPPLY`, and two business integration wait states. Developers modifying this logic should be aware that SOD status changes must be coordinated through the proper SOD workflow before registration can succeed.

- **Function code distinction** — Note the difference between `FUNC_CD_6` (used in `confirmCreate()` for pre-check) and `FUNC_CD_5` (used in `fix()` for actual registration). Swapping these would cause the confirmation step to register data prematurely or the fix step to only perform a pre-check.

- **Screen navigation** — All screen transitions are handled through `setNextScreen()`, which writes to the common info bean rather than returning a screen ID string. This means navigation target is determined by what the logic writes, not by the framework's routing. The constant `SCREEN_ID_SCW00301` maps to the search screen, `SCREEN_ID_SCW00302` to confirmation, and `SCREEN_ID_SCW00303` to completion.

- **Hold field pattern** — The service contract number hold field (`KEY_SVC_KEI_NO_HOJI`) is used to preserve the user's search input across screen transitions. It is cleared during `init()` and `complete()`, and copied into during `search()`. This pattern ensures the contract number survives the round-trip to the backend without requiring the user to re-enter it.

- **Data bean array management** — The `clearDatabean()` method does not just clear the array; it also adds a fresh empty `DataBean` element. This is important because downstream code (such as `confirmCreate()`) expects at least one element to exist in the `ESC0021A010CBSMSG1LIST` array.

- **Synchronous service calls** — `invokeService()` is called synchronously in both `search()` and `fix()`. There is no async handling or retry logic visible in this class. Failures are handled by displaying the service's error message and returning control to the user.