VS Code 에서 i-AUD 보고서 개발하기

i-AUD Developer Kit 는 Visual Studio Code (VS Code) 에서 i-AUD 보고서 스크립트를 손쉽게 개발할 수 있도록 도와주는 공식 확장 도구(extenstion) 입니다.

💡 또한, GitHub Copilot 기반의 AI 코딩 에디터인 Cursor에서도 완벽하게 호환되어, AI 보조 기능과 함께 활용할 수 있습니다.

이 확장을 사용하면 다음과 같은 작업을 빠르고 간단하게 진행할 수 있습니다:

• i-AUD 보고서의 다운로드 & 업로드 - i-AUD 보고서를 가져오고 다시 올릴 수 있어요.
• TypeScript 기반 개발 - 클라이언트/서버 스크립트를 TypeScript 로 작성할 수 있습니다.
• 명령어 기반 실행 & 테스트 - 명령어 기반으로 보고서를 실행하고 테스트할 수 있습니다.
• 코드 자동 생성 - 보고서 컨트롤에 필요한 코드를 자동으로 생성해줍니다.

이 확장은 다음과 같은 분들에게 특히 유용합니다:

• i-AUD 보고서를 직접 개발하는 개발자
• 보고서 유지·보수를 담당하는 운영자
• 프로젝트 협업자

즉, "i-AUD 보고서를 작성·수정·테스트해야 하는 모든 사용자"에게 도움이 됩니다.

i-AUD Developer Kit 확장을 설치하고 사용하기 전에 몇 가지 환경을 먼저 준비해야 합니다.

✅ 1. 인증키 발급 안내

개발환경 세팅 과정에는 인증키 발급 절차가 포함되어 있습니다.

인증키를 발급받아야 i-AUD 서버와 정상적으로 연결할 수 있습니다.

• 📎 첨부파일(AccessToken 발급하기.pptx)을 참고해 인증키를 먼저 발급해 주세요.
• 🔗 인증키 가이드 보러가기

✅ 2. 개발환경 세팅을 위한 준비물 체크리스트

설치 전, 아래 항목들이 준비되어 있는지 확인해주세요.

• VS Code 설치

• Node.js (LTS 버전) 설치
  → 설치 후 명령어로 정상 설치 여부 확인

  node -v
  npm -v

• TypeScript 전역 설치
  → 설치 후 명령어로 정상 설치 여부 확인

  tsc -v

• 인증키 발급 완료 여부
  → 인증키가 없으면 보고서 다운로드·업로드가 동작하지 않습니다.

가장 간단한 방법은 Visual Studio Code Marketplace 를 통해 설치하는 것입니다.

1. VS Code 왼쪽 사이드바에서 Extensions(확장) 아이콘 클릭
2. 검색창에 i-AUD Developer Kit 입력
3. Install(설치) 버튼 클릭

VS Code 명령 팔레트(Ctrl+Shift+P) 에서 "AUD" 입력 시 관련 명령어 나타나는지 확인

프로젝트를 시작할 폴더를 먼저 정한 뒤, 해당 폴더에서 VS Code 를 열어주세요.

code .

1. GitHub에서 개발 환경에 필요한 Seed Project 를 다운로드합니다.
   URL : https://github.com/AUD-DEV-TEAM/i-AUD-Developer-Kit

2. 터미널에서 아래 명령어를 실행하여 프로젝트 빌드에 필요한 라이브러리를 설치하세요:

   npm install

1. Ctrl + Shift + P 로 명령 팔레트를 열기
2. AUD 입력
3. Import Report 명령어 선택
   이때 아래와 같은 경고가 표시됩니다:
   "설정 파일(settings.json)의 'aud.config.SourcePath' 항목이 비어 있습니다. 값을 입력해주세요."

⚡ 이 과정을 거치면 .vscode 폴더 하위에 settings.json 파일이 자동 생성됩니다.

생성된 settings.json 파일에 아래 예시와 속성 설명을 참고해서, 사용자의 환경에 맞게 값들을 수정해 주세요:

