# KKW00127SFLogic

## Purpose

`KKW00127SFLogic` is the central screen-logic controller for the **Application Information Update** workflow in the K-Opticom Customer Contract system (顧客契約). It handles the three-screen flow for updating application (submission) information — update screen (KKW00127), confirmation screen (KKW00133), and completion screen (KKW00139). This class is the most important type in its subsystem because four separate XML configuration files reference it, acting as the single point of entry for the entire submission-update lifecycle.

## Design

`KKW00127SFLogic` extends `JCCWebBusinessLogic` and follows a standard web-layer business logic pattern used throughout the eo (Fujitsu Futurity) framework. It serves as a **screen controller / facade** that orchestrates:

1. **Screen initialization** — loading customer contract inheritance data from the session, fetching application details from the backend via service calls (KKSV0036 mapper), and setting up pulldown lists.
2. **Validation** — checking pulldown selections, validating agent codes, and enforcing business rules (e.g., blocking standard labor cost changes during active ONU exchange work).
3. **Data persistence** — calling the appropriate backend service based on the migration category (ido_div): registration correction (`KKSV0037`) or bundle information update (`KKSV0063`).
4. **Navigation** — routing between the update, confirmation, and completion screens, as well as dispatching to external systems (payment, inquiry history, visit history, etc.).

The class is tightly coupled to the X31 data bean architecture. Every interaction with the UI data goes through `X31SDataBeanAccess` and `X31SDataBeanAccessArray` objects, using a message-passing API (`sendMessageString`, `sendMessageObject`, `getDataBeanArray`).

### Screen Flow

The three screens managed by this class form a standard update-confirm-complete pattern:

```mermaid
flowchart TD
    A[KKW00127SFLogic] --> B[JCCWebBusinessLogic]
    C[WEBGAMEN_KKW001270PJP] --> A
    D[WEBGAMEN_KKW001330PJP] --> A
    E[WEBGAMEN_KKW001390PJP] --> A
    F[x31business_logic_KKW00127SF] --> A
    A --> G[KKSV0036 Mapper]
    A --> H[KKSV0037 Mapper]
    A --> I[KKSV0063 Mapper]
    A --> J[KKSV0056 Mapper]
    A --> K[KKSV1039 Mapper]
```

### Migration Categories (ido_div)

The class branches logic based on the **migration category code** stored in the instance field `ido_div`:

| Value | Meaning | Update Service |
|---|---|---|
| `00032` | Registration information correction | KKSV0037 |
| `00034` | Application information correction | KKSV0037 |
| `00040` | Bundle information update | KKSV0063 |

This branching affects which backend mapper is invoked during `actionFix()` and how input data is gathered in `getPulldownUpd()`.

## Key Methods

### Entry Point

#### `actionInit() → boolean` [lines 206–254]

**Purpose:** The primary entry point for the screen. Determines which of the three screens to render (update, confirmation, or completion) based on `NEXT_SCREEN_ID` from the shared form bean.

**Flow:**
1. Retrieves the screen ID from `CommonInfoCFConst.NEXT_SCREEN_ID`.
2. Dispatches to `initKKW00127()`, `initKKW00133()`, or `initKKW00139()` based on the screen ID.
3. If an unrecognized screen ID is passed, defaults to the update screen (KKW00127).
4. Sets `NEXT_SCREEN_NAME` and returns `true`.

**Side effects:** Sets the screen name in the common info bean.

### Initialization

#### `initKKW00127(X31SDataBeanAccess commoninfoBean) → boolean` [lines 626–1047]

**Purpose:** The core initialization method that populates the update screen with data. This is the most complex single method in the class (over 400 lines) and handles nearly all screen setup.

**Flow:**
1. **Screen info transfer** — calls `getScreenInfo()` to copy inheritance data (migration code, system ID, service contract number, etc.) from the shared bean to the service form bean.
2. **Code setup** — calls `setCode()` to set progress status code and reservation application date.
3. **Initial service call** — invokes `invokeInitService()` which calls the `KKSV0036` mapper with the `KKSV0036OP` operation. This is the main data-fetching service call that retrieves:
   - Application details (EKK0021)
   - Service contract info (EKK0081)
   - Agent code info (EKK0071)
   - Pulldown reference data (payway, service content, cancellation documents, etc.)
   - Temporary payment settings (ICJKN_SETTE)
   - Coupon code list (EKK0311)
