# KKW02504SFLogic

## Purpose

`KKW02504SFLogic` is the web-view business logic controller for the **My Home Page (My HP) information management screen** in the NTT DOCOMO K-Line online service system. It handles the full lifecycle of a customer's My Home Page subscription: initial page load, modification (URL or capacity), cancellation, reactivation, and reservation cancellation. The class acts as a **screen controller / facade** — it reads DataBeans from the HTTP session, maps them to business service requests, invokes backend AP services, and maps the responses back to the view layer.

## Design

This class follows the **screen-controller pattern** used throughout the JCC (Java Customer Center) web framework. It extends `JCCWebBusinessLogic` and implements no additional interfaces. The class is tightly coupled to the screen `KKW02504` (the My HP information change/cancel confirmation screen) and its successor screens `KKW02505` (update confirmation) and `KKW02506` (completion).

Architecturally, `KKW02504SFLogic` is a **facade over five backend AP services**:

| Service | Operation | Purpose |
|---|---|---|
| KKSV0007 | KKSV0007OP | My Home Page info inquiry (initial display) |
| KKSV0008 | KKSV0008OP | My Home Page change confirm |
| KKSV0009 | KKSV0009OP | My Home Page cancel confirm |
| KKSV0004 | KKSV0004OP | My Home Page reactivation |
| KKSV0017 | KKSV0017OP | Reservation cancellation |

The class uses a **handler dispatch pattern**: each public method (`actionInit`, `actionUpdMyHPInfo`, `actionFixMyHPInfo`, etc.) corresponds to a user action on the screen (init, submit update, confirm, cancel, back, etc.). Within the update and confirm flows, the class further dispatches to sub-handlers based on `trandiv` (transaction division): `CHGE` (change), `DSL` (cancel), `KAIHK` (reactivate), or `RSV_CL` (reservation cancel).

## Key Methods

### actionInit() — Initial Display Handler

```java
public boolean actionInit() throws Throwable
```

The entry point for the screen's initial load. This is the most complex method in the class (lines 207-483) and orchestrates the full screen initialization:

1. **Screen info acquisition** - calls `JCCWebCommon.getScreenInfo(this)` to populate screen metadata.
2. **DataBean preparation** - calls `setDataInit()` to set up the service form DataBean with default values (operation date, plan codes, service codes, customer contract info).
3. **Service parameter mapping** - uses `KKSV0007_KKSV0007OPDBMapper` to map DataBean fields to the KKSV0007 inquiry service's input parameters. This involves 13 `setKKSV0007XXSC` calls covering operation service contracts, sub-op service contracts (home page capacity, ISP, access analysis), code name management, service contract status, cost lists, reservation lists, and business parameters.
4. **Service invocation** - calls `invokeService("KKSV0007", "KKSV0007OP")` to fetch current My Home Page data.
5. **Response mapping** - uses the same mapper's `getKKSV0007XXSC` methods to extract results into the DataBean.
6. **Billing judgment** - if the sub-op service status indicates active service (`SVC_KEI_STAT_TEIKYO`), calls `JKKWebCommon.jdgHiChrg()` to determine billing start/end dates and the `chrg_flg` flag (non-billing determination).
7. **Pulldown setup** - configures the home page capacity and access analysis pulldown lists using `JKKWebCommon.setPulldownListNoIndex()`, including min/max/value constraints for the capacity selector.
8. **Post-fetch initialization** - calls `storeGetDataInit()` to compute the free capacity value, flags for whether home page capacity / access analysis contracts exist, and pre-select the appropriate pulldown values.
9. **Editability gating** - based on the `trandiv` (transaction type) and the operation service contract status (`op_svc_kei_stat`), sets `CHG_KAHI_FLG` (change possible flag) to control whether the user can modify the screen. Different rules apply per transaction type:
   - **Change (`CHGE`)**: editable only if status is `010` (received), `020` (under review), `030` (contracted), or `100` (service in progress).
   - **Cancel (`DSL`)**: editable only if a URL is set AND status is `030`, `100`, or `210` (suspended/interrupted).
   - **Reactivate (`KAIHK`)**: editable only if status is `910` (canceled), and displays a "My HP option cannot be reactivated" message (option reactivation is not supported).
   - **Reservation Cancel (`RSV_CL`)**: editable if status is `010`, `020`, `030`, or `100`.

