# Com / Optage / Kopt

## Overview

The `com.optage.kopt` package is a modular subsystem within the Optage KOPT application. It organizes a set of loosely related capabilities — batch job processing, SOD (Send-Off-Dispatch) workflow orchestration, contract processing, emergency shutdown control, and data transfer — into named subpackages. At the moment, most of the subpackages contain auto-generated fixture stubs designed for SPEC-SCOPED-WIKI test scaffolding, meaning the business logic is largely placeholder code awaiting real implementation.

The one area with meaningful cross-package wiring is the interaction between `batch` and `ekk`, where `KKPRC14901` delegates processing to `EKK0301A010`. The `bp` (SOD workflow) subpackage also connects to both `batch` and `kkw`, forming a small cluster of interdependent modules.

## Sub-module Guide

### com.optage.kopt.batch — Batch Job Processing

The `batch` subpackage serves as the entry point for scheduled batch operations. It defines three classes (`KKPRC14901`, `KKPRC24901`, `KKPRC34901`) that follow a common `run()` method signature. `KKPRC14901` is the only class with real wiring: its `run()` method instantiates `EKK0301A010` from the `ekk` package and delegates processing. The other two are no-op stubs.

### com.optage.kopt.bp — SOD (Send-Off-Dispatch) Workflow

The `bp` subpackage coordinates the SOD workflow — dispatching and validation. The central class, `JKKHakkoSODCC`, orchestrates two flows:

- **dispatch()** creates a `JKKSodSendCC` instance and calls `send()` to execute the outbound SOD dispatch.
- **validate()** instantiates `KKPRC14901` from the `batch` package and calls `check()` on it.

This means `bp` sits at the intersection of multiple submodules: it depends on `batch` for validation and on `dto` (via the `JKKSodRequestDTO` / `JKKSodResponseDTO` pair) for data transport. A helper class (`JKKHakkoSODHelper`) provides simple string trimming utility.

### com.optage.kopt.dto — Data Transfer Objects

The `dto` subpackage holds the request/response data shape for SOD operations. `JKKSodRequestDTO` carries `tenantId` and `serviceId` fields, scoping requests to a particular tenant and service. `JKKSodResponseDTO` carries a `status` and `message` for the response. These are minimal, behaviorless DTOs — no constructors, no serialization annotations, no validation logic.

### com.optage.kopt.ekk — Contract Processing

The `ekk` subpackage contains the contract processing classes. `EKK0301A010` is the primary class, with a `process()` stub and a `notify()` method that actively instantiates `KKW0100B001` and calls `trigger()`. This makes `ekk` a thin intermediary that forwards notification requests to the `kkw` subsystem. `EKK0301A020` is a secondary, no-op contract processor.

### com.optage.kopt.esc — Emergency Shutdown Controller

The `esc` subpackage holds a single fixture class, `ESC0101B001`, with an empty `control()` method. It is intended to manage emergency shutdown procedures but has no implementation today. It has no dependencies on other subpackages and no outgoing links.

### com.optage.kopt.kkw — KKW Batch Trigger

The `kkw` subpackage contains `KKW0100B001`, a batch trigger entry point. Its `trigger()` method is currently a no-op stub. However, `ekk` actively calls it — `EKK0301A010.notify()` creates a new `KKW0100B001` and invokes `trigger()`. This makes `kkw` a downstream dependency of `ekk`.

### com.optage.kopt.unrelated — Test Fixtures

The `unrelated` subpackage contains `XYZ99999Unrelated`, a completely isolated test artifact. It has no fields, no methods with behavior, and no dependencies. It exists solely as a neutral, inert class for SPEC-SCOPED-WIKI tests.

## How the Sub-modules Relate

While most subpackages are independently scaffolded stubs, several meaningful interaction paths exist:

1. **batch --> ekk**: `KKPRC14901` delegates batch processing to `EKK0301A010`, which handles contract processing.
2. **bp --> batch**: `JKKHakkoSODCC.validate()` calls `KKPRC14901.check()`, so the SOD validation path reaches into batch.
3. **bp --> dto**: The SOD workflow uses the DTOs (`JKKSodRequestDTO`, `JKKSodResponseDTO`) to carry request/response data.
4. **ekk --> kkw**: `EKK0301A010.notify()` triggers `KKW0100B001.trigger()`, making `kkw` a downstream leaf of `ekk`.
5. **esc** stands alone — no incoming or outgoing links to other subpackages.
6. **unrelated** is a self-contained test artifact with zero integration.

The most active data flow, conceptually, follows this chain:

`bp` (orchestrates) --> `dto` (carries request) --> `bp` (dispatches via `JKKSodSendCC`) and `batch` (validates via `KKPRC14901`) --> `ekk` (contract processing) --> `kkw` (notification trigger)

## Key Patterns and Architecture

### Fixture / Stub Pattern

Almost every class across the subpackages is an auto-generated fixture for SPEC-SCOPED-WIKI tests. Method bodies contain inline comments like `/* SOD dispatch logic */`, `/* Contract processing */`, or `/* ESC service control */` — indicating intended behavior that has not yet been implemented. Developers should treat these as scaffolding, not production code.