4. **Pulldown list setup** — calls `JKKPulldownUtil.setPulldownList()` for each reference data type: payment continuation method, service content continuation, cancellation document delivery, service charges, standard labor costs, and bundle info.
5. **Service type detection** — calls `setSvc()` which determines the service flag (`svc_cd`) based on the price group code (`prc_grp_cd`) and whether the customer is a mansion customer. Maps price group codes to service types (eo light net home type, eo light net mansion type, mobile, ADSL, eo light TV, etc.).
6. **Application data extraction** — reads application number, application detail number, application submission type code, and submission dates from the form bean arrays.
7. **Service contract data extraction** — retrieves introduction code, service code, price group code, and desired service start date.
8. **Date formatting** — calls `set_Ymd()` to convert YYYYMMDD strings to YYYY/MM/DD format for display.
9. **Agent code handling** — iterates through the agent code list (toriatsu_cd), calling `setToriatsukaiInfo()` for each display order (1–4). This method copies both current and pre-change agent data (code, name, submission agent number, update datetime) for all four agent slots.
10. **Standard labor cost processing** — iterates through temporary payment settings, identifying service charges vs. standard labor costs by checking the first two digits of the payment number. Sets commission display labels (none/yes/half/designated amount) and formats amounts with comma separators via `setChgAmnt()`.
11. **Contract content notification** — sets up checkbox configurations for contract content notices.
12. **Pulldown display initialization** — calls `setPulldownInit()` to set default selections for all pulldowns.
13. **Service contract common map** — calls `getSvckeiCommonMap()` to build a summary map of the service contract for display in the common header area (customer name, address, service contract number, system ID, rank, family pack status, etc.).
14. **Screen info persistence** — saves customer contract inheritance data to the session for return trips via `getHktgiDataMap()`.
15. **Button display setup** — calls `setBtnDispData()` and `setBtnActiveData()` to configure the map button, usage suspension history button, and work cost total notification button visibility.

**Return value:** Always `true`.

**Side effects:** Extensive — populates the service form bean with hundreds of fields, sets the `svc_cd`, `prc_grp_cd`, and `ido_div` instance fields, and stores data in the service contract common data map (`svc_kei_dataMap`).

#### `invokeInitService(X31SDataBeanAccess[] paramBean) → HashMap<String, Object>` [lines 1054–1163]

**Purpose:** Invokes the KKSV0036 service with the KKSV0036OP operation to fetch all initial screen data. Builds the mapping request by calling over 30 `set*SC` methods on the `KKSV0036_KKSV0036OPDBMapper` instance, then calls `invokeService()`, and finally pulls results back via 25+ `get*SC` methods.

**Key parameters:** The mapper handles over 30 different data fetch operations covering service contract info, application info, agent info, pulldown reference data, temporary payment settings, special conditions, and premium service status.

### Update Operations

#### `actionUpd() → boolean` [lines 262–440]

**Purpose:** Handles the **Update Confirmation** button press. Validates the form data, gathers updated pulldown selections, and navigates to the confirmation screen (KKW00133).

**Validation performed:**
1. **Agent code validation** — iterates through the four agent code slots. If an agent code is set, calls `collAgntNm()` to fetch the agent name from the KKSV0056 service. Sets the agent name in the form bean. If the agent name is null after lookup, displays error `EKB0300-KW` ("Agent Mask").
2. **ONU exchange business rule** (ANK-4315-00-00) — if the migration category is bundle update (`00040`) and the project event type is ONU exchange (`015`) but the project event status is not "work completed" (`200`), validates that standard labor cost and service charges haven't changed since the previous update. Blocks if they have.
3. **Transfer source service contract number check** (ANK-4427-00-00) — calls `chkSvcNo()` to validate that if the transfer source service contract number has changed, the new contract belongs to the same customer (same SYSID).

**Side effects:** Calls `editPrgTkjk()` to concatenate progress-specific notes (up to 128 characters), calls `setPullDowntoView()` to prepare display values, sets `NEXT_SCREEN_ID` to KKW00133, loads service contract common info into the shared header area, and displays message `EKB0370--I`.