i-AUD Designer 에서 새로운 보고서를 생성하고, 필요한 컴포넌트를 배치하여 디자인을 완료합니다.

저장을 완료하면 해당 보고서가 서버에 등록됩니다.

1. Vs Code 명령 팔레트( Ctrl + Shift + P ) 에서 AUD: Download Report 실행합니다.
2. 이때 파라미터 입력 창이 나타나며, 여기서 ReportCode 를 입력합니다.
3. 다운로드가 완료되면, 보고서 관련 파일들이 src/reports/보고서명 폴더 하위에 생성됩니다.
   성공적으로 저장되면 아래와 같은 일림이 표시됩니다:
   "📢 보고서가 성공적으로 src/reports/ 폴더에 저장되었습니다. (보고서명)"

기본적으로 보고서 스크립트는 "보고서명.script.js" 로 생성됩니다.

TypeScript 로 개발하려면 파일 확장자를 .ts 로 변경하세요.

• 예: 보고서명.script.ts

명령 팔레트에서 AUD: Generate Starter Code 실행 → TypeScript 빌드에 필요한 모듈 import 코드가 자동 추가됩니다.

TypeScript 로 작성한 소스는 저장 시 트랜스파일 되어야 합니다.

이를 위해 settings.json 의 AutoBuild 속성 값을 어떻게 설정하느냐에 따라 두 가지 방법 중 하나를 선택할 수 있습니다.

tsc -w

1. VS Code 에서 소스를 수정한 뒤 저장합니다.
2. 명령 팔레트에서 AUD: Save Script 실행 → 현재 변경된 내용이 서버에 반영됩니다.
3. AUD: Run Designer 명령어 실행 → Chrome 브라우저가 열리며 보고서를 실행합니다.
4. 브라우저에서 보고서를 새로고침(Refresh) 해야 변경된 소스가 정상 반영됩니다.

증상

"작업하실 보고서 소스 파일을 편집기에서 먼저 선택해 주세요."

원인

활성 에디터가 없거나, 보고서 소스 파일이 선택되지 않음

보고서 폴더에 .aud.json 파일이 없거나, 내부에 지정된 ReportCode 값이 잘못되었을 수 있음

해결

1. VS Code 에서 해당 보고서의 스크립트 파일(.script.ts 등)을 탭으로 열어 활성화하세요.
2. 명령을 다시 실행합니다.
3. 여전히 동작하지 않는다면, 보고서 폴더에 .aud.json 파일이 존재하는지 확인하세요.
4. .aud.json 이 존재한다면, 내부에 기록된 ReportCode 값이 실제 서버에 저장된 보고서 코드와 일치하는지 점검하세요.

증상

"설정 파일(settings.json)의 'aud.config.SourcePath' 항목이 비어 있습니다. 값을 입력해 주세요."

“'aud.config.OutputPath' 항목이 비어 있습니다…”

“'aud.config.ServiceURL' 항목이 비어 있습니다…”

원인

aud.config 의 필수 항목이 비어 있거나 경로 또는 값이 잘못됨

해결

1. .vscode/settings.json 열고 환경에 맞게 수정하세요.

   항목	꼭 확인할 점
   SourcePath	소스(.ts) 위치 → .../src/reports/
   OutputPath	빌드 결과(.js) 위치 → .../out/reports/
   ServiceURL	서버 주소(context_root 포함)
   ApiKey	발급받은 인증
   UserName	MTX_USER 테이블에 존재하는 사용자 코드

증상

"이 동작을 수행하려면 src 폴더 안에 있는 보고서 소스 파일을 선택해야 합니다."

원인

settings.json 의 "SourcePath" 는 올바르게 설정되어 있지만, 현재 열려 있는 파일이 그 경로 하위가 아님

VS Code 프로젝트를 루트가 아닌 다른 상위 폴더로 열어서, 활성 파일 경로와 SourcePath 가 불일치함

해결

