# Com / Optage / Kopt

## Overview

The `com.optage.kopt` package is the top-level module for the **Optage KOPT** system, a batch processing and Start of Day (SOD) coordination framework. KOPT appears to be a Japanese enterprise banking or financial services platform (indicated by naming conventions such as `JKK`, `SOD`, `Hakko`, and the `SPEC-SCOPED-WIKI` test infrastructure).

The system provides:

- **Batch job orchestration** — Entry-point classes (`KKPRC*`) invoked by a scheduler (cron, Spring Batch, Airflow) to run daily or periodic batch operations.
- **Start of Day (SOD) processing** — Coordination of the daily batch initialization sequence that prepares the system before business operations begin. This includes dispatching data to downstream systems and validating data integrity before dispatch.
- **Contract processing** — Secondary processing paths (`EKK`) that handle contract-level operations and coordinate with the KKW (production/issuance) subsystem.
- **Data model** — DTOs (`JKKSodRequestDTO`, `JKKSodResponseDTO`) that carry structured SOD data between layers.

As of the current codebase state, much of the `kopt` module exists as **auto-generated test scaffolding** — stubs and fixtures designed to exercise the wiki-generation and SPEC-SCOPED-WIKI test infrastructure. Production logic is largely placeholder, but the structural patterns and cross-module dependencies are already defined, giving developers a clear blueprint for future implementation.

## Sub-module Guide

### batch — Entry Points

The `com.optage.kopt.batch` package provides three entry-point classes (`KKPRC14901`, `KKPRC24901`, `KKPRC34901`) that serve as the **top-level execution points for batch operations**. These classes are the bridge between an external scheduler and the business logic below.

- `KKPRC14901` is the only fully wired entry point. Its `run()` method delegates to `EKK0301A010.process()`, and it offers an optional `check()` method for pre-flight validation.
- `KKPRC24901` and `KKPRC34901` are currently no-op stubs, awaiting implementation.

The batch classes themselves contain no constructor parameters, no injected dependencies, and no state. They are pure static entry points following a simple pattern: **scheduler invokes `run()` → class delegates to the processor below.**

### bp — Start of Day Coordination

The `com.optage.kopt.bp` package handles **SOD processing coordination**. It is the architectural heart of the daily initialization workflow:

- `JKKHakkoSODCC` is the central orchestrator. It provides `dispatch()` to trigger SOD data sending and `validate()` to validate data before dispatch. The `dispatch()` path creates a `JKKSodSendCC` instance; the `validate()` path reaches into the `batch` package, instantiating `KKPRC14901` to call its `check()` method.
- `JKKSodSendCC` owns the SOD dispatch/sending logic.
- `JKKHakkoSODHelper` provides string formatting utilities (trimming) used during SOD processing.
- `JKKBpServiceBase` is the inheritance root, providing a shared `baseInit()` hook for all batch services in the package.

This module depends on the `batch` package for validation — the `bp` package is not self-contained. It also consumes DTOs from the sibling `com.optage.kopt.dto` package.

### ekk — Contract Processing

The `com.optage.kopt.ekk` package contains two fixture classes (`EKK0301A010`, `EKK0301A020`) representing contract processing entry points.

- `EKK0301A010` is the primary contract processor. Its `process()` method is the structural placeholder for contract handling, and its `notify()` method establishes the **only cross-module dependency** in the entire `kopt` system — it creates and calls `KKW0100B001.trigger()` in the `kkw` package.
- `EKK0301A020` is a secondary contract processor with a simpler, self-contained structure.

The `ekk` module acts as a command-like bridge: external callers invoke `process()` for contract work and `notify()` to send side-effect signals downstream to `kkw`.

### kkw — Production/Fixtures

The `com.optage.kopt.kkw` package is the leaf node in the module tree. It contains `KKW0100B001`, a minimal fixture class with a single no-op `trigger()` method. This package has no outgoing dependencies and is imported only by `ekk`.

It appears to represent a **production or issuance subsystem** (the Japanese word "Hakko" — found in `JKKHakkoSODCC` — translates to "production" or "issuance"). The `kkw` classes are purely synthetic scaffolding; real logic should be added outside this fixture package.

### How the Sub-modules Relate

The `kopt` package forms a **layered execution pipeline**:

1. **Entry** — The `batch` package provides scheduler-facing entry points (`KKPRC*`).
2. **Orchestration** — The `bp` package (`JKKHakkoSODCC`) coordinates the daily SOD workflow, calling into `batch` for validation and managing its own dispatch logic.
3. **Processing** — The `ekk` package handles contract-level processing triggered by batch or dispatch operations.
4. **Side-effects** — When contract processing needs to signal downstream systems, it reaches into `kkw`.

The data flows from the scheduler, through `batch` entry points, into `bp` coordination, and finally into `ekk` contract processing, with `kkw` as a terminal signal handler. DTOs from the `dto` package carry structured data at each layer.

## Key Patterns and Architecture

### Delegation Over Inheritance

The dominant design pattern across `kopt` is **thin delegators**. Each class owns a single responsibility and delegates to specialized classes rather than implementing logic inline:

- `KKPRC14901.run()` → `EKK0301A010.process()`
- `JKKHakkoSODCC.dispatch()` → `JKKSodSendCC.send()`
- `JKKHakkoSODCC.validate()` → `KKPRC14901.check()`

This keeps classes narrow and makes the system easy to extend — new capabilities are added by creating new dedicated classes rather than expanding existing ones.

### Template Method via Base Class

`JKKBpServiceBase` provides a `baseInit()` hook that establishes a shared initialization contract for all batch services in the `bp` package. This follows the Template Method pattern, ensuring consistent setup across all derived services.

### Fixture-Driven Development

