# Eo / Web / Webview

## Overview

The `eo.web.webview` package serves as the **web presentation layer** for the K-Opticom customer base system — a telecommunications service management platform. It implements the view-tier logic for browser-based operator screens, handling HTTP request processing, business control enforcement, authority validation, file upload/download operations, and invocation of backend EJB services. The package is built on top of the **Fujitsu Futurity X31/X33 web framework**, which provides a structured approach to managing page lifecycles, form beans, and business logic delegation.

At a high level, this package sits between the JSP view layer and the EJB service layer. Every screen in the system follows a consistent four-class pattern: a **Bean** (form data holder), a **Logic** class (business orchestrator extending `JCCWebBusinessLogic`), a **Checker** (validation stub), and a **Const** class (field key constants). The shared base class `JCCWebBusinessLogic` provides cross-cutting capabilities — file handling, session management, business restriction enforcement, and authority control — that every screen inherits.

The `CommonInfoCF` subpackage contains dozens of data beans that serve as the **shared context carrier** across screens, holding user session data, screen metadata, authorization context, and persistent per-request state. The `common` subpackage provides the utility infrastructure that screens rely on daily: business control, authority control, date selection, web common helpers, and upload/download restriction caches.

## Sub-module Guide

### Shared Infrastructure Classes

These classes exist at the top level of the package and provide foundational capabilities used by all screens.

**JCCWebBusinessLogic** — This is the central base class that every screen's logic class extends. There are three variant copies of this file across the codebase (`koptWebFrontCommon`, `koptWebA`, `koptWebB`), each growing in scope as new features are added (e.g., GCRM integration in v48.00.00). The class provides:

- **Request lifecycle hooks** — `prereceiveMessageWeb()` and `postreceiveMessageWeb()` are overridden to run business control checks, authority validation, session date clearance, and IP address sharing on every request.
- **Service invocation** — `invokeService()` wraps the framework's service call mechanism with custom workflow service detection (`chkWksijService`) and electronic file number replacement (`getReplaceNoMap`).
- **File upload/download management** — `getFileInfoArray()` processes all uploaded files in a request, validating file extensions against configurable allow/deny lists, checking for zero-byte files, managing temporary file storage (session vs. HDD), and producing ZIP archives when needed. This handles CRC32 checksums and buffered I/O.
- **System-wide restriction codes** — Constants `RESTRICTION_ALL_SELECT_UPDATE` ("PCGKA0001") and `RESTRICTION_ALL_UPDATE` ("PCGKA0002") control read/write freeze states across all system features.

```java
// source/koptWebFrontCommon/src/eo/web/webview/JCCWebBusinessLogic.java:88
public class JCCWebBusinessLogic extends X31BWebBusinessLogic
```

**InvConvertParam** — A parameter conversion class for external integration. It extends `X33VRequestParamInverterBL` and overrides `invertValue()` to extract a single query string value from a HashMap of bean values. This appears to be a minimal adapter used when the system needs to pass form data as URL-encoded parameters to external systems. The class is referenced by 86 XML configuration files, suggesting it's a widely-used integration point.

```java
// source/koptWebFrontCommon/src/eo/web/webview/InvConvertParam.java:38
public class InvConvertParam extends X33VRequestParamInverterBL
```

### Screen Modules (KKWxxxxSF Family)

The `koptWebB` source tree contains the majority of operator-facing screens, organized into sub-packages named `KKWxxxxSF`. Each sub-package follows the standard four-class pattern. The most extensively documented screen is:

**KKW00191SF — Review Cancellation**

This module implements the "Review Cancellation" feature (照査取消部品), allowing operators to cancel or withdraw a service contract that has previously passed or failed a review check. The module's flow is:

1. On screen load (`actionInit`), it inherits screen data (system ID, service contract number, cancellation location address, customer details) from a previous screen.
2. It branches based on the `shosa_dsl_fin_cd` (review cancellation completion code):
   - If review passed (`CD00469_1`): invokes the standard review cancellation service `KKSV0408`.
   - If review failed (`CD00469_2`): invokes the NG-specific cancellation service `KKSV0742`.
3. Results are mapped back to the form bean with date reformatting (YYYYMMDD -> YYYY/MM/DD).
4. On completion (`actionComp`), the operator is redirected to the service contract agreement list screen (`KKW01101`).

The screen uses four data beans (`KKW00191SF01DBean` through `KKW00191SF04DBean`) to represent service contract details, application details, common info, and inherited data respectively.

```java
// source/koptWebB/src/eo/web/webview/KKW00191SF/KKW00191SFLogic.java
// source/koptWebB/src/eo/web/webview/KKW00191SF/KKW00191SFBean.java
// source/koptWebB/src/eo/web/webview/KKW00191SF/KKW00191SF01DBean.java
// source/koptWebB/src/eo/web/webview/KKW00191SF/KKW00191SFChecker.java
```

