# Business Logic — JKKTvSvcKeiCourceChgCC.callSC() [37 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKTvSvcKeiCourceChgCC` |
| Layer | Common Component (CC) — shared service invocation utility |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKTvSvcKeiCourceChgCC.callSC()

This method serves as the central **service component dispatcher and response handler** for the service detail source change (Service Kei Souchi Henkou) domain. It orchestrates a single service component invocation through the `ServiceComponentRequestInvoker`, collects the structured response, and performs unified error processing — making it the standard gateway through which all downstream service operations (registration, change, cancellation) flow for this screen.

The method follows a **delegation + template routing** design pattern: it receives an inbound `CAANMsg`, transforms it into a parameter map via `editInMsg`, dispatches the call through the generic `scCall.run()` bridge (which routes to the actual SC implementation based on the embedded service type), and then unpacks the `CAANMsg` template array from the result. The first template becomes the return message to the caller.

After the service component returns, this method performs **unified post-processing**: it normalizes the return code and status fields, delegates error enrichment to `editErrorInfoCom` and `TemplateErrorUtil.getErrorInfo`, stores structured error information into the control map, and finally enforces a gate — if either the return code is not `"0"` or the status is non-zero, it throws an `SCCallException` to abort the calling chain.

In the larger system, this is a **private shared utility** called exclusively by `JKKTvSvcKeiCourceChgCC.courceChange()`, which handles service contract line item modifications (Fiber-to-the-Home, Mail, ENUM) within screen KKSV0004. The method abstracts away the boilerplate of SC invocation so that business logic methods can focus on domain operations without boilerplate error handling.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["callSC params"])
    START --> A["editInMsg: Build paramMap"]
    A --> B["scCall.run: Invoke service component"]
    B --> C["Extract templates from result"]
    C --> D["Get return_code"]
    D --> E["Get status"]
    E --> F["editErrorInfoCom: Update error info"]
    F --> G["Get errList from control map"]
    G --> H["Set ERROR_INFO via TemplateErrorUtil"]
    H --> I{Code equals 0 and status equals 0?}
    I -->|"No"| J["Throw SCCallException"]
    I -->|"Yes"| K["Return msg"]
    J --> END(["End"])
    K --> END
