# Com

## Overview

The `com` package is the top-level Java namespace for the entire project, encompassing three distinct and unrelated business domains. It contains no source files or classes directly; instead, it acts as the root container for sub-packages that serve entirely different purposes:

- **`com.example`** — A fixture/tree of empty classes used to exercise Java import resolution, static analysis, and code-quality tooling.
- **`com.fujitsu`** — A legacy Java EE web application (Fujitsu Futurity) providing the HTTP-facing boundary of the system, currently scaffolded as no-op stubs registered through XML deployment descriptors.
- **`com.optage`** — An internal batch-processing framework (KOPT) for orchestrating Start-of-Day (SOD) operations, currently scaffolded with real cross-module wiring but stubbed method bodies.

These three domains are siblings under `com` with no shared dependencies or direct communication. They represent three different stages of codebase maturity: `com.example` is a synthetic test fixture, `com.fujitsu` is a structural skeleton awaiting implementation, and `com.optage` is a scaffolded production system with intentional cross-module wiring but incomplete business logic.

## Sub-module Guide

### com.example — Fixture / Tooling Tree

The `com.example` package is not a production application. It exists solely to exercise tooling — Java import resolution, static analysis, and code-quality checks — through minimal, well-known classes. Its most significant sub-package is `com.example.bugca002`, which contains `KnownClass`, an intentionally empty class that serves as an import resolution anchor. Other modules (particularly JSP views) import `KnownClass` to validate that the build pipeline can resolve cross-package, cross-language (Java-to-JSP) imports correctly.

This is a leaf module: it has no outgoing dependencies and is consumed by other parts of the codebase to verify tooling health.

### com.fujitsu — Fujitsu Futurity Web Tier

The `com.fujitsu` package is the web-facing boundary of the Fujitsu Futurity application. It defines the servlet-container boundary — the entry point through which HTTP requests and application lifecycle events flow from the JEE container into the domain logic of downstream packages.

The package today is best understood as a **structural skeleton**. Its components (a Shift JIS encoding filter and an application context listener in `com.fujitsu.futurity.web.x33`) are registered exclusively through XML deployment descriptors (`web.xml` and `web-full.xml`) and are currently no-op stubs. The infrastructure is wired; the business logic is not yet implemented. This appears to be a legacy Java EE application targeting Japanese enterprise deployments, using a configuration-over-code pattern and a stub-first, implement-later approach.

### com.optage — KOPT Batch Processing Framework

The `com.optage` package contains the KOPT system, an internal framework for orchestrating Start-of-Day (SOD) operations for the JKK client or internal system. It follows a strict layered delegation architecture with four active sub-modules:

| Sub-module | Role | Status |
|---|---|---|
| **`bp`** | SOD dispatch coordination (top-level orchestration) | Scaffolded, wiring active |
| **`batch`** | Batch execution scaffolding | Partially wired |
| **`ekk`** | Contract processing layer | Scaffolded |
| **`kkw`** | Batch-trigger notification mechanism | Scaffolded |
| **`dto`** | External data contract (request/response) | Defined, minimal |

KOPT follows a top-down delegation model: dispatch → validation → contract processing → notification. The `dto` layer sits alongside this chain as the external API contract.

### How They Relate

The three sub-modules are independent and have no shared dependencies:

```mermaid
flowchart TD
    Root["com - Root Java Package"]

    subgraph EX["com.example - Fixture/Tooling Tree"]
        EXRoot["com.example root"] --> EXBug["com.example.bugca002"]
        EXBug --> Known["KnownClass.java"]
    end

    subgraph FUJ["com.fujitsu - Fujitsu Futurity Web Tier"]
        FUJRoot["com.fujitsu root"] --> FUT["com.fujitsu.futurity"]
        FUT --> Web["com.fujitsu.futurity.web"]
        Web --> X33["com.fujitsu.futurity.web.x33"]
        X33 --> Filter["X33JVRequestEncodingSjisFilter"]
        X33 --> Listener["X33AppContextListener"]
    end

    subgraph OPT["com.optage - KOPT Batch Processing"]
        OPTRoot["com.optage root"] --> KOPT["kopt - KOPT system"]
        KOPT --> BP["bp - SOD Dispatch Coordination"]
        KOPT --> BATCH["batch - Execution Scaffolding"]
        KOPT --> EKK["ekk - Contract Processing"]
        KOPT --> KKW["kkw - Batch Trigger"]
        KOPT --> DTO["dto - Data Contracts"]
    end

    Root --> EX
    Root --> FUJ
    Root --> OPT
```

While these sub-modules do not communicate with each other, they share a common theme: much of the codebase under `com` is in a **scaffolded or transitional state**. Both `com.fujitsu` and `com.optage` have real architectural wiring with stubbed method bodies, while `com.example` is a synthetic fixture with no behavior at all.

## Key Patterns and Architecture

### Fixture / Test-Class Pattern (com.example)

Every class in `com.example` follows the same pattern: define a minimal, empty public type in a clearly named sub-package, keep it devoid of fields, constructors, or business logic, and make it a cross-reference target for downstream consumers (JSP views, analysis scripts). This is a common pattern in static-analysis test projects where the goal is to verify tooling, not application behavior.

### Configuration-over-Code Registration (com.fujitsu)

