# Eo / Ejb / Cbs

## Overview

The `eo.ejb.cbs` package is the **Customer Business Service** layer within the eo customer core system (`eo顧客基幹システム`), a telecommunications customer management platform originally developed by Fujitsu for K-Opticom (now part of KDDI's "eo" brand). This module serves as the central bridge between the BPM (Business Process Management) operation layer and external/legacy services. It is responsible for receiving CBS message schemas from BPM operations, executing the corresponding business processing logic (often calling REST or HTTP-based APIs), and returning structured responses.

The module follows a clear two-layer split between message definitions and processing logic, enabling each CBS service (identified by a template ID such as `EKKA1880001`) to be defined, implemented, and invoked independently.

## Sub-module Guide

The module is organized into two sub-packages:

### `cbsmsg` — Message Schema Definitions

The `cbsmsg` directory holds hundreds of Java classes that define the message schemas used by each CBS service. Each service typically has two associated classes:

- A **message class** (e.g., `EKKA1880001CBSMsg`) that extends `CAANSchemaInfo` and defines the template item array mapping field names to types, plus constants for field keys.
- A **message list class** (e.g., `EKKA1880001CBSMsg1List`) that defines the schema for array/detail sub-elements within the message.

The naming convention encodes the service domain and identifier:

- `E` prefix — Customer Business Service message
- `AC` / `CC` / `CH` / `CK` / `CR` / `CKA` / `CNA` / `DK` — domain prefixes indicating the functional area (e.g., `AC` = account, `CC` = contract, `CH` = customer home, `CK` = service plan, `CR` = registration, `CNA` = network access)
- Numeric segment — unique service identifier
- Suffix like `CBSMsg` or `CBSMsg1List` / `CBSMsg2List` — indicates top-level message vs. detail lists

These message classes also support nested lists (`CBSMsg2List`, `CBSMsg3List`, etc.) for complex multi-level message structures.

### `mainproc` — Main Processing Handlers

The `mainproc` directory contains the implementation classes for each CBS service's processing logic. Each class (e.g., `JEKKA1880001TPMA`) implements the `TemplateMainHandler` interface and is responsible for:

1. Receiving a `CAANMsg` (the CBS message) populated with input data from the BPM layer.
2. Performing field-level validation (mandatory checks, format checks, row count checks).
3. Reading configuration values (URLs, auth tokens, timeouts) from system settings tables.
4. Invoking external services — often via HTTP REST APIs (e.g., SMS push services, mansion management APIs).
5. Returning structured results back in the `CAANMsg` response object.

The naming convention for processing classes is `J` + domain code + service ID + `TPMA` (e.g., `JEKKA1880001TPMA`, `JECNA0010001TPMA`). Not all message classes have corresponding main processing classes; some CBS services may be handled through other mechanisms.

### How the Sub-modules Relate

The two sub-packages work in a **define-then-execute** relationship:

1. A CBS service is first **defined** in `cbsmsg` by specifying its request and response message schemas.
2. The processing logic in `mainproc` is implemented against those same schemas, reading input fields by their constant keys and populating output fields.
3. BPM operations (in the `koptBp` module) construct `CAANMsg` objects using the `cbsmsg` classes, pass them to the `mainproc` handler, and then read the response using the same schema definitions.

This means the `cbsmsg` classes act as the **contract** between layers — changes to a message schema require corresponding updates to the handler that reads/writes those fields.

## Key Patterns and Architecture

### Template-based Service Invocation

Each CBS service is identified by a template ID (e.g., `EKKA1880001`). This template ID is embedded in the CBS message as a field and used throughout the processing pipeline for routing, logging, and configuration lookup.

### CAANMsg Data Flow

All messages flow through the `CAANMsg` object, a structured message container from the Fujitsu Futurity framework:

```
BPM Operation → CAANMsg (input) → mainproc handler → CAANMsg (output) → BPM Operation
```

The handler reads input data from the `CAANMsg`, performs business logic (often HTTP API calls), and writes results back. Field access uses constant strings defined in the corresponding `cbsmsg` class.

### External Service Integration Pattern

The main processing classes typically follow this pattern for external service calls:

1. Read configuration parameters (URL, auth token, timeouts) from system settings.
2. Build a JSON payload from the `CAANMsg` fields.
3. Set HTTP headers (`Authorization`, `Content-Type` as `application/json`).
4. Execute an HTTP POST to the target service URL.
5. Parse the JSON response and map fields back to the `CAANMsg`.
6. Handle errors with specific error codes (E1-E3 for validation, EA for config errors, EB for response errors, EC for runtime errors).

### Stub/Test Mode Support

Several handlers include stub mode support (`STUB_HTTP_STATUS_KEY`, `DUMMY_AUTHORIZATION`) for development and testing without hitting real external endpoints.

## Dependencies and Integration

### Upstream Consumers

The `eo.ejb.cbs` module is consumed by a wide range of modules across the system:

- **BPM Operations** (`koptBp/ejbModule/com/fujitsu/futurity/bp/custom/bpm/`) — dozens of operation classes (e.g., `KKSV0154OPOperation`, `KKSV0202OPOperation`, `KKSV0097OPOperation`) import `cbsmsg` classes and call `mainproc` handlers.
- **Mapping Classes** (`koptBp/ejbModule/com/fujitsu/futurity/bp/custom/mapping/`) — classes like `KKSV0980_KKSV0980OP_EKKA1880001BSMapper` bridge the BPM layer to CBS services, implementing `IInputMessageEditor`/`IOutputMessageEditor`.
- **Common Components** (`koptBp/ejbModule/com/fujitsu/futurity/bp/custom/common/`) — shared component classes (e.g., `JKKGetMansionKanriInfoCC`) invoke CBS handlers for reusable functionality.
- **Web View Layers** (`koptWebR/src/eo/web/webview/`) — many web view logic classes reference `*CBSMsg1List` constants from the parent package for data binding.

### Internal Dependencies

Within the `koptModel` module, `eo.ejb.cbs` depends on:

- `eo.common` — string utilities (`JCHStringUtil`), constants (`JPCModelConstant`, `JFUStrConst`)
- `eo.ejb.common` — database security processing (`JKKejbKK3351SecProc`)
- `com.fujitsu.futurity.model` — `CAANMsg`, `CAANSchemaInfo`, `StatusCodes`, `TemplateMainHandler`, Jackson JSON libraries

## Notes for Developers

- **No child wiki pages exist for this module's source files** — the `cbsmsg` and `mainproc` directories contain hundreds of auto-generated classes, each of which has its own class-level Javadoc. The `cbsmsg` classes are generated from BPMXML templates (version 2.6), and the `mainproc` classes are hand-written implementations.
- **Changes require coordinated updates** — when adding or modifying a CBS message field, you must update the `cbsmsg` schema class and every `mainproc` handler that reads or writes that field.
- **Error codes are standardized** — each handler uses the same error flag convention (E1 = mandatory check, E2 = domain check, E3 = row count check, EA = config error, EB = response error, EC = runtime error).
- **The module is part of a large, long-lived codebase** — source files date back to 2011 and have undergone continuous updates through 2025. The version history headers (e.g., `v75.00.00 2025/03/26`) reflect incremental feature additions (NTT decommissioning, home gateway changes, Netflix integration, etc.) rather than major refactors.
- **No class-level symbols are indexed in the codebase tooling** — this is because the module primarily consists of data schema classes and template-implemented handlers rather than complex object-oriented hierarchies.

## Module Interaction

```
flowchart TD
    A["BPM Operations
koptBp"] -->|"Defines"| B["CBS Message Layer
eo.ejb.cbs.cbsmsg"]
    A -->|"Calls"| C["Main Processing
eo.ejb.cbs.mainproc"]
    B -->|"Schema contract for"| C
    C -->|"Implements"| D["TemplateMainHandler
interface"]
    D -->|"Invokes"| E["External Services
REST/HTTP APIs"]
    B -->|"Referenced by"| F["Web View Layers
koptWebR"]
    C -->|"Writes CAANMsg response"| A
```

The diagram above shows the relationship between the CBS module's sub-packages and the consuming layers. BPM operations own the workflow orchestration, define message structures via `cbsmsg` classes, delegate to `mainproc` handlers for service-level processing, and receive structured results back through `CAANMsg`.