#### `actionFix() → boolean` [lines 448–617]

**Purpose:** Handles the **Confirm** (finalize) button press. This is the method that persists the changes to the database.

**Flow:**
1. Gets the service form bean, operation date, and operation datetime stamp.
2. Sets `UNYO_YMD` and `UNYO_DTM` fields on the bean.
3. Calls `setUpdDataActionFix()` to assign sequential agent numbers (MSKM_AGNT_NO_1 through 4) based on which agent code fields are populated.
4. **Branches based on `ido_div`:**
   - For registration correction (`00032`) or application correction (`00034`): calls KKSV0037 mapper with the `KKSV0037OP` operation, invoking over 25 `set*SC` methods for data persistence.
   - For bundle update (`00040`): calls KKSV0063 mapper with the `KKSV0063OP` operation, invoking over 20 `set*SC` methods.
   - After the mapper setup, calls `chkSvcNo()` again to re-validate the transfer source service contract number.
5. Calls `invokeService()` to execute the backend update.
6. Sets `NEXT_SCREEN_ID` to KKW00139 (completion screen).
7. Loads service contract common info, displays message `EKB4390--I`.

**Return value:** Always `true`.

**Important:** The actual database write happens inside `invokeService()`, which is inherited from `JCCWebBusinessLogic`. This class only prepares the parameters and invokes the service.

#### `actionShusei() → boolean` [lines 1867–1888]

**Purpose:** Handles the **Correction** button press on the confirmation screen. Returns to the update screen (KKW00127), preserving the service contract common info.

### Screen Data Gathering

#### `getPulldownUpd(X31SDataBeanAccess svcFormBean) → void` [lines 1331–1348]

**Purpose:** Dispatches to the appropriate data-gathering method based on `ido_div`. For registration/application correction, calls `getInputData()`. For bundle updates, calls `getInpuBundleData()`.

#### `getInputData(X31SDataBeanAccess svcFormBean) → void` [lines 1355–1460]

**Purpose:** Gathers input data from pulldown list boxes for non-TV services. Extracts the selected index from each pulldown list box and copies the corresponding code values to the form bean fields. Handles service-type-specific logic: for certain service codes, also sets service continuation content and cancellation document delivery values. For TV services (code 03/04/05), sets the bundle information.

#### `getInpuBundleData(X31SDataBeanAccess svcFormBean) → void` [lines 1467–1759]

**Purpose:** Gathers input data specifically for bundle information updates. More complex than `getInputData()` as it processes temporary payment settings, service charges, standard labor costs, and their pre-change values. Extracts data from multiple temporary payment records, differentiating between service charges (payment number starting with 01/04/11/21) and standard labor costs (starting with 99/02).

### Pulldown Setup

#### `setPulldownInit(X31SDataBeanAccess svcFormBean) → void` [lines 1229–1324]

**Purpose:** Sets initial selections and display names for all pulldowns on the update screen. Reads the current values from the form bean, looks up the display name via `getPulldownMame()`, and sets the pre-change values for tracking. Also handles the application submission type pulldown via `configPulldown()`, which copies codes and names from a source list to a target list, optionally prepending a blank option.

#### `setPullDowntoView(X31SDataBeanAccess svcFormBean) → void` [lines 1766–1859]

**Purpose:** Converts pulldown selection indices to human-readable display names for the confirmation screen. Reads the selected index from each pulldown's list box and copies the corresponding code name to the display field.

### Navigation Handlers

Each of these methods sets the `NEXT_SCREEN_ID` and `NEXT_SCREEN_NAME` in the common info bean and returns `true`:

