# Com

## Overview

The `com` package serves as the top-level namespace for the **K-Opticom (eo brand)** enterprise telecommunications platform — a Java EE application built by Fujitsu for customer lifecycle management. This umbrella namespace covers multiple business domains, most notably the Fujitsu-specific business process layer under `com.fujitsu`.

The `com` module acts as the bridge between web-facing client applications (customer, enterprise, resident, finance, and REST portals) and the underlying data persistence infrastructure (Service Components and the PMP customer information platform). It implements customer registration, information updates, contract management, billing, guarantor coordination, and external system integration through a model-driven business process approach.

This area of the codebase is built on a model-driven architecture: business process definitions are authored declaratively in BPMXML templates and compiled into Java classes via the Fujitsu BPM Framework (version 3.2.0.a, BPMXML 2.6), keeping business logic separate from framework boilerplate.

## Sub-module Guide

### `com.fujitsu` — Business Process Engine

The `com.fujitsu` sub-package forms the core business process layer. It does not contain independently indexed source files at its top level; instead, all its logic lives within child sub-modules that implement the Fujitsu BPM (Business Process Model) framework for orchestrating customer-facing workflows.

The primary child module is `com.fujitsu.futurity.bp`, organized into four architectural tiers:

| Tier | Package | Role |
|---|---|---|
| Flow | `bpm/` | Stateful EJB entry points (`AbstractService` subclasses). Grouped into three functional domains: ACSV (~39 processes), CCSV (~11 processes), CHSV (~22 processes) |
| Operation | `bpm/` | `AbstractOperation` subclasses that execute sequential steps within a process |
| Common Component | `common/` | Over 100 reusable business logic classes for shared operations |
| Mapping | `mapping/` | 150+ mapper classes transforming data between BPM layer and Service Component DTOs |

**Relationship between components:** The ACSV, CCSV, and CHSV flow groups share the same Common Component pool and mapping infrastructure — they differ only in their BPMXML process definitions and which specific CC/mapper combinations they invoke. This means adding a new process (e.g., `ACSV0040`) is a matter of defining a new BPMXML template and generating flow/operation classes, without modifying framework infrastructure. The three flow prefixes represent distinct functional domains (registration screens, system maintenance, and complex guarantor coordination) that converge on the same underlying execution engine.

## Key Patterns and Architecture

### Template-Driven Code Generation

Every Flow and OPOperation class is generated from BPMXML templates:

```java
// GENERATED BY TEMPLATE VERSION 3.2.0.a
// BASED ON BPMXML VERSION 2.6
```

This model-driven approach means the business process structure is defined separately from its implementation. Developers modify BPMXML or template definitions to create or modify flows rather than hand-writing boilerplate flow code. The generated classes extend `AbstractService` (`@Stateless`) for flows and `AbstractOperation` for operations. Common Components, mapping classes, and utilities are hand-written.

### Standard Three-Phase Execution

Every business process follows a consistent lifecycle:

```
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
```

The Flow class delegates to a `BPMOperator` which manages `DBConnectionInfo` setup, broker invocations, and exception judgment across steps.

### Two Broker Types for Cross-Cutting Concerns

- **ServiceComponentBroker** — Wraps remote Service Component calls for database persistence. Bound to a specific SC process name and requires explicit `DBConnectionInfo` setup per step.
- **CCRequestBroker** — Invokes local Common Component methods directly for business logic that does not need direct database access. References a specific CC class and method.

### Conditional Execution and Granular Exception Handling

Operations can use `ExeCondition` objects to implement conditional branching — steps annotated with conditions (e.g., checking `cust_type`) determine dynamically 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.

### Architecture Diagram

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

```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.
- **Fujitsu Model Layer** (`com.fujitsu.futurity.model.*`) — Data transfer objects used throughout.
- **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 container-managed transactions. 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.