@flextudio/scenario 0.1.0

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

@@ -0,0 +1,176 @@
+# Sector (섹터)
+
+> "컬렉션을 구성하는 기본 단위. 독립적인 노드이며 Key-Value 쌍으로 데이터를 보관" — 공식 가이드
+> "RDB 한 Row = 하나의 섹터"
+
+## 1. 정의
+
+- 코드: `class Sector extends Object` (`collection.js:26`)
+- 모든 섹터는 발급된 고유 ID(`_SUID`, 8+자리 영숫자)를 가지며, 이 SUID 가 mapper 의 키이다.
+- 섹터의 일반 속성(컬렉션키)은 `string | number | boolean | null` 또는 **InnerBlock**(`Block` 인스턴스, 섹터의 자식 배열) 일 수 있다.
+
+```js
+sector = {
+    _SUID: "abc12XYZ",
+    fName: "홍길동",
+    fAge: 30,
+    fItems: Block([                       // InnerBlock — 자식 섹터들
+        Sector({ _SUID: "...", ... }),
+        Sector({ _SUID: "...", ... })
+    ])
+}
+```
+
+InnerBlock 안의 자식 Sector 도 **컬렉션의 mapper 에 동일하게 등록** 된다. 즉 어떤 깊이의 섹터든 `_c.mapper[suid]` 한 번에 찾을 수 있다.
+
+## 2. 상태값과 게터
+
+`Sector` 인스턴스는 자체적으로 상태를 보관하지 않고, **블록의 상태집합** (`block.status` = `_cStatus` 또는 `_cStatus.InnerStatus[msuid+mKey]`) 을 조회하여 boolean 을 반환한다.
+
+| getter | 코드 | 의미 |
+|---|---|---|
+| `isAdded`     | `block.isOnStatus(C_ADDED, suid)`     | added 목록에 포함 |
+| `isUpdated`   | `block.isOnStatus(C_UPDATED, suid)`   | updated 목록에 포함 |
+| `isDeleted`   | `block.isOnStatus(C_DELETED, suid)`   | deleted 목록에 포함 |
+| `isSelected`  | `block.isOnStatus(C_SELECTED, suid)`  | selected 목록에 포함 |
+| `isActive`    | `block.isActive(suid)`                | `status[C_ACTIVE] == suid` |
+| `isLast`      | `_cStatus.lastReflected.indexOf(suid) > -1` | 직전 서비스/이벤트 반영분 |
+| `status`      | `D > A > U` 우선순위 단일 문자       | 디버거/저장 페이로드용 |
+
+> setter 는 **debug 모드에서만 에러를 출력**하며 실제 값은 변경되지 않는다 (`collection.js:53,124,...`). 상태 변경은 항상 메서드(`activate`/`select`/`delete`/`set` 등) 또는 `block.addStatus()` 를 통해서만 가능하다.
+
+## 3. 생성
+
+```js
+new Sector(block, obj, isForced)         // 직접 호출은 거의 없음
+block.addSector(obj, categoryName, isForced, targetIndex)
+_collections.addSector(obj)              // 컬렉션 최상위
+f.Collection.addSector(obj, category, targetIdx)   // 공개 API → fCreateSector
+```
+
+생성 단계:
+1. `block.issueSUID(obj, isForced)` — `obj._SUID` 가 있고 mapper 에 없으면 그대로 사용, 충돌 시 `generateUID()` 재발급(`isForced`) 또는 에러.
+2. `obj` 의 모든 키를 순회하며 — Block 형이면 InnerBlock 으로 래핑, 아니면 그대로 복사.
+3. `block.push(sector)` + `mapper[suid] = sector`.
+4. (옵션) `categoryName` 인자 시 카테고리에 SUID 등록.
+5. `passChangeCollection()` — 디버거 반영.
+
+> **주의**: `f.Collection.addSector` 자체는 `addStatus(C_ADDED, suid)` 를 호출하지 않는다 (`fCreateSector` → `addSector` 까지만). 즉 단순 추가는 `added` 표시가 자동 부여되지 않으므로, 저장 흐름에서 신규로 분기하려면 별도의 `addStatus(C_ADDED)` 호출 또는 `DataUsage:"new"` 자동 동작을 통한 진입이 필요하다.
+> 단, `initScenarioCollection` 의 시작 섹터, 알림 진입 섹터, `restoreCollection` 등 일부 경로는 명시적으로 `addStatus(C_ADDED, suid)` 를 호출한다.
+
+## 4. 변형 (mutation)
+
+### 4-0. 직접 대입 vs `set()` — 실무 표준
+
+```js
+// 직접 대입 — 값만 바뀜. updated 상태 부여 X, reload X
+_c.CtgList[n].fName = '홍길동';
+
+// set — updated 자동 + 해당 SUID 바인딩 컨트롤 자동 reload
+_c.CtgList[n].set('fName', '홍길동');
+```
+
+| 방식 | updated 표시 | 자동 reload | 추천 상황 |
+|---|---|---|---|
+| `sector.콜렉션키 = 값` | ✗ | ✗ | 다량의 키를 한 번에 변경 후 마지막에 그룹 단위 `reload()` |
+| `sector.set(k,v,...)` | ○ | ○ | 단건 변경, 즉시 화면 반영 필요 |
+| `sector.setValue(k,v,...)` | ○ | ✗ | updated 표시는 필요하지만 reload 는 묶어서 한 번 |
+
+활성 섹터 기준 작업의 표준형:
+
+```js
+if (!_c.CtgList) return;                     // 가드
+const cur = _c.CtgList.activeSector;         // 클릭/선택된 섹터
+if (!cur) return;
+cur.fStatus = '확정';                         // 직접 대입
+cur.fApprovedDate = today;
+group.reload();                              // 화면 일괄 반영
+```
+
+### 4-1. `set(...args)` — reload 트리거
+
+```js
+sector.set("fName", "홍길동", "fAge", 30)
+```
+
+- `block.addStatus(C_UPDATED, suid)` — `updated` 자동 표시
+- 짝수 인자(key, value)를 순회하며 섹터 속성에 직접 대입
+- `reloadControlsBySectorChanged(suid, ...changedKeys)` — 해당 SUID 에 바인딩된 컨트롤 자동 갱신
+- InnerBlock 안의 섹터인 경우, **마스터 섹터의 reload 도 함께 트리거** (`collection.js:257`)
+
+### 4-2. `setValue(...args)` — reload 없음
+
+`set` 과 거의 동일하지만 `reloadControlsBySectorChanged` 를 호출하지 않는다.
+- 다량의 값을 한꺼번에 변경하고 마지막에 한 번만 그룹 reload 를 걸어야 할 때 사용.
+- key 자리에 배열을 주면 **여러 키에 같은 값**을 한 번에 set (`collection.js:280`).
+
+### 4-3. `mergeSector(obj)` / `replaceSector(obj)`
+
+- `mergeSector` — 동일 키는 덮어쓰고, InnerBlock 키는 release 후 새 Block 으로 교체.
+- `replaceSector` = `remove()` + `mergeSector(obj)`. SUID 는 유지된다.
+
+### 4-4. `remove(...keys)` / `release()` / `delete()`
+
+| 메서드 | 효과 | 상태 |
+|---|---|---|
+| `remove(...keys)` | 지정 키만 삭제 (없으면 모든 키). `_SUID` 는 보존 | (변경 없음) |
+| `release()` | 섹터를 컬렉션/블록/카테고리/모든 status 인덱스에서 제거 | 완전 제거 (mapper 에서도 사라짐) |
+| `delete()` | `isAdded` 면 `release()` (저장된 적 없으니 흔적 제거), 아니면 `addStatus(C_DELETED, suid)` | `deleted` 또는 완전 제거 |
+
+> **저장 패턴** (운영 — 백엔드 동기화 흐름): 화면에서 사용자가 "삭제" 했을 때 `sector.delete()` 를 부르면, 신규 추가분은 깨끗이 사라지고 기존 데이터는 deleted 표시만 남는다. 저장 이벤트에서 `_c.CtgList.getSUIDsOfStatus('deleted')` 로 모아서 서버 삭제 요청 → `_c.CtgList.remove(...suids)` 로 컬렉션에서 제거 → `reload(group)`.
+>
+> ★ **생성 시나리오 정책 — 삭제는 `release()`**: 생성 시나리오는 서버 동기화가 없으므로 `delete()` 의 deleted 잔존 표시가 무의미하며, 잔존 섹터가 집계 루프(`isDeleted` 가드 필요)·카운트를 오염시킨다. 화면 삭제는 **`sector.release()` (완전삭제)** 가 정본 — intent.script.deleteActive 가 자동 emit, raw `.delete()` 호출은 `[script-allow]` 가 차단.
+
+### 4-5. `activate()` / `select()` / `unSelect()`
+
+```js
+sector.activate()    // 같은 블록의 다른 섹터 active 해제 후 자기 자신 active. outerSector 가 있으면 그것도 active
+sector.select()      // selected 목록에 자기 SUID 추가 (다중 가능)
+sector.unSelect()    // selected 목록에서 제거
+```
+
+`activate` 는 **InnerBlock 의 마스터 섹터까지 함께 active** 가 되도록 처리한다 (`collection.js:172` 영역, outerSector chain).
+
+## 5. 상태 전이 다이어그램
+
+```
+            ┌──────────────────────────────────────────────┐
+            │                                              │
+       ┌─── added ───set()──→ added+updated ──delete()──→ release(완전제거)
+       │                                                   ▲
+   addSector                                               │
+       │                                                   │
+   normal ───set()──→ updated ───delete()──→ deleted ─────┘ (deleted 상태에서 delete 재호출 시 그대로)
+       │
+       └ select()/unSelect()  (added/updated/deleted 와 직교)
+       └ activate()/unActivate()  (블록당 1개)
+       └ isLast (서비스/이벤트가 반영한 마지막 묶음 = _cStatus.lastReflected)
+```
+
+`setStatus(status)` (`collection.js:163`) 는 `added/updated/deleted` 셋을 모두 해제한 뒤 인자만 set 한다. 단순 강제 변경 용도.
+
+## 6. 컬렉션키 명명 규칙 (요약)
+
+> 상세는 [naming.md](./naming.md).
+
+- 컨벤션: `f` 접두 + camelCase (`fName`, `fAge`, `fStatus`).
+- **시스템 게터와 충돌 금지** — 다음 이름은 컬렉션키로 사용 불가:
+  `_SUID`, `_mSUID`, `block`, `collection`, `innerBlocks`, `status`,
+  `isAdded`, `isUpdated`, `isDeleted`, `isSelected`, `isActive`, `isLast`, `keys`, `outerSector`, `outerBlock`
+- `_` 접두로 시작하는 키 금지 (`_temp`, `_flag` 등) — 시스템 영역.
+- JS 빌트인/예약어 금지 — `length`, `toString`, `constructor`, `for`, `class`, `delete`, `new`...
+- 시스템 표준 키 의미 보존 — `fBaseUserNo` / `fBaseUserName` / `fOrgName` / `fEmail` 은 정해진 의미로만.
+- `Panel.Collection.Ckeys` 에 `_SUID` 포함 + 모든 카테고리 Ckey 합집합.
+
+## 7. SUID 발급 규칙
+
+```js
+// collection.js:499  issueSUID
+- 입력 obj 에 _SUID 가 있고 mapper 에 없으면 → 그대로 사용
+- 입력 obj 에 _SUID 가 있고 mapper 에 이미 있으면 →
+    isForced=true → generateUID 로 새 SUID 재발급
+    isForced=false → error 출력
+- 입력 obj 에 _SUID 가 없으면 → generateUID 로 신규 발급
+```
+
+`generateUID` 는 8자리 영숫자(0-9a-zA-Z). mapper 크기가 10000+ 이면 자릿수 자동 증가 — `Math.max(8, String(idsArr.length).length + 4)`.

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