### Other Screen Families

Screens in this package span multiple business domains, identifiable by their prefix:

- **ACWxxxxSF / CHWxxxxSF** — Contract/Change-related operator screens (e.g., service agreement changes, account modifications)
- **CCWxxxxSF** — Common/central screens
- **FUWxxxxSF** — Utility screens, mostly containing `Const` classes that serve as constant holders for other parts of the system

Each screen sub-package contains a Bean, Logic, Checker, and Const class, following the same structural pattern. The Beans extend `X33VViewBaseBean` and implement `X33VListedBeanInterface`; the Logic classes extend `JCCWebBusinessLogic`; the Checkers implement `X31SGuiCheckBase`.

### Common Info Data Beans (CommonInfoCF)

The `CommonInfoCF` subpackage contains 73+ data beans (`CommonInfoCFBean` through `CommonInfoCF72DBean`), each holding a distinct set of context data carried across screens during a session. These beans represent the shared state model — user identity, organization context, authorization tokens, screen navigation history, operational dates, and domain-specific context (customer data, contract info, mansion/apartment details). The `CommonInfoCFConst` class provides field key constants used by all these beans.

```java
// source/koptWebFrontCommon/src/eo/web/webview/CommonInfoCF/CommonInfoCFBean.java
// source/koptWebFrontCommon/src/eo/web/webview/CommonInfoCF/CommonInfoCFConst.java
```

### Common Utilities (common subpackage)

The `eo.web.webview.common` subpackage provides shared utilities consumed by every screen:

- **Business Control** — `JCCBusinessControl`, `JCCBusinessControlApi`, `JCCBusinessControlStatus` enforce operational restrictions (e.g., system-wide freeze periods, maintenance windows). Separate API and online variants exist.
- **Authority Control** — `JCCAuthorityCtrl`, `JCCAuthorityCtrlApi`, `JCCAuthorityCtrlStatus`, `JCCAuthorityCtrlCache`, `JCCAuthorityCtrlUtil` manage user authorization, including IP-based access restriction for API endpoints.
- **Web Common** — `JCCWebCommon` (~101KB) is the primary utility class providing screen helpers, message handling, date formatting, and form bean accessors.
- **Restriction Caches** — `JCCUploadRestrictionCache`, `JCCDownloadRestrictionCache`, `JCCWorkRestrictionCache`, `JCCSearchRestrictionCache` cache file type restrictions and operational constraints.
- **Request Processing** — `JCCRequestProcessLogic` handles keep-alive detection and request routing.
- **Operation Date** — `JCCsvlGetOperationDateUtil` manages session-based operation date selection.

```java
// source/koptWebFrontCommon/src/eo/web/webview/common/JCCWebCommon.java
// source/koptWebFrontCommon/src/eo/web/webview/common/JCCBusinessControl.java
// source/koptWebFrontCommon/src/eo/web/webview/common/JCCAuthorityCtrl.java
```

### Mapping Layer (mapping subpackage)

The `eo.web.webview.mapping` subpackage contains database mapper classes that transform form bean fields into the input maps expected by EJB services. Examples include `CCSV0001_CCSV0001OPDBMapper` and `CCSV0008_CCSV0008OPDBMapper`, which map fields for specific use case operations. The `KKW00191SF` module uses `KKSV0408_KKSV0408OPDBMapper` to map review cancellation form data to the service layer.

## Key Patterns and Architecture

### Three-Layer Screen Pattern

Every screen in this package follows a strict three-class pattern enforced by the X31/X33 framework:

```
JSP View --> Screen Bean --> Screen Logic --> Service Layer (EJB)
                              Screen Checker (validation)
```

1. **Screen Bean** — Extends `X33VViewBaseBean`, implements `X33VListedBeanInterface` and `X31CBaseBean`. Holds all display data as fields with the standard `xxx_update` / `xxx_value` / `xxx_state` triple pattern. List-type data uses `X33VDataTypeList` containing typed data beans (`X33VDataTypeBeanInterface`).
2. **Screen Logic** — Extends `JCCWebBusinessLogic`. Implements entry-point methods (`actionInit`, `actionComp`, etc.) and business-specific orchestration. Invokes EJB services via `invokeService()`.
3. **Screen Checker** — Implements `X31SGuiCheckBase`. Often a no-op placeholder; client-side validation is frequently handled at the JSP layer instead.
4. **Screen Const** — Pure constant holder (`public static final String`) providing field keys matching the Japanese display labels used by `loadModelData()` / `storeModelData()`.

### Cross-Cutting Concerns in the Request Lifecycle

