@simplysm/sd-claude 14.0.80 → 14.0.82

package/claude/references/sd-simplysm14/manuals/client-crud.md

@@ -48,7 +48,7 @@
 | `#commandTpl`       | 상단(또는 modal/control 모드의 명령 영역) 추가 액션 버튼.                  |
 | `#bottomCommandTpl` | modal 하단 좌측 영역. modal + selectMode 면 "선택 해제/확인" 과 함께 표시. |
 
-`<sd-sheet-column>` 은 `<sd-crud-list>` 의 직속 자식으로 두면 내부 시트로 자동 투영된다.
+`<sd-sheet-column>` 은 `<sd-crud-list>` 의 직속 자식으로 두면 내부 시트로 자동 투영됨.
 
 ### viewType 별 동작
 

package/claude/references/sd-simplysm14/manuals/client-demo.md

@@ -1,6 +1,6 @@
 # 클라이언트 데모 작성 매뉴얼
 
-`@simplysm/angular` v14 로 spec.md §4.x 화면을 **데모** 로 옮길 때의 추가 처방. 컴포넌트 일반 규약(파일명·시그널·DI·핸들러·시트·폼·버튼·모달 호출·합성 패턴 등)은 [client-component.md](./client-component.md). 본 문서는 spec § → 산출물 매핑과 데모 한정 패턴만 다룬다.
+`@simplysm/angular` v14 로 spec.md §4.x 화면을 **데모** 로 옮길 때의 추가 처방. 컴포넌트 일반 규약(파일명·시그널·DI·핸들러·시트·폼·버튼·모달 호출·합성 패턴 등)은 [client-component.md](./client-component.md). 본 문서는 spec § → 산출물 매핑과 데모 한정 패턴만 다룸.
 
 ## §4.x 화면 유형 → 파일 역할
 

package/claude/references/sd-simplysm14/manuals/client-setup.md

@@ -1,10 +1,10 @@
 # 클라이언트 환경 셋업 매뉴얼
 
-화면 작성 시점에는 거의 건드리지 않으며, 새 앱 부트스트랩이나 새 서비스/마스터 데이터 추가 시에만 본다.
+화면 작성 시점에는 거의 건드리지 않으며, 새 앱 부트스트랩이나 새 서비스/마스터 데이터 추가 시에만 봄.
 
 ## AppServiceProvider
 
