# KKA14201SFLogic

## Purpose

`KKA14201SFLogic` is the central business-logic controller for the **My Home Page Information Change** feature in K-Opticom's contract management system. It handles the full lifecycle of modifying or canceling a customer's My Home Page option service — including changing home page capacity (free/paid), toggling access analysis, modifying the custom URL, canceling the service, restoring a canceled service, and reserving a future cancellation. It serves as the orchestrator that coordinates between the web-tier DataBeans, service-layer calls (KKSV0004 through KKSV0017), and the JSP view layer.

## Design

This class follows the **Controller/Orchestrator** pattern within the K-Opticom X31 web framework. It extends `JCCWebBusinessLogic`, inheriting session management, DataBean access, and screen navigation helpers. The class operates as a multi-step wizard controller: each user action (initial display, update, confirm, cancel, restore) maps to a dedicated public `action*` method that:

1. Retrieves and initializes DataBeans
2. Maps request data to service-layer input via `KKSV*OPDBMapper` objects
3. Invokes the appropriate backend service through `invokeService()`
4. Maps service responses back to DataBeans for rendering
5. Sets button visibility flags to control which UI elements appear
6. Returns control to the framework with the next screen ID

The class also provides a **OneStop API** entry point (`apiControl`) that exposes the same business operations through a REST-like XML interface for cross-application (wanstot) integration, typically invoked from mobile or external portals.

### Code Organization

The 71 methods fall into these logical groups:

| Group | Methods | Purpose |
|-------|---------|---------|
| OneStop API | `apiControl`, `apiInit`, `apiTerminal` | Cross-application API entry point |
| Screen Actions | `actionInit`, `actionInit0`, `actionUpdMyHPInfo`, `actionFixMyHPInfo`, `actionShusei`, `actionBack`, `actionFin`, `actionClear` | Screen lifecycle handlers |
| Button Visibility | `setKbnButtonVisible`, `setBtnVisibleAtTel`, `setBtnVisibleAtNet`, `setBtnVisibleAtTv`, `setFooterBtnDispFlg` | Control UI button states per service type |
| Data Preparation | `setDataInit`, `setDataUpd`, `setDataDsl`, `setDataKaihk`, `setDataDslStp`, `storeGetDataInit` | Populate DataBeans for display |
| Service Invocation | `invokeService`, `getSvckeiCommonMap`, `searchList` | Call and map backend services |
| Button Validation | `actionBtnShokaiChk`, `actionBtnChgChk`, `actionBtnDslChk`, `actionBtnKaihkChk`, `actionBtnRsvClChk` | Guard logic per action button and service code |
| Navigation | `getNextScreenInfo` | Determine next screen ID for action buttons |
| OneStop Validation | `singleChkForOneStop`, `commonKnrnChkForOneStop`, `senkoKnrnChkForOneStop`, `knrnChkForOneStop` | Input validation for API requests |
| UI Helpers | `setPulldownList`, `setPulldownListTV`, `editServiceFormBean`, `editDisableObjectValue`, `getPulldownSelected` | Populate dropdowns and editable fields |
| Data Conversion | `getDsl_kind`, `getUpd_kind_hp`, `getUpd_kind_accs`, `getUpd_kind_url`, `changeAccssBnsk`, `dslChk` | Code-to-label and flag conversions |

## Key Methods

### Screen Lifecycle Methods

#### `actionInit()` -> `boolean`

The primary entry point for the initial display of the My Home Page information change screen. Orchestrates the full page load:

1. Reads screen information from the shared form via `JCCWebCommon.getScreenInfo(this)`
2. Calls `setDataInit()` to initialize all DataBean fields
3. Maps input data using `KKSV0007_KKSV0007OPDBMapper` for multiple sub-services:
   - `KKSV000701SC` - Option service contract agreement (cancel)
   - `KKSV000702SC` - Option service contract (ISP) agreement
   - `KKSV000703SC` through `KKSV000705SC` - Sub-option service agreement for HP capacity, ISP, and access analysis
   - `KKSV000709SC`, `KKSV000710SC` - Code management for HP and access analysis
   - `KKSV000711SC` through `KKSV000714SC` - Contract agreement, pricing plan, reservation list, business parameter