**Returns**: `true` for normal completion (always, even when errors are displayed).

### actionUpdMyHPInfo() — Update Confirmation Handler

```java
public boolean actionUpdMyHPInfo() throws Exception
```

Processes the user's update request on the confirmation screen. This method dispatches based on `trandiv`:

- **Change (`CHGE`)**: Validates that removing a URL (non-empty to empty) is not allowed (line ~520). Calls `setDataUpd()` to prepare update parameters, then invokes `setMappedKKSV0008(FUNC_CD_2)` (check-only mapping) followed by `invokeService("KKSV0008", "KKSV0008OP")` to pre-verify the change. Also handles progression timestamp mapping for new contracts (`IDO_DIV_SINKI`) or service additions (`IDO_DIV_TSUIKA`).
- **Cancel (`DSL`)**: Calls `setDataDsl()` to prepare cancellation parameters, then invokes `setMappedKKSV0009(FUNC_CD_2)` (check-only) followed by `invokeService("KKSV0009", "KKSV0009OP")`, then extracts the cancellation confirmation code (`getOpsvckeiDslCC`).

After the service call, if a `RTN_MSG_ID` is returned (indicating an error), it displays the appropriate error message via `getMsgRep()`. Otherwise, it sets the next screen to `KKW02505` (the confirmation result screen) and displays an info message.

### actionFixMyHPInfo() — Final Confirmation Handler

```java
public boolean actionFixMyHPInfo() throws Exception
```

Processes the user's final confirmation (the "determine" button press). This is the method that commits changes:

- **Change (`CHGE`)**: Calls `setMappedKKSV0008(FUNC_CD_1)` (full register/update mapping) and invokes KKSV0008.
- **Cancel (`DSL`)**: Calls `setMappedKKSV0009(FUNC_CD_1)` (full register/update mapping) and invokes KKSV0009.
- **Reactivate (`KAIHK`)**: Calls `setDataKaihk()`, then uses `KKSV0004_KKSV0004OPDBMapper` to map the reactivation parameters (including check-and-register for both reactivation CC and SODCC), and invokes KKSV0004.
- **Reservation Cancel (`RSV_CL`)**: Calls `setDataDslStp()`, then uses `KKSV0017_KKSV0017OPDBMapper` to map the cancellation parameters (including check-and-register for reservation cancel CC, SODCC, and updated application form support work info), and invokes KKSV0017.

Upon success, sets the next screen to `KKW02506` (the completion screen).

### actionShusei() — Return to Edit Handler

```java
public boolean actionShusei() throws Exception
```

Simple navigation handler that returns the user to the edit screen (`KKW02504`) when they need to correct their input. Sets `NEXT_SCREEN_ID` to `KKW02504` in the common form bean.

### actionBack() / actionFin() — Navigation Handlers

```java
public boolean actionBack() throws Exception
public boolean actionFin() throws Exception
```

Both are simple navigation handlers. `actionBack()` returns to the previous screen (read via `JCCWebCommon.getScreenId(this)`). `actionFin()` returns to the calling screen ID (same mechanism). Both log the DataBean state before returning.

### actionClear() — Reset Handler

```java
public boolean actionClear() throws Throwable
```

Resets the screen state by clearing all DataBean fields except the customer contract succession list. It iterates through all item names, clearing pulldown lists (`HP_CAPA_INFO`, `ACCSS_BNSK_INFO`) individually and other fields via `DATABEAN_CLEAR`. Then calls `actionInit()` to reinitialize the screen fresh.

### invokeService() — Service Invocation Wrapper

