@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/excel/utilities/excel-utils.md

@@ -0,0 +1,101 @@
+# ExcelUtils
+
+Excel 유틸리티 함수 모음. 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 정적 메서드를 제공한다.
+
+## When to use
+
+- ✅ "A1" 형식 문자열과 0 기반 좌표 간 변환이 필요할 때
+- ✅ JavaScript 타임스탬프와 Excel 날짜 숫자 간 변환이 필요할 때
+- ❌ 셀 값 읽기/쓰기 시 날짜 변환은 `ExcelCell.setValue()`/`getValue()`가 자동 처리하므로 직접 호출할 필요 없음
+
+## Signature
+
+```typescript
+export class ExcelUtils {
+  // 주소 변환
+  static stringifyAddr(point: ExcelAddressPoint): string;
+  static stringifyRowAddr(r: number): string;
+  static stringifyColAddr(c: number): string;
+  static parseRowAddr(addr: string): number;
+  static parseColAddr(addr: string): number;
+  static parseCellAddr(addr: string): ExcelAddressPoint;
+  static parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint;
+  static stringifyRangeAddr(point: ExcelAddressRangePoint): string;
+
+  // 날짜/숫자 변환
+  static convertTimeTickToNumber(tick: number): number;
+  static convertNumberToTimeTick(value: number): number;
+
+  // 숫자 형식 처리
+  static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat;
+  static convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat;
+  static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `stringifyAddr` | static | `(point: ExcelAddressPoint) => string` | 셀 좌표를 "A1" 형식 문자열로 변환 |
+| `stringifyRowAddr` | static | `(r: number) => string` | 행 인덱스(0 기반)를 행 주소 문자열로 변환 |
+| `stringifyColAddr` | static | `(c: number) => string` | 열 인덱스(0 기반)를 열 주소 문자열로 변환. 범위: 0~16383 |
+| `parseRowAddr` | static | `(addr: string) => number` | 셀 주소에서 0 기반 행 인덱스 추출 |
+| `parseColAddr` | static | `(addr: string) => number` | 셀 주소에서 0 기반 열 인덱스 추출 |
+| `parseCellAddr` | static | `(addr: string) => ExcelAddressPoint` | 셀 주소를 좌표로 변환 |
+| `parseRangeAddr` | static | `(rangeAddr: string) => ExcelAddressRangePoint` | 범위 주소를 좌표로 변환 |
+| `stringifyRangeAddr` | static | `(point: ExcelAddressRangePoint) => string` | 범위 좌표를 주소 문자열로 변환. 시작=끝이면 단일 셀 주소 반환 |
+| `convertTimeTickToNumber` | static | `(tick: number) => number` | JavaScript 타임스탬프(ms)를 Excel 날짜 숫자로 변환 |
+| `convertNumberToTimeTick` | static | `(value: number) => number` | Excel 날짜 숫자를 JavaScript 타임스탬프(ms)로 변환 |
+| `convertNumFmtCodeToName` | static | `(numFmtCode: string) => ExcelNumberFormat` | 숫자 형식 코드를 형식 이름으로 변환 |
+| `convertNumFmtIdToName` | static | `(numFmtId: number) => ExcelNumberFormat` | Excel 내장 숫자 형식 ID를 형식 이름으로 변환 |
+| `convertNumFmtNameToId` | static | `(numFmtName: ExcelNumberFormat) => number` | 숫자 형식 이름을 형식 ID로 변환 |
+
+## Usage
+
+```typescript
+import { ExcelUtils } from "@simplysm/excel";
+
+// 주소 변환
+ExcelUtils.stringifyAddr({ r: 0, c: 0 });   // "A1"
+ExcelUtils.stringifyAddr({ r: 2, c: 3 });   // "D3"
+ExcelUtils.parseCellAddr("B3");             // { r: 2, c: 1 }
+ExcelUtils.parseRangeAddr("A1:C3");         // { s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }
+ExcelUtils.stringifyRangeAddr({ s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }); // "A1:C3"
+
+ExcelUtils.stringifyRowAddr(0);  // "1"
+ExcelUtils.stringifyColAddr(0);  // "A"
+ExcelUtils.stringifyColAddr(26); // "AA"
+ExcelUtils.parseRowAddr("A3");   // 2
+ExcelUtils.parseColAddr("B3");   // 1
+```
+
+## `convertNumFmtCodeToName` 변환 규칙
+
+| 형식 코드 패턴 | 반환값 |
+|----------------|--------|
+| `"General"` | `"number"` |
+| `yy`, `dd`, `mm`(날짜 문맥) 포함 + 시간(`h`, `ss`) 포함 | `"DateTime"` |
+| `yy`, `dd`, `mm`(날짜 문맥) 포함 | `"DateOnly"` |
+| `h`, `ss` 포함 | `"Time"` |
+| 숫자 패턴 (`0`, `#`, `.` 등) | `"number"` |
+
+## `convertNumFmtIdToName` 내장 형식 ID 범위
+
+| ID 범위 | 형식 |
+|---------|------|
+| 0~13, 37~40, 48 | `"number"` (숫자/일반/통화/퍼센트) |
+| 14~17, 27~31, 34~36, 50~58 | `"DateOnly"` (날짜, 로컬라이즈 포함) |
+| 22 | `"DateTime"` (날짜+시간) |
+| 18~21, 32~33, 45~47 | `"Time"` (시간) |
+| 49 | `"string"` (텍스트) |
+
+## `convertNumFmtNameToId` 매핑
+
+| 형식 이름 | ID |
+|-----------|-----|
+| `"number"` | 0 |
+| `"DateOnly"` | 14 |
+| `"DateTime"` | 22 |
+| `"Time"` | 18 |
+| `"string"` | 49 |

