# Com / Optage / Kopt

## Overview

The `com.optage.kopt` package is a Java subpackage within the Optage codebase that implements the **KOPT system** — a modular framework centered around batch processing, dispatch coordination, and contract handling. The name KOPT appears to stand for an internal optimization or processing system that orchestrates Start-of-Day (SOD) operations for the JKK client or internal system, with supporting infrastructure for batch execution, data transfer, and cross-module notifications.

The system is organized into several focused sub-modules, each responsible for a distinct layer of responsibility:

- **`bp`** — The top-level coordination and SOD dispatch layer. This is the primary entry point where callers trigger dispatch operations.
- **`batch`** — The underlying batch processing infrastructure, providing fixture classes that route execution to specialized handlers.
- **`dto`** — Lightweight data transfer objects that define the request/response contract for SOD operations.
- **`ekk`** — Contract processing logic, where core business processing happens (or is stubbed for now).
- **`kkw`** — Batch trigger infrastructure — a notification bridge used by the contract processing layer.
- **`esc`** — A service control placeholder, currently empty and waiting for implementation.
- **`unrelated`** — An isolated test fixture used to validate the documentation tooling itself.

Most classes in this module are currently auto-generated fixtures (scaffolding) for SPEC-SCOPED-WIKI tests, meaning their method bodies are largely placeholder comments. However, the architecture and cross-module wiring is already visible in the non-trivial classes, particularly the path from `bp` through `batch`, `ekk`, and `kkw`.

## Sub-module Guide

### bp — SOD Dispatch Coordination

The `bp` package sits at the highest level of the KOPT module hierarchy and serves as the **orchestration layer**. Its central class, `JKKHakkoSODCC`, acts as a facade that callers interact with. When a caller invokes `dispatch()`, the class delegates to `JKKSodSendCC.send()` for the actual dispatch mechanics and to `KKPRC14901.check()` (from the batch package) for pre-dispatch validation.

`JKKBpServiceBase` provides shared initialization (`baseInit()`) for any new service classes that need SOD-related setup, following a Template Method pattern to avoid duplication. `JKKHakkoSODHelper` offers simple string formatting (trimming), a utility used to clean input data before processing.

This is the package you would modify if you needed to change how SOD dispatch is initiated or validated.

### batch — Batch Processing Infrastructure

The `batch` package provides the **execution scaffolding** that the `bp` layer delegates to. It contains three fixture classes (`KKPRC14901`, `KKPRC24901`, `KKPRC34901`) that follow a naming convention of `KKPRC` plus a numeric suffix, suggesting different batch processing profiles or modes.

Of the three, only `KKPRC14901` has concrete logic: its `run()` method instantiates `EKK0301A010` and calls its `process()` method, creating the first real cross-module handoff — from batch processing into contract processing. The `check()` method in `KKPRC14901` is an empty placeholder, likely intended for future validation hooks.

The existence of three numbered variants (14901, 24901, 34901) suggests the system was designed to support multiple batch processing strategies, with additional profiles to be implemented later.

### dto — Data Transfer Contracts

The `dto` package defines the **external contract** for SOD operations. It contains two plain Java objects:

- **`JKKSodRequestDTO`** — Carries `tenantId` and `serviceId` as the minimum information needed to initiate an SOD operation.
- **`JKKSodResponseDTO`** — Carries a `status` (machine-readable) and `message` (human-readable) as the result.

These DTOs are pure data carriers with no methods, no validation annotations, and no builders. They are designed to be serialized to JSON (likely via Jackson or Gson) for API transport. Input validation is handled by the consuming service layer, not within these DTOs themselves.

### ekk — Contract Processing

The `ekk` package is where the **core business processing** logic resides (at least conceptually; currently stubbed). It contains two classes:

- **`EKK0301A010`** — The primary contract processor. Its `process()` method is the main entry point for contract-specific logic, and its `notify()` method bridges to the `kkw` package via `KKW0100B001.trigger()`.
- **`EKK0301A020`** — A simpler secondary contract processor with only a `process()` method, no notification path.

The flow through this layer is: `batch.KKPRC14901.run()` → `EKK0301A010.process()`. If `notify()` is called, it reaches `KKW0100B001.trigger()`. This is the deepest chain of actual method calls currently wired in the system.

### kkw — Batch Trigger