```java
private X31CMessageResult invokeService(String usecase_id, String operation_id) throws Exception
```

Internal helper that wraps the parent class's `invokeService()` method. Sets up the parameter map with `TELEGRAM_INFO_USECASE_ID` and `TELEGRAM_INFO_OPERATION_ID`, clears the message result list, and calls the parent service. Logs DataBean state before and after the call for debugging.

**Returns**: `X31CMessageResult` - `null` on success, or an error message object if an AP error occurred.

### setDataInit() — Pre-Service DataBean Setup

```java
private void setDataInit() throws Exception
```

Prepares the service form DataBean before the initial inquiry service call. Sets:
- Operation date, plan codes (`PPLAN_CD_HP`, `PPLAN_CD_ACSS`), cost codes (`PCRS_CD_HP`, `PCRS_CD_ACSS`)
- Sub-op service codes for home page capacity and access analysis
- Service contract status values for "canceled" and "canceled" statuses
- Customer contract succession list data, including transaction division, SYSID, service contract number, progression division, and application number
- First operation service contract number (if any)

### storeGetDataInit() — Post-Service DataBean Setup

```java
private void storeGetDataInit() throws Exception
```

Prepares the DataBean after the initial inquiry service returns. Sets:
- Free home page capacity value (`hp_capa_mryo_val`)
- Flags for whether home page capacity contract (`sbop_hp_flg`) and access analysis contract (`sbop_accs_flg`) exist (based on whether `upd_dtm_0170`/`upd_dtm_0440` are set)
- Pre-selected pulldown values for access analysis ("有" if contract exists, "無" otherwise)
- For change transactions: pre-sets the selected capacity pulldown to the current value, pre-selects access analysis, and sets domain defaults if not configured

### getUpd_kind_hp() — Home Page Capacity Change Type Determination

```java
private String getUpd_kind_hp(int hp_capa_bf, int hp_capa_sel)
```

Determines the update type code for home page capacity changes:
- **No contract**: capacity > free value -> "1" (paid), otherwise -> "4" (free continuation)
- **Has contract**: both > free value -> "3" (paid continuation); old > free and new <= free -> "2" (delisting/paid to free); otherwise -> "4" (free continuation)

### getUpd_kind_accs() — Access Analysis Change Type Determination

```java
private String getUpd_kind_accs(String accss_bnsk_sel)
```

Determines the update type code for access analysis changes:
- **No contract** and selected "有" -> "1" (paid); otherwise -> "5" (no change)
- **Has contract** and selected "有" -> "5" (no change); selected "無" -> "2" (free)

### getUpd_kind_url() — URL Change Type Determination

```java
private String getUpd_kind_url()
```

Compares the previous account (`hpad_account`) with the change-info account (`chg_hpad_account`) to determine if the URL changed:
- Same values or both null -> "5" (no change)
- Different values -> "1" (changed)

### getDsl_kind() — Cancellation Type Determination

```java
private String getDsl_kind(String opeDate)
```

Determines cancellation type: if the operation date equals the user's specified end date, it's "2" (immediate cancel); otherwise "1" (scheduled cancel).

### setMappedKKSV0008() — KKSV0008 Service Parameter Mapping

```java
private void setMappedKKSV0008(String func_cd)
```

Maps DataBean fields to the KKSV0008 (change confirm) service's input parameters. Covers 25+ service items including application content acceptance registration, billing advance list, ISP info changes, ISP start dates, URL encoding registration/usage completion, home page capacity registration/view summary/start/change, access analysis registration/view summary/start/cancel/cancel decision, progression list, progression info registration, application detail inquiry/back-office delegation, SODCC, execution condition judgments, and application form entry support work info.

### setMappedKKSV0009() — KKSV0009 Service Parameter Mapping

```java
private void setMappedKKSV0009(String func_cd)
```

Maps DataBean fields to the KKSV0009 (cancel confirm) service's input parameters. Covers the cancellation CC, execution condition judgments, SODCC, and work items.