4. Invokes the `KKSV0007` / `KKSV0007OP` service to fetch all contract data
5. Maps output data back to DataBeans
6. Sets pulldown lists for HP capacity and access analysis
7. Determines if the update button should be enabled based on `trandiv` (transaction division) and `op_svc_kei_stat` (option service contract status)
8. Calculates billing flags (whether charges are applicable) by calling `JKKWebCommon.jdgHiChrg()`

**Parameters:** None

**Return:** `true` for normal completion, `false` for abnormal termination

**Side effects:** Populates `inputMap`, `outputMap`, and all DataBean fields on the service form

---

#### `actionInit0()` -> `boolean`

The OneStop variant of `actionInit()`. Used when navigating from the option service contract list screen (KKW02301). Performs a similar but distinct flow:

1. Gets session data and sets the operation date
2. Invokes `KKSV0042` service with 11+ sub-queries covering: service contract agreement, common info, promotion, code name management, discount service contracts, eo HIKARI phone details, service contract contents, option channel info, and customer ranking
3. Maps results using `KKSV0042_KKSV0042OPDBMapper`
4. Sets the phone number pulldown list via `setPulldownList()`
5. Calls `searchList()` to filter the option service contract list
6. Sets common head information via `getSvckeiCommonMap()` and `JKKWebCommon.setSvckeiInfo()`
7. Configures button visibility via `setKbnButtonVisible()`
8. Fetches customer contract history via `getHktgiDataMap()`
9. Sets map screen data and footer button display flags

**Important:** The OneStop entry point validates that the selected option service is "My Home Page" (OP_SVC_CD_VALUE_0020) and that it has not already been canceled (via `dslChk()`). If the contract is already in a canceled state, it returns `false` with error E5004.

---

#### `actionUpdMyHPInfo()` -> `boolean`

Handles the "update" button press. This method determines the transaction division (`trandiv`) from the DataBean - which can be **CHANGE**, **CANCEL**, **RESTORE**, or **RESERVE_CANCEL** - and invokes the appropriate backend service:

| `trandiv` | Service | Mapper | Operation |
|-----------|---------|--------|-----------|
| CHANGE (`01`) | `KKSV0008` | `KKSV0008_KKSV0008OPDBMapper` | Update My Home Page info |
| CANCEL (`02`) | `KKSV0009` | `KKSV0009_KKSV0009OPDBMapper` | Cancel My Home Page option |
| RESTORE (`03`) | `KKSV0004` | `KKSV0004_KKSV0004OPDBMapper` | Restore canceled My Home Page |
| RESERVE_CANCEL (`04`) | `KKSV0017` | `KKSV0017_KKSV0017OPDBMapper` | Reserve future cancellation |

After service invocation, it checks the return message ID (`RTN_MSG_ID`) and sets appropriate error or success messages.

**Return:** `true` on success

---

#### `actionFixMyHPInfo()` -> `boolean`

The confirmation action - called when the user clicks the "confirm" button. Mirrors `actionUpdMyHPInfo()` in structure but represents the final submission. After invoking the appropriate service:

- If no return message ID is set (success), it navigates to screen `KKW02506` (completion screen)
- Sets a success message using the `MSGSTRING` array: "My Home Page Information Change", "My Home Page Information Cancellation", "My Home Page Information Restoration", or "My Home Page Information Reservation Cancellation"
- If a return message ID is set (error), it resolves the message via `getMsgRep()` and displays it

---

#### `actionShusei()` -> `boolean`

"Edit" action - returns to the update confirmation screen (`KKW02504`) allowing the user to modify their changes before final confirmation.

#### `actionBack()` -> `boolean`

"Back" action - returns to the calling screen by retrieving the stored screen ID.

#### `actionFin()` -> `boolean`

"Finish" action - returns to the calling screen (same as back).

#### `actionClear()` -> `boolean`

"CLEAR" action - resets the DataBean to its initial state, clearing pulldown lists and field values while preserving inherited information (`CUST_KEI_HKTGI_LIST`).

### OneStop API Methods

#### `apiControl()` -> `boolean`

The single entry point for the OneStop (cross-application) API. Executes a complete request/response cycle:

1. `apiInit()` - Parses XML request, validates `func_code`, creates message maps
2. `singleChkForOneStop()` - Validates individual fields (`func_code`, `sysid`, `svc_kei_no`, `ido_rsn_dbri_cd`, etc.) with format, length, and reference checks
3. `commonKnrnChkForOneStop()` - Validates related-field combinations
4. `overwriteDataBeanForInit0()` - Prepares DataBeans for the option service list screen
5. `actionInit0()` - Displays the option service list screen
6. Message check via `JKKOneStopApiCommonUtil.msgChk()`
7. `senkoKnrnChkForOneStop()` - Pre-check dependent validations
8. `overwriteDataBeanForInit()` - Prepares DataBeans for the My Home Page info screen
9. `actionInit()` - Displays the My Home Page information screen
10. More validation checks (`singleKnrnChkForOneStop`, `knrnChkForOneStop`)
11. `overwriteDataBeanForUpdCfm()` - Prepares for update confirmation
12. `actionUpdMyHPInfo()` - Executes the update
13. If `func_code = "1"`, additionally calls `actionFixMyHPInfo()` (confirmation)
14. `apiTerminal("00")` - Returns success XML; errors return "99"

---

#### `apiInit()` -> `boolean`

Parses the incoming XML request, extracts `func_code`, performs business regulation checks (only `func_code = "1"` or `"2"` are allowed), creates message maps, and initializes the warning list.

#### `apiTerminal(String returnCd)` -> `void`

Wraps the result in an XML response with the given return code (`"00"` for success, `"99"` for system error).

### Button Visibility and Navigation

#### `setKbnButtonVisible(OneStopDataBeanAccess[] paramBean)` -> `void`

Determines which action buttons are visible, active, or inactive based on:

- **Service code** (SVC_CD): Determines whether the user is on the net, phone, or TV service section
- **Transaction division** (ido_div): New contract, service addition, option setup, etc.
- **Option service context**: Whether an option service exists, and if it is in a canceled state

Delegates to service-specific methods:
- `setBtnVisibleAtNet()` - For internet services
- `setBtnVisibleAtTel()` - For phone services
- `setBtnVisibleAtTv()` - For TV services

Each button type has a visibility flag (`shokai_btn_v_kbn`, `add_btn_v_kbn`, `chg_btn_v_kbn`, `dsl_btn_v_kbn`, `kaihk_btn_v_kbn`, `rsv_cl_btn_v_kbn`, `bk_btn_v_kbn`, `op_pack_btn_v_kbn`) stored in the DataBean.

---

#### `getNextScreenInfo(String actionBtn, String op_svc_cd, String[] OPSVCCDS_SENIKKW2525)` -> `String[]`

A large conditional method that maps `(actionBtn, op_svc_cd)` pairs to next screen IDs. Returns a `String[3]` containing `[nextScreenId, nextScreenName, nextEndScreenId]`.

For example:
- "History View" -> `KKW02304`
- "Add" -> `KKW00837` (with multiple return-screen mappings configured)
- "Restore" for email -> `KKW02502` / end at `KKW02503`
- "Restore" for My Home Page (0020) -> `KKW02505` / end at `KKW02506`
- "Restore" for mobile list -> `KKW02402` / end at `KKW02403`
- "Change" / "Cancel" for most services -> `KKW02525` / end at `KKW02527`

The `OPSVCCDS_SENIKKW2525` array is a configurable list of option services that route through a special screen (`KKW02525`/`KKW02526`).

### Validation Methods

#### `actionBtnKaihkChk(...)` -> `boolean`

The most complex validation method. Checks whether the "Restore" button should be enabled:

1. Service code is not in the "cannot navigate" list (`OPSVCCDS_DONTSENI`)
2. Service code is not in the "cannot restore" list (`OPSVCCDS_DONTKAIHK`)
3. Service code is not in the special screen list (`OPSVCCDS_SENIKKW2525`)
4. **Date range check**: The current date must not exceed `op_svc_end_ymd + kaihk_psb_prd` (restoration permission period). Uses `setCalendar()` to compute dates and compares against the operation date.
5. **Femtocell count check**: For the femtocell service (`OP_SVC_CD_VALUE_FMTCEL`), enforces a maximum count limit - if restoring a femtocell (LTE) would exceed the maximum, it blocks the action.

Returns `false` with an appropriate error message if any check fails.

---

