# Com / Optage

## Overview

The `com.optage` package is a subpackage within the Optage platform that supports core banking and financial processing workflows. It centers on SOD (Start of Day) operations — the set of automated routines that validate, dispatch, and notify across subsystems before the business day begins. The architecture is deliberately layered, separating batch entry-points, business-process orchestration, contract processing, external notifications, and data-transfer objects into distinct sub-packages that communicate through well-defined interfaces.

At the moment, all classes within the subpackages are auto-generated fixture stubs intended for SPEC-SCOPED-WIKI automated tests and wiki-generation tooling. However, the class structure, method signatures, and inter-package dependencies are fully designed — providing a stable API surface against which test infrastructure can operate well before production logic is implemented.

## Sub-module Guide

The `com.optage` package currently has one documented child module:

### `com.optage.kopt`

The **Kopt** subpackage is the most fully structured area of `com.optage`. It handles SOD dispatch and validation through seven internal sub-packages, each with a distinct responsibility:

| Sub-package | Responsibility |
|---|---|
| `batch` | Public entry points for triggering batch operations |
| `bp` (business processing) | Orchestrates SOD dispatch and validation workflows |
| `ekk` (contract processing) | Handles contract operations and triggers downstream notifications |
| `kkw` (notifications) | Receives notification triggers from EKK |
| `dto` | Lightweight request/response containers for SOD operations |
| `esc` | Future-facing stub for an Engine Service Controller feature |
| `unrelated` | Isolated placeholder classes for tooling validation |

These sub-packages form a **top-down pipeline**:

1. Callers (external schedulers or UI layers) construct a `JKKSodRequestDTO` and invoke the business processing layer.
2. The business processing layer (`bp`) coordinates validation (delegating to the batch layer) and dispatch (creating a send handler).
3. If batch execution is required, the batch layer (`batch`) delegates to contract processing (`ekk`).
4. Contract processing may trigger notifications (`kkw`) as a downstream side effect.
5. Results flow back through the layers as a `JKKSodResponseDTO`.

```mermaid
flowchart TD
    subgraph Kopt["com.optage.kopt"]
        subgraph Batch["Batch Layer"]
            B1["KKPRC14901"]
            B2["KKPRC24901"]
            B3["KKPRC34901"]
        end
        subgraph Bp["Business Processing"]
            BP1["JKKHakkoSODCC"]
            BP2["JKKSodSendCC"]
            BP3["JKKHakkoSODHelper"]
            BP4["JKKBpServiceBase"]
        end
        subgraph Ekk["Contract Processing"]
            E1["EKK0301A010"]
            E2["EKK0301A020"]
        end
        subgraph Kkw["KKW Notifications"]
            K1["KKW0100B001"]
        end
        subgraph Dto["Data Transfer"]
            D1["JKKSodRequestDTO"]
            D2["JKKSodResponseDTO"]
        end
        subgraph Esc["ESC Control"]
            ESC1["ESC0101B001"]
        end
        subgraph Unrelated["Test Fixtures"]
            U1["XYZ99999Unrelated"]
        end
    end

    BP1 -->|"dispatch() sends"| BP2
    BP1 -->|"validate() calls"| B1
    B1 -->|"process() delegates"| E1
    E1 -->|"notify() triggers"| K1
    BP3 -->|"format() supports"| BP1
    D1 -->|"consumed by"| BP1
    D2 -->|"produced by"| BP1
    U1 -->|"isolated fixture"| Kopt
```

The SOD (Start of Day) flow is the most coherent production path within Kopt. A caller creates a `JKKSodRequestDTO`, which flows to `JKKHakkoSODCC` — the central orchestrator. That controller performs two operations: it delegates validation to `KKPRC14901` (via the batch layer) and dispatch by creating a `JKKSodSendCC` instance that communicates with downstream systems. If batch execution occurs, `KKPRC14901.run()` delegates to `EKK0301A010.process()`, which may notify the KKW subsystem. The final outcome is returned as a `JKKSodResponseDTO`.

## Key Patterns and Architecture

### Delegation over Composition

Classes within `com.optage.kopt` consistently create new instances of their collaborators on each method call rather than holding long-lived references. For example, `JKKHakkoSODCC.dispatch()` creates a fresh `JKKSodSendCC` instance, and `EKK0301A010.notify()` creates a fresh `KKW0100B001`. This keeps individual classes stateless and simple to reason about, though it means dependencies are instantiated on every invocation rather than being injected once.

### Facade Pattern

Both the batch and business processing layers use the facade pattern to hide implementation complexity from callers:

- `KKPRC14901` exposes only `check()` and `run()` as its public interface, abstracting away the deeper `EKK0301A010.process()` logic.
- `JKKHakkoSODCC` exposes only `dispatch()` and `validate()` as entry points, hiding the multi-step workflow involving send handlers, validators, and formatters.

