# Com / Fujitsu / Futurity / Bp

## Overview

This module represents the **custom business logic layer** for the K-Opticom (eo brand) customer base system — an enterprise application built on Java EE by Fujitsu. Located under `com.fujitsu.futurity.bp.custom`, it serves as the bridge between web-facing client applications and the underlying data persistence infrastructure. The code handles a wide range of telecommunications customer lifecycle operations including new customer registration, customer information updates, service contract management, billing inquiries, guarantor coordination, and external system integration with the PMP (Customer Information Platform).

The module follows a strict three-tier layered architecture driven by a BPM (Business Process Model) framework (version 3.2.0.a / BPMXML 2.6):

1. **Flow layer** — Stateless EJB entry points that orchestrate overall process flow
2. **Operation layer** — Business operation classes that execute sequential steps
3. **Common Component (CC) layer** — Reusable business logic classes
4. **Mapping layer** — Data transformation classes between the BPM layer and Service Components (SC)

All Flow and OPOperation classes are **code-generated** from BPMXML templates, indicating a model-driven development approach where the business process definitions are authored separately and compiled into Java classes.

## Sub-module Guide

### BPM Processes (`bpm/`)

The `bpm/` directory contains approximately **70+ distinct process definitions**, organized into three named sub-packages. Each sub-package groups flows by a functional prefix convention.

#### `bpm/acsv` — A-CSV Flows (~39 flows)

Named with the `ACSV` prefix, this is the largest group. These flows appear to handle **application-side CSV processing and registration screens**. A representative example is `ACSV0001`, which handles temporary gold registration screen information retrieval. These flows tend to have more complex Operation classes (some exceeding 58,000 bytes) because they coordinate multiple Service Component calls and CC invocations.

Key responsibilities include:
- Screen data retrieval and pre-processing
- Temporary registration workflows
- Customer information display operations
- Pricing simulation data gathering

#### `bpm/ccsv` — C-CSV Flows (~11 flows)

Named with the `CCSV` prefix, these flows handle **common and electronic file management screens**. `CCSV0001`, for example, implements the electronic file management service consent screen operation. These flows are typically smaller and more focused — often executing a single Service Component call wrapped in the standard Flow-Op pattern.

Key responsibilities include:
- Electronic file management service agreements
- Common screen operations
- System maintenance and logging operations

#### `bpm/chsv` — H-CSV Flows (~22+ flows)

Named with the `CHSV` prefix, these flows handle **high-priority / household (kaizu) service operations**. `CHSV0001` is described as a guarantor company screen operation (`保証照会OP`). These include some of the most complex operations in the codebase — `CHSV0019OPOperation` is over 39,000 bytes, and `CHSV0007OPOperation` exceeds 31,000 bytes.

Key responsibilities include:
- Guarantor company inquiries and coordination
- Service contract information display
- Customer history retrieval
- Complex multi-step business transactions

### Common Components (`common/`)

The `common/` directory contains **100+ reusable business component classes** organized by functional prefix:

| Prefix | Area | Examples |
|--------|------|----------|
| `JCK*` | Customer management | Registration (`JCKSV902201CC`), customer info updates, list searches, customer group management |
| `JCH*` | Service/household operations | Customer info display, pricing, response records, bank info, service contracts |
| `JAC*` | Advanced/complex logic | Pricing simulation, billing details, contract management, after-hours reports |
| `JCC*` | Common utilities | Customer card, network, common operations |
| `JCHB*` | Business helpers | Bank info status, pricing adjustments |

`JCKPmpCommonUtil` is the central shared utility for PMP integration, providing standardized patterns for:
- Service Component invocation (`scCallRun`)
- Result extraction from request parameters
- External system calls (PMP coordination, last update time retrieval)
- Debug logging

`JCCBPCommon` and `JCKBPCommon` are smaller utility classes providing date handling, operation date retrieval, and shared constants.

### Data Mapping (`mapping/`)

The `mapping/` directory contains **150+ mapper classes** responsible for data transformation between the BPM/CC layer and the Service Component (SC) persistence layer. Mappers follow a naming convention: `PROCESSID_OPERATIONID_TARGETBSMapper.java`.

Each mapper:
- Converts between BPM request parameter maps and SC-specific message DTOs (e.g., `ECH0011B012CBSMsg`)
- Handles bidirectional data conversion (input mapping and output mapping are sometimes split into separate mapper files)
- Is referenced by the OPOperation class through `ServiceComponentBroker`

