# 파일 ✨/mnt/d/D/_NR_/__AIWK_COMM_St/aiwk/AIWK_COMMON/win/ai_read.md
# AIWK_COMMON/win - 창관리 엔진 기준
# 버전: v075-stage2.2-win-engine-plan-start

## 역할
이 폴더는 AIWK의 공통 창관리 엔진이다. 특정 도메인 자동화 기능을 직접 담는 곳이 아니라, 모든 도메인/모듈/팔레트 기능이 공통으로 사용할 창 생성·표시·드래그·리사이즈·접기·메뉴·상태 저장 기반을 제공한다.

## 현재 내장 파일
```text
aiwk_win.js
aiwk_win_class.js
aiwk_win_drag.js
aiwk_win_menu.js
aiwk_win_render.js
aiwk_win_resize.js
```

## 기준
1. 새 창 엔진을 중복 생성하지 않는다.
2. 기존 `aiwk_win*.js`를 기준으로 확장한다.
3. template는 창 안에 무엇을 얼마나 넣을지 결정한다.
4. skin은 색상과 시각 느낌만 결정한다.
5. module은 실제 자동화 기능을 담당한다.
6. clientId는 모든 창/아이콘에서 우선 표시한다.
7. 버튼, 제목, badge, 메뉴 텍스트는 가능한 한 드래그 선택 가능해야 한다.
8. 큰 패널보다 항상 보이는 작은 아이콘/미니창을 먼저 안정화한다.

## template 후보
```text
template.icon    아이콘 1개
template.mini    clientId/WSS/BUS/NR/R/T 표시
template.panel   버튼/입력/상태/로그 포함
template.chat    채팅 UI
template.log     로그 UI
template.toolbar 도구 호출 메뉴
```

## skin 후보
```text
skin.dark
skin.white
skin.purple
```

## v075 작업 기준
v075에서는 이 폴더의 기존 엔진을 확인하고 문서화한다. 실제 대형 구조 변경은 하지 않는다. 다음 단계에서 floating icon과 mini status window를 이 win 엔진에 연결한다.

---

## v076 차트 template/skin 검증 기준
차트 기능은 새 창관리 엔진을 만들지 않고 기존 `AIWK_COMMON/win` 창 엔진 위에서 module만 추가해 검증한다.

```text
창 = win 엔진
기능 = chart.demo module
개발 화면 = chart-dev-win
운영 화면 = chart-viewer-win
색상 = skin
설정 = localStorage chart_demo_config_v076 JSON
```

이 검증이 성공하면 이후 SNS 인젝션, 크롤링, 자동 실행도 동일하게 창별 module JS를 할당하고 template로 개발용/운영용/자동실행용을 나눈다.


## v080-stage2.7-menu-skin-harmony

- 창 헤더의 `☰`는 공통 창 메뉴 버튼이다.
- 헤더 오른쪽에 흩어져 있던 디자인/JS/TEST/접기/닫기 빠른 버튼은 중복 UI로 보며 표시하지 않는다.
- 운영용/편집용/개발용 모드 전환은 `☰ > 모드` 메뉴에서 처리한다.
- 메뉴 패널은 창보다 위에 보여야 하므로 z-index는 `2147483647` 기준으로 고정한다.
- 기능을 만들면 해당 공통 모듈 폴더의 `ai_read.md`에 목적, 로딩 순서, 버튼, 권한, 다음 작업을 기록한다.
- `home.yjm.kr/aiwk/chart/?dev=1&token=...` 진입은 개발용 테스트 진입점이다. token은 localStorage에 저장하고, 다른 크롬 프로필에서는 token 없이 운영용 화면을 확인한다.
- URL token은 브라우저 히스토리/로그에 남을 수 있으므로 운영 배포에서는 단기 token 또는 별도 로그인 경로로 바꾸는 것이 안전하다.

## v081-stage2.8-menu-system-global-skin

### ☰ 공통 메뉴 확장 규칙
공통 창 메뉴는 다음 구조를 기본으로 한다.

