# Root

## Overview

This is the top-level namespace for the **K-Opticom (eo brand)** enterprise telecommunications platform — a Java EE application built by Fujitsu for end-to-end customer lifecycle management. At the root level, the codebase does not contain directly indexed source files, classes, or methods; instead, it serves as the umbrella under which business-domain packages such as `com` are organized.

The platform spans multiple customer-facing portals (web and REST) and integrates with an external customer information platform (PMP). All business logic is driven by a model-driven, template-generated architecture based on the Fujitsu BPM Framework, where processes are defined in declarative BPMXML templates and compiled into Java at build time.

The root module's purpose is to house and coordinate these domain packages. It currently has no source files indexed directly under it — its role is structural, providing the top-level namespace hierarchy that packages like `com` descend from.

## Sub-module Guide

### `com` — Business Process and Customer Lifecycle Management

The `com` package is the most prominent and fully documented child module. It acts as the bridge between web-facing client applications and the underlying data persistence infrastructure. Its responsibilities include:

- **Customer registration, updates, and contract management** — handled through the `com.fujitsu` business process layer
- **Billing and guarantor coordination** — via Common Component (CC) classes
- **External system integration** — through PMP platform sync and Service Component messaging

The `com.fujitsu.futurity.bp` sub-package is organized into four architectural tiers:

| Tier | Role |
|---|---|
| Flow | Stateless EJB entry points grouped by process family (ACSV, CCSV, CHSV) |
| Operation | Sequential step executors within each process |
| Common Component | 100+ reusable business-logic classes shared across all process families |
| Mapping | 150+ data-transform classes between the BPM layer and Service Components |

**How these tiers relate:** A single customer registration flow (e.g., `ACSV0001`) enters through a Flow class, delegates to an Operation class, which in turn calls CC classes for business rules and Mappers for data transformation. Both CCs and Mappers ultimately communicate with external Service Components for database persistence. The three process families (ACSV, CCSV, CHSV) share the same CC and Mapping infrastructure, differing only in which specific CC/mapper combinations they invoke and the BPMXML process definitions that orchestrate them. This means new processes can be added by defining new BPMXML templates without modifying the framework code.

## Key Patterns and Architecture

### Template-Driven Code Generation

The most significant architectural decision in this codebase is its reliance on model-driven design. Flow and Operation classes are **generated from BPMXML templates** (version 2.6, using Fujitsu BPM Framework 3.2.0.a). Business analysts or engineers define the process structure declaratively in BPMXML, and the framework generates the Java boilerplate. The generated classes extend `AbstractService` (as `@Stateless` EJBs) for flows and `AbstractOperation` for operations.

This approach means:
- Business process logic lives in BPMXML, not in hand-written Java
- Generated classes should **never be hand-edited** — changes are overwritten on the next generation
- Common Component classes and Mapper classes are **hand-written** and are the primary modification points

### Standard Three-Phase Execution Model

Every business process follows a consistent lifecycle that developers can rely on when tracing execution:

```
Flow.run()
  |-- Pre-processing: Common CC -- mappingInit
  |-- Operation: OPOperation.execute()
  |   |-- Step 1: ServiceComponentBroker -> SC call
  |   |-- Step 2: ServiceComponentBroker -> SC call (if needed)
  |   |-- Step 3: CCRequestBroker -> CC call (if needed)
  |   `-- ... additional steps
  `-- Post-processing: Common CC -- mappingDispose
```

### Dual-Broker Architecture

The system uses two distinct broker patterns for cross-cutting concerns:

- **ServiceComponentBroker** — Wraps remote Service Component calls for database persistence. Each broker invocation requires explicit `DBConnectionInfo` setup and controls transaction scope.
- **CCRequestBroker** — Invokes local Common Component methods directly for business logic that does not require database access.

This separation of concerns means business rules (CC) and data persistence (SC) are cleanly decoupled, even though they share the same invocation pattern from operations.

### Conditional Execution and Granular Exception Handling

Operations support dynamic branching via `ExeCondition` objects — steps annotated with conditions (e.g., checking `cust_type`) determine at runtime whether a step executes. Exception handling is granular per step: each step specifies its own `ExceptionJudge` class array with three tiers — `DefaultCCExceptionJudge` for Common Component errors, `DefaultSCExceptionJudge` for Service Component errors, and a mapping-specific exception judge.

### System Architecture

The following diagram shows how the web application layer, EJB module, and external systems interact:

```mermaid
flowchart TD
    subgraph Client["Web Application Layer"]
        WebA["WebA
(eo customer front)"]
        WebB["WebB
(enterprise front)"]
        WebR["WebR
(resident front)"]
        WebF["WebF
(finance front)"]
        WebRest["WebRest
(REST API)"]
    end

    subgraph EJB["EJB Module
koptBp"]
        subgraph BPM["Business Process Model"]
            Flow["Flow classes
ACSV/CCSV/CHSV
entry points"]
            Op["Operation classes
OPOperation
execute steps"]
        end

        subgraph CC["Common Component Layer"]
            CC_Base["Shared utilities
JCKPmpCommonUtil
JCCBPCommon etc."]
            CC_Business["Business logic
JCKSV902201CC
customer registration
JCH* customer info
JCK* customer management"]
        end

        subgraph Mapping["Data Mapping Layer"]
            Mapper["BSMapper classes
ACSV0001_*Mapper
convert between BPM
and Service Components"]
        end

        Flow --> Op
        Op --> CC
        Op --> Mapper
        Mapper --> CC
        CC --> CC_Base
    end

    subgraph External["External Systems"]
        PMP["PMP Platform
customer info platform"]
        SC["Service Components
DB persistence"]
    end

    CC --> PMP
    CC --> SC
    Mapper --> SC
```

### Flow Execution Detail

The following diagram illustrates the step-by-step execution of a single business process:

```mermaid
flowchart LR
    Client["Web Screen
Request"] --> Flow["Flow Class
@Stateless
AbstractService"]

    subgraph FlowPhases["Flow Execution Phases"]
        MI["Pre-processing
mappingInit"]
        OP["Operation
OPOperation
AbstractOperation"]
        MD["Post-processing
mappingDispose"]
    end

    Flow --> MI --> OP --> MD

    subgraph OpSteps["Operation Internal Steps"]
        SC1["ServiceComponent
Broker to SC"]
        SC2["ServiceComponent
Broker to SC"]
        CC1["CC Request
Broker to CC"]
        CC2["CC Request
Broker to CC"]
    end

    OP --> SC1 --> SC2
    OP --> CC1 --> CC2

    SC1 --> DB[(Database)]
    SC2 --> DB
    CC1 --> DB
    CC2 --> DB
```

## Dependencies and Integration

### Internal Dependencies

- **Fujitsu BPM Framework** (`com.fujitsu.futurity.bp.x21.*`) — Core process engine providing `AbstractService`, `AbstractOperation`, `BPMOperator`, `ServiceComponentBroker`, `CCRequestBroker`, `RequestParameter`, and exception handling infrastructure.
- **Fujitsu Model Layer** (`com.fujitsu.futurity.model.*`) — Data transfer objects used throughout the business process layer.
- **eo Common Layer** (`eo.common.*`, `eo.ejb.*`) — Utility classes for string handling, date manipulation, logging, and shared constants from the broader K-Opticom platform.

### External Integration

- **PMP Platform** — The external Customer Information Platform for customer data synchronization. The `JCKPmpCommonUtil` class provides the standardized integration layer, including service component invocation, result extraction, and debug logging.
- **Service Components** — The mapping layer translates BPM data into SC messages (classes like `ECH*CBSMsg`, `ECK*CBSMsg`, `EKK*CBSMsg`, `EZM*CBSMsg`) which handle actual database operations.

### Transaction Management

Flow classes are `@Stateless` EJBs with `TransactionManagementType.BEAN`, meaning transaction boundaries are controlled explicitly through the BPM framework rather than by the EJB container. Each `DBConnectionInfo` constructed for a step determines the transaction scope, allowing granular control over where transaction boundaries fall within a multi-step business process.

## Notes for Developers

### Working with Generated Code

- Flow and OPOperation classes are **generated from BPMXML templates**. Do not hand-edit these files directly — changes will be overwritten on the next generation. If you need to modify a business process, update the BPMXML or template definitions.
- Common Components (CC), mapping classes, and utility classes are **hand-written** and can be modified freely.

### Adding a New Process

To add a new process (e.g., `ACSV0040`):

1. Define the process in BPMXML — this generates `bpm/acsv0040/ACSV0040Flow.java` and `bpm/acsv0040/ACSV0040OPOperation.java`
2. Add the corresponding Service Component calls to the generated OPOperation class (or define them in BPMXML)
3. Create `ACSV0040_ACSV0040OP_*BSMapper.java` files in the `mapping/` directory for data transformation
4. If new business logic is needed, create a new CC class in `common/`

### Naming Conventions

| Component Type | Pattern | Example |
|---|---|---|
| Flow classes | `{PREFIX}{NNNN}Flow` | `ACSV0001Flow` |
| Operation classes | `{PREFIX}{NNNN}OPOperation` | `ACSV0001OPOperation` |
| Mappers | `{PREFIX}{NNNN}_{OPNAME}_{TARGET}Mapper` | `ACSV0001_ACSV0001OP_ECH0401B010BSMapper` |
| CC classes | `J{AREA}{DESCRIPTION}CC` | `JCKSV902201CC` |

### Large Files and High-Coupling Classes

Several Common Component classes exceed 100,000 bytes — for example, `JCHTushinSvcPrcChohyoCC` at ~500KB, `JCHZuijiNkinAddCC` at ~299KB, and `JACSeikyUpdCC` at ~105KB. These handle complex, multi-step business operations and are high-coupling classes touching many data paths. Exercise caution when modifying these.

### Logging

All Flow and Operation classes use `JSYbpmLog` for process-level logging. Standard log levels include `JSYLogBase.EXECUTION` for service start/end messages and `JSYLogBase.DEBUG` for step-level debug information.