package/claude/references/sd-simplysm-v14/excel/wrapper/excel-wrapper.md

@@ -0,0 +1,108 @@
+# ExcelWrapper
+
+Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기 래퍼. 스키마에서 타입 정보를 추론하여 타입 안전한 읽기/쓰기를 제공한다.
+
+## When to use
+
+- ✅ 정형화된 레코드 구조의 Excel 파일을 읽기/쓰기할 때 (업로드/다운로드 시나리오)
+- ✅ Zod 스키마로 유효성 검사를 자동 수행하고 싶을 때
+- ❌ 셀 단위 세밀한 조작(병합, 이미지 삽입, 수식 등)이 필요하면 [`ExcelWorkbook`](../core-classes/excel-workbook.md) + [`ExcelWorksheet`](../core-classes/excel-worksheet.md)를 직접 사용
+
+## Signature
+
+```typescript
+export class ExcelWrapper<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  constructor(schema: TSchema);
+
+  async read(
+    file: Bytes | Blob,
+    wsNameOrIndex?: string | number,
+    options?: { excludes?: (keyof z.infer<TSchema>)[] },
+  ): Promise<z.infer<TSchema>[]>;
+
+  async write(
+    wsName: string,
+    records: Partial<z.infer<TSchema>>[],
+    options?: { excludes?: (keyof z.infer<TSchema>)[] },
+  ): Promise<ExcelWorkbook>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `constructor` | method | `(schema: TSchema) => ExcelWrapper<TSchema>` | Zod 스키마를 받아 인스턴스 생성. `.describe()`로 Excel 헤더 이름을 지정한다 |
+| `read` | method | `(file, wsNameOrIndex?, options?) => Promise<z.infer<TSchema>[]>` | Excel 파일을 레코드 배열로 읽기. 스키마 유효성 검사 수행 |
+| `write` | method | `(wsName, records, options?) => Promise<ExcelWorkbook>` | 레코드 배열을 Excel 워크북으로 변환. 반환된 워크북의 `close()`는 호출자 책임 |
+
+## Parameters
+
+### `read(file, wsNameOrIndex?, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file` | `Bytes \| Blob` | Excel 파일 데이터 |
+| `wsNameOrIndex` | `string \| number` | 워크시트 이름 또는 0 기반 인덱스 (기본값: `0`) |
+| `options.excludes` | `(keyof z.infer<TSchema>)[] \| undefined` | 읽기에서 제외할 필드 키 배열 |
+
+**타입 변환 규칙:**
+
+| 스키마 타입 | 변환 동작 |
+|------------|-----------|
+| `z.string()` | 문자열로 변환 (`String(rawValue)`) |
+| `z.number()` | 숫자로 파싱 (`num.parseFloat`) |
+| `z.boolean()` | `"1"`, `"true"` → `true`, `"0"`, `"false"` → `false` |
+| `z.optional()` / `z.nullable()` | 빈 셀을 `undefined`로 반환 |
+| `z.default(value)` | 빈 셀에 기본값 적용 |
+| `DateOnly` / `DateTime` / `Time` | `instanceof`로 직접 전달 |
+
+### `write(wsName, records, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `wsName` | `string` | 워크시트 이름 |
+| `records` | `Partial<z.infer<TSchema>>[]` | 레코드 배열 |
+| `options.excludes` | `(keyof z.infer<TSchema>)[] \| undefined` | 쓰기에서 제외할 필드 키 배열 |
+
+**쓰기 동작:**
+
+- 첫 번째 행에 헤더 자동 생성 (스키마의 `.describe()` 값 사용)
+- 모든 셀에 테두리 스타일 자동 적용
+- 필수 비boolean 필드의 헤더에 노란색 배경(`00FFFF00`) 강조
+- 확대/축소 85%, 첫 번째 행 틀 고정 자동 설정
+- 내부에서 에러 발생 시 워크북이 자동으로 `close()`됨
+
+## Usage
+
+```typescript
+import { ExcelWrapper } from "@simplysm/excel";
+import { z } from "zod";
+
+const schema = z.object({
+  name: z.string().describe("이름"),
+  age: z.number().describe("나이"),
+  email: z.string().optional().describe("이메일"),
+  active: z.boolean().default(false).describe("활성"),
+});
+
+const wrapper = new ExcelWrapper(schema);
+
+// 쓰기 (시트명, 레코드 배열)
+const wb = await wrapper.write("사람", [
+  { name: "김철수", age: 30, email: "kim@example.com" },
+  { name: "이영희", age: 28 },
+]);
+try {
+  const bytes = await wb.toBytes();
+} finally {
+  await wb.close();
+}
+
+// 읽기 (시트명 또는 인덱스, 기본값: 0)
+const records = await wrapper.read(bytes, "사람");
+// z.infer<typeof schema>[] 타입으로 반환
+
+// excludes 옵션으로 특정 필드 제외
+const filtered = await wrapper.read(bytes, 0, { excludes: ["email"] });
+```

package/claude/references/sd-simplysm-v14/lint/README.md

@@ -0,0 +1,183 @@
+# @simplysm/lint
+
+> Simplysm 모노레포 전용 ESLint 플러그인 및 공유 Flat Config 설정.
+> 커스텀 규칙 9개(`@simplysm/*`)와 TypeScript/Angular/HTML 파일별 권장 설정을 제공한다.
+> ESLint Flat Config(`eslint.config.js`) 환경에서 동작한다.
+
+## Installation
+
+```bash
+npm install @simplysm/lint
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 프로젝트에 ESLint 설정 적용 | 이 문서의 [Usage Examples](#usage-examples) |
+| 개별 규칙만 활성화 | 이 문서의 [Plugin](#plugin-simplysmlinteslint-plugin) |
+| 파일 패턴별 적용 규칙 확인 | 이 문서의 [Config 블록 구성](#config-블록-구성) |
+
+## API Overview
+
+### Plugin (`@simplysm/lint/eslint-plugin`)
+
+`{ rules: {...} }` 형태의 ESLint 플러그인 객체. 9개의 커스텀 규칙을 포함한다.
+
+#### Rules
+
+| Rule | Type | Fixable | 언제 쓰나 |
+|------|------|---------|-----------|
+| `no-hard-private` | problem | autofix | ECMAScript `#private` 필드를 금지하고 TypeScript `private _` 스타일을 강제할 때. 선언(`#field`, `#method()`, `accessor #field`)과 사용(`this.#field`) 모두 감지. 이름 충돌 시 `nameConflict` 메시지 보고 |
+| `no-subpath-imports-from-simplysm` | problem | autofix | `@simplysm/*` 패키지에서 `src` 하위 경로 import를 금지할 때. 정적 import, 동적 import, re-export 모두 감지. `@simplysm/pkg/src/...` -> `@simplysm/pkg`로 자동 수정 |
+| `ts-no-throw-not-implemented-error` | suggestion | - | `@simplysm/core-common`의 `NotImplementedError`가 프로덕션에 남아있는지 경고할 때. named/aliased/namespace import 감지. 동적 import는 미감지 |
+| `ts-no-unused-injects` | problem | autofix | 미사용 Angular `inject()` 필드를 자동 제거할 때. 클래스 내 `inject()` 호출로 초기화된 프로퍼티 중 참조되지 않는 필드를 보고 |
+| `ts-no-unused-protected-readonly` | problem | autofix | Angular `@Component` 클래스의 미사용 `protected readonly` 필드를 자동 제거할 때. 인라인 템플릿(`template` 프로퍼티)과 클래스 본문 모두에서 참조 여부를 확인. `@angular/compiler`의 `parseTemplate`으로 템플릿 AST 기반 정확 추출 |
+| `ng-no-async-effect` | problem | - | `@angular/core`의 `effect()`에 async 함수 직접 전달을 금지할 때. `await` 이후의 signal read가 의존성으로 추적되지 않는 함정을 방지. named/aliased/namespace import 모두 감지 |
+| `ng-template-no-strict-null-check` | problem | - | Angular 템플릿에서 `=== null`/`!== null`/`=== undefined`/`!== undefined` 사용을 금지하고 `== null`/`!= null`로 통일할 때. autofix 미제공(인라인 템플릿 offset 매핑 문제) |
+| `ng-template-no-todo-comments` | problem | - | HTML 템플릿 내 `<!-- TODO: ... -->` 주석을 경고할 때. raw text regex 방식으로 동작 |
+| `ng-template-sd-require-binding-attrs` | problem | autofix | `sd-*` 컴포넌트에서 허용 목록 외 plain attribute 사용을 금지하고 Angular property binding(`[attr]="..."`)을 강제할 때 |
+
+#### `ng-template-sd-require-binding-attrs` Options
+
+유일하게 사용자 옵션을 받는 규칙이다.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `selectorPrefixes` | `string[]` | `["sd-"]` | 검사 대상 엘리먼트의 태그명 접두사 목록 |
+| `allowAttributes` | `string[]` | `["id", "class", "style", "title", "tabindex", "role"]` | plain attribute로 허용할 속성명 목록 |
+| `allowAttributePrefixes` | `string[]` | `["aria-", "data-", "sd-"]` | plain attribute로 허용할 속성명 접두사 목록 |
+
+### Recommended Config (`@simplysm/lint/eslint-recommended`)
+
+`tseslint.config()`으로 생성된 `FlatConfig.Config[]` 배열. 커스텀 플러그인과 외부 플러그인(`typescript-eslint`, `angular-eslint`, `eslint-plugin-import`, `eslint-plugin-unused-imports`)을 조합한 권장 설정이다.
+
+#### Config 블록 구성
+
+| 파일 패턴 | 적용 플러그인 | 주요 규칙 |
+|-----------|-------------|-----------|
+| `**/*.js`, `**/*.mjs`, `**/*.cjs` | `@simplysm`, `import`, `unused-imports` | `no-hard-private`, `no-subpath-imports-from-simplysm`, `require-await`, `no-shadow` |
+| `**/*.ts` | `@typescript-eslint`, `@simplysm`, `import`, `unused-imports`, `angular-eslint` | 전체 커스텀 규칙 + `require-await`, `strict-boolean-expressions`, `prefer-readonly`, `only-throw-error`, `no-array-delete` 등 |
+| `**/*.html` | `@simplysm`, `@angular-eslint/template` (recommended + accessibility) | `ng-template-no-strict-null-check`, `ng-template-no-todo-comments`, `ng-template-sd-require-binding-attrs` |
+| `**/tests/**/*.ts` | - | `no-console`, `import/no-extraneous-dependencies`, `ts-no-throw-not-implemented-error` 비활성화 |
+| `**/vitest.config.ts` | - | `no-restricted-properties` 비활성화 (`process.env` 접근 허용) |
+
+#### 공유 규칙 변수
+
+| Variable | Description |
+|----------|-------------|
+| `commonRules` | `eqeqeq` (`null` 비교만 `==` 허용), `no-warning-comments`, `no-self-compare`, `array-callback-return` |
+| `noNodeBuiltinsRules` | `Buffer` 전역 사용 금지, `buffer`/`events`/`eventemitter3` import 금지 |
+| `noDirectEnvAccessRules` | `process.env` 및 `import.meta.env` 직접 접근 금지 (`env("...")` 사용 강제), `NODE_ENV` 환경변수 사용 금지, `=== undefined` / `!== undefined` 비교 금지 (`== null` / `!= null` 사용 강제) |
+| `unusedImportsRules` | 미사용 import 자동 제거 (`_` 접두사 변수 무시) |
+
+#### Ignores
+
+`**/node_modules/**`, `**/dist/**`, `**/.*/**` (dotfiles 디렉토리)를 무시한다.
+
+## Usage Examples
+
+### 최소 예제: Flat Config에서 권장 설정 사용
+
+```typescript
+// eslint.config.js
+import recommended from "@simplysm/lint/eslint-recommended";
+
+export default [
+  ...recommended,
+];
+```
+
+대부분의 경우 이것만으로 충분하다. 권장 설정에 TS/JS/HTML 파일별 규칙이 모두 포함되어 있다.
+
+### 전형 예제: 플러그인만 사용하여 개별 규칙 활성화
+
+```typescript
+// eslint.config.js
+import plugin from "@simplysm/lint/eslint-plugin";
+
+export default [
+  {
+    plugins: {
+      "@simplysm": plugin,
+    },
+    rules: {
+      // 규칙명 앞에 반드시 "@simplysm/" 네임스페이스를 붙인다
+      "@simplysm/no-hard-private": "error",
+      "@simplysm/no-subpath-imports-from-simplysm": "error",
+    },
+  },
+];
+```
+
+### 전형 예제: `ng-template-sd-require-binding-attrs` 옵션 커스터마이징
+
+```typescript
+// eslint.config.js
+import recommended from "@simplysm/lint/eslint-recommended";
+
+export default [
+  ...recommended,
+  {
+    files: ["**/*.html"],
+    rules: {
+      "@simplysm/ng-template-sd-require-binding-attrs": [
+        "error",
+        {
+          selectorPrefixes: ["sd-", "app-"],  // "app-" 접두사 컴포넌트도 검사 대상에 추가
+          allowAttributes: ["id", "class", "style", "title", "tabindex", "role", "name"],
+          allowAttributePrefixes: ["aria-", "data-", "sd-", "app-"],
+        },
+      ],
+    },
+  },
+];
+```
+
+## 🚫 Anti-patterns
+
+### effect()에서 async 콜백 사용
+
+```typescript
+// ❌ await 이후 signal read가 의존성으로 추적되지 않는다
+effect(async () => {
+  const val = this.someSignal();
+  await this.doAsync();
+});
+
+// ✅ 동기 콜백에서 signal을 읽고, 비동기 작업은 untracked 내부에서 수행
+effect(() => {
+  this.someSignal();
+  void untracked(async () => {
+    await this.doAsync();
+  });
+});
+```
+
+**근거**: `effect()` 콜백이 async면 `await` 이후의 signal read는 reactive context를 벗어나 추적되지 않으며, 반환값이 `Promise<void>`가 되어 `EffectCleanupFn` 등록도 불가능하다.
+
+### recommended 설정과 중복 규칙 선언
+
+```typescript
+// ❌ recommended에 이미 포함된 규칙을 다시 선언
+export default [
+  ...recommended,
+  {
+    rules: {
+      "@simplysm/no-hard-private": "error",  // 이미 recommended에 포함
+    },
+  },
+];
+
+// ✅ recommended만 spread하면 충분. 오버라이드가 필요한 경우에만 재선언
+export default [
+  ...recommended,
+];
+```
+
+**근거**: `eslint-recommended`에 모든 커스텀 규칙이 파일 패턴별로 이미 설정되어 있다. 중복 선언은 유지보수 부담만 증가시킨다.
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- Simplysm 모노레포 코딩 규칙(`#private` 금지, `Buffer` 금지, `process.env` 직접 접근 금지 등)을 따르지 않는 프로젝트 -- 범용 ESLint 설정이 아니므로 해당 규칙이 불필요한 프로젝트에는 적합하지 않다.
+- Angular를 사용하지 않는 프로젝트에서 `eslint-recommended`를 그대로 사용하는 경우 -- Angular 관련 플러그인/규칙이 포함되어 있으므로 불필요한 의존성이 추가된다. 플러그인만 import하여 필요한 규칙만 개별 활성화한다.

package/claude/references/sd-simplysm-v14/orm-common/README.md

@@ -0,0 +1,156 @@
+# @simplysm/orm-common
+
+DBMS 독립적인 ORM 코어 라이브러리. TypeScript Fluent API로 스키마를 정의하고, SQL AST(QueryDef)를 경유하여 MySQL/MSSQL/PostgreSQL 세 방언(dialect)의 SQL을 생성한다.
+
+## 스키마 정의 지침
+
+**CRITICAL: 컬럼은 `NOT NULL` 기본. `.nullable()`/`.default(...)` 모두 "쓰지 않는 것이 기본"이며, 도메인상 정당한 근거가 있을 때만 붙인다.**
+
+### `.nullable()` 사용 기준
+
+- 값이 없을 수 있는 근거가 **도메인 모델 자체**에 있을 때만 허용한다.
+  - 허용 예: 선택 입력 필드(회원가입 시 선택적으로 받는 전화번호), 아직 발생하지 않은 이벤트 시각(`deletedAt`, `completedAt`), 선택적 외래키(소속이 없을 수 있는 사용자의 `companyId`).
+- 아래 이유로는 절대(NEVER) nullable로 만들지 않는다:
+  - "초기값을 정하기 애매해서" → nullable도 default도 답이 아니다. 도메인상 값이 반드시 있어야 하면 INSERT 시점에 호출자가 넣도록 강제한다.
+  - "마이그레이션 중간 단계에서 값이 없을 수 있어서" → 마이그레이션 스크립트에서 backfill 후 `NOT NULL`로 전환한다.
+  - "어떤 값을 넣어야 할지 몰라서" → 사용자에게 질문한다. 추측으로 nullable 처리 금지.
+
+### `.default(...)` 사용 기준
+
+- 기본값은 **DB가 값을 결정해야 하는 경우**에만 지정한다. 애플리케이션 코드로 결정 가능한 값은 default로 넣지 않는다.
+  - 허용 예: `CURRENT_TIMESTAMP` 같이 DB 시각을 기준으로 해야 하는 경우, DB 차원에서 불변 상수로 고정되어야 하는 경우.
+  - 금지 예: "보통 0이니까 `.default(0)`", "대부분 false니까 `.default(false)`", "빈 문자열로 초기화" 등 **의미 없는 기본값으로 NOT NULL 제약을 우회하는 행위**.
+- default가 있으면 호출자가 값을 빼먹어도 insert가 성공해버려, 정작 필수값이 누락된 채 DB에 들어간다. 정합성은 호출자의 명시적 전달로 지킨다.
+
+판단이 애매하면 반드시 **사용자에게 질문**한다. nullable/default 여부는 데이터 정합성의 핵심이므로 임의 결정 금지.
+
+## 삭제 전략 지침
+
+데이터 성격에 따라 soft delete와 물리 delete를 구분하여 적용한다.
+
+### Soft Delete 권장 — 기초정보(마스터 데이터)
+
+품목, 거래처, 사용자, 부서, 창고 등 **다른 테이블에서 FK로 참조되는 기초정보**는 soft delete를 사용한다.
+- 이미 발행된 문서가 참조하고 있으므로, 물리 삭제 시 FK 무결성이 깨진다.
+- `isDisabled` 등의 컬럼으로 비활성 처리하고, 조회 시 필터링한다.
+
+### 물리 Delete 권장 — 프로세스 문서(트랜잭션 데이터)
+
+입고지시, 입고, 출고지시, 출고, 주문, 검수 등 **업무 프로세스상 생성·처리·완료되는 문서**는 물리 delete를 사용한다.
+- 문서는 생성-진행-완료의 생명주기를 가지며, 취소/삭제 시 관련 데이터(상세 행 포함)를 함께 물리 삭제한다.
+- soft delete로 남기면 삭제된 문서가 집계·조회에 혼입되는 버그 원인이 된다.
+- **FK 참조 차단**: 물리 삭제 전에 해당 레코드를 FK로 참조하는 다른 테이블의 데이터가 존재하는지 확인하고, 존재하면 삭제를 차단하며 사용자에게 안내 메시지를 출력한다 (예: "해당 입고지시를 참조하는 입고 데이터가 존재하여 삭제할 수 없습니다").
+
+## Installation
+
+```bash
+npm install @simplysm/orm-common
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 테이블/뷰 스키마 정의 | [Table](./schema-builders/table.md), [View](./schema-builders/view.md) |
+| DbContext 정의 및 연결/트랜잭션 관리 | [DbContext](./core/db-context.md) |
+| SELECT/INSERT/UPDATE/DELETE 쿼리 구성 | [Queryable](./queryable-executable/queryable.md) |
+| WHERE 조건, 집계, 문자열/날짜 표현식 작성 | [expr](./expression/expr.md) |
+| FK/관계 정의 (N:1, 1:N, 1:1) | [ForeignKeyBuilder](./schema-builders/foreign-key-builder.md) |
+| Stored Procedure 정의 및 실행 | [Procedure](./schema-builders/procedure.md), [Executable](./queryable-executable/executable.md) |
+| 사용자 검색어를 SQL LIKE 패턴으로 변환 | [parseSearchQuery](./queryable-executable/parse-search-query.md) |
+| QueryDef AST를 SQL 문자열로 변환 (테스트용) | [createQueryBuilder](./query-builder/create-query-builder.md) |
+| DB 원시 결과를 중첩 객체로 파싱 (커스텀 executor용) | [parseQueryResult](./types/parse-query-result.md) |
+
+## API Overview
+
+### Core
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`DbContext`](./core/db-context.md) | class | DB 연결/트랜잭션/DDL/초기화를 관리할 때 |
+| [`DbTransactionError`](./core/db-transaction-error.md) | class | 트랜잭션 에러를 DBMS 독립적으로 처리할 때 |
+
+### Queryable / Executable
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`Queryable`](./queryable-executable/queryable.md) | class | SELECT/INSERT/UPDATE/DELETE/UPSERT 쿼리를 체이닝으로 구성할 때 |
+| [`Executable`](./queryable-executable/executable.md) | class | Stored Procedure를 실행할 때 |
+| [`parseSearchQuery`](./queryable-executable/parse-search-query.md) | function | 사용자 검색 텍스트를 SQL LIKE 패턴으로 변환할 때 |
+
+### Expression
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`expr`](./expression/expr.md) | const | WHERE 조건, SELECT 표현식, 집계/윈도우 함수를 작성할 때 |
+| [`ExprUnit`](./expression/expr-unit.md) | class | 표현식의 타입 정보를 래핑하여 타입 안전 체인을 구성할 때 |
+
+### Schema Builders
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`Table`](./schema-builders/table.md) | function | 테이블 스키마를 정의할 때 |
+| [`View`](./schema-builders/view.md) | function | 뷰 스키마를 정의할 때 |
+| [`Procedure`](./schema-builders/procedure.md) | function | Stored Procedure 스키마를 정의할 때 |
+| [`ColumnBuilder`](./schema-builders/column-builder.md) | class | 컬럼의 타입/nullable/autoIncrement/default를 설정할 때 |
+| [`IndexBuilder`](./schema-builders/index-builder.md) | class | 인덱스를 정의할 때 |
+| [`ForeignKeyBuilder`](./schema-builders/foreign-key-builder.md) | class | FK/역참조/논리적 관계를 정의할 때 |
+
+### Models
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`_Migration`](./models/migration.md) | const | 마이그레이션 이력을 관리하는 시스템 테이블 |
+
+### Query Builder
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`createQueryBuilder`](./query-builder/create-query-builder.md) | function | QueryDef AST를 dialect별 SQL 문자열로 변환할 때 (테스트용) |
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-------------|
+| [`Dialect`](./types/dialect.md) | type | DB 방언 및 런타임 타입을 참조할 때 |
+| [`DataType`](./types/data-type.md) | type | SQL 데이터 타입 매핑을 참조할 때 |
+| [`QueryDef`](./types/query-def.md) | type | SQL AST 구조를 이해할 때 |
+| [`Expr`](./types/expr.md) | type | 표현식 AST 구조를 이해할 때 |
+| [`parseQueryResult`](./types/parse-query-result.md) | function | DB 원시 결과를 중첩 TypeScript 객체로 변환할 때 (커스텀 executor용) |
+
+## Usage Examples
+
+```typescript
+import { DbContext, Table, expr } from "@simplysm/orm-common";
+
+// 스키마 정의
+const User = Table("User")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+  }))
+  .primaryKey("id");
+
+// DbContext 정의
+class MainDb extends DbContext {
+  user = this.queryable(User);
+  migrations = [
+    { name: "001_init", up: async (db) => { await db.createTable(User); } },
+  ];
+}
+
+// 쿼리 실행
+const db = new MainDb(executor, { database: "mydb" });
+await db.connect(async () => {
+  const users = await db.user()
+    .where((u) => [expr.eq(u.name, "Alice")])
+    .orderBy((u) => u.name)
+    .execute();
+});
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 실제 DB 연결이 필요하면 `@simplysm/orm-node` (`NodeDbContextExecutor`)를 함께 사용한다. 이 패키지는 SQL AST 생성까지만 담당하고, DB 드라이버 연결은 제공하지 않는다.
+- 서비스 클라이언트에서 서버를 경유하여 DB에 접근하려면 `@simplysm/service-client`의 `SdServiceDbContextExecutor`를 사용한다.