```text
공통 메뉴
+ 창별 메뉴(cfg.menuRows 또는 cfg.menu)
+ 모듈별 메뉴(module.menuRows)
```

구분선은 다음 둘 다 허용한다.

```js
"--"
{ sep: 1 }
```

메뉴 row 기본 형식:

```js
{ label:"실행", kind:"action", value:"run", role:"guest", title:"설명" }
{ label:"2단 노드", kind:"fold", value:"2", role:"guest" }
{ label:"기능", kind:"label" }
```

공통 메뉴는 표시 체계만 먼저 고정하고, 실제 세부 기능은 각 창/모듈 JS에서 점진적으로 연결한다.

### 스킨 상속
창 단독 스킨이 아니라 전체 page/window/menu/chart가 같은 색상 변수를 공유해야 한다.
WEB `home.yjm.kr/aiwk/chart/`에서는 `nssb-dark`, `nssb-light`를 기준으로 기존 농가 관제 화면 분위기를 맞춘다.

## v082: export/import와 투명도
공통 창 메뉴는 모든 창에 내보내기/불러오기 기능을 제공한다.
- 창 내보내기: 현재 창의 id/title/module/rect/template/skin/alpha/collapse/route를 JSON으로 복사한다.
- 창 불러오기: JSON을 현재 창에 적용한다.
- 전체 내보내기: 현재 페이지의 모든 AIWK 창을 layout JSON으로 복사한다.
- 전체 불러오기: windows 배열을 읽어 창들을 생성 또는 갱신한다.

투명도는 1~5단계로 공통 제공한다. 차트창을 겹쳐 농가별 변화를 비교하거나 보조 관제창을 반투명하게 올릴 수 있게 하기 위한 기능이다.
메뉴가 길어지는 문제를 줄이기 위해 접기와 투명도는 inline 가로 버튼 묶음으로 표시한다.


## v102-stage4.9-ext4-store-resize-noise-fix
- 목적: 오류 발생 시 원인 후보와 해결 안내를 화면에 표시한다.
- AIWK.error.report() 공통 오류 패널을 추가했다.
- window error / unhandledrejection을 잡아 우측 하단 AIWK 오류 패널에 표시한다.
- AIWK.win.create()는 창 생성 중 오류를 잡아 win_id/module/context와 함께 보고한다.
- AIWK.store가 없을 때 `Cannot read properties of undefined (reading get)`처럼 모호하게 죽지 않고, `aiwk_store.js 로드/순서/캐시 문제`로 안내한다.
- chart/index.php의 로컬 JS/CSS에는 버전 query를 붙여 캐시로 구버전과 신버전이 섞이는 문제를 줄인다.

## v102-stage4.9-ext4-store-resize-noise-fix
접힘 상태에서도 `☰` 메뉴는 반드시 열려야 한다.

규칙:
- 1단/2단/3단 접힘 상태에서도 `.aiwk-win-menu-wrap`은 숨기지 않는다.
- 3단 아이콘 상태에서는 `☰`를 우측 상단 작은 원형 오버레이로 표시한다.
- 메뉴가 열린 창은 `.aiwk-menu-open` 클래스를 갖고 가장 높은 z-index로 올라간다.
- 접기 단계와 투명도 단계는 메뉴 세로 길이를 줄이기 위해 inline 가로 버튼으로 둔다.
- 메뉴가 길어지는 경우 전체 메뉴를 아코디언으로 바꾸기 전에, 우선 inline/scroll 조합으로 처리한다.

## v085: 메뉴 스킨 버튼과 없는 모듈 안전 처리
- ☰ 공통 메뉴의 짧은 선택 항목은 가로 버튼으로 배치한다.
- 스킨 버튼은 D/W/C/P 약자를 사용한다: D=nssb-dark, W=nssb-light, C=cyan, P=purple.
- 메뉴 row에 `requiredModule`이 있으면 해당 모듈이 등록된 경우에만 표시한다.
- WEB chart 검증센터처럼 EXT 전용 dev 모듈이 없는 환경에서는 TEST 메뉴가 자동으로 숨겨져야 한다.