@flextudio/scenario 0.1.0

package/contract-data/runtime/v1/collection/category.md

@@ -0,0 +1,165 @@
+# Category (카테고리)
+
+> "하나의 시나리오에는 하나의 컬렉션만 존재한다. 컬렉션 안의 섹터들을 분리하고 화면에 별도로 연결하기 위해 카테고리를 사용한다." — 공식 가이드
+
+## 1. 정의
+
+- 코드: `class Category extends Array` (`collection.js:1121`)
+- **컬렉션 안에 이미 존재하는 Sector 의 부분집합 인덱스**. Category 자체는 데이터를 소유하지 않으며, `Sector` 인스턴스를 push 해 두지만 그 Sector 의 본체는 Collection 에 있다.
+- 카테고리는 자체 `_active` 를 가진다 (컬렉션의 active 와 별개). 카테고리 단위로 "지금 활성 섹터는 누구냐" 를 추적할 수 있다.
+
+```
+Collection ─────── _category ───────┐
+   ├─ Sector A                       ├─ "CtgItemList"  → [ A, B, C ]      _active = "B"
+   ├─ Sector B                       ├─ "CtgFilter"    → [ F ]
+   ├─ Sector C                       └─ "CtgApprView"  → [ V ]
+   ├─ Sector F (필터)
+   └─ Sector V (결재 임시)
+```
+
+## 2. 메타 정의 ↔ 런타임
+
+| 메타 | 런타임 |
+|---|---|
+| `Panel.Category.CtgItemList = { Ckeys: [...], ... }` | `Collection._category["CtgItemList"]` 인스턴스 생성 |
+| `Panel.CategoryOrder = ["CtgItemList", "CtgFilter"]` | 카테고리 순서 — 디버거 표시·캡쳐 시 기준 |
+| `DataConnection.CategoryName = "CtgItemList"` | 그룹이 어떤 카테고리에 바인딩될지 지정 |
+
+> Validator 강제: `Panel.CategoryOrder` 는 `Panel.Category` 의 키 집합과 정확히 일치해야 한다 (`validator.ts:626`).
+> Category 의 `Ckeys` 는 모두 `Panel.Collection.Ckeys` 의 부분집합이어야 한다 (`validator.ts:645`).
+
+## 3. 구조
+
+| 속성/메서드 | 설명 |
+|---|---|
+| `name` | 카테고리 이름 (불변, `Object.defineProperty`) |
+| `_active` | 카테고리 자체의 active SUID. writable |
+| `_collections` | 소속 컬렉션 (서브시나리오 컬렉션 분리를 위해 보관) |
+| `active` (getter) | `_active` 가 있으면 반환, 없고 길이가 1이면 `[0]._SUID` 자동 반환 |
+| `activeSector` | `this._collections.mapper[this.active]` |
+| `suids`, `sectors` (=this) | SUID 배열 / 섹터 배열 |
+| `status` | 컬렉션의 status 를 그대로 위임 |
+
+## 4. 메서드
+
+### 4-1. 활성 섹터
+
+```js
+category.setActive(suid)     // _active 변경 (mapper 검증 포함)
+category.activate(suid)      // setActive 별칭
+category.unActivate()        // setActive(undefined)
+category.removeActive(suid)  // 해당 suid 가 active 였으면 해제
+category.isActive(suid)      // boolean
+```
+
+### 4-2. 섹터 추가/제거
+
+```js
+category.addSector(obj, isForced=true)
+  → this._collections.addSector(obj, undefined, isForced)        // 컬렉션에 추가
+  → this.add(sector._SUID)                                        // 자기 자신에도 SUID 등록
+
+category.removeSector(...suids)
+  → 카테고리에 존재하는 SUID 만 추려서 컬렉션에서 remove (즉, **컬렉션에서도 함께 사라진다**)
+
+category.add(...suids)             // 이미 컬렉션에 있는 섹터들을 카테고리에 등록
+category.addAtIndex(idx, ...suids) // 특정 인덱스에 삽입
+category.remove(...suids)          // 카테고리에서만 제거 (컬렉션은 유지)
+```
+
+> `addSector` 와 `add` 의 구분이 중요하다.
+> - `addSector(obj)` — **새 데이터** 를 컬렉션과 카테고리에 동시 등록.
+> - `add(suid)` — 이미 컬렉션에 있는 섹터를 카테고리 인덱스에 등록만 (다중 카테고리 가능).
+> - `removeSector(...suids)` — **컬렉션 전체에서 삭제**. 다른 카테고리에서도 사라진다.
+> - `remove(...suids)` — 이 카테고리 인덱스에서만 제거. (`collection.js:1236`)
+
+### 4-3. 상태 기반 조회
+
+```js
+category.getSUIDsOfStatus('active'|'added'|'updated'|'deleted'|'selected'|'all')
+category.getSectorsOfStatus(status)
+category.getSUIDsOfTarget(targetMeta)   // DataConnection.TargetSector.Filters 평가
+```
+
+`getSUIDsOfStatus` 는 컬렉션 단위 상태값과 카테고리 멤버십을 교집합 한다.
+
+```js
+// collection.js:1252
+if (status == 'active') return [this.active];
+return this._collections[status].filter(suid => this.isExist(suid));
+```
+
+→ 카테고리에 속한 섹터만, 그 카테고리에서의 active(`_active`) 또는 컬렉션 단위의 added/updated/deleted/selected 와 교차.
+
+### 4-4. 캡쳐 / 복원
+
+```js
+_collections.captureCategory(deep=true)    // { name: { suids:[...], active } } 형태로 직렬화
+_collections.restoreCategory(json)         // 카테고리 사전 재구성
+```
+
+`captureCollection` 의 `category` 필드로 함께 저장되어 뒤로가기 / 서브시나리오 진입 시 복원된다 (`collection.js:1408`).
+
+## 5. 자주 쓰는 패턴
+
+### 5-1. 검색 결과 필터링 (마스터 카테고리 패턴)
+
+```js
+// CtgDataListAll = 원본 (서버에서 받아온 전체)
+// CtgDataList    = 화면에 보여줄 필터 결과
+f.Collection.removeCategory('CtgDataList');
+f.Collection.createCategory('CtgDataList');
+const all = _c.CtgDataListAll.sectors;
+const filtered = all.filter(s => s.fName.includes(keyword));
+filtered.forEach(s => _c.CtgDataList.add(s._SUID));    // 본체는 유지, 인덱스만 새로
+group.reload();
+```
+
+### 5-2. 결재 ViewMode (활성 섹터 임시 카테고리)
+
+```js
+// activeSector 만 표시하는 임시 카테고리
+f.Collection.removeCategory('CtgApprView');
+f.Collection.createCategory('CtgApprView');
+const cur = _c.CtgList.activeSector;                   // 현재 보고 있는 섹터
+_c.CtgApprView.add(cur._SUID);
+_c.CtgApprView.activate(cur._SUID);
+```
+
+### 5-3. Init mock 데이터 패턴 (AI 생성)
+
+AI 생성에서 Init 핸들러는 **`f.Collection.addSector` 만** 출력한다. `addSector` 는 카테고리가 없으면 자동 생성하므로 `removeCategory + createCategory + [0].set()` 3-step 패턴이 불필요.
+
+```js
+// ✅ 권장 — Init mock 섹터 (카테고리 자동 생성)
+f.Collection.addSector({ keyword: '', fromDate: f.Date().format('YYYYMMDD') }, 'CtgFilter');
+```
+
+```js
+// ❌ Init 에서 출력 금지
+f.Collection.removeCategory('CtgFilter');   // validator 차단
+f.Collection.createCategory('CtgFilter');   // validator 차단
+_c.CtgFilter[0].set('keyword', '', ...);    // addSector 로 대체
+Current.step.reload();                      // Init 은 재실행되지 않으므로 의미 없음
+```
+
+> `_c.카테고리[n].set()` 자체는 사용자 트리거 이벤트(Click 등)에서는 정상 사용. Init 에서는 mock seed 만 박으면 되므로 `addSector` 로 충분.
+
+## 6. 명명 규칙 (요약)
+
+> 상세는 [naming.md](./naming.md).
+
+- 카테고리명: `Ctg` 접두 + PascalCase. 영문/숫자/`_` 만, 숫자 시작 금지, 한글/특수문자/콜론 금지.
+- 안티패턴: `Ctg(New|Edit|Add|Insert)*` — 별도 카테고리 대신 `DataUsage:"new"`/`"update"` 사용.
+- 카테고리 경로 표기 (`CtgA:CtgB:key`) 금지 — 일부 컨트롤이 인식 못 함.
+- `Panel.CategoryOrder` 의 키 집합은 `Panel.Category` 의 키 집합과 정확히 일치해야 함.
+- 카테고리의 `Ckeys` 는 `Panel.Collection.Ckeys` 의 부분집합.
+
+## 7. 안티패턴
+
+| 안티패턴 | 문제 | 권장 |
+|---|---|---|
+| `removeSector('all')` | 카테고리 전체 섹터를 컬렉션에서까지 날려 mapper 무결성 깨짐 | `removeCategory` + `createCategory` |
+| `CtgNew*` / `CtgEdit*` 별도 카테고리 | 입력 폼마다 새 카테고리 + addSector + Init 복사 + Save 복사 → 사이드이펙트와 가비지 섹터 | 기존 리스트 카테고리 + `DataUsage:"new"` 또는 `"update"` |
+| 카테고리 경로 표기 (`CtgSchedule:CtgSchedule:dayData`) | Scheduler 등 일부 컨트롤은 인식 못 함 | 단일 카테고리명 + InnerBlock Ckey 사용 |
+| 문자열 카테고리명 오타 | 런타임에서 `_c.CtgXxx` 가 `undefined` → 실행 시점 에러 | validator 의 `category_references` 가 사전 검출 |

