Iaud Module Create

i-AUD 모듈(Module) 생성 가이드

1. 모듈이란?

i-AUD 모듈은 프로세스 봇(WorkFlow)에서 재활용할 수 있는 클라이언트 스크립트 단위입니다. 모듈은 익명 함수 형태로 호출되며, 파라미터는 arguments[n]으로 전달받습니다.

실행 구조:
(function() {
    // ← SCRIPT_TEXT 내용이 여기에 들어감
    // arguments[0], arguments[1], ... 로 파라미터 수신
})(파라미터1값, 파라미터2값, ...)

2. 출력 파일 형식

모듈 생성 결과물은 .module.json 파일입니다. 파일명은 모듈 제목과 동일하게 합니다: [모듈제목].module.json

2.1 전체 JSON 구조

{
    "TYPE": "Single",
    "MTX_MODULE_INFO": [
        {
            "MODULE_CODE": "",
            "MODULE_SUBJECT": "모듈 제목",
            "USE_AUTHORITY": "0",
            "EDIT_AUTHORITY": "-1",
            "MODULE_DESCRIPTION": "모듈 설명",
            "SCRIPT_TEXT": "... JavaScript 소스코드 ...",
            "MODULE_TYPE": "",
            "RESULT_TYPE": "",
            "ORIGINAL_MODULE_CODE": "",
            "CREATE_USER": "",
            "MODIFY_USER": "",
            "MODULE_SEQ": "3",
            "WF_YN": "",
            "EVENT_YN": "N",
            "ATTR1": "",
            "ATTR2": "",
            "ATTR3": "",
            "MTX_MODULE_PARAMS": [
                {
                    "MODULE_CODE": "",
                    "PARAM_SEQ": "1",
                    "PARAM_TYPE": "INP001",
                    "NULLABLE": "N",
                    "PARAM_DESCRIPTION": "파라미터 설명",
                    "DEFAULT_VALUE": "",
                    "ATTR1": "",
                    "ATTR2": "",
                    "ATTR3": ""
                }
            ]
        }
    ]
}

2.2 주요 필드 설명

2.3 EVENT_YN 판단 기준

• "N" (기본): 모듈 실행 시 즉시 동작하고 완료 (예: 값 설정, 데이터 변환, Alert 표시)
• "Y": 모듈이 이벤트 핸들러를 등록하여 이후 사용자 동작에 반응 (예: 버튼 클릭 시 동작, 그리드 데이터 바인딩 시 동작)

3. 파라미터 타입 (PARAM_TYPE)

INP999 사용 시 ATTR1 설정

INP999는 ATTR1에 파이프(|)로 구분한 선택 목록을 정의합니다. 항목의 실제 값과 사용자에게 표현값을 달리하려면 값;표시문자 형태로 합니다.

{
    "PARAM_TYPE": "INP999",
    "PARAM_DESCRIPTION": "집계 함수를 선택해 주세요.",
    "DEFAULT_VALUE": "SUM",
    "ATTR1": "SUM;합계|COUNT;개수|AVG;평균|MIN;최소값|MAX;최대값"
}

4. 스크립트 작성 규칙

4.1 핵심 규칙

1. 순수 JavaScript로 작성 - TypeScript 문법 사용 불가 (var 사용, 타입 어노테이션 없음)
2. 익명 함수 본문 - function 선언 없이 바로 실행 코드 작성
3. 파라미터는 arguments[n] - 0부터 시작, 모두 string 타입
4. Matrix 객체 사용 가능 - 전역으로 접근 가능
5. EXECUTE_NEXT() 호출 - WorkFlow에서 다음 단계로 진행 시 호출 (비동기 작업 완료 후)
6. SCRIPT_TEXT는 한 줄 문자열 - JSON 내에서 줄바꿈은 \n, 따옴표는 \", 탭은 \t로 이스케이프

4.2 스크립트 구조 패턴

// 1. 파라미터 수신
var gridName = (arguments[0] || "").trim();
var chartName = (arguments[1] || "").trim();

// 2. 입력 검증 (validate)
var errors = [];
if (!gridName) errors.push("그리드 이름은 필수입니다.");
if (errors.length > 0) {
    Matrix.Alert("파라미터 오류\n\n" + errors.join("\n"));
    return;
}

// 3. 비즈니스 로직 (함수 정의 → 실행)
function doSomething() {
    var grid = Matrix.getObject(gridName);
    // ... 로직 ...
}

// 4. 실행 또는 이벤트 등록
doSomething();                          // EVENT_YN = "N" 일 때
// 또는
grid.OnDataBindEnd = function() { ... }; // EVENT_YN = "Y" 일 때

4.3 이벤트 등록 모듈 패턴 (EVENT_YN = "Y")

이벤트를 등록하는 모듈은 실행 즉시 이벤트 핸들러를 바인딩하고, 이후 사용자 동작 시 실제 로직이 동작합니다.

var controlName = arguments[0];
var grid = Matrix.getObject(controlName);
if (grid) {
    grid.OnDataBindEnd = function(_sender, _args) {
        // 데이터 바인딩 완료 시 실행할 로직
    };
}

