# Com / Optage

## Overview

The `com.optage` package sits at the root of the Optage codebase and serves as the top-level namespace for the system's core processing infrastructure. Currently, it contains a single active subpackage — `kopt` — which implements the **KOPT system**, an internal batch-processing and dispatch framework.

KOPT is responsible for orchestrating **Start-of-Day (SOD) operations** for the JKK client or internal system. It provides a layered architecture that takes SOD dispatch requests, validates them through batch processing hooks, executes contract-level business logic, and emits batch-trigger notifications. The system is organized into focused sub-modules, each owning a distinct layer of responsibility — from public API coordination down to low-level batch triggers.

At present, much of the KOPT module consists of **auto-generated scaffolding** (fixtures for SPEC-SCOPED-WIKI tests) with placeholder method bodies. However, the cross-module wiring is real and intentional, establishing a clear architectural blueprint for the system's eventual production implementation.

## Sub-module Guide

The `com.optage` package contains one child sub-package today:

| Sub-package | Role | Status |
|---|---|---|
| **`kopt`** | KOPT system — batch processing, dispatch coordination, and contract handling | Scaffolded, wiring active |

### KOPT (`kopt`) — Batch Processing and SOD Dispatch Framework

The `kopt` package is a modular framework for orchestrating Start-of-Day operations. It is organized into six focused sub-modules, each responsible for a distinct layer:

- **`bp`** — The top-level **orchestration layer**. `JKKHakkoSODCC` acts as the primary facade, accepting SOD dispatch requests and delegating to the validation and send layers below.
- **`batch`** — The **execution scaffolding**. Contains fixture classes (`KKPRC14901`, `KKPRC24901`, `KKPRC34901`) that route batch processing to specialized handlers. Only `KKPRC14901` has concrete wiring today.
- **`ekk`** — The **contract processing layer**. `EKK0301A010` is the primary processor, performing core business logic and bridging to the notification layer.
- **`kkw`** — The **batch-trigger notification mechanism**. `KKW0100B001.trigger()` is the endpoint called by contract processors to emit events.
- **`dto`** — The **external data contract**. Plain Java objects (`JKKSodRequestDTO`, `JKKSodResponseDTO`) defining the API request/response shape.
- **`esc`** — A **service control placeholder**. Currently empty, awaiting implementation.

Two additional sub-modules exist at the leaf level but serve no operational purpose:

- **`unrelated`** — A deliberately isolated test fixture for validating the documentation tooling.
- **`esc`** — A named structural placeholder with no cross-module wiring.

### How They Relate

The KOPT system follows a **strict top-down delegation model**. Calls flow through four layers without any sideways branching:

1. **`bp`** (dispatch coordination) → 2. **`batch`** (execution routing) → 3. **`ekk`** (contract processing) → 4. **`kkw`** (notification)

The `dto` layer sits alongside this chain as the external API contract, while `esc` and `unrelated` are currently disconnected. This architecture was designed so that each sub-module has a single, well-defined responsibility and no layer depends on its peers.

## Key Patterns and Architecture

### Layered Delegation Architecture

The system follows a clean layered delegation pattern where each sub-module has one responsibility and calls flow strictly top-down:

```mermaid
flowchart TD
    subgraph BP["bp — SOD Dispatch Coordination"]
        BCC["JKKHakkoSODCC"]
        SSC["JKKSodSendCC"]
        SBL["JKKBpServiceBase"]
        SHL["JKKHakkoSODHelper"]
    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 DTO["dto — Data Contracts"]
        JRD["JKKSodRequestDTO"]
        JRS["JKKSodResponseDTO"]
    end
    subgraph ESC["esc — Service Control (stub)"]
        ESC01["ESC0101B001"]
    end
    BCC --> "dispatch" --> SSC
    BCC --> "validate" --> K14
    K14 --> "process" --> E01
    E01 --> "notify" --> KKW01
```

```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 time of this documentation, the only non-trivial cross-module call chain is:

1. **`bp.JKKHakkoSODCC.dispatch()`** — Creates `JKKSodSendCC` and calls `send()` to initiate dispatch.
2. **`bp.JKKHakkoSODCC.validate()`** — Instantiates `batch.KKPRC14901` and calls `check()` for pre-dispatch validation.
3. **`batch.KKPRC14901.run()`** — Instantiates `ekk.EKK0301A010` and calls `process()` for contract processing.
4. **`ekk.EKK0301A010.notify()`** — Instantiates `kkw.KKW0100B001` and calls `trigger()` to emit a batch event.

This gives the system its four-layer spine: **dispatch → validation → contract processing → notification**.

### Fixture-Based Scaffolding

The majority of classes in `kopt` are auto-generated fixtures for SPEC-SCOPED-WIKI tests, with method bodies consisting of placeholder comments. The architecture is designed and wired; the business logic is not yet implemented. This means the cross-module dependencies between `bp` → `batch` → `ekk` → `kkw` are intentional and real, even though the internal method bodies are stubs.

### Systematic Class Naming

Classes follow a consistent **3-letter prefix + 6-digit code** pattern (e.g., `KKP0301A010`). The prefix encodes the module (`KKP` = batch, `EKK` = contract processing, `KKW` = triggers, `ESC` = service control), and the digits encode the specific role within that module. This convention is used across both scaffolded and real implementation classes.

### DTO-First Design

The `dto` package defines the external request/response contract (`JKKSodRequestDTO`, `JKKSodResponseDTO`) before the processing logic is fully implemented. These are minimal plain objects with no validation, no builders, and no business logic — treating the external API contract as the source of truth, with internal classes built to fulfill it.

### Template Method for Shared Initialization

`JKKBpServiceBase` provides shared `baseInit()` logic for new service classes in the `bp` layer, following the Template Method pattern to avoid duplicating SOD-related setup across multiple services.

## 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()` |

### External Dependencies

No external package dependencies are detected in the index beyond `java.lang` standard library types. The `dto` classes are intended to be serialized over JSON (likely via Jackson or Gson) but do not currently declare those libraries as imports in their current form.

### Integration Points

This module appears to integrate with the broader system as a **consumer and provider**:

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

The `esc` module, `unrelated` fixture, and the stub batch profiles (`KKPRC24901`, `KKPRC34901`) are not currently integrated into any active 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 `KKPRC14901`'s structure: a class with a `run()` method that delegates to the next layer. For two-phase classes (check + run), model the approach on `KKPRC14901`.
- **Validation is centralized.** The `validate()` method in `bp` delegates to `batch.KKPRC14901` rather than embedding validation inline. If validation rules 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 `String` fields following the existing naming conventions.
- **Input validation belongs in the service layer.** The DTOs have no validation annotations. Ensure `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.