Ezworks 요청 가이드

1. 개요

본 문서는 프로젝트 내 데이터 요청(Transaction) 처리를 위한 SQL 작성 및 화면 스크립트 구현 가이드입니다.

---

2. SQL 작성 (MyBatis)

SQL은 MyBatis 라이브러리를 사용하여 작성하며 다음 위치에 정의되어 있습니다. src/main/resources/ezinc/sqlmap

2.1. 기본 구조

MyBatis XML 파일은 mapper 루트 엘리먼트로 시작하며, namespace를 통해 해당 SQL들이 속한 그룹을 지정합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="example_namespace">
    <!-- SQL 정의 -->
</mapper>

2.2. CRUD 태그 및 속성

주요 SQL 작업을 위해 다음과 같은 태그를 사용합니다.

• <select>: 데이터 조회 (resultType 또는 resultMap 필수)
• <insert>: 데이터 삽입
• <update>: 데이터 수정
• <delete>: 데이터 삭제

[예시]

<select id="s01" resultType="java.util.HashMap">
    SELECT A.CFG_KEY    AS CFG_KEY
         , A.CFG_NM     AS CFG_NM
      FROM EZ_SYS_CFG_M A
     WHERE A.CFG_KEY = #{CFG_KEY}
</select>

2.3. 동적 SQL

• <if>: 조건부 SQL 포함
• <where>: ⚠️ 사용 금지 (팀 규칙상 WHERE 1=1과 <if> 조합을 사용하며, 기존 코드 참고용으로만 숙지)
• <choose>, <when>, <otherwise>: 다중 조건 처리 (Java의 switch-case 유사)

[예시]

<select id="s01" resultType="java.util.HashMap">
    SELECT A.CLA_CD      AS CLA_CD
         , A.CLA_CD_NM   AS CLA_CD_NM
      FROM CSB_COMN_CLA_CD_M A
     WHERE 1=1
    <if test="CLA_CD != null and CLA_CD != ''">
       AND A.CLA_CD = #{CLA_CD}
    </if>
</select>

2.4. 공통 예약 파라미터 (세션 정보)

_USER_INFO로 시작하는 파라미터는 **세션(Session)**에서 관리되는 정보입니다.

• #{_USER_INFO.USER_ID}: 로그인 사용자 ID
• #{_USER_INFO.USER_IP}: 사용자 접속 IP
• #{_PROG_INFO.MENU_ID}: 현재 메뉴 ID
• #{_PROG_INFO.PGM_PATH}: 현재 프로그램 경로

2.5. 복합 쿼리 (PL/SQL)

여러 개의 DML을 한 번에 실행할 때는 BEGIN ... END; 블록을 사용합니다.

<delete id="d01">
    BEGIN
        DELETE FROM CSB_COMN_CLA_CD_M WHERE CLA_CD=#{CLA_CD};
        DELETE FROM CSB_COMN_CD_M WHERE CLA_CD=#{CLA_CD};
    END;
</delete>

---

3. 화면 스크립트 작성 (Nexacro)

우리 프로젝트는 this.tx 객체를 통해 모든 서버 통신을 처리하며, Promise 기반의 async-await 문법을 표준으로 사용합니다.

3.1. 주요 메소드

• search: 데이터 조회 및 데이터셋 채우기
• save: 데이터셋의 변경사항(추가/수정/삭제)을 일괄 반영
• exec: 프로시저 호출 등 특정 로직 실행
• insert, update, delete: 개별 동작 수행

3.2. 트랜잭션 함수 정의 예시

우리 팀은 트랜잭션 요청 함수(예: fn_search)가 this.tx가 반환하는 Promise를 그대로 리턴하도록 작성하며, 화살표 함수(Arrow Function) 형식을 사용합니다.

// 조회 (search)
this.fn_searchMain = () => {
    const args = $f.mkArg({
        $div: this.div_search,
    });

    return this.tx.search({
        action : "basic",
        svcId  : "searchList",
        sqlId  : "hhj_0102_u01.s01",
        outDs  : "ds_main",
        param  : args
    });
};

// 저장 (save)
this.fn_saveMain = () => {
    return this.tx.save({
        svcId : "saveList",
        sqlId : "hhj_0102_u01.i01,hhj_0102_u01.u01,hhj_0102_u01.d01",
        inDs  : "ds_main"
    });
};

// 실행 (exec)
this.fn_execMain = () => {
    const sParam = $f.mkArg({
        $div : this.div_search,
    });

    return this.tx.exec({
        svcId : "execProc",
        sqlId : "hhj_0102_u01.p01",
        param : sParam
    });
};

3.3. 함수 호출 및 후처리 예시

트랜잭션 요청 함수를 호출하는 곳(버튼 클릭 이벤트 등)에서 async-await를 사용하여 후속 로직(알림창, 재조회 등)을 처리합니다.

// 조회 버튼 클릭 시
this.fn_search = async function() {
    await this.fn_searchMain();
};

// 저장 버튼 클릭 시
this.fn_save = async function() {
    await this.fn_saveMain();
    this.pop.alert("저장되었습니다.");
    await this.fn_search(); // 저장 후 재조회
};

// 실행 버튼 클릭 시
this.fn_execTask = async function() {
    const { data } = await this.pop.confirm({
        msg : "처리를 진행하시겠습니까?",
    });
    
    if(data) {
        await this.fn_exec();
        this.pop.alert("처리가 완료되었습니다.");
    }
};

3.4. 트랜잭션 정보 객체 주요 속성

속성명	타입	설명
svcId	string	요청 고유 ID (중복 불가)
sqlId	string	MyBatis SQL ID (namespace.id)
inDs	string	서버로 전달할 데이터셋
outDs	string	결과를 받을 데이터셋
param	object	추가 파라미터

3.5. 에러 처리

ErrorCode < 0 발생 시 프레임워크에서 자동 메시지를 출력합니다. 개별 처리가 필요한 경우에만 try-catch를 사용합니다.

---

4. 주의 사항 및 참고 링크 (⚠️)

4.1. 개발 규칙

1. 중복 svcId 금지: 수행 중인 요청과 동일 ID 요청 시 에러 발생
2. SQL 별칭 필수: 테이블 별칭(A) 및 컬럼 별칭(AS ...) 필수 입력
3. 세션 값 활용: _USER_INFO 등은 파라미터로 보낼 필요 없음

4.2. 상세 문서

• this.tx (EzTrans) 도움말
• $f.mkArg 도움말