| Method | Destination |
|---|---|
| `actionBack()` | Returns to the screen the user came from (gets screen ID from the parent) |
| `actionCustIcrnShokai()` | CKW00101 — Customer list screen |
| `actionIdoDivChoice()` | KKW00145 (migration choice) or CCW00104/CCW00105 (popup/inline mode) |
| `actionIdoDivChoiceFin()` | KKW00145 — Migration choice confirmation |
| `actionSearch1()` through `actionSearch4()` | Agent name lookup via `getToriatsuCd()` for agent code slots 1–4 |
| `actionMskmshoImg()` | Opens application document in external system (CCSV0006), or navigates to KKW14301 for reading |
| `actionParentMskmshoImg()` | No-op — returns true |
| `actionTaSys()` | KKW00146 — Other system selection screen |
| `actionParentTasys()` | No-op |
| `actionPrcHe()` | CHW00101 — Payment authorization screen |
| `actionDslLetterSch()` | KKW21811 — Cancellation letter search |
| `actionTaiorrki()` | CRW01201 — Comprehensive inquiry response history |
| `actionDtl()` | KKW00149 — Agent code detail screen |
| `actionParentDtl()` | No-op |
| `actionVsitShokai()` | KKW06304 — Visit history screen (popup mode) |
| `actionParentVsitShokai()` | No-op |
| `actionRiyofukaRireki()` | KKW17801 — Fee history screen |
| `action_KjhSgkTtsho()` | KKW21904 via `screenTransfer()` — Work cost total notification |
| `actionItiKakunin()` | Opens map via CCSV0006 service, sets map URL and opens flag |
| `actionTransferTrank()` | Transfers to TRANK system |
| `actionTchishoShokai()` | Displays office location |
| `actionTransferVcms()` | Transfers to VCMS system |

#### `screenTransfer(JCCWebBusinessLogic bl, HashMap<String, Object> screenTransferMap, HashMap<String, Object> dataHikitugiMap, HashMap<String, Object> searchConditionMap) → boolean` [lines 2594–2678]

**Purpose:** A reusable screen transfer helper. Creates inheritance data maps and return-condition maps from the service form bean, stores them in the session, and performs the actual navigation. Used by `action_KjhSgkTtsho()`.

### Tab Handlers

Methods `actionTab1()` through `actionTab11()` handle tab clicks. Each delegates to `JKKTabCommonLogic` with the appropriate screen ID and data keys. These tabs correspond to: Application Info, Service Contract, Customer Info, Equipment Info, Option Info, Billing Contract Info, Progress Info, Discount Info, Address Info, ADSL Work Info, and Contents.

### Service Contract Common Map

#### `getSvckeiCommonMap(HashMap<String, Object> outputMap, X31SDataBeanAccess[] paramBean) → HashMap<String, Object>` [lines 3860–4031]

**Purpose:** Builds a summary map of service contract data for the common header area displayed across multiple screens. Extracts customer name, address, phone, service contract number, billing contract number, system ID, EO user ID, price group name, plan name, P-ID, category ID, reservation status, dismantling business operator name, and ski-room type from the `KKSV003602SC` output. Also extracts migration category name from `KKSV003622SC` and family pack status from `KKSV003624CC`. Sets the default next tab to `Tab1`.

## Utility Methods

| Method | Description |
|---|---|
| `isNull(Object)` | Checks if an object is null or has zero-length string representation |
| `getTratCdElement(X31SDataBeanAccessArray, int)` | Finds the element in an agent code list matching a given display order |
| `getPulldownMame(X31SDataBeanAccess, String, String)` | Looks up the display name for a pulldown code |
| `selectedPulldownIndex(X31SDataBeanAccess, String, String)` | Sets the selected index in a pulldown list box matching a code |
| `configPulldown(X31SDataBeanAccess, String, String, String, boolean)` | Copies a code list from source to target, prepending a blank option if requested |
| `getHktgiDataMap(X31SDataBeanAccess, String, String[])` | Extracts inheritance data fields from the service form bean into a HashMap |
| `set_Ymd(String)` | Formats an 8-digit date string (YYYYMMDD) to YYYY/MM/DD |
| `setChgAmnt(String)` | Formats a numeric amount string with comma separators using `DecimalFormat` |
| `setToriatsukaiInfo(X31SDataBeanAccess, X31SDataBeanAccessArray, X31SDataBeanAccessArray, int)` | Sets agent code data for a specific display order, copying both current and pre-change values for code, name, agent number, and update datetime |
| `setUpdDataActionFix(X31SDataBeanAccess)` | Assigns sequential agent numbers (001, 002, 003, 004) to the MSKM_AGNT_NO fields based on which agent code slots are populated |
| `setSvc(X31SDataBeanAccess, Map<String, Object>)` | Determines the service flag (`svc_cd`) based on price group code and whether the customer is a mansion resident |
| `editPrgTkjk(X31SDataBeanAccess)` | Edits progress-specific notes by concatenating old and new values, up to 128 characters |
| `setSessionKKW00127SFBean(X31SDataBeanAccess, String)` | Creates a session map with screen-specific data for navigation between screens |
| `getHktgParameter(String)` | Convenience wrapper that extracts a single inheritance data parameter from the service form bean |
| `getMapInfo(X31SDataBeanAccess)` | Fetches map coordinates (latitude/longitude) via KKSV0793 service |
| `setBtnDispData(X31SDataBeanAccess)` | Configures display for map button and usage suspension history button |
| `setBtnActiveData(X31SDataBeanAccess)` | Enables the work cost total notification button |
| `setMapGmnData(X31SDataBeanAccess)` | Sets map-related data for the map display feature |
| `setTsuchishoList(X31SDataBeanAccess)` | Sets the office/location list data |
| `chkSvcNo(X31SDataBeanAccess, Map<String, Object>)` | Validates transfer source service contract number changes by checking SYSID match via KKSV1039 |
| `collAgntNm() → boolean` | Calls the KKSV0056 service to look up an agent name from an agent code |
| `callGetSvcKeiSc(X31SDataBeanAccess) → HashMap<String, Object>` | Invokes the KKSV1039 service to fetch service contract agreement data for transfer source validation |