### getPulldownSelected() — Pulldown Index Lookup

```java
private void getPulldownSelected(X31SDataBeanAccess bean, String code, ArrayList<String> param)
```

Iterates through a pulldown DataBean's code list to find the index matching the given code. Populates the `param` list with [index, code, name1, name2] of the matching entry, or ["0", "", ""] if not found.

### setDataUpd() — Update Parameter Preparation

```java
private boolean setDataUpd() throws Exception
```

Prepares all parameters for a My HP change update. Extracts selected home page capacity and access analysis values, determines URL change type, compares before/after values to check if any change occurred (returns `false` if nothing changed), determines the update type codes for HP capacity and access analysis, and sets all submission fields including application code, timestamps, contract status, service start/end dates, billing info, encoding targets, and progression info.

### setDataDsl() / setDataKaihk() / setDataDslStp() — Cancellation/Reactivation/Reservation Cancel Parameter Setup

These three methods prepare DataBean fields for their respective operations:

- **setDataDsl()**: Sets cancellation type, end date, service end/billing end dates, encoding targets (URL + WebID), and progression notes.
- **setDataKaihk()**: Sets reactivation date, encoding targets (URL + WebID), and progression notes.
- **setDataDslStp()**: Sets encoding targets (URL + WebID) and progression notes for reservation cancellation.

### getMsgRep() — Message Replacement Text Resolution

```java
private String[] getMsgRep(String trandiv, String rtn_msg_id)
```

Returns placeholder replacement text arrays for specific error messages based on transaction type:
- **Cancel**: `EKB0690_NW` -> ["利用終了日", "過去"] (end date, "past")
- **Reactivate**: `EKB5440_JW` -> ["回復可能期間外", "回復は"] (outside recovery period, "recovery is")
- **Reservation Cancel**: `EKB5420_JW` -> ["オプション", "予約取消"] (option, "reservation cancellation")

Returns `null` if no replacements are needed (message uses its own ID directly).

## Relationships

```mermaid
flowchart TD
    A["KKW02504SFLogic"] --> B["KKSV0007
My Home Page Info
Inquiry Service"]
    A --> C["KKSV0008
Change Confirm
Service"]
    A --> D["KKSV0009
Cancel Confirm
Service"]
    A --> E["KKSV0004
Reactivation
Service"]
    A --> F["KKSV0017
Reservation Cancel
Service"]
    A --> G["JCCWebBusinessLogic
Parent class"]
    H["KKW02504 Screen
WEBGAMEN_KKW025040PJP.xml"] --> A
    I["KKW02505 Screen
WEBGAMEN_KKW025050PJP.xml"] --> A
    J["KKW02506 Screen
WEBGAMEN_KKW025060PJP.xml"] --> A
    K["Business Logic Config
x31business_logic_KKW02504SF.xml"] --> A
    style A fill:#e1f5ff
```

### Inbound (users of KKW02504SFLogic)

| Dependent | Relationship |
|---|---|
| `WEBGAMEN_KKW025040PJP.xml` | Screen definition for the initial My HP info screen |
| `WEBGAMEN_KKW025050PJP.xml` | Screen definition for the update confirmation result screen |
| `WEBGAMEN_KKW025060PJP.xml` | Screen definition for the completion screen |
| `x31business_logic_KKW02504SF.xml` | Business logic configuration wiring this class into the framework |

### Outbound (dependencies of KKW02504SFLogic)

| Dependency | Relationship |
|---|---|
| `JCCWebBusinessLogic` | Parent class - provides `invokeService()`, `getServiceFormBean()`, `getCommonInfoBean()`, `clearMessageResultList()`, `dumpDatabean()` |
| `KKSV0007_KKSV0007OPDBMapper` | Maps parameters for the My HP inquiry service |
| `KKSV0008_KKSV0008OPDBMapper` | Maps parameters for the change confirm service |
| `KKSV0009_KKSV0009OPDBMapper` | Maps parameters for the cancel confirm service |
| `KKSV0004_KKSV0004OPDBMapper` | Maps parameters for the reactivation service |
| `KKSV0017_KKSV0017OPDBMapper` | Maps parameters for the reservation cancel service |
| `JCCWebCommon`, `JKKWebCommon`, `JCCWebCommon` | Common utility classes for screen info, dates, messages, pulldowns |
| `JKKCommonConst`, `JKKScreenConst`, `KKW02504SFConst` | Constants - status codes, screen IDs, DataBean field keys |