package/contract-data/runtime/v1/collection/collection.md

@@ -0,0 +1,135 @@
+# Collection (컬렉션)
+
+> "시나리오가 시작해서 종료될 때까지 모든 데이터의 흐름을 관리하는 곳" — flextudio 공식 가이드
+
+## 1. 정의
+
+- **시나리오당 1개**의 컬렉션이 존재한다. 모든 화면(Step), 모든 입력 컨트롤, 모든 서비스 결과가 **하나의 Collection 인스턴스**를 공유한다.
+- 코드 상으로는 `class Collection extends Block extends Array` (`collection.js:1076`). 즉 컬렉션 자체가 **Sector 를 원소로 갖는 배열** 이다.
+- 컬렉션 인스턴스는 `_totalCollection[scenarioId]` 에 보관되며, 현재 실행 중인 시나리오의 컬렉션은 전역 게터 `_collections` (별칭 `_c`) 로 접근한다. `publicscript.js:413` 의 `f.Collection` 은 변형 API 만 노출하는 래퍼.
+
+```js
+// collection.js:1336~
+window._totalCollection            // { [scenarioId]: Collection }
+window._collections  ≡  _totalCollection[_scenarioID]    // 현재 시나리오 컬렉션
+window._c            ≡  _collections                      // 스크립트 단축 별칭
+window._totalStatus[scenarioId]    // CollectionStatus (active/added/updated/... SUID 인덱스)
+window._cStatus      ≡  _totalStatus[_scenarioID]
+```
+
+## 2. 내부 구조
+
+| 멤버 | 타입 | 설명 |
+|---|---|---|
+| `Collection` 자체 | `Array<Sector>` | 시나리오의 모든 (최상위) 섹터 평면 배열 |
+| `mapper` | `{ [suid]: Sector }` | 컬렉션 내부의 **모든 섹터** (InnerBlock 포함) 를 SUID 로 평탄 인덱싱. `Object.defineProperty` 로 비열거형 |
+| `_category` | `{ [name]: Category }` | 카테고리 사전. `Category` 는 SUID 의 부분집합 인덱스 |
+| `status` | `CollectionStatus` (= `_cStatus`) | 5종 상태값(active/added/updated/deleted/selected) 의 SUID 목록과 step 별 binder |
+| `passInit` | `boolean?` | 서브시나리오 클로닝 시 초기화 1회 스킵 플래그 (`collection.js:1369`) |
+
+`Block` 베이스 클래스 (`collection.js:384`) 는 다음을 제공한다.
+- `addSector(obj, categoryName?, isForced=true, targetIndex?)` — 새 Sector 생성 후 `push` + `mapper` 등록 + (옵션) 카테고리 등록
+- `issueSUID(sector, isForced)` — 8자리 영숫자 SUID 발급 (`generateUID`, 충돌 시 자릿수 증가 / 강제생성 시 재발급)
+- 내부 InnerBlock 의 `master SUID + masterKey` 로 `_cStatus.InnerStatus[msuid+mKey]` 에 별도 BlockStatus 보유 (`collection.js:425`)
+
+## 3. 시나리오 라이프사이클과 컬렉션
+
+### 3-1. init (시나리오 시작 시)
+
+```js
+// collection.js:1368
+function initScenarioCollection(sectorsJson) {
+    if (_totalCollection[_scenarioID] && _totalCollection[_scenarioID].passInit) {
+        delete _totalCollection[_scenarioID].passInit;        // 서브시나리오 클론본은 재초기화 스킵
+    } else {
+        _totalCollection[_scenarioID] = new Collection();
+        _totalStatus[_scenarioID]     = new CollectionStatus();
+    }
+    // 알림 Action 으로 진입 시 sectorsJson 으로 초기 섹터 채움 + addStatus(C_ADDED, suid)
+    // 그 외에는 빈 Sector 1개를 자동 추가 + addStatus(C_ADDED) → start step 의 활성 섹터 보장
+}
+```
+
+요점:
+- 신규 진입 시 컬렉션은 **항상 1개 이상의 섹터를 갖는다** (스타트 스텝의 데이터 바인딩 누락 시에도 `_c.activeSector` 가 `undefined` 가 되지 않도록 보장).
+- 알림에서 데이터를 들고 진입한 경우 그 데이터가 `added` 상태로 컬렉션에 박힌다.
+
+### 3-2. step 진입 — bind
+
+`StepBinder` (`status.js:103`) 가 step 별로 생성된다. 각 Layout/Group 은 자신의 `fId` 키로 `LayoutBinder` (= 섹터 SUID 배열) 를 갖는다.
+
+```
+_cStatus._stepBinders[stepId] = StepBinder
+StepBinder.bind = { [fId]: LayoutBinder([suid, suid, ...]) }
+```
+
+Step 이동 시 `beforeReload(step)` → 기존 step 의 binder 를 `bindBeforeReloaded` 로 임시 저장 → 새 step 렌더 → `afterReload()` 에서 정리 (`status.js:54~67`).
+
+### 3-3. capture / restore
+
+뒤로가기, undo 등에서 컬렉션 스냅샷을 만들고 되돌릴 수 있다.
+
+```js
+// collection.js:1405
+captureCollection() = {
+    collection: JSON.stringify(_collections),
+    status:     _cStatus.capture(),                      // JSON.stringify(this)
+    category:   JSON.stringify(_collections.captureCategory(true))
+}
+
+restoreCollection(captured)   // collection.js:1413
+  → new Collection(parsed)
+  → restoreCategory(parsedCategory)
+  → _cStatus.restore(captured.status)
+  → passChangeCollection()      // 디버거 동기화
+```
+
+> 메타의 Step 옵션 `CopyCollection` (= `K_COPYCOLLECTION`) 이 `false` 인 경우, **뒤로가기 시 컬렉션을 복원하지 않는다**. 상세/조회 화면에서 PopUp/SlideUp 로 변경한 결과를 메인으로 가져갈 때 사용. (system-prompt-v2.md:288)
+
+### 3-4. 서브시나리오 클로닝
+
+```js
+// collection.js:1421
+cloneCurrentCollectionTo(scenarioId, status)
+```
+
+`status` 인자에 따라 일부 또는 전체 섹터를 새 시나리오 컬렉션에 복사. 지원 모드: `C_ALL | C_ACTIVE | C_SELECTED | C_LAST | C_ADDED | C_UPDATED | C_DELETED`.
+
+복사된 컬렉션은 `passInit = true` 가 박혀, 서브시나리오 진입 시 `initScenarioCollection` 의 재초기화를 1회 건너뛴다.
+
+## 4. Collection 클래스 메서드
+
+| 메서드 | 설명 |
+|---|---|
+| `activate(suid)` | 기존 active 해제 후 해당 섹터 활성화. `Sector.activate()` 위임 |
+| `unActivate()` | `_cStatus[C_ACTIVE]` 와 `InnerStatus[*][C_ACTIVE]` 모두 비움 |
+| `select(suid)` / `unSelect(suid)` | 다중 선택 set/unset |
+| `addSector(obj, categoryName?, isForced?, targetIndex?)` | 상속받은 Block 메서드. 카테고리 동시 등록 가능 |
+| `removeCategory(name)` | 카테고리 인스턴스를 통째로 비움 (섹터는 컬렉션에 잔류) |
+| `getSUIDsOfStatus(status)` / `getSectorsOfStatus(status)` | 'active' / 'added' / 'updated' / 'deleted' / 'selected' / 'all' 로 SUID·섹터 조회 |
+| `captureCategory(deep)` / `restoreCategory(json)` | 카테고리 ↔ JSON 직렬화 |
+| `validateMapper(suids)` | mapper 에 실재하는 suid 만 통과시키는 가드 |
+
+## 5. 게터 — `active` / `last` / `displayed`
+
+```js
+// Block (collection.js:559)
+get active() {
+    if (this.status[C_ACTIVE] && this.mapper[this.status[C_ACTIVE]])
+        return this.status[C_ACTIVE];
+    let firstSUID = this.displayed[0];     // 화면 바인딩된 첫 섹터로 fallback
+    if (firstSUID && this.mapper[firstSUID]) return firstSUID;
+    if (this[0]) return this[0][C_SUID];   // 그래도 없으면 배열 첫 섹터
+    return undefined;
+}
+get activeSector() { return this.mapper[this.active]; }
+get last()        { return this.getSUIDsOf(..._cStatus.lastReflected) }   // 직전 reload 에 반영된 섹터들
+```
+
+요점: `_c.activeSector` 는 **명시적으로 active 가 없어도** "지금 화면에 보이는 첫 섹터" 또는 "컬렉션의 첫 섹터" 를 fallback 으로 반환한다. 따라서 `_c.activeSector` 는 거의 항상 truthy.
+
+## 6. 디버거 동기화 (`passChangeCollection`)
+
+`Sector.set` / `addSector` / `remove` / `activate` / `select` 등 모든 변형 연산은 마지막에 `passChangeCollection(suid?, changedKeys?)` 를 호출하여 디버거 패널의 Collection/Category 탭에 즉시 반영한다 (`collection.js:1511`).
+
+스튜디오 디버거의 **상태값 필터(Status of)** (`flextudio-guide.md:508`) 는 이 데이터를 그대로 사용하여 added/updated/deleted/selected 만 골라 보여준다.