#### `actionBtnChgChk(String op_svc_cd, String[] OPSVCCDS_SENIKKW2525)` -> `boolean`

Checks whether the "Change" button should be enabled. Blocks changes for:

- Services in `OPSVCCDS_DONTCHG` (hardcoded list)
- Services in `OPSVCCDS_DONTSENI` (cannot navigate)
- Services in `OPSVCCDS_DONTHENKO` (cannot change)
- Services in `OPSVCCDS_SENIKKW2525` (special screen routing)

#### `actionBtnShokaiChk(String op_svc_cd)` -> `boolean`

Checks whether the "View" button should be enabled. Blocks for services in `OPSVCCDS_DONTSENI` or `OPSVCCDS_DONTSHOKAI`.

#### `actionBtnDslChk(String op_svc_cd)` -> `boolean`

Checks whether the "Cancel" button should be enabled. Blocks for services in `OPSVCCDS_DONTSENI`.

### Data Preparation Methods

#### `setDataInit()` -> `void`

Initializes DataBean values for the My Home Page change screen. Sets up the transaction division, service codes, pricing plan codes, and various status flags. Configures the HP capacity pulldown with options:
- "1" - Become paid
- "2" - Become free
- "3" - Continue paid
- "4" - Continue free
- "5" - No change

#### `setDataUpd()` -> `boolean`

Prepares DataBean values when the user presses the update button. Maps the pulldown selections to internal update kind codes (e.g., `UPD_HP_YRYO` for "become paid", `UPD_ACCS_MRYO` for "access analysis: free").

#### `storeGetDataInit()` -> `void`

Retrieves stored/persistent DataBean values, including URL domain and account information, service billing start/end dates, and operation start/end datetimes.

### Helper Methods

#### `setPulldownList(OneStopDataBeanAccess svcFormBean, HashMap<String, Object> outputMap, String pulldownKey, String outMapKey, boolean blankFlag, String msgKey, String cdKey, String nmKey, String statKey, boolean indexNoFlg)` -> `void`

A generic pulldown list populator. Reads code lists from the service output map and populates DataBean pulldown arrays. Handles blank option insertion, status filtering, and index number flags.

#### `getSvckeiCommonMap(HashMap<String, Object> outputMap, OneStopDataBeanAccess[] paramBean)` -> `HashMap<String, Object>`

Extracts and aggregates common service contract information from the KKSV0042 output map, including:
- Service contract status name
- Mansion ID / Pair ID (selects P-ID for speeds >= 1G, otherwise mansion ID)
- Customer name, phone number, address
- System ID, EO ID, pricing group, pricing plan name
- Family pack presence, promotion status, router type
- Customer rank and total eopoints
- Optional: NTT equipment installation name, SCM type/name

#### `dslChk(String opSvcKeiStat)` -> `boolean`

Checks if the option service contract status indicates "canceled" (`SVC_KEI_STAT_DSL = "910"`). Used to prevent restoring an already-restored service.

#### `getDsl_kind(String opeDate)` -> `String`

Returns "1" (immediate cancel) or "2" (reserved cancel) based on whether the operation date matches the service end date.

## Relationships

### Inbound (who uses this class)

Two XML configuration files reference `KKA14201SFLogic`:

- **`WEBGAMEN_KKA142010PJP.xml`** - Web screen configuration mapping the JSP screen (KKW02504) to this logic class
- **`x31business_logic_KKA14201SF.xml`** - X31 business logic routing configuration

### Outbound (dependencies)

| Dependency | Relationship | Purpose |
|-----------|-------------|---------|
| `JCCWebBusinessLogic` | Extends | Base framework class providing session, DataBean, and screen utilities |
| `KKSV0004_*` | Uses | Restore (restore) service mapping |
| `KKSV0007_*` | Uses | Initial display / inquiry service mapping |
| `KKSV0008_*` | Uses | Change service mapping |
| `KKSV0009_*` | Uses | Cancel service mapping |
| `KKSV0017_*` | Uses | Reservation cancel service mapping |
| `KKSV0042_*` | Uses | Option service contract list service mapping |
| `KKSV0061_*`, `KKSV0062_*`, `KKSV0043_*`, `KKSV0042_*` | Uses | Various display and lookup services |
| `JKKOneStopApiCommonUtil` | Uses | OneStop API XML marshaling and validation utilities |
| `JCCWebCommon`, `JKKWebCommon` | Uses | Shared web utilities for screen navigation, message display, pulldown lists |
| Various `JKKCommonConst`, `KKW02301SFConst`, `KKW02504SFConst` | Uses | Constants for screen IDs, service codes, operation statuses, field names |