### Naming Convention

Classes follow a structured naming pattern:
- **Subpackage prefix**: `KK`, `ESC`, `JKK` identifies the subsystem.
- **Numeric code**: The digits (e.g., `0301A010`, `0101B001`) encode a spec identifier and component variant.
- **Batch procedures**: `KKPRC` followed by a number (e.g., `14901`) indicates batch procedure type, with sequential numbering (14901, 24901, 34901).

### Delegation over Composition

The few classes with active code use a delegation pattern. `KKPRC14901.run()` creates `EKK0301A010` inline and calls `process()`. `JKKHakkoSODCC.dispatch()` creates `JKKSodSendCC` inline and calls `send()`. `EKK0301A010.notify()` creates `KKW0100B001` inline and calls `trigger()`. This suggests a pattern of simple, stateless delegation — no factory or dependency injection is used.

### Request/Response DTO Structure

The `dto` package follows a standard request/response pair pattern: `JKKSodRequestDTO` scopes the operation, and `JKKSodResponseDTO` reports the outcome. This decouples data shape from service logic and allows the same DTOs to be used across multiple SOD-related classes.

## Module Diagram

The diagram below shows the primary interaction paths between subpackages:

```mermaid
flowchart TD
    subgraph KOPT["Com / Optage / Kopt Module"]
        BATCH["batch
Batch Job Processing"]
        BP["bp
SOD Workflow"]
        DTO["dto
Data Transfer Objects"]
        EKK["ekk
Contract Processing"]
        ESC["esc
Emergency Shutdown"]
        KKW["kkw
KKW Batch Trigger"]
        UNREL["unrelated
Test Fixtures"]
    end

    BATCH -->|"delegates to"| EKK
    BP -->|"dispatch creates"| SODSEND["JKKSodSendCC"]
    BP -->|"validate uses"| BATCH
    BP -->|"uses helper"| HELPER["JKKHakkoSODHelper"]
    DTO -->|"carries data for"| BP
    EKK -->|"notify triggers"| KKW
    BATCH -.->|"stub entries"| KKPRC1["KKPRC14901"]
    BATCH -.->|"stub entries"| KKPRC2["KKPRC24901"]
    BATCH -.->|"stub entries"| KKPRC3["KKPRC34901"]
    BP -.->|"stub entries"| SODCC["JKKHakkoSODCC"]
    EKK -.->|"stub entries"| EKK010["EKK0301A010"]
    EKK -.->|"stub entries"| EKK020["EKK0301A020"]
    ESC -.->|"stub entries"| ESC010["ESC0101B001"]
    KKW -.->|"stub entries"| KKW010["KKW0100B001"]
```

Solid arrows indicate active dependencies (classes that reference other classes at runtime). Dashed arrows indicate that the named class resides within the subpackage as a fixture stub.

## Dependencies and Integration

### Internal Dependencies

| Source Package | Target Package | Nature of Dependency |
|---|---|---|
| `com.optage.kopt.batch` | `com.optage.kopt.ekk` | `KKPRC14901.run()` instantiates `EKK0301A010` |
| `com.optage.kopt.bp` | `com.optage.kopt.batch` | `JKKHakkoSODCC.validate()` calls `KKPRC14901.check()` |
| `com.optage.kopt.ekk` | `com.optage.kopt.kkw` | `EKK0301A010.notify()` instantiates `KKW0100B001` |
| `com.optage.kopt.bp` | `com.optage.kopt.dto` | SOD workflow uses request/response DTOs |

### External Dependencies

No external package dependencies were detected at the package level. The only external (test-scope) dependency is JUnit, used by `JKKHakkoSODCCTest` in the `bp` package.

## Notes for Developers

- **Most code is stubs**: The vast majority of classes in `com.optage.kopt` are auto-generated fixtures. Do not assume any non-stub class represents finished business logic. Always check the method body for placeholder comments before relying on behavior.
- **Only two classes have meaningful wiring**: `KKPRC14901` (batch -> ekk delegation) and `EKK0301A010` (ekk -> kkw notification) are the only classes with actual cross-package references beyond stubs.
- **bp is the coordination hub**: If you are tracing the SOD workflow, start in `bp`. It connects to `batch` (validation), `dto` (data), and `bp` internals (`JKKSodSendCC`, `JKKHakkoSODHelper`).
- **esc and unrelated are isolated**: Neither subpackage has incoming or outgoing dependencies. `esc` is a standalone emergency shutdown scaffold; `unrelated` is a test artifact with zero behavior.
- **Naming conventions are consistent**: When adding new classes, follow the prefix + numeric code pattern used across subpackages. New batch procedures should use the `KKPRC` prefix with sequential numbers. New fixture classes should use the `SubsystemXXXXX` format.
- **DTOs need augmentation**: The `dto` classes are plain field containers with no accessors, constructors, or serialization annotations. Production use will require generating or adding these.
- **`JKKHakkoSODHelper.format()` is the only concrete utility**: Of all classes in the package, this is the only one with a non-trivial, non-stub implementation. It trims whitespace from a string input with no null safety.