package/contract-data/runtime/v1/collection/lifecycle.md

@@ -0,0 +1,140 @@
+# Collection · Lifecycle
+
+시나리오 시작에서 종료까지 컬렉션이 거치는 전 과정. 메타·런타임·디버거 3자가 어떻게 상호작용하는지 정리.
+
+## 1. 전체 흐름
+
+```
+┌────────────┐   1. initScenarioCollection
+│ 시나리오    │ ─────────────────→ new Collection() / new CollectionStatus()
+│  Start     │                       + 빈 섹터 1개 (added) — 또는 알림 sectorsJson
+└──────┬─────┘
+       │
+       ▼
+┌────────────┐   2. Step 진입 — bindLayout(jsonMeta, outerSector)
+│ Step N     │ ─────────────────→ StepBinder.bind[fId] = LayoutBinder([suids])
+│ render     │                    DataConnection 평가 → 섹터 매칭 → 컨트롤 채움
+└──────┬─────┘
+       │
+       │ 사용자 입력 / 이벤트
+       ▼
+┌────────────┐   3. mutation
+│ 변형 호출  │  sector.set / addSector / removeSector / activate / select / delete
+│            │  → status 변경 + reload + passChangeCollection
+└──────┬─────┘
+       │
+       │ 다음 Step or 뒤로가기
+       ▼
+┌────────────┐   4-A. 일반 이동 — captureCollection? 또는 그냥 진행
+│ Step 이동  │   4-B. 뒤로가기 — restoreCollection (CopyCollection != false)
+│            │   4-C. 서브시나리오 — cloneCurrentCollectionTo(subId, status)
+└──────┬─────┘
+       │
+       ▼
+┌────────────┐   5. 시나리오 종료 / 다른 시나리오 진입
+│ End        │ ─────────────────→ _totalCollection / _totalStatus 의 해당 시나리오 키 정리
+└────────────┘
+```
+
+## 2. 단계별 상세
+
+### 2-1. 초기화 — `initScenarioCollection(sectorsJson?)`
+
+- `_totalCollection[scenarioID]` 가 비어있거나 `passInit !== true` 인 경우 새 인스턴스 생성.
+- 알림(`f.Notification`) 으로 데이터 동반 진입 시:
+  - `sectorsJson` 이 배열 → 각 항목을 `addSector` 후 `addStatus(C_ADDED)`
+  - 객체 1개 → 동일 처리 + `activate()`
+- 일반 진입 시:
+  - 컬렉션이 빈 상태면 빈 섹터 1개를 추가 + `addStatus(C_ADDED)` — start step 의 `_c.activeSector` 가 항상 truthy 가 되게 보장.
+
+### 2-2. 메타 정의의 카테고리 인스턴스화
+
+`Panel.Category` 의 키별로 Category 가 사전 생성되는 시점은 메타 로드 직후의 컬렉션 정의 평가에서 이뤄진다 (`CollectionStatus.define` 게터로 `K_COLLECTIONS` 메타 조회 — `status.js:68`). 이후 모든 `_c.CtgXxx` 접근은 이 인스턴스를 사용한다.
+
+### 2-3. Step 렌더 — bindLayout
+
+```js
+// status.js:108
+StepBinder.bindLayout(jsonMeta, outerSector)
+  → fId = jsonMeta[K_FID]
+  → this.bind[fId] = new LayoutBinder(jsonMeta, outerSector)
+  → return _collections.allSectorsOf(...this.bind[fId])
+```
+
+`LayoutBinder` 는 그룹의 DataConnection 을 평가하여 어떤 SUID 가 화면에 드러날지를 배열로 가진다.
+
+#### DataUsage → LayoutBinder 가 갖는 SUID 묶음
+
+| DataUsage | 진입 시 자동 동작 | LayoutBinder 가 보유하는 SUID 묶음 |
+|---|---|---|
+| `default` | 카테고리에 섹터 0개면 빈 섹터 1개 자동 생성. 1개 이상 있으면 기존 사용 | 카테고리의 첫 섹터 1개 (단일 폼) |
+| `new` | **항상 빈 섹터 1개 새로 생성** + `added` 자동 부여 | 새 섹터 1개 — 입력값이 자동으로 이 섹터에 저장 |
+| `update` | 카테고리의 `activeSector` 만 바인딩 (읽기+쓰기) — 입력 시 active 섹터가 곧장 갱신 | activeSector 1개 |
+| `detail` | 카테고리의 `activeSector` 만 바인딩 (읽기 전용) | activeSector 1개 |
+| `query` | 카테고리 섹터 수만큼 그룹 자체가 복제 (DOM 단위) | 카테고리 전체 (또는 `TargetSector.Filters` 가 통과시킨 부분집합) |
+
+> 메타 표면 카탈로그 (DataConnection 객체 키 enum, FilterType 4종, conditionOperators 10종 등) 는 본 문서에서 다루지 않는다 — [../../../schema/v1/data-objects.md](../../../schema/v1/data-objects.md) 가 SSOT.
+
+#### Init mock 데이터 패턴 — `addSector` 만 사용
+
+AI 시나리오 생성에서 Init 핸들러는 **`f.Collection.addSector(obj, '카테고리')` 호출만** 출력한다. `addSector` 는 카테고리가 없으면 자동 생성하므로 `removeCategory` / `createCategory` 선행 불필요. `_c.카테고리[0].set(...)` 도 `addSector` 로 대체 (인자 obj 에 초기값 포함).
+
+```js
+// ✅ 권장 — Init 에서 mock 섹터 1건 박기
+f.Collection.addSector({ StatusFilter: '', StatusFilterName: '전체' }, 'CtgStatusFilter');
+
+// ❌ 출력 금지 — removeCategory/createCategory 는 validator 가 차단,
+//    _c[0].set 도 addSector 로 대체 가능하므로 mock 생성 시 사용하지 않음.
+//    Current.step.reload / f.Content().reload 도 Init 에서는 의미 없음 (재실행 안 됨).
+```
+
+`DataUsage:"new"` 와 Init `addSector` 를 함께 쓰면 가비지 섹터 발생 — 한쪽만 사용.
+
+### 2-4. 변형 — set / add / remove
+
+- 모든 변형은 마지막에 `passChangeCollection(suid?, changedKeys?)` 호출 → 디버거 패널 실시간 반영.
+- `set` 은 자동 reload, `setValue` 는 reload 생략 (배치 변경 시 사용).
+- InnerBlock 안의 섹터를 `set` 하면 마스터 섹터의 reload 도 함께 트리거.
+
+### 2-5. Step 전환 시 상태 처리
+
+```
+beforeReload(stepID)
+  → _stepBinders[stepID].bind 가 있으면 bindBeforeReloaded 로 임시 저장
+  → removeStepBinder(stepID)            // step 이 다시 진입할 때 새 binder 로 시작
+
+afterReload()
+  → bindBeforeReloaded 삭제
+```
+
+이 사이에 화면을 그리는 동안에는 이전 binder 정보를 참고하여 **포커스/스크롤/active 상태를 유지** 한다.
+
+### 2-6. 캡쳐 / 복원
+
+| 시점 | 동작 |
+|---|---|
+| Step 이동 (`CopyCollection: true` 또는 미지정) | 현재 컬렉션 + status + category 를 captureCollection 로 스냅샷 → 스택 push |
+| 뒤로가기 | 스택 pop → restoreCollection — Collection / status / category 모두 새 인스턴스로 복원 |
+| `CopyCollection: false` Step | 스냅샷 미저장 → 뒤로가기 후에도 PopUp/SlideUp 에서 변경한 데이터가 유지 |
+| 서브시나리오 | `cloneCurrentCollectionTo(subId, status)` — `C_ALL/C_ACTIVE/C_SELECTED/C_LAST/C_ADDED/C_UPDATED/C_DELETED` 부분 복사. 새 컬렉션은 `passInit=true` 로 마킹되어 진입 시 재초기화 1회 스킵 |
+
+### 2-7. 정리
+
+- 시나리오를 떠날 때 `_totalCollection` / `_totalStatus` 의 해당 키는 그대로 유지될 수 있다 (서브 → 메인 복귀 시 메인 컬렉션이 살아있어야 하기 때문). 메모리 정리는 외부에서 별도로 관리.
+
+## 3. 메타 옵션이 라이프사이클에 미치는 영향
+
+| 메타 키 | 영향 |
+|---|---|
+| `Step.CopyCollection` | `false` 면 step 이동 시 capture 생략 → 뒤로가기 시 변경 내역 유지 |
+| `DataConnection.DataUsage` | 진입 시점에 어떤 자동 동작(빈 섹터 생성 / activeSector 바인딩 / 카테고리 반복 렌더) 을 트리거할지 결정 |
+| `DataConnection.UseNewSector` | `default`/`new` 에서 빈 섹터 자동 생성 여부 |
+| `DataConnection.OnlyIfNoSector` | `default` 에서 이미 섹터가 있으면 생성 스킵 — Init `set()` 패턴의 안전 가드 |
+| `DataConnection.UseTargetSector` + `TargetSector.Filters` | 어떤 상태/조건의 섹터만 그룹에 바인딩할지 결정 |
+| `Group.UseEmptyView` | `query` 그룹에서 매칭 섹터 0건일 때 빈 뷰 표시 |
+
+## 4. 디버그 모드와의 관계
+
+- `_mode == "debug"` 일 때 setter 들이 에러 출력 (`fDebug.error(R_MESSAGE.COLLECTION_ESCAPE)`) — 잘못된 직접 대입 방지.
+- 디버거 우측 하단 탭 (`localStorage.K_DEBUG.ACTIVE_RIGHTBTM_TAB`) 이 Category 탭일 때만 `passChangeCollection` 이 `captureCategory()` 까지 동행 — 성능 절약.
+- 디버거의 "Status of" 필터는 `fDebug.collectionStatus` 를 통해 `getSectorsOfStatus` 로 직접 조회.

