# Eo / Business / Util

## Overview

The `eo.business.util` package is a utility layer within the **eo Customer Backbone System** (eo顧客基幹システム), a telecom billing and customer management platform operated by K-Opticom. It lives inside the `koptBatch` application module and serves as the centralized constants repository for all batch-processing file I/O and database entity definitions.

Rather than containing business logic or reusable helper methods, this package follows a simple but widespread convention in the codebase: every class is a **constant class** (定数クラス) — a collection of `public static final String` field definitions. These constants act as the single source of truth for field names, column names, and record-type codes used throughout batch jobs, input/output file handlers, and data access layers.

This approach ensures consistency across dozens of batch modules: the same constant (`"SEIKY_KEI_NO"`) refers to the same logical field regardless of whether it appears in a file-processing class, a database entity, or a downstream service call.

## Sub-module Guide

### file — Flat File Processing Constants

The `eo.business.util.file` sub-package defines constants for every flat file that batch jobs read from or write to. There are **over 200 constant classes** organized by file type and processing domain.

The naming convention encodes the file's role:

| Prefix Pattern | Purpose |
|---|---|
| `JBSbatACIFE...` | Input file (IFE = Input File Entity) — customer contract, pricing, service data files |
| `JBSbatACIFM...` | Master file (IFM = Input File Master) — master data files for account, service, and billing information |
| `JBSbatKKIF...` / `JBSBatKKIF...` | KK-specific interface files — partner bank, financial institution, and special business flows |
| `JBSbatCHIF...` | CH-domain interface files — accounting, payment, and collection-related files |
| `JBSbatAKIF...` | AK-domain interface files — billing statement and estimate files |
| `JBSbatCKIF...` | CK-domain interface files — customer data management files |
| `JBSbatZDIF...` / `JBSbatFUIFI...` | Specialized domain files — deletion notification, CASSE flag files, smart running promotion data |
| `JBSbatCNIF...` | CN-domain interface files — content cancellation target files |

Each class documents the file's purpose in Japanese in its header comment (機能概要), for example:

- **JBSbatACIFE002** — (eo光電話利用呼情報データファイル)定数クラス — EO Fiber Phone usage call information data file constants
- **JBSbatACIFE012** — (US課金ログ情報)定数クラス — US Billing log information constants
- **JBSbatACIFE027** — (はぴeポイント引当審査結果データ(出力))定数クラス — HAPIe Point allocation review results output file constants
- **JBSbatACIFM001** — (UM課金対象サービス契約情報)定数クラス — UM billing target service contract information constants
- **JBSbatACIFM145** — (会計売掛金情報勘定科目化)定数クラス — Accounting receivables information account classification constants
- **JBSbatACIFM146** — (会計収納情報勘定科目化)定数クラス — Accounting collection information account classification constants
- **JBSBatKKIFM946** — 金融機関廃合情報一括登録ファイル — Financial institution merger information batch registration file constants

The constant classes handle a wide range of billing and customer operations: contract registration, pricing calculations, service charges, point allocation, financial institution data, cancellation processing, collection management, and financial settlement.

### table — Database Table/Entity Constants

The `eo.business.util.table` sub-package defines constants for database table column names. There are **over 100 entity classes** covering the batch application's data model.

These are organized by functional domain:

| Prefix Pattern | Domain |
|---|---|
| `JBSbatCK_T_...` | Customer management (customers, groups, corporate, individual) |
| `JBSbatCC_T_...` | Common/communication (mail, fax, login, temp files, recovery points) |
| `JBSbatCH_T_...` | Accounting (invoices, receipts, payments, special accounting) |
| `JBSbatAC_T_...` | Account-level transaction data (service contracts, call details, HAPIe points, NHK charges) |
| `JBSbatAC_M_...` | Account master data (pricing, penalties, tax rates, collection judgments) |
| `JBSbatCN_T_...` / `JBSbatCN_M_...` | Content/contract data (service contracts, genre, sales info) |
| `JBSbatAK_T_...` / `JBSbatAK_M_...` | Billing/estimation (billing plans, pricing) |