### Enums

The class defines two inner enums used for branching:

- **`svcflg`** — Maps price group codes (CD01–CD16, NOCD) to string values, with a `tocd(String)` method for reverse lookup. Used in `setSvc()` to determine the service type flag.
- **`dtlflg`** — Maps button IDs (BTNID1–BTNID4, NOBTNID) to strings, with a `tobtn(String)` method. Used in `actionDtl()` to determine which agent code detail button was pressed.

## Relationships

### Who depends on this class (4 inbound connections)

```mermaid
flowchart LR
    A1[WEBGAMEN_KKW001270PJP] -->|references| K[KKW00127SFLogic]
    A2[WEBGAMEN_KKW001330PJP] -->|references| K
    A3[WEBGAMEN_KKW001390PJP] -->|references| K
    A4[x31business_logic_KKW00127SF] -->|references| K
```

1. **WEBGAMEN_KKW001270PJP.xml** — Configuration for the update screen (KKW00127). This is the primary screen where users enter and modify application information.
2. **WEBGAMEN_KKW001330PJP.xml** — Configuration for the confirmation screen (KKW00133). Displays the data after validation for review before final commit.
3. **WEBGAMEN_KKW001390PJP.xml** — Configuration for the completion screen (KKW00139). Shown after successful data persistence.
4. **x31business_logic_KKW00127SF.xml** — The X31 business logic definition file that registers this class with the framework's service invocation pipeline.

### What this class depends on (outbound)

| Dependency | Usage |
|---|---|
| `JCCWebBusinessLogic` | Parent class — provides `invokeService()`, `getCommonInfoBean()`, `getServiceFormBean()`, `dumpDatabean()` |
| `KKSV0036` mapper | Initial screen data fetch (application info, service contract, agent codes, pulldowns, temporary payments) |
| `KKSV0037` mapper | Data persistence for registration/application correction |
| `KKSV0063` mapper | Data persistence for bundle information updates |
| `KKSV0056` mapper | Agent name lookup service |
| `KKSV1039` mapper | Transfer source service contract validation |
| `KKSV0793` mapper | Map coordinate retrieval and button data |
| `CCSV0006` mapper | Application document image reference, map display |
| `JKKWebCommon` | Service contract common info loading |
| `JKKPulldownUtil` | Pulldown list population |
| `JCCWebCommon` | Screen info management, message display |
| `JKKTabCommonLogic` | Tab navigation handling (delegated) |
| `JCHPageTransferUtil` | Page transfer map creation |

## Usage Example

A typical user flow through this class:

1. User arrives at the update screen (KKW00127) → `actionInit()` routes to `initKKW00127()`, which fetches all data from KKSV0036 and populates the screen.
2. User modifies fields and clicks "Update Confirmation" → `actionUpd()` validates agent codes, checks business rules (ONU exchange protection, transfer source contract validation), and redirects to the confirmation screen.
3. User reviews on the confirmation screen (KKW00133) → `actionUpd()` has already set `NEXT_SCREEN_ID` to KKW00133.
4. User clicks "Confirm" → `actionFix()` calls the appropriate backend mapper (KKSV0037 or KKSV0063) to persist the changes, then redirects to the completion screen (KKW00139).
5. User clicks "Correction" → `actionShusei()` returns to the update screen for re-editing.
6. User clicks "Back" → `actionBack()` returns to whichever screen the user originally came from.

## Notes for Developers

1. **Thread safety:** This class is **not thread-safe**. It maintains mutable instance state (`ido_div`, `svc_cd`, `prc_grp_cd`, `svc_kei_dataMap`) that is set during initialization and read throughout the request. Each screen request creates a new instance (as is standard in this framework), but the class should never be shared across threads.

2. **Service contract common map persistence:** The `svc_kei_dataMap` is populated in `initKKW00127()` via `getSvckeiCommonMap()` and re-loaded before screen transitions via `JKKWebCommon.setSvckeiInfo()`. If you add fields to this map, ensure they are also set during `actionFix()` to maintain consistency across the confirmation and completion screens.

3. **Migration category branching:** The `ido_div` field drives all major branching logic. Be careful when adding new migration categories — the checks in `actionUpd()`, `actionFix()`, `getPulldownUpd()`, `setCode()`, and other methods use explicit string comparisons (`"00032"`, `"00034"`, `"00040"`) rather than enum constants.

4. **Pulldown index vs. value confusion:** The codebase has had bugs where the wrong pulldown sub-bean was read (e.g., reading from `payway_hktgi_subbean` instead of `svc_naiyo_hktgi_subbean` — see the IT2-2014-0000160 fix comments). When adding new pulldowns, double-check the sub-bean source.

5. **Pre-change value tracking:** The class maintains parallel "before change" fields (prefixed with `BF_`) for audit trail purposes: `BF_PAYWAY_HKTGI_CD`, `BF_TORIATSU_CD_1`, `BF_JIMU_COMMISION_AMNT`, etc. These are used in validation (`actionUpd()` ONU exchange check) and for displaying what changed. All four agent code slots have their own set of BF_ fields.

6. **Service type detection (svc_cd):** The `setSvc()` method uses price group codes (`prc_grp_cd`) and mansion type to determine the service flag. This flag controls which input data gathering path is taken (`getInputData()` for non-TV, and specific bundle handling for TV services). Adding a new price group code requires updating the `svcflg` enum and the `setSvc()` switch statement.

7. **Agent code handling:** Four agent code slots (toriatsu_cd_1 through 4) are supported, each with its own code, name, submission agent number, and pre-change tracking fields. The `setToriatsukaiInfo()` method is the central logic for populating these. The `getToriatsuCd()` and `collAgntNm()` methods work together to look up agent names via the KKSV0056 service.

8. **DataBean dump logging:** Nearly every action method calls `JSYwebLog.println(JSYwebLog.DataBean_Dump, getClass(), dumpDatabean(), ...)` for debugging. This dumps the entire service form bean to the log. Be aware of the performance impact in high-traffic environments.

9. **Date formatting:** The `set_Ymd()` method performs manual string substring operations to format dates. This assumes a fixed 8-character YYYYMMDD format and will throw `StringIndexOutOfBoundsException` if given an unexpected length.

10. **Amount formatting:** `setChgAmnt()` uses `DecimalFormat` with `#,###` pattern and parses to `Long` (not `Integer`). This supports amounts up to approximately 9 quadrillion yen. The comma removal in input handling (`jimu_commision_amnt.replace(",", "")`) assumes the amount field may contain commas from prior display formatting.

11. **Transfer source validation (chkSvcNo):** When the transfer source service contract number changes, this method calls KKSV1039 to verify the new contract belongs to the same customer (matching SYSID). If the SYSID doesn't match, or if no contract record exists, it displays error `EKB0720-KW` and prevents the update. This is a critical data integrity check added in ANK-4427-00-00.

12. **Bundle information update restriction:** During ONU exchange work (ido_div `00040`, project event type `015`, status not `200`), the standard labor cost and service charges are locked. Any change attempt triggers error `EKBA510-KW`. This constraint exists because ONU exchange work in progress shouldn't have billing modifications.