## Usage Example

The typical request flow through this class follows a multi-step wizard pattern:

1. **`actionInit()`** is called when the user first navigates to the My HP information screen (KKW02504). It loads the current subscription state from service KKSV0007, determines the user's contract status (active/canceled/suspended), sets up pulldowns for capacity and access analysis selection, and decides which transaction types are available.

2. **`actionUpdMyHPInfo()`** is called when the user clicks "change confirm" on the screen. Depending on `trandiv`, it performs pre-validation via KKSV0008 (change) or KKSV0009 (cancel) in check-only mode. If no errors, it redirects to screen KKW02505.

3. **`actionFixMyHPInfo()`** is called when the user clicks "determine" on the confirmation screen. This time the service mappings use `FUNC_CD_1` (check-and-register) instead of `FUNC_CD_2` (check-only), committing the changes. Depending on the transaction type, it invokes KKSV0008 (change), KKSV0009 (cancel), KKSV0004 (reactivation), or KKSV0017 (reservation cancel). On success, it redirects to screen KKW02506.

4. **`actionShusei()`** returns the user to the edit screen if they need to correct something.

5. **`actionBack()`** and **`actionFin()`** handle browser back-button and completion navigation respectively.

6. **`actionClear()`** resets the entire screen state and calls `actionInit()` again - typically invoked when the user wants to start over.

## Notes for Developers

- **Transaction type (`trandiv`) drives all branching logic.** The four values (`CHGE`, `DSL`, `KAIHK`, `RSV_CL`) determine which sub-handler, which service, and which validation rules apply. This value comes from the customer contract succession list and is set during `setDataInit()`.

- **Thread safety is not a concern** - each request creates a new instance of this logic class (standard for this framework). The instance fields (`inputMap`, `outputMap`, `sbop_hp_flg`, `sbop_accs_flg`, `hp_capa_mryo_val`) are request-scoped.

- **The `CHG_KAHI_FLG` DataBean field controls editability.** It is set to `false` in several guard conditions within `actionInit()` when the user's contract status doesn't permit the requested operation. The view layer checks this flag to disable or hide action buttons.

- **URL removal is explicitly blocked.** In `actionUpdMyHPInfo()`, if the previous account is non-empty and the new account is empty, the system rejects the change with an error ("Home page access cannot be removed"). This is a business rule (lines ~520-525).

- **Reactivation of My HP options is not supported.** In `actionInit()`, the `KAIHK` (reactivate) block has large sections commented out, with a message indicating "My HP option cannot be reactivated." Reactivation only works for customers with status `910` (canceled), and it only reactivates the base service, not the My HP option itself.

- **The `CAPA_ZERO_MASK = 4` field** is used as a zero-packing width for home page capacity values - capacities are left-padded with zeros to 4 digits before being matched to pulldown options.

- **All public methods return `true` on completion** (even when they display error messages). Error handling is done via DataBean message fields (`setMessageInfo`), not exception throwing (except for `invokeService` errors which propagate as `X31CMessageResult`).

- **SODCC (Standard Operation Data Communication Control)** mapping is present in all service calls, indicating integration with a broader system-of-record or batch processing pipeline.

- **Progression tracking (`PRG_STAT`, `PRG_TKJK_1`, `IDO_DIV`, `IDO_DTM`)** is maintained for all operations. New contracts (`IDO_DIV_SINKI`) and service additions (`IDO_DIV_TSUIKA`) get a progression timestamp set from the service response. The progression type and status are stored for audit/history purposes.