All components in the `com.fujitsu` package are wired into the servlet container exclusively through `web.xml` and `web-full.xml` deployment descriptors. No `@WebFilter` or `@WebListener` annotations are used. This approach is typical of legacy Java EE applications that predate servlet 3.0 annotations, or of enterprise deployments that prefer explicit, auditable, version-controlled XML configuration.

### Stub-First, Implement-Later Pattern (com.fujitsu, com.optage)

Both `com.fujitsu` and `com.optage` follow a stub-first approach: component registration is in place through deployment descriptors or cross-module wiring, but the method bodies are empty or contain placeholder comments. This minimizes merge conflicts and deployment risk when adding new functionality. The architecture is designed and wired; the business logic awaits implementation.

### Layered Delegation Architecture (com.optage)

The KOPT system in `com.optage` follows a clean layered delegation pattern with four active layers and a strict top-down call flow:

```mermaid
sequenceDiagram
    participant Caller
    participant BP as JKKHakkoSODCC
    participant BATCH as KKPRC14901
    participant EKK as EKK0301A010
    participant KKW as KKW0100B001

    Caller ->> BP: JKKSodRequestDTO
    BP ->> BP: validate
    BP ->> BATCH: check
    BATCH ->> EKK: process
    EKK ->> KKW: notify
    KKW -->> EKK: trigger event
    EKK -->> BATCH: process complete
    BATCH -->> BP: validation result
    BP ->> BP: dispatch
    BP -->> Caller: JKKSodResponseDTO
```

The call chain flows: dispatch (`bp`) → validation (`batch`) → contract processing (`ekk`) → notification (`kkw`). Each layer delegates to the next without sideways branching. The `dto` layer provides the external API contract (`JKKSodRequestDTO`, `JKKSodResponseDTO`) that the `bp` layer consumes and produces.

### Systematic Class Naming Convention (com.optage)

Classes in the KOPT package 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. This convention spans both scaffolded and real implementation classes.

### Template Method for Shared Initialization (com.optage)

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

### Cross-Language Import Resolution (com.example)

A distinguishing architectural feature of the `com.example` package is that Java types are referenced from JSP views. The `com.example.bugca002` package is the primary Java-side anchor in this relationship. The build system must correctly resolve these cross-language references, and successful resolution is treated as a pass/fail signal for tooling health.

## Dependencies and Integration

### Internal Dependencies (within com.optage)

| 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

| Sub-package | Dependencies |
|---|---|
| `com.example` | None — it is a leaf module consumed by JSP views |
| `com.fujitsu` | `javax.servlet.*` API only (Filter, ServletRequest, ServletResponse, FilterConfig, FilterChain) |
| `com.optage` | `java.lang` standard library only; DTOs are intended for JSON serialization (Jackson/Gson) but do not currently declare those libraries |

### Integration with the Rest of the System

The `com` package contains three sibling sub-modules that integrate with the broader system in different ways:

- **`com.example`** — Consumed by JSP views and analysis tools. It is a leaf in the module dependency graph and serves as an import resolution anchor.
- **`com.fujitsu`** — Serves as the HTTP-facing entry point for the Fujitsu Futurity application. Incoming HTTP requests flow through its registered filters and listeners, then land in downstream servlets, controllers, or action classes in sibling packages outside `com.fujitsu`.
- **`com.optage`** — Acts as both a consumer and provider. The `bp` layer receives SOD dispatch requests (likely via API endpoints accepting `JKKSodRequestDTO`) and routes them through the KOPT processing chain, then produces output (including `JKKSodResponseDTO`) flowing back to callers.

## Notes for Developers

- **Do not treat `com.example` as production code.** Its empty classes are test fixtures for tooling. Removing sub-packages without verifying consumers can break JSP imports and code-quality checks. When adding new sub-packages, follow the existing pattern: minimal class with an empty method, in its own sub-package under `com.example`.

- **`com.fujitsu` components are no-ops.** The Shift JIS filter does not perform encoding, and the application context listener runs no initialization code. To activate the filter, add `((HttpServletRequest) req).setCharacterEncoding("Windows-31J")` in `doFilter()` before `chain.doFilter(req, res)`. To make the listener functional, add `implements javax.servlet.ServletContextListener` and implement `contextInitialized` / `contextDestroyed`.

- **Both `com.fujitsu` components are registered in two deployment descriptors** (`web.xml` and `web-full.xml`). Changes to one may need to be mirrored in the other depending on your deployment profile.

- **`com.optage` is scaffolded, not complete.** Most method bodies are placeholder comments. The cross-module wiring between `bp` → `batch` → `ekk` → `kkw` is intentional and real, but the business logic is not yet implemented. Follow the existing delegation pattern when adding new fixtures.

- **Input validation belongs in the service layer, not DTOs.** The `dto` classes carry only fields strictly necessary for their roles and have no validation annotations. Validate `tenantId` and `serviceId` in consuming services, not within the DTOs.

- **Class naming follows a systematic convention.** Use the 3-letter prefix + 6-digit code pattern (`KKP` for batch, `EKK` for contract processing, `KKW` for triggers, `ESC` for service control). When adding new classes, follow existing prefix conventions.

- **`JKKBpServiceBase` is a base class.** New services in the `bp` area should extend it to inherit shared `baseInit()` logic.

- **`esc` and `unrelated` are inert.** These modules in `com.optage` have no wiring or behavior. `unrelated` is purely for documentation tooling edge-case testing. If `esc` becomes operational, `control()` is the entry point.