The `kkw` package provides the **notification trigger** mechanism. Its single class, `KKW0100B001`, exposes a `trigger()` method that is called by `EKK0301A010.notify()`. Currently this is an empty stub, but its position in the call chain suggests it is intended to emit some form of batch-trigger event or notification once implemented.

The dependency direction is clear: `ekk` depends on `kkw` — it is the one module in this system that is depended upon by another internal module rather than being a starting point itself.

### esc — Service Control (Stub)

The `esc` package is a structural placeholder with a single class, `ESC0101B001`, containing an empty `control()` method. It has no dependencies on any other module and no runtime behavior. If this module is intended to become an operational ESC (Event Service Component or Edge Service Controller), the `control()` method is the hook point where initial logic would be added.

As it stands, this module is inert — a named entry point in the package hierarchy with no wiring to other modules.

### unrelated — Test Fixture

The `unrelated` package contains `XYZ99999Unrelated`, a deliberately empty test fixture class. It has no dependencies, no fields, and no behavior. Its sole purpose is to serve as an edge-case test input for the wiki generation tooling — validating that the documentation pipeline handles classes with zero cross-module relationships gracefully. It is not part of the KOPT system's operational architecture.

## How the Sub-modules Interact

The following diagram shows the **actual wired dependencies** between sub-modules, where real cross-module calls exist today:

```mermaid
flowchart TD
    subgraph BP["bp - SOD Dispatch"]
        BCC["JKKHakkoSODCC"]
        SSC["JKKSodSendCC"]
        SBL["JKKBpServiceBase"]
        SHL["JKKHakkoSODHelper"]
    end
    subgraph DTO["dto - Data Contracts"]
        JRD["JKKSodRequestDTO"]
        JRS["JKKSodResponseDTO"]
    end
    subgraph BATCH["batch - Batch Processing"]
        K14["KKPRC14901"]
        K24["KKPRC24901"]
        K34["KKPRC34901"]
    end
    subgraph EKK["ekk - Contract Processing"]
        E01["EKK0301A010"]
        E02["EKK0301A020"]
    end
    subgraph KKW["kkw - Batch Trigger"]
        KKW01["KKW0100B001"]
    end
    subgraph ESC["esc - Service Control"]
        ESC01["ESC0101B001"]
    end
    BCC -->|dispatch| SSC
    BCC -->|validate| K14
    K14 -->|process| E01
    E01 -->|notify -> trigger| KKW01
```

The data flow for an SOD dispatch operation looks like this:

```mermaid
flowchart LR
    Caller["Caller"] -->|"JKKSodRequestDTO"| BCC["JKKHakkoSODCC"]
    BCC -->|"dispatch"| SSC["JKKSodSendCC"]
    BCC -->|"validate"| K14["KKPRC14901"]
    K14 -->|"process"| E01["EKK0301A010"]
    E01 -->|"notify"| KKW01["KKW0100B001"]
    SSC -->|"JKKSodResponseDTO"| Caller
```

### The active call chain

At the moment, the only non-trivial call chain across modules is:

1. **`bp.JKKHakkoSODCC.dispatch()`** creates `JKKSodSendCC` and calls `send()` to initiate the dispatch.
2. **`bp.JKKHakkoSODCC.validate()`** instantiates `batch.KKPRC14901` and calls `check()` for validation.
3. **`batch.KKPRC14901.run()`** instantiates `ekk.EKK0301A010` and calls `process()`.
4. **`ekk.EKK0301A010.notify()`** instantiates `kkw.KKW0100B001` and calls `trigger()`.

This forms a clear layered architecture: **dispatch** (`bp`) → **validation** (`batch`) → **contract processing** (`ekk`) → **notification** (`kkw`).

### The disconnected pieces

Several components exist but are not yet wired into any active path:

- **`dto`** classes exist as the external API contract, but none of the internal classes (`bp`, `batch`, `ekk`) currently use them. They are likely intended for API endpoints that wrap the internal KOPT operations.
- **`esc`** is entirely isolated — no class in the system references it, and it references nothing.
- **`unrelated`** is deliberately isolated by design.
- **`batch.KKPRC24901`** and **`batch.KKPRC34901`** are stubs awaiting implementation.
- **`ekk.EKK0301A020`** exists but is not referenced by any other class.

## Key Patterns and Architecture

### Fixture/Stub-based scaffolding