package/contract-data/runtime/v1/collection/naming.md

@@ -0,0 +1,174 @@
+# 카테고리 / 컬렉션키 — 명명 규칙과 예약어
+
+`Panel.Category` 의 카테고리명과 `Panel.Collection.Ckeys` (= Sector 의 일반 속성 = "컬렉션키") 작성 규칙. 잘못된 이름은 런타임 에러·디버거 경고·바인딩 실패로 직결되므로 본 문서의 규칙을 시나리오 생성과 사용자 스크립트 양쪽에서 모두 적용한다.
+
+> **schema 강제 (생성 시 차단)**: 본 문서의 §3-2 시스템 게터 + §3-5 JS 예약어/빌트인 충돌은 `meta-contract/schema/v1/naming-objects.schema.json` (`ckey` / `ckeyWithSuid` / `categoryName`) 으로 schema 레벨에서 차단된다. 적용 위치: 컨트롤 `Ckeys` (controlBase / calendarControl / comboListControl / searchListControl / calendar-navigator / tab), `Panel.Collection.Ckeys`, `Panel.Category` 키, `Panel.CategoryOrder`, `DataConnection.CategoryName`, `TargetSector.CategoryName`, `DataSource.CategoryName`, `paramBlock.CategoryName` (빈 문자열 예외), `resultBlock.CategoryName`, `resultBlock.PKeys`, `sectorFilter.Condition.ConditionKey`, `sectorFilter.Parent.DCParentKey`/`DCChildKey`. AI 생성 / `flex-scenario validate` 가 이 단계에서 거부.
+
+## 1. 공통 — JS 식별자 규칙
+
+`_c.카테고리.컬렉션키` 형태로 점 표기법 접근하므로 카테고리명·컬렉션키 모두 **JS 식별자 규칙**을 따라야 한다.
+
+| 규칙 | 카테고리명 | 컬렉션키 |
+|---|---|---|
+| 영문/숫자/언더스코어(`_`) 만 사용 | ✅ | ✅ |
+| 숫자로 시작 금지 | ✅ ([rules.md:271](../../../spec/rules.md) 명시) | ✅ |
+| 숫자**만**으로 구성 금지 | ✅ ([rules.md:271](../../../spec/rules.md)) | ✅ (사실상 식별자 자체가 안 됨) |
+| 공백·하이픈(`-`)·콜론(`:`)·점(`.`) 등 특수문자 금지 | ✅ | ✅ |
+| 한글/이모지 금지 (코드 식별자로 사용 불가) | ✅ | ✅ |
+| JS 예약어 (`for`, `class`, `if`, `delete`, `new` 등) 금지 | ✅ | ✅ |
+
+> 카테고리명에 콜론(`:`)을 넣은 "카테고리 경로 표기" (`CtgSchedule:CtgSchedule:dayData` 같은 형태) 는 일부 컨트롤(Scheduler 등) 이 인식하지 못한다. 항상 **단일 토큰** 카테고리명 + InnerBlock 키로 표현.
+
+## 2. 카테고리명 (CategoryName)
+
+### 2-1. 컨벤션 — `Ctg` 접두 + PascalCase
+
+```
+✅  CtgItemList,  CtgFilter,  CtgApprView,  CtgUserList,  CtgDataListAll
+❌  itemList     (Ctg 누락)
+❌  CtgItem-List (하이픈)
+❌  Ctg item     (공백)
+❌  CtG_Item     (혼합 케이스)
+```
+
+> 시스템 프롬프트 ([system-prompt-v2.md:3546](../../../flextudio-ai-studio/system-prompt-v2.md)) — "`Ctg` prefix + descriptive PascalCase name."
+
+### 2-2. 안티패턴 (validator 경고)
+
+다음 prefix 카테고리는 **별도 카테고리를 만드는 안티패턴**으로 검출된다 ([validator.ts:1069](../../../flextudio-ai-studio/lib/validator.ts) — `/^Ctg(New|Edit|Add|Insert)/i`):
+
+| 안티 prefix | 본래 의도 | 권장 대체 |
+|---|---|---|
+| `CtgNew*` | 신규 등록 폼용 별도 카테고리 | 메인 리스트 카테고리 + `DataUsage:"new"` |
+| `CtgEdit*` | 수정 폼용 별도 카테고리 + Init/Save 복사 | 메인 리스트 카테고리 + `DataUsage:"update"` |
+| `CtgAdd*` | 〃 | `DataUsage:"new"` |
+| `CtgInsert*` | 〃 | `DataUsage:"new"` |
+
+> 정당화되는 유일한 케이스: **저장 전 별도 체크로직(복잡한 비즈니스 검증)이나 데이터 변환(포맷 변경, 계산 필드 생성 등)이 필요한 경우** 만 별도 카테고리(`DataUsage:"default"`) 패턴 허용.
+
+### 2-3. 정합성 강제 (validator)
+
+| 검사 | 위치 | 내용 |
+|---|---|---|
+| `category_references` | [validator.ts:587](../../../flextudio-ai-studio/lib/validator.ts) | `DataConnection.CategoryName` / 서비스의 `CategoryName` / `SetCategory` 등 모든 참조가 `Panel.Category` 에 정의되어 있어야 함 |
+| `category_order` | [validator.ts:621](../../../flextudio-ai-studio/lib/validator.ts) | `Panel.CategoryOrder` 의 키 집합과 `Panel.Category` 의 키 집합이 정확히 일치 |
+| `ckeys_consistency` | [validator.ts:645](../../../flextudio-ai-studio/lib/validator.ts) | 각 카테고리의 `Ckeys` 가 `Panel.Collection.Ckeys` 의 부분집합 |
+
+### 2-4. 길이/대소문자
+
+- 길이 제한은 명시 없음 — 그러나 **PascalCase 단어 4개 이내** 권장 (`CtgUserMessageList` 정도까지). 이상이면 의미가 흐려진다.
+- 대소문자 구분됨 (`CtgItem` ≠ `Ctgitem`).
+
+## 3. 컬렉션키 (Ckey, Sector 의 속성명)
+
+### 3-1. 컨벤션 — `f` 접두 + camelCase
+
+```
+✅  fName,  fAge,  fStatus,  fApprovedDate,  fBaseUserNo
+❌  Name        (접두 f 누락 — 충돌 가능성, 시스템 키와 구별 어려움)
+❌  fname       (소문자만)
+❌  fOrgName, fEmail, fBaseUserNo  ← 이건 시스템 표준 키 (의미 보존, 임의 변경 금지)
+```
+
+> 컨벤션은 강제는 아니지만, `f` prefix 가 누락되면 시스템 게터/예약어와 충돌할 위험이 커진다. 신규 키는 `f` 로 시작하는 것을 권장.
+
+### 3-2. 시스템 예약 키 — 사용 절대 금지
+
+`Sector` 인스턴스의 **getter 로 정의된 이름**은 컬렉션키로 사용 불가. setter 가 debug 모드에서 에러를 출력하고 (`COLLECTION_ESCAPE`), 정상 모드에서도 값이 반영되지 않는다.
+
+> schema 차단: `naming-objects.schema.json#/$defs/sectorReservedKeys`. 컨트롤 `Ckeys` 어떤 위치든 이 enum 의 값을 박으면 `flex-scenario validate` 가 fail. (`Panel.Collection.Ckeys` 는 시스템 등록 슬롯 — `_SUID` 만 예외 허용 = `ckeyWithSuid`).
+
+| 예약명 | 출처 | 의미 |
+|---|---|---|
+| `_SUID` | [const.js:1217](../../../public/engine/common/const.js) | 섹터 고유 ID (8+자리). 시스템이 자동 발급. **Collection.Ckeys 에는 포함되어야 함** |
+| `_mSUID` | [const.js:1216](../../../public/engine/common/const.js) | InnerBlock 의 마스터 섹터 SUID 참조 |
+| `block` | [collection.js:57](../../../public/engine/common/collection.js) | 섹터가 속한 Block 인스턴스 |
+| `collection` | [collection.js:68](../../../public/engine/common/collection.js) | 컬렉션 인스턴스 |
+| `innerBlocks` | [collection.js:79](../../../public/engine/common/collection.js) | 섹터 내부의 InnerBlock 들 |
+| `status` | [collection.js:91](../../../public/engine/common/collection.js) | `'A'` / `'U'` / `'D'` / `''` 단일 표기 |
+| `isAdded` / `isUpdated` / `isDeleted` / `isSelected` / `isActive` / `isLast` | [collection.js:99~152](../../../public/engine/common/collection.js) | 상태 boolean |
+| `keys` | [collection.js:212](../../../public/engine/common/collection.js) | 섹터의 컬렉션키 배열 |
+| `outerSector` / `outerBlock` | [collection.js:518~522](../../../public/engine/common/collection.js) | InnerBlock → 마스터 |
+
+### 3-3. 시스템 표준 키 — 정해진 의미가 있어 임의 변경 금지
+
+다음 키는 시스템·서비스가 자동으로 채우거나 약속된 의미를 가진다. **임의 의미로 재정의 금지**, 사용 시 정해진 의미로만.
+
+| 키 | 출처 | 의미 |
+|---|---|---|
+| `fBaseUserNo` | `_base.User.fBaseUserNo` / `GetUserList` 응답 | 사용자 번호 — 푸시 발송 수신자 ID, ServiceBinding 사용자 식별 |
+| `fBaseUserName` | 〃 | 사용자 이름 |
+| `fOrgName` | `GetUserList` 응답 | 조직명 |
+| `fEmail` | 〃 | 이메일 |
+| `fScenarioName` | scenarioMeta 루트 | 시나리오 이름 |
+
+> 예: 결재자 정보를 다른 이름(`approverNo` 등)으로 매핑하면 수신자 기반 런타임 헬퍼가 사용자를 인식하지 못한다. 반드시 `fBaseUserNo` 그대로 사용.
+
+### 3-4. `_` 접두 키 — 시스템 영역
+
+`_SUID` / `_mSUID` 외에 언더스코어로 시작하는 키는 시스템 내부용으로 예약되어 있다. **사용자 컬렉션키로 `_` 접두 사용 금지** — 향후 시스템 키와 충돌 가능성.
+
+```
+❌  _temp,  _flag,  _mode   (사용 금지)
+✅  fTemp,  fFlag,  fMode
+```
+
+### 3-5. JS 예약어 / 빌트인 충돌 금지
+
+```
+❌  for, while, if, delete, new, class, return, typeof, void, this, super
+❌  constructor, prototype, length, toString, hasOwnProperty, valueOf
+❌  Object, Array, String, Number, Boolean, Date, Math, JSON
+```
+
+`sector.length`, `sector.toString` 등은 JS 빌트인이라 동작이 깨진다. **항상 `f` 접두를 붙여 회피** (`fLength`, `fToString`).
+
+> schema 차단: `naming-objects.schema.json#/$defs/jsReservedWords` enum. 컨트롤 `Ckeys`, `CategoryName` 양쪽 모두 적용. CategoryName 에서 `class`/`for`/`new` 같은 키 사용 시 `flex-scenario validate` 가 fail.
+
+### 3-6. 정합성 강제 (validator)
+
+| 검사 | 규칙 |
+|---|---|
+| `Ckeys Consistency` | 각 `Panel.Category[*].Ckeys` ⊆ `Panel.Collection.Ckeys` ([validator.ts:645](../../../flextudio-ai-studio/lib/validator.ts)) |
+| `Collection.Ckeys` 포함 | `_SUID` 가 반드시 포함되어야 함 ([system-prompt-v2.md:3540](../../../flextudio-ai-studio/system-prompt-v2.md)) |
+| `Category 별 Ckeys` | 그 카테고리에서 실제 사용하는 키만 (불필요한 키 나열 금지) |
+
+## 4. 카테고리명 / Ckey 빠른 자가 점검표
+
+```
+[ ] 영문/숫자/_ 만 사용했는가?
+[ ] 숫자로 시작하지 않는가?
+[ ] 카테고리명에 Ctg prefix + PascalCase?
+[ ] 카테고리명이 CtgNew*/CtgEdit*/CtgAdd*/CtgInsert* 안티패턴이 아닌가?
+[ ] 컬렉션키가 시스템 게터(_SUID/status/isAdded/keys 등) 와 충돌하지 않는가?
+[ ] 컬렉션키가 _ 접두로 시작하지 않는가? (_SUID 자체는 예외)
+[ ] 컬렉션키가 JS 예약어/빌트인(length/toString/constructor 등) 과 충돌하지 않는가?
+[ ] fBaseUserNo / fBaseUserName / fOrgName / fEmail 같은 시스템 표준 키를
+    임의 의미로 재정의하지 않았는가?
+[ ] Collection.Ckeys 에 모든 카테고리의 Ckey + _SUID 가 포함되었는가?
+[ ] CategoryOrder 의 키 집합이 Category 키 집합과 정확히 일치하는가?
+[ ] DataConnection.CategoryName / 서비스 CategoryName 이 Panel.Category 에 정의되어 있는가?
+```
+
+## 5. 잘못된 예 → 권장 예
+
+| ❌ 잘못된 형태 | 문제 | ✅ 권장 |
+|---|---|---|
+| `Category: { "1차결재": {...} }` | 한글 식별자 — 점 표기법 불가 | `CtgFirstApprov` |
+| `Category: { "Ctg-Item-List": {...} }` | 하이픈 — JS 식별자 위반 | `CtgItemList` |
+| `Category: { "CtgNewMember": {...} }` | 신규 등록용 별도 카테고리 안티패턴 | `CtgMemberList` + `DataUsage:"new"` |
+| `Ckeys: ["status", "isActive"]` | Sector 시스템 게터와 충돌 | `Ckeys: ["fStatus", "fIsActive"]` |
+| `Ckeys: ["length", "toString"]` | JS 빌트인 충돌 | `Ckeys: ["fLength", "fLabel"]` |
+| `Ckeys: ["_userNo", "_state"]` | `_` 접두 시스템 영역 | `Ckeys: ["fUserNo", "fState"]` |
+| `CategoryOrder: ["CtgItemList"]` 인데 `Category: { CtgItemList:..., CtgFilter:... }` | 키 집합 불일치 | `CategoryOrder: ["CtgItemList", "CtgFilter"]` |
+| 임의 매핑 `addReceiver(s.approverNo, false)` | `fBaseUserNo` 가 아니라 동작 안 함 | `addReceiver(s.fBaseUserNo, false)` |
+
+## 6. 메타 작성 시 권장 흐름
+
+1. 화면별 사용 데이터 식별 → 카테고리 후보 (`CtgItemList`, `CtgFilter` 등) 도출
+2. 각 카테고리의 컬렉션키 (Ckey) 확정 — `f` 접두 + camelCase
+3. `Panel.Collection.Ckeys` 에 **모든 카테고리의 Ckey 합집합 + `_SUID`** 채움
+4. `Panel.Category` 에 카테고리별 자기 Ckeys 만 채움
+5. `Panel.CategoryOrder` 에 카테고리 키 순서 (선언 순서) 채움
+6. 그룹의 `DataConnection.CategoryName` 에 정의된 카테고리명만 사용
+7. validator 통과 확인 — `category_references`, `category_order`, `ckeys_consistency`, `ctg_new_edit` 모두 pass