1. 현재 열려 있는 파일의 실제 경로를 확인합니다.
   반드시 SourcePath 로 시작하는 하위 폴더 안에 있어야 합니다.
2. VS Code 를 올바른 프로젝트 루트로 다시 "폴더 열기" 해서, SourcePath 경로와 일치하도록 맞춥니다.
3. 여전히 맞지 않다면, .vscode/settings.json 의 "SourcePath" 를 다시 확인해 실제 소스 루트(...\src\reports\)와 동일하게 수정하세요.

증상

"보고서 정보를 불러올 수 없습니다. .aud.json 파일을 확인해 주세요."

원인

.aud.json 파일이 없음 / 손상됨

해결

1. 보고서 루트에 .aud.json 존재 확인
2. JSON 파싱 오류 시 → 다시 다운로드

증상

"서버에서 오류를 반환하였습니다. Response(Code: …, Msg: … )"

원인

인증/ 접속 문제

• ApiKey 만료 또는 오입력, 토큰 불일치
• ServiceURL 오설정 ( 도메인/포트/컨텍스트 루트 누락 )
• 네트워크/프록시/방화벽 차단

대상 보고서 식별 문제

• 현재 폴더의 .aud.json 누락 또는 손상
• .aud.json 의 ReportCode 가 실제 서버 코드와 불일치
• (권한) DB 의 MTX_AUTHORITY 에 사용자 권한 미부여
• (등록) DB 의 MTX_REPORT 에 보고서 정보 미등록

리소스 기대 불일치

• 서버가 MX_GRID_ZIP_PATH 를 주지 않거나, settings.json 의 MX_GRID_BACKUP=false 로 리소스 다운로드를 끔

해결

1. 환경값을 재확인합니다.
   .vscode/settings.json 파일에서 ServiceURL, ApiKey, UserName 등등의 속성들이 올바른지 점검합니다.
2. 보고서 식별/권한 확인
   작업 폴더에 .aud.json 파일이 존재하는지 확인하고 ReportCode 가 올바른지, 해당 보고서가 MTX_REPORT 및 MTX_AUTHORITY 테이블에서 관리되는지 확인합니다.
3. 경로/작업 위치 점검
   현재 활성 파일이 SourcePath 하위인지 확인하고 프로젝트를 올바른 루트 폴더로 다시 오픈합니다.
4. 리소스 다운로드 기대 시
   .vscode/settings.json 파일에서 MX_GRID_BACKUP=true 로 설정하고 재시도합니다.

증상

"tsconfig.json not found."

원인

tsconfig.json 탐색 실패

해결

1. 루트에 tsconfig.json 위치 확인

증상

디자이너 실행 시 브라우저가 열리지 않음

원인

Chrome 미설치, 실행 경로 문제

해결

1. Chrome 설치 및 OS 별 실행 경로 확인

증상

"실행 할 SQL 파일을 활성화 해주세요."

원인

.sql 파일 아님

.mtsd / .sc 없음

연결 코드 미설

해결

1. SQL 파일을 활성화합니다.
2. 보고서 루트에 .mtsd 또는 .sc 가 존재하는지 확인합니다.
3. SQL 상단에 연결 코드( --@CONNECTION_CODE )를 추가합니다.

증상

"컨트롤 변수를 생성하시려면 Client Script(.script.ts) 파일을 선택해 주세요."

원인

Client Script 파일 아님

보고서 루트에 .mtsd / .sc 없음

해결

1. 보고서명.script.ts 를 열고 실행합니다.

증상

서버에서 오류 응답

성공 시 → "스크립트가 정상적으로 저장되었습니다."

원인

ApiKey / ServiceURL 설정 오류

네트워크 문제

해결

1. .vscode/settings.json 의 인증키와 URL 입력 정보를 확인합니다.
2. 방화벽/프록시 정책을 확인합니다.

증상

"워크스페이스 폴더가 열려있지 않습니다…"

원인

VS Code가 파일 단독 실행 모드

해결

1. 폴더 단위로 VS Code를 오픈합니다.