# Eo / Web

## Overview

The `eo.web` package is 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 sits between the JSP view layer and the EJB service layer. Every screen follows a consistent four-class pattern — a **Bean** (form data holder), a **Logic** class (business orchestrator), a **Checker** (validation stub), and a **Const** class (field key constants). A shared base class, `JCCWebBusinessLogic`, provides cross-cutting capabilities including file handling, session management, business restriction enforcement, and authority control that every screen inherits.

Built on top of the **Fujitsu Futurity X31/X33 web framework**, the package provides structured page lifecycle management, form bean handling, and business logic delegation. At its core, it is an operator-facing web application where telecom service representatives perform service agreements, contract changes, reviews, and cancellations through a standardized screen interface.

## Sub-module Guide

The `eo.web` module is organized around the **webview** sub-module, which serves as the primary entry point and shared infrastructure for all operator screens.

### Webview — The Central Screen Infrastructure

The `eo.web.webview` package is the backbone of the web presentation layer. It contains three distinct concerns:

- **Shared base classes** — `JCCWebBusinessLogic` (the central base class every screen logic extends) and `InvConvertParam` (an integration adapter for external system parameter conversion).
- **Screen modules** — Operator-facing screens organized into sub-packages (`KKWxxxxSF`, `ACWxxxxSF`, `CHWxxxxSF`, etc.), each following the four-class pattern. The most extensively documented screen is `KKW00191SF` (Review Cancellation), which branches between normal and NG-specific cancellation workflows based on a review status code.
- **Shared infrastructure subpackages** — `CommonInfoCF` (73+ data beans carrying session and navigation context across screens), `common` (business control, authority control, web utilities, restriction caches), and `mapping` (database mappers that transform form data for service layer consumption).

These pieces relate tightly: the shared infrastructure subpackages exist to serve the screen modules. Every screen logic class delegates to `JCCWebBusinessLogic` for cross-cutting concerns (business control, authority checks, file handling), while `CommonInfoCF` beans carry contextual state (user identity, authorization tokens, navigation history) across screen transitions. The `mapping` subpackage bridges the gap between the web-form bean data structures and the input maps expected by EJB services.

## Key Patterns and Architecture

### Three-Layer Screen Pattern

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

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

1. **Screen Bean** — Holds all display data as fields with the standard `xxx_update` / `xxx_value` / `xxx_state` triple pattern. List-type data uses `X33VDataTypeList` containing typed child beans.
2. **Screen Logic** — Extends `JCCWebBusinessLogic` and implements entry-point methods (`actionInit`, `actionComp`, etc.). Orchestrates business logic and invokes EJB services.
3. **Screen Checker** — Often a no-op placeholder; client-side validation is frequently handled at the JSP layer.
4. **Screen Const** — Pure constant holder providing field keys matching the Japanese display labels used by the framework's data binding API.

### Cross-Cutting Concerns in the Request Lifecycle

`JCCWebBusinessLogic` intercepts every HTTP request through overridden framework hooks. On each request, it runs **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?) before any business logic executes. This ensures consistent security and operational policy enforcement across all screens without requiring individual screen implementations to duplicate these checks.

### Service Invocation Pattern

Screen logics invoke backend services through a uniform three-step pattern:

1. Build an input map using a DB mapper class that transforms form bean fields.
2. Invoke the service through the centralized `invokeService()` method in `JCCWebBusinessLogic`, which adds custom logic such as workflow service detection.
3. Map results back to the form bean.

The centralized invocation method also detects whether the target is a workflow service and uses a specialized invocation path for workflow services, and performs electronic file number replacement after execution.

### Data Bean Hierarchies

Form beans use a hierarchical data model. The main bean contains scalar fields plus typed list collections, each holding child data beans. Each list is initialized with exactly one element in the bean constructor. Data beans use Japanese display labels as field keys for reflection-free data access, consistent with the framework's `sendMessageString()` / `loadModelData()` API.

### File Upload/Download Architecture

File handling is centralized in `JCCWebBusinessLogic.getFileInfoArray()`. Screen logics delegate to this method rather than re-implementing file validation. The architecture handles upload restriction validation (file extensions, zero-byte checks, cumulative sizes), temporary file management (session vs. HDD), ZIP archive generation with CRC32 checksums, and caches restrictions in dedicated cache classes to avoid repeated configuration lookups.

## Dependencies and Integration

### Outbound Dependencies

| Dependency | Purpose |
|---|---|
| `eo.common.util` | Common exception and string utilities |
| `eo.web.webview.common` | Shared web-layer utilities (business control, authority control, web common) |
| `eo.web.webview.CommonInfoCF` | Shared context data beans (73+ beans for cross-screen state) |
| `eo.web.webview.mapping` | Service field mapping |
| `eo.business.common`, `eo.business.service` | Business domain layer |
| `eo.ejb.common`, `eo.ejb.common.edit` | EJB common components |
| `com.fujitsu.futurity.web.x31`, `com.fujitsu.futurity.web.x33` | X31/X33 web framework |

### Integration Diagram

```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** — constant classes use Japanese labels as the primary key for data bean access, consistent with the framework's API.
- **Checker classes are often no-ops** — 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.

### 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. 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.