`JCCWebBusinessLogic` intercepts every HTTP request through overridden framework hooks:

```
prereceiveMessageWeb()
  -> Skip if keep-alive event
  -> Check request flag
  -> Invoke JCCBusinessControl (online) or JCCBusinessControlApi (API)
  -> Invoke JCCAuthorityCtrl (online) or JCCAuthorityCtrlApi (API)
  -> Set IP address to common info bean
  -> super.prereceiveMessageWeb()

postreceiveMessageWeb()
  -> Skip if keep-alive event
  -> Set up business control status
  -> Set up authority control status
  -> Clear session operation date
  -> Set IP address to common info bean
```

This ensures that **business restriction checks** (is the system in maintenance mode? is the operator's organization restricted?) and **authority checks** (does this user have access to this screen?) run on every single request before any business logic executes.

### Service Invocation Pattern

Screen logics invoke backend services through a uniform pattern:

```java
// 1. Build input map using a DB mapper
KKSV0408_KKSV0408OPDBDBMapper mapper = new KKSV0408_KKSV0408OPDBMapper();
mapper.setKKSV040802SC(paramBean, inputMap);
mapper.setKKSV040803SC(paramBean, inputMap);

// 2. Invoke the service
invokeService(paramMap, inputMap, outputMap);

// 3. Map results back to the form bean
getKKSV040803SC(outputMap, paramBean);
editServiceFormBean();
```

The `invokeService()` method in `JCCWebBusinessLogic` adds custom logic: it detects whether the target is a workflow service (via `chkWksijService`) and uses a specialized invocation path for workflow services, or delegates to the framework's standard `super.invokeService()`. After service execution, it performs electronic file number replacement.

### Data Bean Hierarchies

Form beans use a hierarchical data model. The main bean contains scalar fields plus `X33VDataTypeList` collections, each holding typed child beans:

```
ScreenBean (main form)
  |-- scalar fields (sysid, svc_kei_no, shosa_ymd, etc.)
  |-- svc_kei_list_list [X33VDataTypeList]
  |     +-- [0] Screen01DBean (detail data)
  |-- mskm_dtl_list_list [X33VDataTypeList]
  |     +-- [0] Screen02DBean (application data)
  +-- cust_kei_hktgi_list_list [X33VDataTypeList]
        +-- [0] Screen04DBean (inherited data)
```

Each list is initialized with exactly one element in the bean constructor. Data beans implement `X33VDataTypeBeanInterface`, using Japanese display labels as field keys for reflection-free data access via `loadModelData(key, subkey)`.

### File Upload/Download Architecture

`JCCWebBusinessLogic` provides comprehensive file handling:

- **Upload restriction validation** — Checks file extensions against allow/deny lists (system-wide and per-screen/event), validates zero-byte files, and checks cumulative file sizes.
- **Temporary file management** — Determines whether to store uploaded files in session or HDD based on configuration (`FILEUPLOAD_TEMPORARILY_SESSION`).
- **Archive generation** — Produces ZIP archives with CRC32 checksums for multi-file downloads, using buffered I/O streams.
- **Restriction caching** — Upload/download restrictions are cached in `JCCUploadRestrictionCache` / `JCCDownloadRestrictionCache` to avoid repeated configuration lookups.

## Dependencies and Integration

### Outbound Dependencies (packages imported by this module)

| Dependency | Purpose |
|---|---|
| `eo.common.util` (`JCCFrameworkException`, `JPCEditString`) | Common exception and string utilities |
| `eo.web.webview.common` (`JCCWebCommon`, `JCCBusinessControl`, `JCCAuthorityCtrl`, etc.) | Shared web-layer utilities |
| `eo.web.webview.CommonInfoCF` (`CommonInfoCFBean`, `CommonInfoCFConst`) | Shared context data beans |
| `eo.web.webview.mapping` (`CCSV0001_CCSV0001OPDBMapper`) | Service field mapping |
| `eo.web.webview.KKW00127SF`, `KKA06601SF`, `KKA17101SF`, `KKA17201SF`, `KKA17401SF` | Related screen modules |
| `eo.business.common`, `eo.business.service` | Business domain layer |
| `eo.ejb.common`, `eo.ejb.common.edit` | EJB common components |
| `com.fujitsu.futurity.bp.custom.common` | Fujitsu Futurity framework extensions |
| `com.fujitsu.futurity.web.x31`, `com.fujitsu.futurity.web.x33` | X31/X33 web framework |

### Inbound Dependencies

- `x33VParameterInfo.xml` references `InvConvertParam` for parameter inversion configuration.
- Screen XML configs (e.g., `WEBGAMEN_KKW001910PJP.xml`, `x31business_logic_KKW00191SF.xml`) wire up `KKW00191SFBean` and `KKW00191SFLogic` to the framework.

### Integration with Other Modules

The `eo.web.webview` package connects to the broader system through several channels:

```mermaid
flowchart LR
    A["JSP View"] --> B["Screen Bean
X33VViewBaseBean"]
    B --> C["Screen Logic
JCCWebBusinessLogic"]
    C --> D["CommonInfoCF
Common bean"]
    C --> E["DB Mapper
field mapping"]
    E --> F["Service Layer
KKSVxxxx use case"]
    F --> G["EJB
Session Bean"]
    G --> H["Database"]
    C --> I["JCCWebCommon
shared utilities"]
    C --> J["Business Control
JCCBusinessControl"]
    C --> K["Authority Control
JCCAuthorityCtrl"]
```

### Module Interaction Map

```mermaid
flowchart TD
    A["KKWeb
Screen Modules"] --> B["JCCWebBusinessLogic
Base Class"]
    A --> C["Screen Bean
form data"]
    A --> D["Screen Logic
extends base"]
    A --> E["Screen Checker
validation"]
    A --> F["Screen Const
constants"]
    B --> G["Business Control
restrictions"]
    B --> H["Authority Control
access rights"]
    B --> I["Service Invocation
EJB calls"]
    B --> J["File Upload/Download
file handling"]
    D --> C
    D --> I
    E --> C
    F --> D
    F --> C
    K["CommonInfoCF
shared data beans"] --> B
    L["common subpackage
utilities"] --> B
    M["mapping subpackage
DB mappers"] --> I
    I --> N["EJB Layer
business services"]
    subgraph framework["Fujitsu Futurity Framework"]
        O["X31/X33 web framework"]
    end
    B -.-> O
    C -.-> O
    A -.-> O
    N -.-> O
```

## Notes for Developers

### Screen Development Conventions

- **Always extend `JCCWebBusinessLogic`** for screen logic classes. The base class handles critical cross-cutting concerns (business control, authority control, file handling) that must run on every request.
- **Bean fields use the triple pattern**: `xxx_update` (update flag), `xxx_value` (displayed value), `xxx_state` (editable/readonly/disabled). This is a framework convention enforced by the X31/X33 data binding layer.
- **List beans are initialized with one element** in the constructor. If multi-row display is needed, the initialization pattern changes — but most screens currently display a single record's details.
- **Field keys are Japanese strings** — `CommonInfoCFConst` and screen-specific `Const` classes use Japanese labels as the primary key for data bean access. This is consistent with the framework's `sendMessageString()` / `loadModelData()` API.
- **Checker classes are often no-ops** — `checkMethod()` returning `true` unconditionally is common. Validation logic typically lives in the JSP layer or in business service validation, not in the web-layer checker.

### Date and Time Handling

- Dates arrive from the service layer in `YYYYMMDD` format and are reformatted to `YYYY/MM/DD` display format in the bean's `editServiceFormBean()` method.
- Operation dates are managed through `JCCsvlGetOperationDateUtil`, which clears and validates session-based operation date selection — important for date-dependent business rules.

### File Handling

- File upload/download logic is centralized in `JCCWebBusinessLogic.getFileInfoArray()`. Screen logics should not re-implement file validation.
- Upload restrictions are configurable per-screen and per-event via `gamenID;eventID` keys in the restriction cache.
- ZIP archive generation uses CRC32 checksums for integrity verification.

### Branching Logic Example (KKW00191SF)

The review cancellation screen demonstrates the primary branching pattern:

```
shosa_dsl_fin_cd == CD00469_1 --> invokeService(KKSV0408)  // Normal cancellation
shosa_dsl_fin_cd == CD00469_2 --> shosaNgCl() -> invokeService(KKSV0742)  // NG cancellation
```

When adding new screens with conditional service paths, follow this pattern: check a completion/status code from the inherited data, then invoke the appropriate use case operation.

### Multi-Module Source Layout

Note that `JCCWebBusinessLogic` exists in three source trees (`koptWebFrontCommon`, `koptWebA`, `koptWebB`). These are not separate packages — the same class is deployed across different WAR artifacts. Changes may need to be propagated across all three. The `koptWebB` version tends to be the most up-to-date.

### Address Concatenation

Address fields are stored as individual components (state, city, district, block, lot number) in the bean but are concatenated server-side into display strings (`kaisen_addr`, `keisha_addr`). The individual components remain the authoritative source; concatenated values are display-only.

### API vs Online Path Differentiation

The `prereceiveMessageWeb()` method differentiates between online operator screens and API integration paths using `REQUEST_FLG` and `TARGET_SYSTEM` config. API paths bypass certain online-specific checks and set HTTP 404 for unauthorized access rather than rendering error pages.