## Key Patterns and Architecture

### Template-Driven Code Generation

Every Flow and OPOperation class carries a header:

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

The architecture separates **process definitions** (stored in BPMXML format) from **Java implementation**. The template engine generates:
- Flow classes that extend `AbstractService` (a stateless EJB with `@Stateless` annotation)
- Operation classes that extend `AbstractOperation`

This means the business process structure is defined declaratively, and developers modify the templates or BPMXML to generate new flows rather than hand-writing boilerplate.

### Standard Execution Flow

Every process follows a consistent three-phase pattern:

```
Flow.run()
  ├── Common CC: mappingInit (pre-processing)
  ├── Operation: [ACSV/CCSV/CHSV]OP.execute()
  │     ├── Step 1: ServiceComponentBroker → SC call
  │     ├── Step 2: ServiceComponentBroker → SC call (if needed)
  │     ├── Step 3: CCRequestBroker → CC call (if needed)
  │     └── ... additional steps
  └── Common CC: mappingDispose (post-processing)
```

The Flow class orchestrates this using a `BPMOperator`, which manages:
- `DBConnectionInfo` setup per step
- `ServiceComponentBroker` invocation for persistence
- `CCRequestBroker` invocation for business logic
- Exception judgment via pluggable `ExceptionJudge` classes

### Two Broker Types

The OPOperation layer uses two broker types depending on what needs to be executed:

- **ServiceComponentBroker** — Wraps a remote Service Component call. Used for DB persistence operations. Requires DB connection info setup and is bound to a specific SC process name (e.g., `ACSV000101SC`).

- **CCRequestBroker** — Invokes a local Common Component method directly. Used for business logic that doesn't need direct DB access. References a specific CC class and method name (e.g., `JCHGetPrcKmkCsChgeListCC.getPrcKmkCsChgeList`).

### Conditional Execution

Some OPOperation classes (notably `CHSV0001`) use `ExeCondition` objects to implement **conditional branching** within the operation flow. Each step can be annotated with conditions (e.g., `cust_type = "カスタム"`) that determine whether the step executes, enabling dynamic process paths from the same code.

### Exception Judgment Hierarchy

The framework distinguishes three levels of exception judgment:
- **DefaultCCExceptionJudge** — For Common Component errors
- **DefaultSCExceptionJudge** — For Service Component errors
- **DefaultCCExceptionJudge (mapping)** — For pre/post-processing errors

Each step in an OPOperation specifies its own exception judge class array, allowing fine-grained error handling per step.

## Dependencies and Integration

### Internal Dependencies

- **Fujitsu BPM Framework** (`com.fujitsu.futurity.bp.x21.*`) — The 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 module integrates with an external Customer Information Platform for customer data synchronization, using `JCKPmpCommonUtil` as the standardized integration layer.
- **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.

### Architecture Diagram

```
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-to-Operation Interaction

```
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 → SC]
        SC2[ServiceComponent
Broker → SC]
        CC1[CC Request
Broker → CC]
        CC2[CC Request
Broker → CC]
    end

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

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

## 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 the 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. The BPMXML definition creates: `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

- Flow classes: `{PREFIX}{NNNN}Flow` — e.g., `ACSV0001Flow`
- Operation classes: `{PREFIX}{NNNN}OPOperation` — e.g., `ACSV0001OPOperation`
- Mappers: `{PREFIX}{NNNN}_{OPNAME}_{TARGET}Mapper` — e.g., `ACSV0001_ACSV0001OP_ECH0401B010BSMapper`
- CC classes: `J{AREA}{DESCRIPTION}CC` — e.g., `JCKSV902201CC`

### Large Files

Several Common Component classes exceed 100,000 bytes (e.g., `JCHTushinSvcPrcChohyoCC` at ~500KB, `JCHZuijiNkinAddCC` at ~299KB, `JACSeikyUpdCC` at ~105KB). These appear to handle complex, multi-step business operations. Exercise caution when modifying these — they are high-coupling classes that touch many data paths.

### Logging

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

### Transaction Management

Flow classes are `@Stateless` EJBs with `TransactionManagementType.BEAN`, meaning transaction boundaries are controlled explicitly through the BPM framework. The `DBConnectionInfo` constructed for each step determines transaction scope.