-`@simplysm/service-client` 위에 앱이 만드는 root provider. 서비스/이벤트 프록시와 ORM 커넥터를 lazy 캐싱으로 노출한다.
+`@simplysm/service-client` 위에 앱이 만드는 root provider. 서비스/이벤트 프록시와 ORM 커넥터를 lazy 캐싱으로 노출함.
 
 ```ts
 @Injectable({ providedIn: "root" })

package/claude/references/sd-simplysm14/manuals/client-tab.md

@@ -1,6 +1,6 @@
 # 탭 컨트롤 사용법
 
-`<sd-tab>` 은 **선택기**다. 콘텐츠 컨테이너가 아니다. 콘텐츠는 탭 바깥에서 `@if` / `@switch` 로 분기 렌더한다.
+`<sd-tab>` 은 **선택기**. 콘텐츠 컨테이너가 아님. 콘텐츠는 탭 바깥에서 `@if` / `@switch` 로 분기 렌더함.
 
 ## API
 
@@ -9,7 +9,7 @@
 | `<sd-tab>`      | `[(value)]` (model) | 현재 선택값. 양방향 필수.             |
 | `<sd-tab-item>` | `[value]` (input)   | 이 항목의 식별값. 클릭 시 부모로 set. |
 
-선택 상태는 `sd-tab-item` 이 부모 `sd-tab` 의 `value` 와 자기 `value` 를 비교해 자동 결정한다.
+선택 상태는 `sd-tab-item` 이 부모 `sd-tab` 의 `value` 와 자기 `value` 를 비교해 자동 결정함.
 
 ## 표준 패턴
 

package/claude/references/sd-simplysm14/manuals/logging.md

@@ -49,7 +49,7 @@ console.error("[X] 실패:", err);
 
 ## 모듈-레벨 logger 주의
 
-모듈 레벨에서 `consola.withTag()` 를 직접 호출하면 호출 시점의 options(level/reporters)가 스냅샷으로 고정되어, 이후 `setupConsola()` 가 reporters 를 갱신해도 child instance 에 반영되지 않는다.
+모듈 레벨에서 `consola.withTag()` 를 직접 호출하면 호출 시점의 options(level/reporters)가 스냅샷으로 고정되어, 이후 `setupConsola()` 가 reporters 를 갱신해도 child instance 에 반영되지 않음.
 
 - **해결**: `createLogger(tag)` 사용 (`@simplysm/core-common`, 내부 구현은 lazy Proxy — 첫 메서드 접근 시점까지 `withTag` 생성을 지연).
 - 모든 환경(Node·브라우저·Capacitor)에서 위치(모듈 레벨·함수 내부·class field)에 관계없이 `createLogger` 로 통일.
@@ -57,9 +57,9 @@ console.error("[X] 실패:", err);
 
 ## 예외 — `eslint-disable no-console` 가 정당화되는 자리
 
-다음 경우에 한해 `/* eslint-disable no-console */` 파일 헤더를 허용한다. 그 외는 모두 consola 로 교체.
+다음 경우에 한해 `/* eslint-disable no-console */` 파일 헤더를 허용함. 그 외는 모두 consola 로 교체.
 
 - **CLI 도움말·yargs help 텍스트** 처럼 stdout 그 자체를 사용자 출력으로 쓰는 경우 (예: `packages/sd-cli/src/sd-cli-entry.ts` 의 `collectYargsHelp`).
 - **ErrorHandler 마지막 안전망** 등 consola 자체가 죽었을 가능성이 있는 catch 블록 — 해당 자리만 `eslint-disable-next-line no-console` + 이유 주석.
 
-예외 적용 시 disable 주석 위에 사유를 1줄로 남긴다.
+예외 적용 시 disable 주석 위에 사유를 1줄로 남김.

package/claude/references/sd-simplysm14/manuals/orm-union.md

@@ -1,15 +1,15 @@
 # ORM UNION 사용법
 
-[단일 쿼리 우선](./orm.md) 규칙을 지키면서 **서로 다른 엔티티를 한 목록으로** 보여줘야 할 때 쓴다. 코드에서 merge 하지 말고, select shape 을 동일하게 맞춘 두 Queryable 을 `Queryable.union(...)` 으로 합친다.
+[단일 쿼리 우선](./orm.md) 규칙을 지키면서 **서로 다른 엔티티를 한 목록으로** 보여줘야 할 때 씀. 코드에서 merge 하지 말고, select shape 을 동일하게 맞춘 두 Queryable 을 `Queryable.union(...)` 으로 합침.
 
 ## 규칙
 
-- 두 쿼리의 select 컬럼 이름·타입·순서가 정확히 일치해야 한다.
-- 행 종류 구분 등 리터럴 값은 JS 값을 그대로 쓴다.
-- 한쪽에만 있는 컬럼은 NULL 자리채움이 필요한데 타입 추론이 안 되므로 `expr.raw("<type>")\`NULL\`` 로 명시한다.
-- 필터(`where`)는 union 전에 각 쿼리에 같은 조건으로 적용한다 — 각 소스에서 미리 행 수를 줄여야 union 비용이 작다 (predicate pushdown). union 결과에 필터를 걸면 두 소스를 다 읽은 뒤 거르게 되고, select 한 컬럼만 남아 join 컬럼으로 필터도 불가하다.
-- 총 건수는 가능하면 **각 소스에서 따로 `count` 후 합산**한다. union 결과의 `count` 는 양쪽 SELECT 를 모두 실행해 머티리얼라이즈한 뒤 세지만, 각각 세면 단순 집계로 끝난다. 중복 제거가 필요해 합산이 부정확해질 때만 union 후 count.
-- `Queryable.union(...)` 결과는 의미상 wrap 된 derived table 로, 그 위에서 호출되는 모든 fluent 연산자(`orderBy` / `limit` / `top` / `distinct` / `groupBy` / `having` / `where` / `select` / `join` 등)는 외부 union 위에 자동 적용된다. sub 별 적용(predicate pushdown 등)을 원하면 union 전에 각 sub-Queryable 에 미리 호출한다.
+- 두 쿼리의 select 컬럼 이름·타입·순서가 정확히 일치해야 함.
+- 행 종류 구분 등 리터럴 값은 JS 값을 그대로 씀.
+- 한쪽에만 있는 컬럼은 NULL 자리채움이 필요한데 타입 추론이 안 되므로 `expr.raw("<type>")\`NULL\`` 로 명시함.
+- 필터(`where`)는 union 전에 각 쿼리에 같은 조건으로 적용함 — 각 소스에서 미리 행 수를 줄여야 union 비용이 작음 (predicate pushdown). union 결과에 필터를 걸면 두 소스를 다 읽은 뒤 거르게 되고, select 한 컬럼만 남아 join 컬럼으로 필터도 불가함.
+- 총 건수는 가능하면 **각 소스에서 따로 `count` 후 합산**함. union 결과의 `count` 는 양쪽 SELECT 를 모두 실행해 머티리얼라이즈한 뒤 세지만, 각각 세면 단순 집계로 끝남. 중복 제거가 필요해 합산이 부정확해질 때만 union 후 count.
+- `Queryable.union(...)` 결과는 의미상 wrap 된 derived table 로, 그 위에서 호출되는 모든 fluent 연산자(`orderBy` / `limit` / `top` / `distinct` / `groupBy` / `having` / `where` / `select` / `join` 등)는 외부 union 위에 자동 적용됨. sub 별 적용(predicate pushdown 등)을 원하면 union 전에 각 sub-Queryable 에 미리 호출함.
 
 ## 예시
 