### Class Diagram

```
classDiagram
    class KKA14201SFLogic {
        +SVC_KEI_STAT_TEIKYO
        +MSKM_STAT_SKBT_CD_SHONIN
        -SVC_KEI_STAT_DSL
        -SVC_KEI_STAT_CANCEL
        -DSL_RSV
        -DSL_SOKU
        -MSGSTRING[]
        +apiControl() boolean
        +actionInit() boolean
        +actionInit0() boolean
        +actionUpdMyHPInfo() boolean
        +actionFixMyHPInfo() boolean
        +actionShusei() boolean
        +actionBack() boolean
        +actionFin() boolean
        +actionClear() boolean
        +invokeService() X31CMessageResult
        +setKbnButtonVisible() void
        +getNextScreenInfo() String[]
        +actionBtnKaihkChk() boolean
        +actionBtnChgChk() boolean
        +singleChkForOneStop() boolean
    }
    class JCCWebBusinessLogic {
        +getServiceFormBean() X31SDataBeanAccess
        +getCommonInfoBean() X31SDataBeanAccess
        +getScreenId() String
        +getSessionId() String
        +dumpDatabean() String
    }
    class KKSV0007OPDBMapper {
        +setKKSV0007SC()
        +getKKSV0007SC()
    }
    class KKSV0008OPDBMapper {
        +setKKSV0008OP()
        +getKKSV0008OP()
    }
    class KKSV0004OPDBMapper {
        +setOpsvckeiKaihkCC()
        +getOpsvckeiKaihkCC()
    }
    class KKSV0017OPDBMapper {
        +setOpsvckeiCnslCC()
    }
    class KKSV0042OPDBMapper {
        +setKKSV0042SC()
        +getKKSV0042SC()
    }
    KKA14201SFLogic --|> JCCWebBusinessLogic
    KKA14201SFLogic --> KKSV0007OPDBMapper
    KKA14201SFLogic --> KKSV0008OPDBMapper
    KKA14201SFLogic --> KKSV0004OPDBMapper
    KKA14201SFLogic --> KKSV0017OPDBMapper
    KKA14201SFLogic --> KKSV0042OPDBMapper
```

### Sequence Diagram - Full Update Flow

```
User -> Controller: Request initial screen
Controller -> KKA14201SFLogic: actionInit()
KKA14201SFLogic -> KKA14201SFLogic: setDataInit()
KKA14201SFLogic -> KKSV0007 Service: invokeService (KKSV0007)
KKSV0007 Service -> Database: Query subscription data
Database -->> KKSV0007 Service: Return data
KKSV0007 Service -->> KKA14201SFLogic: Output map
KKA14201SFLogic -> KKA14201SFLogic: Map to DataBeans
KKA14201SFLogic -> KKA14201SFLogic: Set pulldown lists
KKA14201SFLogic -> KKA14201SFLogic: storeGetDataInit()
KKA14201SFLogic -->> Controller: true (render screen)
Controller -->> User: Display update confirmation screen

User -> Controller: Press Update button
Controller -> KKA14201SFLogic: actionUpdMyHPInfo()
alt trandiv = CHANGE
    KKA14201SFLogic -> KKSV0008 Service: invokeService
else trandiv = CANCEL
    KKA14201SFLogic -> KKSV0009 Service: invokeService
else trandiv = RESTORE
    KKA14201SFLogic -> KKSV0004 Service: invokeService
else trandiv = RESERVE_CANCEL
    KKA14201SFLogic -> KKSV0017 Service: invokeService
end
KKSV* Service -->> KKA14201SFLogic: Result
KKA14201SFLogic -->> Controller: true
Controller -->> User: Display completion screen
```

## Usage Example

### Typical Web Screen Flow

A customer navigates to the My Home Page information change screen:

1. **Initial display** (`actionInit`): The controller calls `actionInit()`, which fetches all relevant contract data via the `KKSV0007` service, populates pulldown lists for HP capacity and access analysis, and determines whether the update button should be enabled based on the current option service status.