4.4 사용 가능한 API

모듈 스크립트에서는 클라이언트 스크립트 API를 사용합니다:

• Matrix.getObject(name) - 컨트롤 참조
• Matrix.Alert(msg) / Matrix.Confirm(msg, title, callback, type) - 메시지
• Matrix.CreateDataSet() - DataSet 생성
• Matrix.doRefresh(controlNames) - 컨트롤 새로고침
• Matrix.ExecutePlan(planName, params, callback) - 실행계획 호출
• Matrix.RunScriptEx(targets, serviceName, params, callback) - 서버 스크립트 호출
• Grid: GetDataSet(), GetFields(), GetRowCount(), SetDataSet(), Calculate(), Draw()
• DataTable: GetRowCount(), getData(rowIdx, fieldName), setData(rowIdx, fieldName, value), AppendRow(), AddColumn(name, isNumber)
• Chart: SetDataSet(ds), Draw()

자세한 API는 /iaud-client-script 스킬 또는 types/aud/ 폴더의 TypeScript 인터페이스를 참조하세요.

5. 모듈 생성 절차

사용자가 모듈 생성을 요청하면 아래 순서로 진행합니다:

Step 1: 요구사항 파악

사용자 요청에서 다음을 파악합니다:

• 모듈이 무엇을 하는지 (기능)
• 어떤 컨트롤을 대상으로 하는지
• 사용자에게 어떤 입력을 받아야 하는지
• 즉시 실행인지 이벤트 등록인지

Step 2: 파라미터 설계

• 각 입력 항목에 적합한 PARAM_TYPE 선택
• 필수/선택 여부(NULLABLE) 결정
• 사용자 친화적인 설명(PARAM_DESCRIPTION) 작성
• 기본값(DEFAULT_VALUE) 설정

Step 3: JavaScript 스크립트 작성

• 파라미터 수신 및 검증 코드
• 비즈니스 로직 함수
• 실행 코드 또는 이벤트 등록 코드

Step 4: .module.json 파일 출력

• 모듈 제목으로 파일명 결정
• JSON 구조에 맞게 조립
• SCRIPT_TEXT를 JSON 문자열로 이스케이프
• src/reports/[보고서폴더]/ 하위에 저장

6. 샘플 모듈

6.1 간단한 모듈: 컨트롤 값 초기화

{
    "TYPE": "Single",
    "MTX_MODULE_INFO": [
        {
            "MODULE_CODE": "",
            "MODULE_SUBJECT": "컨트롤 값 초기화 하기",
            "MODULE_DESCRIPTION": "선택된 컨트롤들의 값을 초기화 합니다.\n값은 빈 값으로 설정합니다.",
            "SCRIPT_TEXT": "var controls = arguments[0].split(\",\");\nvar ctl;\nfor(var i=0;i<controls.length; i++){\n\tctl = Matrix.getObject(controls[i]);\n\tif(ctl){\n\t\ttry{\n\t\t\tif(typeof ctl.SetValue == \"function\"){\n\t\t\t\tctl.SetValue(\"\");\n\t\t\t}else{\n\t\t\t\tif(ctl.Checked=== true){\n\t\t\t\t\tctl.Checked = false;\n\t\t\t\t}\n\t\t\t}\n\t\t}catch(e){}\n\t}\n}",
            "USE_AUTHORITY": "0",
            "EDIT_AUTHORITY": "-1",
            "MODULE_TYPE": "",
            "RESULT_TYPE": "",
            "ORIGINAL_MODULE_CODE": "",
            "CREATE_USER": "",
            "MODIFY_USER": "",
            "MODULE_SEQ": "3",
            "WF_YN": "Y",
            "EVENT_YN": "Y",
            "ATTR1": "",
            "ATTR2": "",
            "ATTR3": "",
            "MTX_MODULE_PARAMS": [
                {
                    "MODULE_CODE": "",
                    "PARAM_SEQ": "1",
                    "PARAM_TYPE": "INP005",
                    "NULLABLE": "N",
                    "PARAM_DESCRIPTION": "대상 컨트롤 목록",
                    "DEFAULT_VALUE": "",
                    "ATTR1": "",
                    "ATTR2": "",
                    "ATTR3": ""
                }
            ]
        }
    ]
}

6.2 이벤트 등록 모듈: 체크박스 변경 시 조회