package/claude/references/sd-simplysm14/manuals/orm.md

@@ -1,75 +1,75 @@
-# ORM 작업 가이드
-
-## 단일 쿼리 우선
-
-연관 데이터는 select 의 `join` 으로 한 쿼리에 모아 가져온다. 여러 쿼리로 나눠 받아 코드(서버/UI)에서 합치지 않는다.
-
-ORM 빌더로 표현 불가능한 경우, 작성 전 사용자 보고 후 중단.
-
-예외: raw query로도 표현 불가하거나 단일 쿼리화가 명백히 비효율일 때만. 사유를 코드 주석에 남긴다.
-
-이종 엔티티(예: 입고 + 출고)를 한 목록으로 보여줘야 할 때 두 결과를 코드에서 merge 하지 않으려면 → [orm-union.md](./orm-union.md) 참조.
-
-## 조회 목록 표준 흐름
-
-list / sheet 화면의 본 쿼리는 다음 순서로 작성한다:
-
-1. root queryable 빌드 (`db.X()`).
-2. 필요한 연관 데이터를 `joinSingle` 로 부착 — 본 행에 곧장 부착하지 않으면 안 되는 컬럼만. join 내부 쿼리도 동일 흐름 (`from → joinSingle → where → select`).
-3. `.select((p) => ({ ...도출 컬럼들... }))` — coalesce / CASE WHEN / 산식 등 모든 도출을 한 번에 projection. select 콜백 안에서 로컬 `const` 로 산식을 잘게 나눠 가독성 확보.
-4. WHERE 는 step 3 의 projected 컬럼 이름으로 직접 참조 (`r.psd`, `r.isCanceled`, `r.status`, …). framework 가 projected ExprUnit AST 를 WHERE 절에 그대로 inline 하므로 wrap 없이도 도출 컬럼 필터링이 동작한다.
-5. `count()` 로 총 건수.
-6. `orderBy(...).limit(page * size, size).execute()`.
-
-WHERE / SELECT 양쪽에서 동일 도출 산식을 쓰겠다고 `buildDerived(p)` 같은 helper 함수 만들지 말 것 — step 3 의 projected 컬럼이 자동으로 그 역할을 한다.
-
-화면 첫 진입 1회만 필요하고 refresh / 필터 변경에 무관한 데이터 (필터 dropdown 옵션 등) 는 본 목록 쿼리에 섞지 말 것. 별도 1회 effect 로 분리해 init 시점에만 로드한다.
-
-## 안티패턴
-
-### SELECT 절 안 `expr.subquery` / `expr.exists` 박지 말 것
-
-도메인 boolean (`isCompleted`, `hasAny` 등) / 집계 (`SUM`, `COUNT`, `MAX`) 가 필요하면 `joinSingle` 안에서 `from + where + select(aggregate)` 로 묶어 outer 행에 컬럼으로 부착한다. SELECT column 에 subquery / exists 박으면 outer 행마다 inner 가 N 회 실행된다.
-
-```ts
-// 나쁜 예 — 행당 subquery N회
-.select((p) => ({
-  isCompleted: expr.is(expr.exists(db.X().where(...))),
-  sumA: expr.subquery("number", db.Y().select(...)),
-}))
-
-// 좋은 예 — joinSingle 로 1회 부착, 컬럼으로 참조
-.joinSingle("state", (q, p) =>
-  q.from(X).where((x) => [expr.eq(x.fk, p.id)])
-    .select((x) => ({
-      rowCount: expr.count(),
-      completedCount: expr.count(x.completedAt),
-      sumA: expr.sum(x.amount),
-    })),
-)
-.select((p) => ({
-  isCompleted: expr.gt(p.state!.completedCount, 0),
-  sumA: expr.coalesce(p.state!.sumA, 0),
-}))
-```
-
-### 불필요한 `wrap()`
-
-`wrap()` 은 framework 가 명시 요구하는 경우에만 쓴다 (대표적으로 `count()` after `distinct()` / `groupBy()` 호출 같은 명시 요구).
-
-도출 컬럼 위에서 필터/정렬을 걸기 위해 wrap 을 끼우는 패턴은 불필요 — `.select(...).where((r) => [...])` 만으로 framework 가 projected ExprUnit AST 를 WHERE / ORDER BY 에 inline 한다.
-
-"Layer 1 = materialize, Layer 2 = derive" 같은 다층 wrap 구조도 군더더기. 단일 select 안 로컬 `const` 로 산식 분리하면 동일 SQL 이 나온다.
-
-## 스키마 정의
-
-컬럼은 `NOT NULL` 기본. `.nullable()`/`.default(...)` 는 도메인 근거가 있을 때만 붙인다.
-
-- `.nullable()`: 도메인상 값이 없을 수 있을 때만 (선택 입력, 미발생 이벤트 시각, 선택적 FK).
-- `.default(...)`: 사용자가 명시 지시한 경우에만.
-- "초기값 애매", "마이그레이션 중간 단계", "넣을 값 모름" 은 nullable/default 근거 아님. 호출자가 넣도록 강제하거나 backfill 후 `NOT NULL`로 전환.
-
-## 삭제 전략
-
-- **기초정보(마스터)**: soft delete (`isDisabled` 등). FK 참조 무결성 보존.
-- **프로세스 문서(트랜잭션)**: 물리 delete. 상세 행 포함 캐스케이드. 단, 다른 테이블이 FK로 참조 중이면 삭제 차단하고 최종 사용자에게 toast 등으로 사유 안내.
+# ORM 작업 가이드
+
+## 단일 쿼리 우선
+
+연관 데이터는 select 의 `join` 으로 한 쿼리에 모아 가져옴. 여러 쿼리로 나눠 받아 코드(서버/UI)에서 합치지 않음.
+
+ORM 빌더로 표현 불가능한 경우, 작성 전 사용자 보고 후 중단.
+
+예외: raw query로도 표현 불가하거나 단일 쿼리화가 명백히 비효율일 때만. 사유를 코드 주석에 남김.
+
+이종 엔티티(예: 입고 + 출고)를 한 목록으로 보여줘야 할 때 두 결과를 코드에서 merge 하지 않으려면 → [orm-union.md](./orm-union.md) 참조.
+
+## 조회 목록 표준 흐름
+
+list / sheet 화면의 본 쿼리는 다음 순서로 작성:
+
+1. root queryable 빌드 (`db.X()`).
+2. 필요한 연관 데이터를 `joinSingle` 로 부착 — 본 행에 곧장 부착하지 않으면 안 되는 컬럼만. join 내부 쿼리도 동일 흐름 (`from → joinSingle → where → select`).
+3. `.select((p) => ({ ...도출 컬럼들... }))` — coalesce / CASE WHEN / 산식 등 모든 도출을 한 번에 projection. select 콜백 안에서 로컬 `const` 로 산식을 잘게 나눠 가독성 확보.
+4. WHERE 는 step 3 의 projected 컬럼 이름으로 직접 참조 (`r.psd`, `r.isCanceled`, `r.status`, …). framework 가 projected ExprUnit AST 를 WHERE 절에 그대로 inline 하므로 wrap 없이도 도출 컬럼 필터링이 동작함.
+5. `count()` 로 총 건수.
+6. `orderBy(...).limit(page * size, size).execute()`.
+
+WHERE / SELECT 양쪽에서 동일 도출 산식을 쓰겠다고 `buildDerived(p)` 같은 helper 함수 만들지 말 것 — step 3 의 projected 컬럼이 자동으로 그 역할을 함.
+
+화면 첫 진입 1회만 필요하고 refresh / 필터 변경에 무관한 데이터 (필터 dropdown 옵션 등) 는 본 목록 쿼리에 섞지 말 것. 별도 1회 effect 로 분리해 init 시점에만 로드함.
+
+## 안티패턴
+
+### SELECT 절 안 `expr.subquery` / `expr.exists` 박지 말 것
+
+도메인 boolean (`isCompleted`, `hasAny` 등) / 집계 (`SUM`, `COUNT`, `MAX`) 가 필요하면 `joinSingle` 안에서 `from + where + select(aggregate)` 로 묶어 outer 행에 컬럼으로 부착함. SELECT column 에 subquery / exists 박으면 outer 행마다 inner 가 N 회 실행됨.
+
+```ts
+// 나쁜 예 — 행당 subquery N회
+.select((p) => ({
+  isCompleted: expr.is(expr.exists(db.X().where(...))),
+  sumA: expr.subquery("number", db.Y().select(...)),
+}))
+
+// 좋은 예 — joinSingle 로 1회 부착, 컬럼으로 참조
+.joinSingle("state", (q, p) =>
+  q.from(X).where((x) => [expr.eq(x.fk, p.id)])
+    .select((x) => ({
+      rowCount: expr.count(),
+      completedCount: expr.count(x.completedAt),
+      sumA: expr.sum(x.amount),
+    })),
+)
+.select((p) => ({
+  isCompleted: expr.gt(p.state!.completedCount, 0),
+  sumA: expr.coalesce(p.state!.sumA, 0),
+}))
+```
+
+### 불필요한 `wrap()`
+
+`wrap()` 은 framework 가 명시 요구하는 경우에만 씀 (대표적으로 `count()` after `distinct()` / `groupBy()` 호출 같은 명시 요구).
+
+도출 컬럼 위에서 필터/정렬을 걸기 위해 wrap 을 끼우는 패턴은 불필요 — `.select(...).where((r) => [...])` 만으로 framework 가 projected ExprUnit AST 를 WHERE / ORDER BY 에 inline 함.
+
+"Layer 1 = materialize, Layer 2 = derive" 같은 다층 wrap 구조도 군더더기. 단일 select 안 로컬 `const` 로 산식 분리하면 동일 SQL 이 나옴.
+
+## 스키마 정의
+
+컬럼은 `NOT NULL` 기본. `.nullable()`/`.default(...)` 는 도메인 근거가 있을 때만 붙임.
+
+- `.nullable()`: 도메인상 값이 없을 수 있을 때만 (선택 입력, 미발생 이벤트 시각, 선택적 FK).
+- `.default(...)`: 사용자가 명시 지시한 경우에만.
+- "초기값 애매", "마이그레이션 중간 단계", "넣을 값 모름" 은 nullable/default 근거 아님. 호출자가 넣도록 강제하거나 backfill 후 `NOT NULL`로 전환.
+
+## 삭제 전략
+
+- **기초정보(마스터)**: soft delete (`isDisabled` 등). FK 참조 무결성 보존.
+- **프로세스 문서(트랜잭션)**: 물리 delete. 상세 행 포함 캐스케이드. 단, 다른 테이블이 FK로 참조 중이면 삭제 차단하고 최종 사용자에게 toast 등으로 사유 안내.