The majority of classes across this module are auto-generated fixtures for SPEC-SCOPED-WIKI tests. Their method bodies consist of placeholder comments (`/* Contract processing */`, `/* KKW batch trigger */`). This pattern means the codebase is in a state where the **architecture is designed but the implementation is not yet complete**. The cross-module wiring that *does* exist (`bp` → `batch` → `ekk` → `kkw`) is intentional and real, even if the method bodies are stubs.

### Layered delegation pattern

The architecture follows a clean layered delegation pattern. Each sub-module has a single, focused responsibility:

- **`bp`** coordinates and exposes the public API.
- **`batch`** provides execution routing.
- **`ekk`** performs contract processing.
- **`kkw`** handles batch-trigger notifications.
- **`dto`** defines the external data contract.

No layer reaches sideways to another at the same level — calls flow top-down through the chain.

### Naming convention

Classes follow a consistent naming pattern: a **3-letter prefix** (e.g., `KKP`, `EKK`, `KKW`, `ESC`) followed by a **6-digit code** (e.g., `0301A010`). This appears to encode the module and role of the class within a specification system, and the same pattern is used across auto-generated fixtures and real implementation classes alike.

### DTO-first design

The `dto` package defines the request/response contract before the processing logic is fully implemented. Both `JKKSodRequestDTO` and `JKKSodResponseDTO` are minimal plain objects with no validation, no builders, and no business logic. This suggests the system's external API contract is treated as the source of truth, with internal processing classes built to fulfill it.

## Dependencies and Integration

### Internal dependencies

| From | To | Mechanism |
|---|---|---|
| `bp.JKKHakkoSODCC` | `batch.KKPRC14901` | `validate()` instantiates and calls `check()` |
| `batch.KKPRC14901` | `ekk.EKK0301A010` | `run()` instantiates and calls `process()` |
| `ekk.EKK0301A010` | `kkw.KKW0100B001` | `notify()` instantiates and calls `trigger()` |

### No detected external dependencies

The index does not report any external package dependencies for this module. All classes appear to depend only on `java.lang` standard library types, plus the other sub-modules listed above. The `dto` classes are intended to be serialized over JSON (likely Jackson or Gson) but do not declare those libraries as imports in their current form.

### Integration with the broader system

This module appears to integrate with the broader Optage system in two ways:

1. **As a consumer** — The `bp` layer receives SOD dispatch requests (likely via API endpoints that accept `JKKSodRequestDTO`) and routes them through the KOPT processing chain.
2. **As a provider** — The `bp` layer (via `JKKSodSendCC`) and the `dto` layer both produce output that flows back to callers, including `JKKSodResponseDTO` results.

The `esc` module and the `unrelated` test fixture are not currently integrated into any integration path.

## Notes for Developers

- **Most code is scaffolding.** The majority of classes are auto-generated test fixtures with empty method bodies. Do not treat them as production-ready. The wiring between modules is real, but the business logic is not yet implemented.
- **Follow the existing delegation pattern.** New batch fixtures should follow the structure of `KKPRC14901`: a class with a `run()` method that delegates to the next layer. If a two-phase class is needed (check + run), model it after `KKPRC14901`'s pattern.
- **Validation is centralized.** The `validate()` method in `bp` delegates to `batch.KKPRC14901` rather than embedding validation inline. If validation rules need to change, the work happens in that external class.
- **DTOs are minimal by design.** `JKKSodRequestDTO` and `JKKSodResponseDTO` carry only the fields strictly necessary for their roles. Do not add business logic to them. If new fields are needed, add them as new `String` fields following the existing naming conventions.
- **Input validation belongs in the service layer.** The DTOs have no validation annotations. Ensure that `tenantId` and `serviceId` are validated by the consuming service, not within the DTOs themselves.
- **`JKKBpServiceBase` is a base class.** If creating a new service in the `bp` area, extend `JKKBpServiceBase` to inherit the shared `baseInit()` logic.
- **Naming convention is systematic.** Classes follow a 3-letter prefix + 6-digit code pattern. When adding new classes, follow the existing prefix conventions: `KKP` for batch, `EKK` for contract processing, `KKW` for triggers, `ESC` for service control.
- **`esc` and `unrelated` are inert.** These modules have no wiring and no behavior. If `esc` is intended to become operational, the `control()` method is the entry point. `unrelated` is purely for documentation tooling edge-case testing and should not be extended.