All classes in `kopt` are currently auto-generated test fixtures (marked with `SPEC-SCOPED-WIKI tests`). This is a **test-first, infrastructure-first** approach: the structural scaffolding is generated to exercise the wiki-generation pipeline, and production logic will be layered on top. The class hierarchy, cross-module dependencies, and method signatures are already in place; only the method bodies are empty or stub implementations.

### Stateless Entry Points

The `batch` classes and `kkw` classes are entirely stateless — no fields, no constructor parameters. Each `run()` or `trigger()` method creates its dependencies on the fly (e.g., `new EKK0301A010().process()`). This is a functional, side-effect-friendly approach well-suited for batch execution.

## Module Interaction Diagram

The following diagram shows how the sub-modules and key classes interact:

```mermaid
flowchart TD
    Sched["Scheduler / Job Framework"]
    BP["bp - SOD Processing"]
    Bt["batch - Entry Points"]
    EK["ekk - Contract Processing"]
    KW["kkw - Fixtures"]
    D["dto - Data Transfer"]

    Sched -->|"invokes"| KKP["KKPRC14901.run()"]
    KKP -->|"delegates to"| EKK["EKK0301A010.process()"]
    EKK -->|"side-effect signal"| KKW["KKW0100B001.trigger()"]
    Sched -->|"invokes"| HKK["JKKHakkoSODCC.dispatch()"]
    HKK -->|"delegates to"| JSS["JKKSodSendCC.send()"]
    HKK -->|"validates via"| KKP2["KKPRC14901.check()"]
    HKK -->|"uses"| HLP["JKKHakkoSODHelper.format()"]

    Bt --> KKP
    Bt --> KKP2
    EK --> EKK
    KW --> KKW
    BP --> HKK
    BP --> JSS
    BP --> HLP
```

## SOD Processing Flow

Within the `bp` package specifically, the SOD processing flow is:

```mermaid
flowchart LR
    HKK["JKKHakkoSODCC"]
    SOD["JKKSodSendCC"]
    KKP["KKPRC14901 (batch)"]
    HLP["JKKHakkoSODHelper"]
    BSP["JKKBpServiceBase"]

    HKK -->|"dispatch"| SOD
    HKK -->|"validate"| KKP
    HKK -->|"uses"| HLP
    BSP -->|"base init"| HKK
```

## Dependencies and Integration

### Internal Dependencies

| Dependency | Direction | Description |
|---|---|---|
| `com.optage.kopt.batch.KKPRC14901` | `bp` → `batch` | `JKKHakkoSODCC.validate()` instantiates `KKPRC14901` and calls its `check()` method for pre-dispatch validation. |
| `com.optage.kopt.ekk.EKK0301A010` | `batch` → `ekk` | `KKPRC14901.run()` instantiates and calls `EKK0301A010.process()`. |
| `com.optage.kopt.kkw.KKW0100B001` | `ekk` → `kkw` | `EKK0301A010.notify()` creates `KKW0100B001` and calls `trigger()`. This is the sole cross-module dependency in the entire system. |
| `com.optage.kopt.dto` | `bp` → `dto` | SOD request/response DTOs (`JKKSodRequestDTO`, `JKKSodResponseDTO`) are consumed by `bp` classes at runtime. |

### External Dependencies

No external (non-`com.optage.kopt`) dependencies were detected for any `kopt` module. The system appears to be **self-contained** at the class-level — it has no imports outside its own package hierarchy. At runtime, the actual batch scheduler (cron, Spring Batch, Airflow) and the DTOs in `dto` provide the external context.

## Notes for Developers

### Current State

- **Most classes are auto-generated stubs.** The `SPEC-SCOPED-WIKI` test infrastructure generates the class structure, but method bodies are empty or `/* placeholder */` comments. Treat the current code as structural templates rather than production-ready logic.

- **Two of three batch entry points are no-ops.** `KKPRC24901` and `KKPRC34901` contain only comment bodies. If you are adding batch processing logic, these are the classes to extend.

- **The test class `JKKHakkoSODCCTest` is a stub.** Its `testMain()` method contains only `assertTrue(true)`. Real test cases should be written once production logic is implemented.

### Naming Conventions

Class names follow a Japanese banking/enterprise software pattern:
- `KK*` prefix — likely refers to a product line or system code (KKK, KKPRC)
- `JKK*` prefix — indicates a specific module or service type (JKKBpServiceBase, JKKHakkoSODCC)
- `EKK*` — contract processing classes
- `KKW*` — production/issuance fixture classes
- The numbering convention (e.g., `0301A010`, `0100B001`) appears to encode spec version and instance identifiers

The exact mapping of these codes to business concepts is unclear from the code alone — check with the team for the naming convention behind these patterns.

### Extension Guidelines

1. **Add new capabilities as new classes**, not new methods on existing orchestrators. Follow the thin delegator pattern.
2. **Extend `JKKBpServiceBase`** for new batch services that need shared initialization.
3. **Keep `batch` and `kkw` classes stateless** — no fields, no constructor parameters.
4. **Do not add production logic directly to fixture classes** (`kkw` especially). Add real logic outside the fixture package to avoid code generation overwrites.
5. **SOD validation always flows through `KKPRC14901.check()`** — if you need to add new validation logic, extend this class rather than creating a parallel validation path.

### Architectural Observations

- The system has a **single point of cross-module dependency**: `EKK0301A010.notify()` → `KKW0100B001.trigger()`. This makes the `kkw` package a terminal node — it receives signals but sends nothing downstream.
- The `dto` package is referenced but not documented in this parent page. If you need SOD data structure details, see the `com.optage.kopt.dto` module documentation.
- The absence of any external imports suggests this module is either **early in development** or designed to be **fully isolated** with dependencies injected at runtime (via Spring or a DI framework not visible at the source level).