```

**Processing Steps:**

1. **`editInMsg(param, inCAANMsg)`** — Transforms the inbound `CAANMsg` and request parameters into a single `HashMap<String, Object>` parameter map that the service component expects as input. This is the request serialization step.

2. **`scCall.run(paramMap, handle)`** — Delegates the parameter map to the `ServiceComponentRequestInvoker`, which dispatches to the actual SC (Service Component) implementation registered under the current screen context. The SC code targeted is determined by the caller's prior setup (e.g., `EKK0362A000SC` for service detail source changes).

3. **Extract `templates`** — Retrieves the `CAANMsg` template array from the result map under `JCMConstants.TEMPLATE_LIST_KEY`. This array contains strongly-typed response message templates.

4. **Extract `msg`** — Assigns `templates[0]` (the primary response template) to the local variable `msg` — this becomes the eventual return value.

5. **Extract `return_code`** — Reads the return code integer from the result map under `JCMConstants.RET_CD_INT_KEY`. This field indicates whether the SC execution succeeded (value `"0"`) or failed.

6. **Extract `status`** — Reads the status field from `templates[0]` via `ETN0081B030CBSMsg.STATUS`. This is a business-level status code on the response message.

7. **`editErrorInfoCom(param, templates, return_code, dataMapKey)`** — Delegates error enrichment: updates error information in the control map and on the parameter object based on the return code and template array.

8. **Retrieve and build error list** — Pulls any existing error list from the control map under `SCControlMapKeys.ERROR_INFO`. If none exists, initializes an empty `ArrayList`.

9. **`TemplateErrorUtil.getErrorInfo(result, errList)`** — Enriches the error list with any additional error details extracted from the result map, then stores the enriched list back into the control map under `SCControlMapKeys.ERROR_INFO`.

10. **Validation gate** — Checks if **both** `return_code` equals `"0"` **and** `status` equals `0`. If either condition fails, throws an `SCCallException` with the literal message "戻値不正" (Return value abnormal), carrying both the `return_code` and `status` as diagnostic properties.

11. **Return** — If validation passes, returns the `msg` (templates[0]) to the caller.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `handle` | `SessionHandle` | The current database session and transaction context. Carries user authentication, tenant/enterprise ID, and JDBC connection state used by the invoked service component to perform data access. |
| 2 | `scCall` | `ServiceComponentRequestInvoker` | The service component dispatch bridge. This invoker is pre-configured by the caller to route to a specific SC (e.g., `EKK0362A000SC` for source change registration). It handles the low-level invocation protocol and result deserialization. |
| 3 | `param` | `IRequestParameterReadWrite` | The request parameter container holding input data for the screen operation. Contains service detail source change data (service type codes, work numbers, order content codes) plus a control map for storing intermediate processing state such as error lists. |
| 4 | `dataMapKey` | `String` | The key used to identify and store error information within the `param`'s control map. Enables error data to be correlated back to a specific data processing step or message within the screen flow. |
| 5 | `inCAANMsg` | `CAANMsg` | The inbound business message containing the raw service detail source change request data. Structured with fields for service detail work number (`svc_kei_ucwk_no`), service type, order content code (`odr_naiyo_cd`), and change reason codes. |

**External state referenced:**

| Source | Description |
|--------|-------------|
| `JCMConstants.TEMPLATE_LIST_KEY` | Static constant used as the map key to extract the `CAANMsg[]` template array from the SC result. |
| `JCMConstants.RET_CD_INT_KEY` | Static constant used as the map key to extract the integer return code from the SC result. |
| `ETN0081B030CBSMsg.STATUS` | Static field from the CBS message class representing the `status` field key in the response template. |
| `SCControlMapKeys.ERROR_INFO` | Static constant used as the control map key for storing and retrieving structured error information (`ArrayList<Object>`). |

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `scCall.run` | (delegated — caller-configured SC) | (delegated) | Generic service component dispatch. The actual SC code and database operations depend on the invoker's pre-configured target (e.g., `EKK0362A000SC` for service detail source changes). |
| U | `JKKTvSvcKeiCourceChgCC.editInMsg` | - | - | Transforms `inCAANMsg` into a parameter map. Updates the `param` object by populating its data map with request values. |
| U | `JKKTvSvcKeiCourceChgCC.editErrorInfoCom` | - | - | Enriches error information in the control map and parameter based on the SC return code and template array. |
| U | `TemplateErrorUtil.getErrorInfo` | - | - | Extracts error details from the SC result map and error list, then stores them under `SCControlMapKeys.ERROR_INFO`. |
| R | `scCall.run` (result.get) | (delegated) | (delegated) | Reads the template list and return code from the SC result map after invocation completes. |

The actual service component SC code and entity/table operations are determined by the `scCall` invoker's configuration set by the caller (`courceChange()`). The `callSC` method itself is SC-code-agnostic — it provides a standardized invocation and error-handling envelope.

## 5. Dependency Trace

### Pre-computed evidence from code analysis graph:

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.
Terminal operations from this method: `getErrorInfo` [R], `getErrorInfo` [R], `getErrorInfo` [R], `editErrorInfoCom` [U], `run` [-], `run` [-], `run` [-], `run` [-], `run` [-], `editInMsg` [U]  # NOSONAR

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKSV0004 (inferred from caller class) | `JKKTvSvcKeiCourceChgCC.courceChange()` → `callSC(handle, scCall, param, dataMapKey, inCAANMsg)` | `scCall.run (delegated SC)` — actual SC code and entity depend on invoker setup by `courceChange()` |

**Caller: `JKKTvSvcKeiCourceChgCC.courceChange()`**
- This method is the **only direct caller** of `callSC`.
- `courceChange()` sets up the `ServiceComponentRequestInvoker` with the appropriate SC target and invokes `callSC` to dispatch the service detail source change operation.
- The screen context is KKSV0004, which handles service contract line item modifications (FTTH, Mail, ENUM).

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] Request Map Construction (L405)

> Transforms the inbound CAANMsg into a parameter map using editInMsg. This is the request serialization step.

| # | Type | Code |
|---|------|------|
| 1 | SET | `paramMap = editInMsg(param, inCAANMsg)` |
| 2 | EXEC | // Build HashMap<String, Object> from param and inCAANMsg fields |

**Block 2** — [CALL] Service Component Invocation (L408)

> Delegates to the SC via the pre-configured invoker. The actual target SC is set up by the caller.

| # | Type | Code |
|---|------|------|
| 1 | SET | `result = scCall.run(paramMap, handle)` |
| 2 | EXEC | // Dispatches to the registered service component; blocks until SC completes |

**Block 3** — [SET] Template and Message Extraction (L410-L411)

> Unpacks the CAANMsg template array from the SC result and captures the primary response message.

| # | Type | Code |
|---|------|------|
| 1 | SET | `templates = (CAANMsg[]) result.get(JCMConstants.TEMPLATE_LIST_KEY)` |
| 2 | SET | `msg = templates[0]` |
| 3 | EXEC | // First template is the primary response message |

**Block 4** — [SET] Return Code and Status Extraction (L414-L415)

> Reads the two key validation fields: the SC return code and the message-level status code.

| # | Type | Code |
|---|------|------|
| 1 | SET | `return_code = result.get(JCMConstants.RET_CD_INT_KEY)` |
| 2 | SET | `status = templates[0].getInt(ETN0081B030CBSMsg.STATUS)` |
| 3 | SET | `JCMConstants.RET_CD_INT_KEY` — map key for the integer return code field |
| 4 | SET | `ETN0081B030CBSMsg.STATUS` — field key "status" in the CBS message |

**Block 5** — [CALL] Error Info Enrichment (L417)

> Delegates to the error processing method which updates the control map and param with initial error state based on the return code.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `editErrorInfoCom(param, templates, (Integer)return_code, dataMapKey)` |
| 2 | EXEC | // Updates error state in control map and parameter object |

**Block 6** — [IF] Error List Retrieval and Population (L420-L425)

> Retrieves any existing error list from the control map, initializes an empty list if none exists, then populates it with enriched error details.

| # | Type | Code |
|---|------|------|
| 1 | SET | `errList = (ArrayList<Object>) param.getControlMapData(SCControlMapKeys.ERROR_INFO)` |
| 2 | EXEC | // SCControlMapKeys.ERROR_INFO — control map key for error information list |

**Block 6.1** — [IF] Initialize Error List (L421-L423)

> If no prior error list exists in the control map, create a fresh one.

| # | Type | Code |
|---|------|------|
| 1 | IF | `errList == null` |
| 2 | SET | `errList = new ArrayList<Object>()` |

**Block 6.2** — [SET] Populate Error List (L426)

> Enrich the error list with error details extracted from the SC result, then store it back into the control map.

| # | Type | Code |
|---|------|------|
| 1 | SET | `param.setControlMapData(SCControlMapKeys.ERROR_INFO, TemplateErrorUtil.getErrorInfo(result, errList))` |
| 2 | EXEC | // Enriches and stores structured error info |

**Block 7** — [IF] Validation Gate — Error Throw (L429-L431)

> After the SC returns, validates that both the return code equals "0" and the status equals 0. If **either** condition fails, throws an SCCallException with the literal message "戻値不正" (Return value abnormal). This is the sole error-exit path from this method.

| # | Type | Code |
|---|------|------|
| 1 | IF | `!(return_code.toString().equals("0") && status == 0)` |
| 2 | [IF-THEN] | **Condition:** `return_code` is not "0" **OR** `status` is non-zero |
| 3 | EXEC | `throw new SCCallException("戻値不正", return_code.toString(), status)` |
| 4 | EXEC | // "戻値不正" — Return value abnormal (Japanese original) |

**Block 8** — [RETURN] Normal Return (L434)

> If validation passes, the primary response message (templates[0]) is returned to the caller.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return msg` |
| 2 | EXEC | // msg is the primary CAANMsg template from the SC response |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `callSC` | Method | Service Component Call — standardized SC invocation and error-handling wrapper method |
| `svc_kei_ucwk_no` | Field | Service Detail Work Number — internal tracking ID for service contract line item processing |
| `odr_naiyo_cd` | Field | Order Content Code — classifies the type of service order (FTTH registration, Mail change, ENUM change, etc.) |
| SC | Acronym | Service Component — a service-layer module that implements a specific business operation (e.g., `EKK0362A000SC`) |
| CC | Acronym | Common Component — shared utility classes used across multiple business logic classes |
| CAANMsg | Type | CAAN Message — Fujitsu's structured message container holding typed business data fields (int, String, etc.) |
| CBS | Acronym | CBS (Customer Business System) — the backend telecom business system; CBSMsg classes model database-queried message structures |
| SCCallException | Exception | Service Component Call Exception — thrown when the SC returns an abnormal return code or status |
| TEMPLATE_LIST_KEY | Constant | Map key for extracting the `CAANMsg[]` template array from the SC invocation result |
| RET_CD_INT_KEY | Constant | Map key for extracting the integer return code from the SC invocation result |
| STATUS | Constant | Field key "status" in the CBS response message (`ETN0081B030CBSMsg`) |
| ERROR_INFO | Constant | Control map key for the `ArrayList<Object>` containing structured error information |
| editInMsg | Method | Input message transformer — converts `CAANMsg` to `HashMap<String, Object>` parameter map |
| editErrorInfoCom | Method | Error info composer — enriches the control map with error details from the SC response |
| TemplateErrorUtil | Class | Utility for extracting structured error information from SC result maps |
| `courceChange` | Method | Service source change orchestrator — sets up SC invoker and dispatches to `callSC` |
| KKSV0004 | Screen | Service detail source change screen — handles FTTH, Mail, and ENUM service contract line item modifications |
| return_code | Field | SC return code — "0" indicates success; non-zero indicates failure |
| status | Field | Business status code on the response template — 0 indicates normal completion |
| "戻値不正" | Japanese phrase | "Return value abnormal" — error message indicating SC returned an invalid return code or non-zero status |