# Com / Optage / Kopt

## Overview

The `com.optage.kopt` package is the batch processing and SOD (complaints dispatch) subsystem of the Optage platform. It provides the entry points and orchestration logic for scheduling, validating, and dispatching complaint/SOD records to downstream systems. The module is organized into two sibling sub-packages — **batch** and **bp** — that share a common delegation pattern: neither package carries out the heavy business logic itself. Instead, they act as orchestrators, instantiating collaborator classes and forwarding work deeper into the `ekk` subsystem (or later into downstream transport).

This appears to be a fixture/stub scaffolding module generated for `SPEC-SCOPED-WIKI` tests rather than production-ready code. The implementations are minimal placeholders, but the structural patterns — create-on-call delegation, facade-style orchestration, tiered batch profiles — provide a blueprint for how the full system is intended to evolve.

## Sub-module Guide

### `com.optage.kopt.batch` — Batch Run Profiles

The batch package provides three entry-point classes, each representing a distinct batch run tier:

| Class | Profile | Status | Delegation Target |
|---|---|---|---|
| `KKPRC14901` | Primary | Implemented | `EKK0301A010.process()` |
| `KKPRC24901` | Secondary | Stub | — |
| `KKPRC34901` | Tertiary | Stub | — |

The naming convention (149xx, 249xx, 349xx) suggests these three classes form a tiered or sequential batch pipeline. Only the primary runner is currently wired up; it delegates to `EKK0301A010` in the `ekk` package, which is where the actual batch logic lives.

### `com.optage.kopt.bp` — SOD Dispatch Orchestration

The bp package handles the SOD (complaints) issuance flow. Its central orchestrator is `JKKHakkoSODCC`, which coordinates two key steps:

1. **Validation** — delegates to `KKPRC14901.check()` from the sibling `batch` package.
2. **Dispatch** — delegates to `JKKSodSendCC.send()`, which transmits validated SOD records to downstream systems.

Additional support in this sub-package includes:
- `JKKHakkoSODHelper.format()` — whitespace normalization for SOD text fields.
- `JKKBpServiceBase.baseInit()` — shared initialization hook for subclasses.
- `JKKHakkoSODCCTest` — placeholder unit test scaffold.

### How the Sub-modules Relate

The relationship between batch and bp is **cross-wired**, not purely hierarchical:

- **bp validates through batch.** When `JKKHakkoSODCC.validate()` is called, it instantiates `KKPRC14901` (from the batch package) and invokes its `check()` method. This makes the batch package the validation authority for the bp subsystem.
- **batch delegates deeper to ekk.** `KKPRC14901.run()` — and by extension the validation path — eventually reaches `EKK0301A010.process()` in the `ekk` package, which contains the real batch execution logic.
- **bp dispatches through its own send class.** `JKKSodSendCC.send()` handles outbound transmission independently of the batch package, but both paths ultimately converge on the `ekk` subsystem for downstream processing.

The data model supporting both sub-packages lives in the sibling `com.optage.kopt.dto` package as `JKKSodRequestDTO` and `JKKSodResponseDTO`.

## Key Patterns and Architecture

### Create-on-Call Delegation

Both sub-packages follow a consistent pattern: collaborators are instantiated inline rather than injected or stored as fields. Examples:

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

This makes each orchestrator **stateless between calls** — every invocation is self-contained. The trade-off is simplicity (no lifecycle management, no shared mutable state) versus the inability to share configuration or context across operations without refactoring to injection.

### Facade / Thin Orchestrator

Neither sub-package performs the core business work itself. Instead, they act as facades:
- The **batch** package exposes entry points that forward to `ekk`.
- The **bp** package exposes SOD issuance operations that forward to `batch` (for validation) and `jkksodsend` (for dispatch), which in turn reach `ekk` downstream.

This layered delegation means the `com.optage.kopt` top-level package is primarily a **naming and organizational container** — the actual logic lives in sub-packages that this overview touches via reference.

### Tiered Batch Profiles

The three KKPRC classes (`149xx`, `249xx`, `349xx`) suggest a planned tiered batch pipeline where primary, secondary, and tertiary batch jobs would run in sequence. Currently only the primary tier is implemented, indicating this is a work-in-progress design.

### Base-class Initialization

`JKKBpServiceBase.baseInit()` provides a protected initialization hook that subclasses can override or extend. This is the module's sole use of inheritance-based code sharing, suggesting that if new SOD service classes are added, they would follow this extension pattern rather than composition.