@@ -0,0 +1,114 @@
+# Sector Status (섹터 상태값)
+
+> 공식 가이드 — "사용자의 동작에 따라 자동으로 상태값이 관리됩니다."
+
+## 1. 상태값 5종 + 1 (lastReflected)
+
+| 이름 | 코드 상수 (`const.js:1228~1236`) | 다중성 | 설명 (가이드 발췌) |
+|---|---|---|---|
+| **active** | `C_ACTIVE = 'active'` | 블록당 1개 | "사용자가 실제 사용하면서 상호작용하고 있는 섹터를 항상 Active 한 상태로 관리". 마지막 사용 중인 단 하나의 섹터만 가짐. |
+| **selected** | `C_SELECTED = 'selected'` | 다중 | 사용자가 직접 선택한 섹터. 체크박스/리스트 다중선택 등에서 사용. |
+| **added** | `C_ADDED = 'added'` | 다중 | "사용자가 섹터를 추가하면 해당 섹터에 Added(추가됨) 상태가 부여". 저장 시 INSERT 대상. 표시 코드 `'A'`. |
+| **updated** | `C_UPDATED = 'updated'` | 다중 | "조회해온 정보를 수정한 경우 Updated(수정됨) 상태가 부여". `sector.set()` 호출 시 자동. 표시 코드 `'U'`. |
+| **deleted** | `C_DELETED = 'deleted'` | 다중 | "삭제하면 화면에 나오지 않지만 섹터에 Deleted(삭제됨) 상태가 부여". 표시 코드 `'D'`. |
+| (lastReflected) | `_cStatus.lastReflected` | 묶음 | "가장 최근에 반영된 변경사항이 있는 데이터" — 서비스 결과/이벤트 반영분 단위 추적용. Sector.isLast 로 조회. |
+
+추가 보조 키:
+- `C_ALL = 'all'` — 모든 섹터 조회용 키워드. (전이 상태 아님)
+- `C_LAST = 'last'` — `lastReflected` 별칭 키워드.
+- `C_DISPLAYED = 'displayed'` — 화면에 바인딩된 SUID 목록(StepBinder 기반).
+
+## 2. 저장 위치
+
+상태는 Sector 자체가 아니라 **소속 블록의 BlockStatus** 가 보관한다 (`status.js:3`).
+
+```js
+class BlockStatus {
+    [C_ADDED]    : [suid, ...],
+    [C_UPDATED]  : [suid, ...],
+    [C_DELETED]  : [suid, ...],
+    [C_SELECTED] : [suid, ...],
+    [C_ACTIVE]   : suid | undefined
+}
+
+class CollectionStatus extends BlockStatus {
+    InnerStatus      : { [msuid+mKey]: BlockStatus, ... }   // InnerBlock 별 별도 상태
+    _stepBinders     : { [stepId]: StepBinder }             // 화면 바인딩 정보
+    lastReflected    : [suid, ...]                          // 최근 반영분
+    bindBeforeReloaded : ?LayoutBinder                      // step 전환 임시 보관
+}
+```
+
+따라서 InnerBlock 안의 섹터는 **외부 컬렉션 status 와 분리된 자체 added/updated/deleted/selected/active** 를 갖는다. 마스터 섹터를 식별자로 한다.
+
+## 3. 상태 전이
+
+### 3-1. `added` 의 진입
+
+| 진입 경로 | 자동? |
+|---|---|
+| `initScenarioCollection` 의 시작 빈 섹터 | ○ — `addStatus(C_ADDED)` 명시 호출 |
+| 알림 Action 진입 시 sectorsJson 으로 추가된 섹터 | ○ |
+| `restoreCollection` 으로 복원된 섹터 (이전에 added 였던 것) | 캡쳐된 status 그대로 복원 |
+| `f.Collection.addSector(obj)` / `category.addSector(obj)` 직접 호출 | × — 명시적으로 `addStatus(C_ADDED, suid)` 호출 필요 |
+| `DataUsage:"new"` 자동 새 섹터 생성 | ○ (런타임의 query/new 분기에서 처리) |
+
+### 3-2. `updated` 의 진입
+
+```js
+sector.set(...)         → block.addStatus(C_UPDATED)         + reload
+sector.setValue(...)    → block.addStatus(C_UPDATED)         (reload 없음)
+sector.setStatus('updated')  → 다른 상태(added/deleted) 해제 후 updated 만 set
+```
+
+### 3-3. `deleted` 의 진입
+
+```js
+sector.delete()
+  if (isAdded)  →  release()                  // 흔적 제거 (added 만 있던 신규)
+  else          →  addStatus(C_DELETED)       // 기존 데이터: 표시만 deleted
+```
+
+### 3-4. `setStatus` 우선순위
+
+`Sector.setStatus(status)` (`collection.js:163`) 는 **added/updated/deleted 셋을 모두 제거**한 뒤 인자만 set 한다. 즉 한 섹터에 added 와 updated 가 동시에 set 되어 있다가도, `setStatus('updated')` 호출 시 added 가 사라진다.
+
+### 3-5. `Sector.status` getter — 단일 표기
+
+```js
+get status() {
+    return this.isDeleted ? C_STATUS_DELETE        // 'D'
+         : this.isAdded   ? C_STATUS_ADD           // 'A'
+         : this.isUpdated ? C_STATUS_UPDATE        // 'U'
+         : '';
+}
+```
+
+→ `D > A > U` 우선순위. 따라서 added 후 set 한 섹터는 `'A'` 로 표시 (저장 시 INSERT 분기용으로 충분).
+
+## 4. 필터 — `TargetSector.Filters` 의 Status 항목
+
+메타에서 그룹의 `DataConnection.UseTargetSector: true` + `TargetSector.Filters: [{FilterType:"Status", Status:[...]}]` 로 어떤 상태의 섹터만 렌더할지 선언한다.
+
+| Status 배열 값 | 카테고리 메서드 매핑 |
+|---|---|
+| `["active"]` | `category.getSUIDsOfStatus('active')` → `[category.active]` |
+| `["selected"]` | `_cStatus.selected ∩ category.suids` |
+| `["added"]` | `_cStatus.added ∩ category.suids` |
+| `["updated"]` | `_cStatus.updated ∩ category.suids` |
+| `["deleted"]` | `_cStatus.deleted ∩ category.suids` |
+| 다중 (e.g. `["added","updated"]`) | OR 조합 (`getSectorsOfTarget` 처리) |
+
+> `DataUsage:"detail"` / `"update"` 는 메타 작성 시 `UseTargetSector: true` + `TargetSector: { Filters: [{ FilterType: "Status", Status: ["active"] }] }` 가 강제된다 (`validator.ts:285`).
+
+## 5. 디버거 표시
+
+스튜디오 하단 패널의 **Collection / Category 탭** 에서 각 섹터의 `status` 컬럼은 `'A'/'U'/'D'/''` 로 표시된다.
+**Status of** 필터(`flextudio-guide.md:508`)는 `_cStatus[C_ADDED|C_UPDATED|C_DELETED|C_SELECTED]` 와 active SUID 를 직접 사용한다.
+
+`passChangeCollection(suid?, changedKeys?)` (`collection.js:1511`) 가 모든 변형 직후 호출되어 디버거가 실시간 갱신된다.
+
+## 6. step 단위 리셋과 `lastReflected`
+
+- Step 이동 시 `_cStatus.beforeReload(stepId)` → 해당 step 의 binder 만 임시 저장 후 제거. **상태값(added/updated/deleted/selected/active) 자체는 시나리오 단위로 유지**된다.
+- 서비스 결과나 이벤트가 컬렉션에 반영되면 `_cStatus.lastReflected` 가 그 SUID 묶음으로 갱신되어, 직후 step 에서 "방금 반영된 것만" 을 골라 보여주는 패턴(`Status: ["last"]`)이 가능하다.