{
    "TYPE": "Single",
    "MTX_MODULE_INFO": [
        {
            "MODULE_CODE": "",
            "MODULE_SUBJECT": "체크박스 상태 변경 시 특정 컨트롤 조회 하기",
            "MODULE_DESCRIPTION": "체크 박스 클릭 시 특정 컨트롤을 조회 합니다.",
            "SCRIPT_TEXT": "var controlNames = arguments[0];\nvar refreshCtls = arguments[1];\nvar controls = controlNames.split(\",\");\nvar chkBox, name;\nfor(var i=0; i<controls.length; i++){\n\tname = controls[i].trim();\n\tchkBox = Matrix.getObject(name);\n\tif(chkBox){\n\t\tchkBox.OnValueChange = function(s, e){\n\t\t\tMatrix.doRefresh(refreshCtls);\n\t\t};\n\t}\n}",
            "USE_AUTHORITY": "0",
            "EDIT_AUTHORITY": "-1",
            "MODULE_TYPE": "",
            "RESULT_TYPE": "",
            "ORIGINAL_MODULE_CODE": "",
            "CREATE_USER": "",
            "MODIFY_USER": "",
            "MODULE_SEQ": "3",
            "WF_YN": "",
            "EVENT_YN": "N",
            "ATTR1": "",
            "ATTR2": "",
            "ATTR3": "",
            "MTX_MODULE_PARAMS": [
                {
                    "MODULE_CODE": "",
                    "PARAM_SEQ": "1",
                    "PARAM_TYPE": "INP005",
                    "NULLABLE": "N",
                    "PARAM_DESCRIPTION": "체크 박스 컨트롤 목록",
                    "DEFAULT_VALUE": "",
                    "ATTR1": "",
                    "ATTR2": "",
                    "ATTR3": ""
                },
                {
                    "MODULE_CODE": "",
                    "PARAM_SEQ": "2",
                    "PARAM_TYPE": "INP005",
                    "NULLABLE": "N",
                    "PARAM_DESCRIPTION": "조회 대상 컨트롤",
                    "DEFAULT_VALUE": "",
                    "ATTR1": "",
                    "ATTR2": "",
                    "ATTR3": ""
                }
            ]
        }
    ]
}

6.3 복합 모듈: 데이터 그리드 필터·그룹핑 → 차트 바인딩

파라미터 6개, 입력 검증, 이벤트 등록을 포함하는 복합 모듈입니다. 실제 샘플은 src/reports/DataTable 필터_그룹핑/차트 데이터 구성하기 (데이터 그리드 필터 및 그룹).module.json을 참조하세요.

주요 특징:

• INP003(그리드 선택), INP004(차트 선택), INP001(텍스트), INP999(목록 선택) 활용
• arguments 수신 → validate → 이벤트 등록 → 비즈니스 함수 호출 패턴
• grid.GetFields()로 Caption → Name 변환 처리

7. SCRIPT_TEXT JSON 이스케이프 규칙

SCRIPT_TEXT는 JSON 문자열이므로 다음을 이스케이프해야 합니다:

중요: JavaScript 코드를 먼저 작성한 뒤, JSON 문자열로 변환하여 SCRIPT_TEXT에 넣습니다.

8. MCP 검증 도구 (validate_module)

모듈 JSON 파일을 작성한 후, MCP validate_module 도구를 호출하여 스키마 검증을 수행합니다.

사용 방법

MCP 도구: validate_module
파라미터:
  - path: 모듈 JSON 파일의 전체 경로
  또는
  - document: 모듈 JSON 문자열/객체

검증 항목

스키마 검증 (에러):

• TYPE이 "Single"인지
• 필수 필드 존재 여부 (MODULE_SUBJECT, SCRIPT_TEXT, USE_AUTHORITY, EDIT_AUTHORITY, MODULE_DESCRIPTION, MODULE_SEQ, EVENT_YN)
• MODULE_SUBJECT, SCRIPT_TEXT가 빈 문자열이 아닌지
• EVENT_YN이 "Y" 또는 "N"인지
• WF_YN이 "Y", "N", 또는 빈 문자열인지
• PARAM_TYPE이 유효한 코드(INP001~INP999)인지
• NULLABLE이 "Y" 또는 "N"인지
• 알 수 없는 속성이 포함되지 않았는지

비즈니스 로직 검증 (경고):

• ATTR3="MTX"인 경우 MATRIX 내장 모듈로 서버에서 가져오기 거부 경고
• PARAM_TYPE="INP999"인데 ATTR1(선택 목록)이 비어있는 경우 경고
• PARAM_SEQ 순번이 배열 순서와 일치하지 않는 경우 경고

모듈 생성 절차에 통합

Step 4(.module.json 파일 출력) 이후 반드시 validate_module 도구를 호출하여 검증합니다. 오류가 발견되면 수정 후 재검증합니다.

9. 체크리스트

모듈 생성 시 아래 항목을 확인합니다:

• 모듈 제목(MODULE_SUBJECT)이 기능을 명확히 설명하는가?
• MODULE_DESCRIPTION에 사용 방법과 주의사항이 있는가?
• 파라미터 타입(PARAM_TYPE)이 적절한가? (그리드→INP003, 컨트롤→INP004/005 등)
• 필수 파라미터의 NULLABLE이 "N"인가?
• 스크립트에서 파라미터 검증(validate)을 하는가?
• 컨트롤을 찾지 못했을 때 Matrix.Alert로 안내하는가?
• EVENT_YN이 올바르게 설정되었는가?
• SCRIPT_TEXT가 순수 JavaScript인가? (var 사용, 타입 어노테이션 없음)
• SCRIPT_TEXT 내의 따옴표, 줄바꿈이 올바르게 이스케이프되었는가?
• MCP validate_module 도구로 검증을 통과했는가?