2. **User selects changes**: The user selects a new HP capacity (e.g., "Become paid"), optionally modifies access analysis settings and URL, then clicks "Update".

3. **Update execution** (`actionUpdMyHPInfo`): Based on the `trandiv` value (set by the user's selection), the appropriate service is called - `KKSV0008` for changes, `KKSV0009` for cancellation, etc. The result is displayed as a confirmation message.

4. **Confirmation** (`actionFixMyHPInfo`): When the user clicks "Confirm", the same service is called again (idempotent operation), and upon success, the user is navigated to the completion screen (`KKW02506`).

5. **Edit/Back/Finish**: If the user needs to modify their changes, "Edit" (`actionShusei`) returns to the confirmation screen. "Back" and "Finish" (`actionBack`, `actionFin`) return to the calling screen.

### OneStop API Usage

An external application can call the My Home Page change endpoint through the OneStop API:

```
POST /api/KKA14201SF
{
    "func_code": "1",
    "sysid": "ABCD123456",
    "svc_kei_no": "12345",
    "ido_rsn_dbri_cd": "01",
    ...
}
```

The `apiControl()` method handles the entire flow - validation, display, update, and confirmation - returning a structured XML response with either a `"00"` (success) or `"99"` (error) return code.

## Notes for Developers

### Screen IDs

Key screen IDs used throughout this class:
- `KKW02504` - My Home Page information change confirmation screen
- `KKW02505` - My Home Page change restoration screen
- `KKW02506` - Completion screen
- `KKW02301` - Option service contract list screen (entry point for OneStop)

### Transaction Divisions (`trandiv`)

The `OP_TRAN_DIV_*` constants define the four transaction types:
- `01` - CHANGE (update)
- `02` - CANCEL (cancel)
- `03` - RESTORE (restore)
- `04` - RESERVE_CANCEL (reservation cancel)

Each determines which backend service is invoked during `actionUpdMyHPInfo()` and `actionFixMyHPInfo()`.

### Update Enable Flag (`CHG_KAHI_FLG`)

The ability to modify My Home Page settings is controlled by `CHG_KAHI_FLG`. It is set to `false` (update disabled) in these conditions:
- The option service contract status is not a valid intermediate state (e.g., already fully canceled with no restoration window)
- For cancel operations: the URL has not been set (URL is required for cancel)
- For restore operations: the contract status is not "canceled" (`910`)

### Button Visibility Complexity

The `setBtnVisibleAtTel`, `setBtnVisibleAtNet`, and `setBtnVisibleAtTv` methods contain deeply nested conditionals based on `ido_div` (transaction division) values and `op_svc_cd` (option service code). There are 10+ different service types with unique button visibility rules. Adding a new option service requires updating all three methods plus `getNextScreenInfo()`.

### Service Code Lists

Several hardcoded arrays control button enablement:
- `OPSVCCDS_DONTSENI` - Services that cannot be navigated to
- `OPSVCCDS_DONTSHOKAI` - Services that cannot be viewed
- `OPSVCCDS_DONTCHG` / `OPSVCCDS_DONTHENKO` - Services that cannot be changed
- `OPSVCCDS_DONTKAIHK` - Services that cannot be restored
- `OPSVCCDS_SENIKKW2525` - Services routed through the special screen `KKW02525`

### Thread Safety

This class is instantiated per HTTP request and holds instance state (DataBeans, maps). It is **not thread-safe** - do not share instances across threads or requests. The `inputMap` and `outputMap` are recreated in each method.

### Migration Context

The OneStop API methods (`apiControl`, `actionInit0`) were added in ANK-2694-00-00 as a "wanstot" (cross-application) migration, copying and adapting logic from the KKW02301SF screen. The OneStop path uses `OneStopDataBeanAccess` instead of `X31SDataBeanAccess`. The traditional web path (`actionInit`) still uses the original `X31SDataBeanAccess` classes.

### Constants Pattern

The class uses a large number of Japanese-language string constants for error messages (the `MSGSTRING` array) and business codes. Many business rules are encoded as literal string comparisons against constants defined in `JKKCommonConst` and `KKW02301SFConst`. When reading or modifying this class, cross-reference these constant files for the actual values.