package/claude/references/sd-simplysm14/manuals/test.md

@@ -1,13 +1,13 @@
 # 테스트 작성
 
-`@simplysm/*` v14 모노레포의 패키지 테스트(`packages/<pkg>/tests/`)와 통합 테스트(`tests/<name>/`) 작성 시 따른다. Vitest project 구성·실행 명령은 루트 `CLAUDE.md` 의 "Vitest 프로젝트 구조" 참조 — 여기서는 작성 규약만 다룬다.
+`@simplysm/*` v14 모노레포의 패키지 테스트(`packages/<pkg>/tests/`)와 통합 테스트(`tests/<name>/`) 작성 시 따름. Vitest project 구성·실행 명령은 루트 `CLAUDE.md` 의 "Vitest 프로젝트 구조" 참조 — 여기서는 작성 규약만 다룸.
 
 ## 파일 규약
 
-- 위치
-  - 패키지: `packages/<pkg>/tests/**/*.spec.ts`
-  - 통합: `tests/<name>/src/**/*.spec.ts`
-- 확장자
+- 위치.
+  - 패키지: `packages/<pkg>/tests/**/*.spec.ts`.
+  - 통합: `tests/<name>/src/**/*.spec.ts`.
+- 확장자.
   - `*.spec.ts` — vitest 실행 대상.
   - `*.acc.spec.ts` — Acceptance 단위 spec. 동일 project 에서 함께 실행.
   - `*.verify.md` — LLM 수동 검증 항목. vitest 실행 대상 아님. 자동화로 잡기 어려운 검증(JSDoc 표현·문서 일관성 등)에만.