## Cross-Module Interaction

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

```mermaid
flowchart LR
    A["bp.JKKHakkoSODCC"] -->|dispatch()| B["bp.JKKSodSendCC.send()"]
    A -->|validate()| C["batch.KKPRC14901.check()"]
    B -.->|downstream| D["ekk.EKK0301A010"]
    C -.->|downstream| D
    E["bp.JKKHakkoSODHelper.format()"] -.-> A
    A -.->|extends| F["bp.JKKBpServiceBase"]
```

Data flows through the system as follows:

1. An external caller (batch scheduler or task) instantiates a bp orchestrator (`JKKHakkoSODCC`).
2. **Validation:** `validate()` delegates to `KKPRC14901.check()`, which in turn delegates deeper into the `ekk` subsystem.
3. **Formatting (optional):** `JKKHakkoSODHelper.format()` normalizes text fields before dispatch.
4. **Dispatch:** `dispatch()` delegates to `JKKSodSendCC.send()`, which sends validated records to downstream systems.
5. Both the validation path and the dispatch path ultimately converge on the `ekk` package for actual processing.

## Dependencies and Integration

### Internal Dependencies

| Dependency | Package | Used By | Purpose |
|---|---|---|---|
| `KKPRC14901` | `com.optage.kopt.batch` | `JKKHakkoSODCC.validate()` | Batch validation via `check()` |
| `EKK0301A010` | `com.optage.kopt.ekk` | `KKPRC14901.run()` | Actual batch execution logic |
| `JKKSodRequestDTO` / `JKKSodResponseDTO` | `com.optage.kopt.dto` | Both sub-packages | Data transfer objects for SOD records |
| `JKKSodSendCC` | `com.optage.kopt.bp` | `JKKHakkoSODCC.dispatch()` | Outbound SOD dispatch |
| `JKKHakkoSODHelper` | `com.optage.kopt.bp` | `JKKHakkoSODCC` | Text normalization |
| `JKKBpServiceBase` | `com.optage.kopt.bp` | Subclasses | Shared initialization |

### External Dependencies

- **JUnit** — Used in `JKKHakkoSODCCTest` for unit testing. No other external dependencies were detected.

### Integration Points

- **Upstream:** External callers (batch schedulers, REST controllers) interact with the module through `JKKHakkoSODCC` (bp) or the KKPRC classes (batch). These are the leaf entry points.
- **Downstream:** Dispatched SOD records flow through `JKKSodSendCC.send()` to downstream systems. The actual transport mechanism is encapsulated within that method.
- **Deeper downstream:** Both validation and dispatch paths route through the `ekk` package (`EKK0301A010`), suggesting the `ekk` subsystem is the primary workhorse for batch and SOD processing.

## Notes for Developers

- **Fixture code:** All classes across both sub-packages are auto-generated fixture classes for `SPEC-SCOPED-WIKI` tests. The implementations are minimal placeholders. When integrating this documentation into a real codebase, replace placeholder descriptions with actual business logic details.

- **Stateless design:** `JKKHakkoSODCC` and `KKPRC14901` do not hold state between calls. If you need to share configuration or context across `dispatch()` and `validate()`, consider adding instance fields or switching to dependency injection.

- **Extension point — formatting:** `JKKHakkoSODHelper.format()` is currently just `String.trim()`. This is the natural home for additional formatting logic (encoding, date formatting, field truncation) as SOD data requirements evolve.

- **Extension point — base initialization:** When adding new service classes that share initialization steps, extend `JKKBpServiceBase` and call or override `baseInit()` rather than duplicating setup code.

- **Tiered batch pipeline:** Only KKPRC14901 (primary) is implemented. KKPRC24901 (secondary) and KKPRC34901 (tertiary) are stubs. To add a new batch workflow, follow the KKPRC14901 pattern — define a class with a `run()` method that instantiates and delegates to the appropriate handler in the `ekk` or other subsystem.

- **Test coverage:** `JKKHakkoSODCCTest.testMain()` is a stub (`assertTrue(true)`). New tests should cover that `dispatch()` correctly delegates to `JKKSodSendCC.send()`, that `validate()` correctly delegates to `KKPRC14901.check()`, and that `JKKHakkoSODHelper.format()` trims whitespace as expected.

- **Check method convention:** KKPRC14901 defines a `check()` method alongside `run()`. If this convention extends to secondary and tertiary batch classes when they are implemented, `check()` may be used for pre-flight validation before execution.