i-AUD MTSD 문서(화면 UI 디자인) 생성 가이드. 새 보고서의 .design.json 파일을 처음부터 만들 때 사용합니다. build_mtsd(MtsdBuilder 스크립트)를 사용한 신규 문서 생성과 MCP 개별 도구를 사용한 기존 문서 수정을 포함합니다. "MTSD 만들기", "보고서 생성", "화면 만들기", "새 프로그램", "Element 추가", "디자인 파일" 등을 요청할 때 사용하세요.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
i-AUD MTSD 문서(화면 UI 디자인) 생성 가이드. 새 보고서의 .design.json 파일을 처음부터 만들 때 사용합니다. build_mtsd(MtsdBuilder 스크립트)를 사용한 신규 문서 생성과 MCP 개별 도구를 사용한 기존 문서 수정을 포함합니다. "MTSD 만들기", "보고서 생성", "화면 만들기", "새 프로그램", "Element 추가", "디자인 파일" 등을 요청할 때 사용하세요.
i-AUD MTSD 문서(화면 UI 디자인) 생성 가이드
1. 개요
MTSD는 i-AUD 보고서의 화면 UI 배치, 데이터소스, 서비스를 정의하는 JSON 문서 포맷입니다.
개발 환경에서는 간소화된 .design.json 파일로 관리합니다:
기본값 생략: 각 컨트롤 타입의 기본값과 동일한 속성은 제거됨 (Visible: true, Enabled: true, 기본 폰트/색상 등)
파일 경로 참조: ScriptText/SQL이 인라인 콘텐츠 대신 파일 경로(예: "./ServerScript/@XX.ts")로 대체됨
.mtsd는 서버 원본(모든 기본값 + 인라인 콘텐츠)을 유지하며 직접 수정하지 않습니다
.design.json이 없는 기존 보고서: save_report 또는 pull_report를 한 번 실행하면 간소화된 .design.json이 자동 생성됩니다.
간소화 원칙: AI가 .design.json을 작성/수정할 때 기본값과 동일한 속성은 생략합니다. 서버의 expandDesignJson()이 자동으로 복원합니다.
MTSD 생성 방식 선택
방식
도구
용도
권장 상황
빌더 스크립트 (1순위)
build_mtsd
JS 스크립트 1회 호출로 완전한 MTSD 생성
신규 보고서 생성
개별 MCP 도구 (2순위)
generate_element 등
Element/DataSource를 하나씩 생성
기존 MTSD 부분 수정/추가
신규 문서는 build_mtsd를 우선 사용합니다. 스크립트 1회 호출로 ID 자동 생성, 스키마 자동 준수, Group/DataGrid 중첩 처리가 모두 해결됩니다.
MCP 도구 목록
MCP 도구
용도
build_mtsd
MtsdBuilder 스크립트를 실행하여 완전한 MTSD 문서 생성 (신규 보고서 1순위)
generate_element
Element 1개 생성 (기존 문서에 추가할 때). compact: true로 간소화 출력
generate_grid_column
DataGrid의 GridColumn 배열 생성. compact: true로 간소화 출력
generate_datasource
DataSource 1개 생성 (기존 문서에 추가할 때). compact: true로 간소화 출력
generate_uuid
i-AUD 보고서용 UUID 생성 (prefix + 32자리 HEX)
get_boxstyle_list
BoxStyle 목록 조회 (Style.Type=1 사용 시 Name 키 확인)
save_boxstyle
BoxStyle 저장/수정
validate_mtsd
완성된 MTSD 또는 .design.json 문서 전체 검증. format: "design" 지정 시 간소화 스키마로 검증
validate_part
부분 검증 (Element, DataSource 등 개별 검증). format: "design" 지정 시 간소화 스키마로 검증
fix_mtsd
MTSD 파일 자동 보정 (파일 경로 입력 → 읽고 수정 후 덮어쓰기)
get_module_list
서버 모듈 목록 조회 (WorkFlow 모듈 노드 설정 시 사용)
get_module_params
특정 모듈의 파라미터 정의 조회 (WorkFlow 모듈 노드 파라미터 설정 시 사용)
2. 신규 문서 생성 — build_mtsd (MtsdBuilder 스크립트)
2.1 아키텍처
AI → JS 스크립트 작성 (MtsdBuilder API 사용) → build_mtsd MCP 도구가 실행 → MTSD JSON 반환
ID(ReportCode, DataSource Id, Element Id, Form Id) 모두 자동 생성
Position, Style, Border, Font, Color 등 복잡한 스키마 객체 내부 자동 처리
build_mtsd 사용 시에는 ID가 자동 생성되므로 generate_uuid가 필요 없습니다.
4. Docking 레이아웃 패턴
4.1 Docking 동작 원리
Docking은 컨트롤의 가장자리를 부모 컨트롤 영역의 가장자리에 맞추는 자동 맞춤 기능입니다.
Left: true → 컨트롤의 왼쪽 가장자리를 부모의 왼쪽에 맞춤
Right: true → 컨트롤의 오른쪽 가장자리를 부모의 오른쪽에 맞춤
Top: true → 컨트롤의 **상단을 부모의 상단(0)**에 맞춤
Bottom: true → 컨트롤의 하단을 부모의 하단에 맞춤
주의: Top: true는 컨트롤의 Top 위치를 유지하는 것이 아니라, 부모 영역의 Top(0)에 맞추는 것입니다. 마찬가지로 Bottom: true는 부모의 Bottom에 맞춥니다. 따라서 fill(모두 true)을 사용하면 부모 영역 전체를 덮게 됩니다.
4.2 기본 패턴
도킹
Left
Right
Top
Bottom
용도
"none"
F
F
F
F
고정 위치/크기
"left"
T
F
F
F
왼쪽 고정
"right"
F
T
F
F
오른쪽 고정
"left+right"
T
T
F
F
좌우 확장 (헤더, 검색바, 고정 높이 그룹)
"left+right+bottom"
T
T
F
T
좌우 확장 + 하단 채움 (그리드, 본문 영역)
"fill"
T
T
T
T
부모 영역 전체 채움 (단독 배치 시만 사용)
"bottom"
F
F
F
T
하단 고정
4.3 일반적인 화면 레이아웃
┌─────────────────────────────────────────┐
│ GRP_HEADER (docking: "left+right") │ 고정 높이 55
│ ├─ LBL_TTL (제목) │ Top: false
│ └─ BTN_SEARCH, BTN_SAVE (버튼) │ Bottom: false
├─────────────────────────────────────────┤
│ GRP_SEARCH (docking: "left+right") │ 고정 높이 60~80
│ ├─ LBL_FROM, CAL_FROM (조건 1) │ Top: false
│ └─ LBL_TO, CAL_TO (조건 2) │ Bottom: false
├─────────────────────────────────────────┤
│ GRD_MAIN (docking: "left+right+bottom")│ 나머지 영역
│ DataGrid │ Top: false ← 상단 위치 유지
│ │ Bottom: true ← 하단으로 확장
└─────────────────────────────────────────┘
4.4 Docking 선택 가이드
배치 유형
올바른 Docking
설명
상단 고정 높이 그룹 (헤더, 검색바)
Left+Right
좌우만 확장, 높이/위치 고정
하단 고정 높이 그룹 (푸터, 버튼바)
Left+Right+Bottom
좌우 확장 + 하단 고정, 높이 고정
그리드/본문 (위에 헤더 있음)
Left+Right+Bottom
좌우 확장 + 하단까지 채움, Top은 false로 상단 위치 유지
그리드/본문 (단독 배치)
fill
부모 전체 채움 (위에 다른 요소가 없을 때만)
그룹 내 고정 위치 컨트롤
none
Label, Button 등 고정 크기 컨트롤
흔한 실수: 헤더/검색바 아래에 그리드를 배치할 때 fill(모두 true)을 사용하면 그리드가 부모 전체를 덮어 헤더를 가립니다. 반드시 Top: false로 설정하여 그리드의 상단 위치를 유지해야 합니다.
4.5 Docking 부속 속성
Docking 객체에는 방향(Left/Right/Top/Bottom) 외에 추가 속성이 있습니다.
Margin — 부모 영역 안쪽 여백
도킹이 활성화된 방향에 대해 부모 가장자리와 컨트롤 사이의 **안쪽 여백(padding)**을 설정합니다.
형식: "Left,Top,Right,Bottom" (픽셀 단위, 쉼표 구분 문자열)
기본값: "0,0,0,0" (여백 없음)
부모 영역
┌──────────────────────────────────┐
│ ← Left margin │
│ ┌────────────────────────────┐ │
│ │ 컨트롤 (도킹 적용) │ │ ↑ Top margin
│ │ │ │
│ │ │ │
│ └────────────────────────────┘ │ ↓ Bottom margin
│ Right margin → │
└──────────────────────────────────┘
사용 예시:
Margin 값
의미
용도
"0,0,0,0"
여백 없음
기본값, 부모 가장자리에 딱 맞춤
"20,0,20,20"
좌·우·하 20px 여백
그리드에 좌우·하단 간격 부여
"20,75,20,20"
좌 20, 상 75, 우 20, 하 20
상단 헤더 영역(75px)을 피해 배치
"5,5,5,5"
전체 5px 여백
그룹 내부 컨트롤 균일 간격
HoldSize — Right/Bottom 도킹 시 크기 고정 (위치만 이동)
타입: boolean (기본값: false)
false: 도킹 방향으로 컨트롤이 늘어남 (기본 동작)
true: 컨트롤의 원래 Width/Height를 유지하고, 도킹 방향의 가장자리에 위치만 이동
핵심: HoldSize: true는 Right 또는 Bottom 도킹에서만 사용합니다. 우측/하단 가장자리를 기준으로 위치를 잡으면서 Width/Height를 고정할 때 씁니다.
주의: Left/Top 도킹에서는 HoldSize를 사용하지 않습니다. Left/Top은 좌측/상단 기준이므로 위치가 자연스럽게 고정되고, Height/Width도 반대편 도킹(Bottom/Right)이 false이면 자동으로 유지됩니다.
잘못된 예: Top: true, HoldSize: true → HoldSize 불필요, HoldSize: false로 변경
잘못된 예: Left: true, Right: false, HoldSize: true → Left 기준이므로 HoldSize 불필요
올바른 예: Right: true, HoldSize: true → 우측 기준 고정 너비
올바른 예: Bottom: true, HoldSize: true → 하단 기준 고정 높이
사용 예시:
화면 너비 변경 시 HoldSize 동작 비교:
HoldSize: false (기본) — 크기가 늘어남
┌─────────────────────────────┐
│ [=========버튼=========] ← │ Right: true → 우측에 맞추며 너비 확장
└─────────────────────────────┘
HoldSize: true — 위치만 이동
┌─────────────────────────────┐
│ [버튼] ← │ Right: true → 우측에 맞추되 원래 크기 유지
└─────────────────────────────┘
// 버튼을 항상 우측에서 20px 떨어진 위치에 고정 (크기 변경 없이 이동만)"Docking":{"Right":true,"HoldSize":true,"Margin":"0,0,20,0"}// 패널을 우측에 도킹하되 원래 너비(460px) 유지"Docking":{"Right":true,"Top":true,"Bottom":true,"HoldSize":true,"Margin":"20,75,20,20"}
필수 규칙: .design.json, .mtsd 또는 .sc 파일을 생성하거나 수정할 때마다 반드시 fix_mtsd → validate_part(또는 validate_mtsd) 순서로 실행합니다. 속성 타입 오류(예: array를 string으로 기입)나 필수 속성 누락은 MCP 검증으로만 확인할 수 있습니다.
참고: .design.json은 .mtsd와 동일한 JSON 구조이지만, 기본값이 생략되고 스크립트/SQL이 파일 경로 참조로 대체된 간소화 개발용 파일입니다. AI는 .design.json을 우선 사용하며, 기본값과 동일한 속성은 생략합니다.
워크플로우 A: 신규 문서 — build_mtsd (권장)
Step 1: build_mtsd 호출 (MtsdBuilder 스크립트 전달)
→ 완전한 MTSD JSON 반환 (ID, 스키마 자동 처리)
Step 2: 반환된 JSON을 .design.json 파일로 Write (없으면 .mtsd)
Step 3: fix_mtsd 실행 (DataSource Name→Id 참조 보정 등)
Step 4: validate_part로 파트별 검증 (Forms, DataSources). .design.json이면 format: "design" 사용
Step 5: save_report → run_designer로 결과 확인
워크플로우 B: 기존 문서 부분 수정 — 개별 MCP 도구
Step 1: 기존 .design.json 파일 Read (없으면 .mtsd/.sc)
Step 2: generate_element / generate_datasource / generate_grid_column으로 추가할 요소 생성
.design.json 대상이면 compact: true 사용
Step 3: 기존 JSON에 병합하여 Edit/Write
Step 4: fix_mtsd 실행 (자동 보정)
Step 5: validate_part로 파트별 검증 → 오류 발견 시 수정
.design.json 대상이면 format: "design" 사용
SELECT*FROMTABLEWHERE STATUS = :VS_STATUS -- 문자열 바인딩 (자동 따옴표 처리)AND AMOUNT > :VN_MIN_AMT -- 숫자 바인딩 (따옴표 없이 값 그대로)AND YMD >= @:VS_YMD_FROM -- @: 빈 값이면 해당 라인 삭제AND NAME LIKE%:VS_KEYWORD%-- %: LIKE 와일드카드 자동 포함AND USER_CODE = :VS_USER_CODE$ -- $: 서버 세션(인증) 값 사용
접두사/지시자
설명
:VS_
문자열 변수 (자동 따옴표 ' 감싸짐)
:VN_
숫자 변수 (따옴표 없이 값 그대로 치환)
@:
빈 값이면 해당 라인 전체를 삭제 (선택적 조건)
%:
LIKE 검색 와일드카드 자동 포함
$ (접미사)
클라이언트 값 대신 서버 세션 값 사용
8. Style.Type과 커스텀 색상 규칙
Style.Type 값과 동작
Type
이름
동작
0
Skin
스킨/테마 스타일 적용. Background/Border/Font의 커스텀 색상이 무시됨
1
BoxStyle
Style.BoxStyle에 지정한 박스스타일 적용
2
Custom
Background/Border/Font의 개별 색상값이 화면에 적용됨
핵심 규칙
배경색, 테두리, 폰트 색상을 커스텀할 때 반드시 Style.Type을 2(Custom)으로 설정해야 합니다.
Type이 0(Skin)이면 Background/Border/Font에 어떤 값을 설정해도 화면에 반영되지 않습니다.
이 경우 배경색이 파란색으로 설정되어 있지만, Type이 0(Skin)이므로 실제 화면에는 스킨 기본 색상이 표시됩니다.
자동 보정: fix_mtsd는 Background/Border/Font에 커스텀 색상이 설정되어 있는데 Type이 0(Skin)이면 자동으로 2(Custom)으로 보정합니다.
BoxStyle (Type=1) 사용법
BoxStyle은 CSS 파일처럼 서버에서 공통으로 관리되는 스타일 세트입니다.
배경색, 테두리(색상/두께/라운드), 폰트(크기/굵기/색상/정렬)를 하나의 키(Name)로 묶어 관리하며, 여러 보고서에서 동일한 디자인을 일관되게 적용할 수 있습니다.
사용자가 서버 관리 화면에서 기존 BoxStyle을 수정하거나 새로운 BoxStyle을 추가할 수 있으므로, 반드시 get_boxstyle_list MCP 도구로 현재 서버의 BoxStyle 목록을 조회하여 Name 키를 확인한 뒤 사용하세요.
기본 BoxStyle 목록과 시각적 속성:
StyleName
용도
배경
테두리
폰트
Button Default
버튼 기본
밝은 회색(249,249,251)
회색 solid 1px, 둥근모서리 4px
Bold 12px, 검정(48,48,49), 중앙정렬
Button Hover
버튼 마우스오버
연보라(238,238,243)
회색 solid 1px, 둥근모서리 4px
Bold 12px, 검정, 중앙정렬
Button Disabled
버튼 비활성
진회색(218,218,222)
회색 solid 1px, 둥근모서리 4px
Bold 13px, 연회색(170,170,172), 중앙정렬
Tab Default
탭 기본
투명
투명, 하단 3px
13px, 회색(115,115,119), 중앙정렬
Tab Hover
탭 마우스오버
투명
파란색(66,97,242) 하단 1px
13px, 회색, 중앙정렬
Tab Active
탭 활성
투명
파란색(66,97,242) 하단 3px
Bold 13px, 검정, 중앙정렬
Label Default
레이블 기본
투명
없음
12px, 검정(48,48,49), 중앙정렬
Textbox Default
텍스트박스 기본
흰색
회색 solid 1px, 둥근모서리 2px
12px, 검정, 좌측정렬
Textbox Disabled
텍스트박스 비활성
연회색(230,230,234)
회색 solid 1px, 둥근모서리 2px
12px, 연회색(170,170,172), 좌측정렬
Infomation
정보 표시 영역
흰색
파란색(126,155,246) solid 1px
12px, 회색(115,115,119), 중앙정렬
Header Title Active
헤더 타이틀
밝은 회색(249,249,251)
회색 하단 1px
Bold 14px, 검정, 좌측정렬
Dialog Header
다이얼로그 헤더
어두운 회색(96,96,98)
없음, 상단 둥근모서리 4px
Bold 14px, 흰색, 좌측정렬
주의: 위 목록은 기본 제공되는 BoxStyle이며, Name(키) 값은 서버 환경마다 다를 수 있습니다. 사용자가 추가한 커스텀 BoxStyle도 있을 수 있으므로, 반드시 get_boxstyle_list로 조회한 Name을 사용하세요.
BoxStyle 적용 예시:
"Style":{"Type":1,"BoxStyle":"BTN_DEFAULT"}
새 BoxStyle 생성 (save_boxstyle):
기존 BoxStyle에 원하는 스타일이 없으면 save_boxstyle로 새로 만들 수 있습니다. 단일 객체 또는 배열로 여러 개를 한 번에 저장할 수 있습니다. Name은 StyleName 기반의 식별자(영문, 숫자, _ 조합)로 지정합니다.
기존 BoxStyle을 수정하려면 get_boxstyle_list로 조회한 Name을 그대로 사용하여 save_boxstyle을 호출하면 됩니다.
사용 시점 판단:
기본 컨트롤 스타일(버튼, 탭, 텍스트박스 등) → Type=1 (BoxStyle) 권장 (서버 공통 디자인 일관성)
사용자가 특정 색상을 직접 지정 → Type=2 (Custom) 사용
여러 보고서에서 재사용할 커스텀 스타일 → save_boxstyle로 새 BoxStyle 생성 후 Type=1 적용
9. 주의사항
신규 문서는 build_mtsd 우선: 신규 MTSD를 처음부터 만들 때는 build_mtsd(MtsdBuilder 스크립트)를 1순위로 사용합니다. ID 자동 생성, Group/InGroup 자동 처리, 스키마 자동 준수 등의 이점이 있습니다.
ID/Name 규칙: Id는 {타입접두사} + 32자리 UUID HEX. Name은 {타입약어}_{용도} 형식의 의미 있는 이름 (예: LBL_TTL, BTN_SEARCH, GRD_MAIN). build_mtsd 사용 시 ID는 자동 생성됩니다.
Group 내 Element: build_mtsd 사용 시 GroupBuilder가 InGroup/ChildElements 자동 처리. 개별 MCP 도구 사용 시에는 수동으로 Group의 ChildElements[]에 넣고, 자식 Element에 "InGroup": "그룹ID" 설정.
DataGrid.DataSource: DataSource의 Id 값이 아닌 Name 값을 사용
MCP 검증 + 자동 보정 필수: MTSD 파일을 생성 또는 수정할 때마다fix_mtsd → validate_part(또는 validate_mtsd) 순서로 실행합니다.
속성 타입 확인: 속성 타입이 불확실할 때는 get_schema_info로 정확한 타입을 확인한 후 값을 설정합니다.
WriteDate/EditDate 패턴: YYYY-MM-DD HH:MM:SS 형식이어야 하며, 빈 문자열은 허용되지 않음. build_mtsd는 자동으로 현재 시간을 설정합니다.
Style.Type 필수 확인: Background/Border/Font 색상을 변경할 때 반드시 Style.Type을 2(Custom)으로 설정 (섹션 8 참조). build_mtsd에서 bg, border, font, color 옵션 사용 시 자동으로 Type=2 설정됩니다.
우측 버튼 다중 배치 시 Margin 누적 필수: 여러 버튼을 Right+HoldSize로 우측에 배치할 때, 각 버튼의 Margin Right 값을 이전 버튼들의 Width+간격 합으로 누적 계산해야 합니다. 누적하지 않으면 버튼이 같은 위치에 겹칩니다 (섹션 4.5 참조).
WorkFlow 모듈 설정 시 모듈 조회 필수: build_mtsd로 WorkFlow를 포함하는 보고서를 생성할 때, 모듈 노드의 moduleCode는 서버에 등록된 실제 코드여야 합니다. get_module_list로 모듈을 검색하고, get_module_params로 파라미터 구조를 확인한 후 설정하세요. WorkFlow 상세는 /iaud-processbot-guide 스킬을 참조합니다.