@@ -29,8 +29,8 @@
 1. `tests/<name>/package.json` — `name: "@simplysm-test/<name>"`, `"private": true`, `"type": "module"`. 필요한 `@simplysm/*` 는 `workspace:*` 로 devDependency 등재.
 2. `tests/<name>/tsconfig.json` — `extends: "../../tsconfig.json"`, `compilerOptions.typeRoots: ["./node_modules/@types"]`.
 3. `tests/<name>/src/**/*.spec.ts` — 스펙.
-4. `vitest.config.ts` `projects[]` 에 entry 추가
-   - `name: "<name>"`, `include: ["tests/<name>/**/*.spec.ts"]`
+4. `vitest.config.ts` `projects[]` 에 entry 추가.
+   - `name: "<name>"`, `include: ["tests/<name>/**/*.spec.ts"]`.
    - 외부 자원 기동 필요시 `globalSetup: "./tests/<name>/vitest.setup.ts"` + `setup`/`teardown` export.
    - 외부 자원이 단일 인스턴스 공유면 `fileParallelism: false` (스펙 파일 직렬 실행).
    - 브라우저 런타임 필요시 `browser: { provider: playwright(), enabled: true, headless: true, instances: [{ browser: "chromium", viewport: { width: 1920, height: 1080 } }] }`.
@@ -43,7 +43,7 @@
 
 - `setup({ provide })` 에서 외부 자원 기동(DB 컨테이너·테스트 서버 등). 동적 값(랜덤 포트 등)은 `provide("key", value)` 로 스펙에 전달.
 - `teardown()` 에서 정리. 실패해도 다음 실행이 망가지지 않도록 best-effort.
-- 타입 보강: 파일 상단에
+- 타입 보강: 파일 상단에.
   ```ts
   declare module "vitest" {
     export interface ProvidedContext { key: T }