### Pre-flight / Execute Split

`KKPRC14901` implements a `check()` / `run()` split — validation and guard conditions are evaluated before the main batch logic executes. This pattern is not yet applied consistently; `KKPRC24901` and `KKPRC34901` currently only provide `run()`. The intent appears to be that callers should validate first, then execute, though the contract is not yet enforced at the type level.

### Fixture-First Development

All production classes are currently auto-generated stubs. The architecture is designed top-down: the class structure, method signatures, and inter-package dependencies are established, with business logic to be filled in later. This approach allows test infrastructure and wiki-generation tooling to operate against a stable API surface before the actual implementation is complete.

### Structured Naming Conventions

The package follows recognizable naming patterns that encode responsibility:

- **`KKPRC[N]4901`** — Batch entry-point classes, where `[N]` distinguishes variants.
- **`JKK*[CC]`** — Business processing classes, with `CC` suffix (likely denoting a batch control concept).
- **`EKK0301A010` / `EKK0301A020`** — Contract processing classes with a numeric specification code.
- **`KKW0100B001`** — Notification classes following a similar numeric pattern.
- **`ESC0101B001`** — ESC service classes with the `ESC` prefix.

## Dependencies and Integration

### Internal Dependencies

Within `com.optage`, the sole child module `com.optage.kopt` defines all of the package's internal coupling:

| Source | Target | Purpose |
|--------|--------|---------|
| `com.optage.kopt.bp` | `com.optage.kopt.batch` | `JKKHakkoSODCC.validate()` calls `KKPRC14901.check()` |
| `com.optage.kopt.batch.KKPRC14901` | `com.optage.kopt.ekk` | `KKPRC14901.run()` delegates to `EKK0301A010.process()` |
| `com.optage.kopt.ekk.EKK0301A010` | `com.optage.kopt.kkw` | `EKK0301A010.notify()` triggers `KKW0100B001.trigger()` |
| `com.optage.kopt.bp` | `com.optage.kopt.dto` | `JKKHakkoSODCC` consumes `JKKSodRequestDTO` / `JKKSodResponseDTO` |

The dependency chain is strictly directional (left to right), forming a clean pipeline with no circular dependencies.

### External Dependencies

No external dependencies were detected in the current source index. The module is self-contained within `com.optage.kopt` and does not reference classes from other packages in the broader Optage platform.

### Internal Dependency Graph

```mermaid
flowchart LR
    Bp["com.optage.kopt.bp"] -->|"validate()"| Batch["com.optage.kopt.batch"]
    Batch -->|"process()"| Ekk["com.optage.kopt.ekk"]
    Ekk -->|"notify()"| Kkw["com.optage.kopt.kkw"]
    Bp -->|"DTOs"| Dto["com.optage.kopt.dto"]
    Esc["com.optage.kopt.esc"] -->|"no deps"| Kopt["com.optage.kopt"]
    Unrelated["com.optage.kopt.unrelated"] -->|"no deps"| Kopt
```

## Notes for Developers

### Implementing Production Logic

- Follow the pattern established by `KKPRC14901.run()` — instantiate the relevant `EKK*` processor and delegate to it.
- The `JKKSodSendCC.send()` method is the primary place to implement the actual SOD dispatch logic.
- String preprocessing needs can be added to `JKKHakkoSODHelper.format()` or as new methods on that class.
- Common initialization for SOD batch operations should use the `JKKBpServiceBase.baseInit()` hook.

### Adding New Components

- **New batch types**: Create a `KKPRC[N]4901` class with at least a `run()` method delegating to the appropriate `EKK*` processor.
- **New contract processors**: Add a class following the `EKK0301A[0-9][0-9]` naming pattern in `com.optage.kopt.ekk`.
- **New DTOs**: Add fields to the existing DTOs or create new request/response pairs, following the flat carrier-class pattern. Consider generating getters, setters, `equals()`, `hashCode()`, and `toString()` (e.g., via Lombok).

### Test Infrastructure

- `JKKHakkoSODCCTest` exists with a placeholder `testMain()` method. Functional test coverage for SOD dispatch and validation flows should be added as implementation progresses.
- The `XYZ99999Unrelated` class in `com.optage.kopt.unrelated` should not be modified — it is a test fixture for wiki-generation tooling.

### Current State

All classes within `com.optage` are currently auto-generated fixtures for SPEC-SCOPED-WIKI tests. Method bodies are no-op placeholders. When implementing real logic, respect the existing class structure and inter-package dependencies — the architecture is designed to support the SOD dispatch and validation workflow described in this document, and the fixture-first approach ensures the API surface is already stable for tooling and testing.