Representative entities include:
- **JBSbatCK_T_CUST** — Customer master table (the largest, at ~13KB of field constants)
- **JBSbatCH_T_SEIKY** — Invoice table
- **JBSbatAC_T_HAPIEPOINT** — HAPIe Point balance/transaction table
- **JBSbatAC_M_PRC_KMK** — Pricing item master
- **JBSbatCH_M_KAIK_UCWK** — Accounting internal classification

### How file and table Sub-modules Relate

These two sub-modules work as complementary layers in the batch data pipeline:

1. **File constants** define the field names of **flat files** — external data exchanged via batch jobs (CSV, fixed-width, etc.)
2. **Table constants** define the column names of **database tables** — where batch jobs persist and query data

When a batch job processes an input file (using `file` constants), it reads records whose fields are referenced through those constants, then maps the data to table entities (using `table` constants) for persistence. Conversely, when a batch job writes an output file, it reads from the database using table constants and writes fields using file constants.

This shared-constant approach means the field name `"SEIKY_KEI_NO"` (請求契約番号 — requested contract number) appears identically in both a flat file class and a database entity class, ensuring the mapping between file records and database rows remains correct across the entire batch pipeline.

## Key Patterns and Architecture

### Constant-Class Pattern (定数クラス)

Every class in this package follows the constant-class pattern:

```java
public class JBSbatACIFM001 {
    /** サービス識別 */
    public static final String SVC_SKBT = "SVC_SKBT";

    /** サービスコード */
    public static final String SVC_CD = "SVC_CD";
    // ... more fields
}
```

Key characteristics:
- Classes have **no methods** — only `public static final String` fields
- Each field has a Japanese doc-comment explaining the field's business meaning
- The string value matches the field name, providing a canonical identifier
- Classes are named with an encoded domain (`AC`, `CH`, `KK`, `CK`, etc.), a role indicator (`IFM`, `IFE`), and a sequential number

### Encoding Conventions in Class Names

The class names encode domain, file type, and sequence:

```
JBSbat  AC  IFM  001
   |     |    |    |
   |     |    |    └─ Sequential number within the domain
   |     |    └────── IFM=Input Master, IFE=Input File Entity
   |     └─────────── Domain code (AC=Account, CH=Accounting, CK=Customer, etc.)
   └───────────────── Application prefix (JBSbat = J-Batch)
```

### File Flow Architecture

The batch application primarily operates through file-driven workflows. A typical batch job in the eo system:

1. Reads an input file whose field names are defined in a `file/*IFE*` or `file/*IFM*` class
2. Performs business logic (pricing calculation, contract change, point allocation)
3. Writes output files or persists data to database tables using `table/*` constants
4. May generate error or detail output files referenced by other `file/` constant classes

This pattern is repeated for billing cycles, customer data updates, financial institution integration, and marketing campaigns.

## Dependencies and Integration

### Internal Dependencies

This package has no external dependencies — it contains only constant definitions. Other modules within `koptBatch` (and across the wider eo system) import these constants to ensure field name consistency. The `file/` and `table/` classes are imported by batch service classes, data access layers, and file processing utilities throughout the codebase.

### Cross-module Relationships

The constants defined here are consumed across the broader eo customer backbone system, which includes multiple application modules beyond `koptBatch`. The domain codes in class names (AC, CH, CK, CN, AK, etc.) correspond to functional areas that may span across multiple applications:

- **Customer domain (CK)** — shared with web-facing applications
- **Accounting domain (CH)** — consumed by billing and payment processing systems
- **Contract domain (CN)** — interfaces with service provisioning systems
- **Financial institution domain (KK)** — connects to external banking systems

## Notes for Developers

- **Adding a new constant class**: Create a new Java class in the appropriate sub-directory (`file/` or `table/`) following the naming convention. Include the standard copyright header and a Japanese doc-comment in the header explaining the file or table purpose.
- **Field naming**: Use UPPER_SNAKE_CASE for field names. The string value should match the field name.
- **Documentation**: Each class should have a header comment block with プログラミング内容 (program name, system name, module name, author, date) and 機能概要 (function description) in Japanese.
- **Maintenance**: Since these constants are shared across many modules, changes to field names require coordination across all consuming modules. Before modifying a constant, verify it is not referenced in unexpected places.
- **The child wiki page** (`.codewiki/eo/business/util/file.md`) provides detailed per-class documentation for the `file/` sub-package.