@simplysm/sd-claude 14.0.51 → 14.0.52

package/claude/references/sd-simplysm-v14/orm-common/core/db-context.md

@@ -0,0 +1,208 @@
+# DbContext
+
+DB 연결/트랜잭션/DDL/초기화를 제공하는 추상 클래스. `queryable()`/`executable()`로 테이블/프로시저를 class 프로퍼티로 등록하며, 각 프로퍼티가 독립 직렬화되어 40+ 테이블에서도 TS7056이 발생하지 않는다.
+
+```typescript
+export abstract class DbContext implements DbContextBase {
+  status: DbContextStatus;
+  _migration: () => Queryable<...>;
+  migrations: Migration[];
+
+  constructor(
+    executor: DbContextExecutor,
+    opt: { database: string; schema?: string },
+  );
+}
+```
+
+## Members
+
+### 상태 / 메타데이터
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `status` | property | `DbContextStatus` | 현재 연결 상태 (`"ready"` \| `"connect"` \| `"transact"`) |
+| `database` | getter | `string \| undefined` | Database 이름 |
+| `schema` | getter | `string \| undefined` | Schema 이름 |
+| `migrations` | property | `Migration[]` | 마이그레이션 정의 배열. 서브클래스에서 오버라이드 |
+| `_migration` | property | `() => Queryable<...>` | 시스템 마이그레이션 테이블 쿼리어블 |
+
+### 등록 메서드
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `queryable(builder)` | method (protected) | `() => Queryable<T>` | 테이블/뷰 쿼리어블 등록. 반환값을 class 프로퍼티에 할당 |
+| `executable(builder)` | method (protected) | `() => Executable<TParams, TReturns>` | 프로시저 실행 래퍼 등록 |
+
+### 연결 관리
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connect(fn, isolationLevel?)` | method | `Promise<TResult>` | 연결 → 트랜잭션 시작 → fn → 커밋 → 종료 |
+| `connectWithoutTransaction(fn)` | method | `Promise<TResult>` | 연결 → fn → 종료. 트랜잭션 없는 DDL/읽기 작업에 사용 |
+| `transaction(fn, isolationLevel?)` | method | `Promise<TResult>` | 이미 연결된 상태에서 부분 트랜잭션 시작 |
+
+### DDL 실행 메서드
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `createTable(table)` | method | `Promise<void>` | CREATE TABLE |
+| `dropTable(table)` | method | `Promise<void>` | DROP TABLE |
+| `renameTable(table, newName)` | method | `Promise<void>` | RENAME TABLE |
+| `createView(view)` | method | `Promise<void>` | CREATE VIEW |
+| `dropView(view)` | method | `Promise<void>` | DROP VIEW |
+| `createProc(procedure)` | method | `Promise<void>` | CREATE PROCEDURE |
+| `dropProc(procedure)` | method | `Promise<void>` | DROP PROCEDURE |
+| `addColumn(table, columnName, column)` | method | `Promise<void>` | ADD COLUMN |
+| `dropColumn(table, column)` | method | `Promise<void>` | DROP COLUMN |
+| `modifyColumn(table, columnName, column)` | method | `Promise<void>` | MODIFY/ALTER COLUMN |
+| `renameColumn(table, column, newName)` | method | `Promise<void>` | RENAME COLUMN |
+| `addPrimaryKey(table, columns)` | method | `Promise<void>` | ADD PRIMARY KEY |
+| `dropPrimaryKey(table)` | method | `Promise<void>` | DROP PRIMARY KEY |
+| `addForeignKey(table, relationName, relationDef)` | method | `Promise<void>` | ADD FOREIGN KEY |
+| `addIndex(table, indexBuilder)` | method | `Promise<void>` | ADD INDEX |
+| `dropForeignKey(table, relationName)` | method | `Promise<void>` | DROP FOREIGN KEY |
+| `dropIndex(table, columns)` | method | `Promise<void>` | DROP INDEX |
+| `clearSchema(params)` | method | `Promise<void>` | 스키마 내 모든 객체 제거 |
+| `schemaExists(database, schema?)` | method | `Promise<boolean>` | 스키마 존재 여부 확인 |
+| `truncate(table)` | method | `Promise<void>` | TRUNCATE TABLE |
+| `switchFk(table, enabled)` | method | `Promise<void>` | FK 제약조건 활성화/비활성화 |
+
+### DDL QueryDef 생성기
+
+직접 실행하지 않고 `QueryDef`만 반환한다. `executeDefs()`로 수동 실행할 때 사용.
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `getCreateTableQueryDef(table)` | method | `QueryDef` | CREATE TABLE QueryDef |
+| `getCreateViewQueryDef(view)` | method | `QueryDef` | CREATE VIEW QueryDef |
+| `getCreateProcQueryDef(procedure)` | method | `QueryDef` | CREATE PROCEDURE QueryDef |
+| `getCreateObjectQueryDef(builder)` | method | `QueryDef` | Table/View/Procedure 구분 없이 CREATE QueryDef |
+| `getDropTableQueryDef(table)` | method | `QueryDef` | DROP TABLE QueryDef |
+| `getRenameTableQueryDef(table, newName)` | method | `QueryDef` | RENAME TABLE QueryDef |
+| `getDropViewQueryDef(view)` | method | `QueryDef` | DROP VIEW QueryDef |
+| `getDropProcQueryDef(procedure)` | method | `QueryDef` | DROP PROCEDURE QueryDef |
+| `getAddColumnQueryDef(table, columnName, column)` | method | `QueryDef` | ADD COLUMN QueryDef |
+| `getDropColumnQueryDef(table, column)` | method | `QueryDef` | DROP COLUMN QueryDef |
+| `getModifyColumnQueryDef(table, columnName, column)` | method | `QueryDef` | MODIFY COLUMN QueryDef |
+| `getRenameColumnQueryDef(table, column, newName)` | method | `QueryDef` | RENAME COLUMN QueryDef |
+| `getAddPrimaryKeyQueryDef(table, columns)` | method | `QueryDef` | ADD PK QueryDef |
+| `getDropPrimaryKeyQueryDef(table)` | method | `QueryDef` | DROP PK QueryDef |
+| `getAddForeignKeyQueryDef(table, relationName, relationDef)` | method | `QueryDef` | ADD FK QueryDef |
+| `getAddIndexQueryDef(table, indexBuilder)` | method | `QueryDef` | ADD INDEX QueryDef |
+| `getDropForeignKeyQueryDef(table, relationName)` | method | `QueryDef` | DROP FK QueryDef |
+| `getDropIndexQueryDef(table, columns)` | method | `QueryDef` | DROP INDEX QueryDef |
+| `getClearSchemaQueryDef(params)` | method | `QueryDef` | Clear Schema QueryDef |
+| `getSchemaExistsQueryDef(database, schema?)` | method | `QueryDef` | Schema Exists QueryDef |
+| `getTruncateQueryDef(table)` | method | `QueryDef` | TRUNCATE QueryDef |
+| `getSwitchFkQueryDef(table, enabled)` | method | `QueryDef` | Switch FK QueryDef |
+
+### 기타
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `getNextAlias()` | method | `string` | 다음 테이블 별칭 생성 (`T1`, `T2`, ...) |
+| `resetAliasCounter()` | method | `void` | 별칭 카운터 초기화 |
+| `executeDefs<T>(defs, resultMetas?)` | method | `Promise<T[][]>` | QueryDef 배열 직접 실행 |
+| `getQueryDefObjectName(tableOrView)` | method | `QueryDefObjectName` | 테이블/뷰의 QueryDef 객체명 반환 |
+| `initialize(options?)` | method | `Promise<boolean>` | Code First 초기화 + 마이그레이션 실행 |
+
+## Related Types
+
+### `DbContextBase`
+
+Queryable, Executable, ViewBuilder 내부에서 사용하는 DbContext 인터페이스.
+
+```typescript
+export interface DbContextBase {
+  status: DbContextStatus;
+  readonly database: string | undefined;
+  readonly schema: string | undefined;
+  getNextAlias(): string;
+  resetAliasCounter(): void;
+  executeDefs<T = DataRecord>(
+    defs: QueryDef[],
+    resultMetas?: (ResultMeta | undefined)[],
+  ): Promise<T[][]>;
+  getQueryDefObjectName(
+    tableOrView: TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  ): QueryDefObjectName;
+  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
+}
+```
+
+### `DbContextStatus`
+
+```typescript
+export type DbContextStatus = "ready" | "connect" | "transact";
+```
+
+| 값 | 설명 |
+|----|------|
+| `"ready"` | 연결 없음. `connect()`/`connectWithoutTransaction()` 호출 가능 |
+| `"connect"` | 연결됨. 트랜잭션 없는 상태 |
+| `"transact"` | 트랜잭션 진행 중 |
+
+### `DbContextDdlMethods`
+
+`DbContext`가 구현하는 DDL 메서드 전체 인터페이스. DDL 실행 메서드(`createTable`, `dropTable`, ...) 및 QueryDef 생성 메서드(`getCreateTableQueryDef`, ...) 모두 포함.
+
+```typescript
+export interface DbContextDdlMethods {
+  createTable(table: TableBuilder<any, any>): Promise<void>;
+  dropTable(table: QueryDefObjectName): Promise<void>;
+  // ... (DbContext의 DDL 메서드 시그니처와 동일)
+}
+```
+
+### `SD_BUILDER`
+
+`DbContext.queryable()`/`executable()`로 등록된 프로퍼티에 부착된 빌더 참조용 Symbol.
+
+```typescript
+export const SD_BUILDER: unique symbol;
+```
+
+## 연결/트랜잭션 패턴
+
+| 메서드 | 용도 |
+|--------|------|
+| `connect(fn)` | 연결 → 트랜잭션 시작 → fn → 커밋 → 종료. 일반 DML 작업에 사용 |
+| `connectWithoutTransaction(fn)` | 연결 → fn → 종료. 트랜잭션 없는 DDL/읽기 전용 작업에 사용 |
+| `transaction(fn)` | 이미 연결된 상태에서 부분 트랜잭션 시작. `connectWithoutTransaction` 내부에서 사용 |
+
+- `connect()`/`connectWithoutTransaction()`은 status가 `"ready"`가 아니면 에러를 던진다 (재진입 방지).
+- 트랜잭션 중 DDL 실행은 런타임 에러를 발생시킨다.
+- 롤백 실패 시 원래 에러의 `cause`에 롤백 에러를 첨부하여 전파한다.
+
+## Usage
+
+```typescript
+class MainDb extends DbContext {
+  user = this.queryable(User);
+  post = this.queryable(Post);
+  activeUsers = this.queryable(ActiveUsers);
+  getUserById = this.executable(GetUserById);
+
+  migrations = [{ name: "001", up: async (db) => { await db.createTable(User); } }];
+}
+
+const db = new MainDb(executor, { database: "mydb", schema: "dbo" });
+
+// 일반 DML (트랜잭션 포함)
+await db.connect(async () => {
+  const users = await db.user().execute();
+  await db.user().insert([{ name: "Alice", createdAt: DateTime.now() }]);
+});
+
+// DDL (트랜잭션 없음)
+await db.connectWithoutTransaction(async () => {
+  await db.createTable(User);
+  await db.addColumn({ name: "User" }, "phone", phoneColumn);
+});
+
+// Code First 초기화 + 마이그레이션
+await db.connectWithoutTransaction(async () => {
+  await db.initialize();
+});
+```

package/claude/references/sd-simplysm-v14/orm-common/core/db-transaction-error.md

@@ -0,0 +1,64 @@
+# DbTransactionError
+
+DBMS별 네이티브 트랜잭션 에러를 표준화된 에러 코드로 래핑하는 에러 클래스. DBMS 독립적인 에러 처리를 지원한다.
+
+```typescript
+export class DbTransactionError extends Error {
+  override readonly name = "DbTransactionError";
+
+  constructor(
+    public readonly code: DbErrorCode,
+    message: string,
+    public readonly originalError?: unknown,
+  );
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `name` | property | `"DbTransactionError"` | 에러 이름 |
+| `code` | property | `DbErrorCode` | 표준화된 에러 코드 |
+| `originalError` | property | `unknown \| undefined` | 원본 DBMS 에러 (디버깅용) |
+
+## Related Types
+
+### `DbErrorCode`
+
+트랜잭션 관련 에러 코드. DBMS별 네이티브 에러 코드를 추상화한다.
+
+```typescript
+export enum DbErrorCode {
+  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",
+  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
+  DEADLOCK = "DEADLOCK",
+  LOCK_TIMEOUT = "LOCK_TIMEOUT",
+}
+```
+
+| 값 | 설명 |
+|----|------|
+| `NO_ACTIVE_TRANSACTION` | 활성 트랜잭션 없음 (ROLLBACK 시 트랜잭션 없음) |
+| `TRANSACTION_ALREADY_STARTED` | 트랜잭션 이미 시작됨 |
+| `DEADLOCK` | 데드락 발생 |
+| `LOCK_TIMEOUT` | 잠금 타임아웃 |
+
+## Usage
+
+```typescript
+try {
+  await executor.rollbackTransaction();
+} catch (err) {
+  if (err instanceof DbTransactionError) {
+    if (err.code === DbErrorCode.NO_ACTIVE_TRANSACTION) {
+      // 이미 롤백된 경우 무시
+      return;
+    }
+    if (err.code === DbErrorCode.DEADLOCK) {
+      // 데드락 재시도 로직
+    }
+  }
+  throw err;
+}
+```

package/claude/references/sd-simplysm-v14/orm-common/expression/expr-unit.md

@@ -0,0 +1,62 @@
+# ExprUnit
+
+타입 안전 표현식 래퍼. TypeScript 제네릭으로 표현식의 반환 타입을 추적한다. `expr.*` 함수들이 반환하며, `Queryable` 콜백에서 column 참조에 사용된다.
+
+```typescript
+export class ExprUnit<TPrimitive extends ColumnPrimitive> {
+  readonly $infer!: TPrimitive;
+
+  get n(): ExprUnit<NonNullable<TPrimitive>>;
+
+  constructor(
+    readonly dataType: ColumnPrimitiveStr,
+    readonly expr: Expr,
+  );
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `$infer` | property | `TPrimitive` | 타입 추론용 마커 (런타임 미사용) |
+| `n` | getter | `ExprUnit<NonNullable<TPrimitive>>` | nullable 타입을 non-nullable로 좁힘 |
+| `dataType` | property | `ColumnPrimitiveStr` | 표현식 반환 타입 이름 |
+| `expr` | property | `Expr` | 표현식 AST |
+
+## Related Types
+
+### `WhereExprUnit`
+
+WHERE 절용 표현식 래퍼. `expr.eq()`, `expr.gt()`, `expr.like()` 등 비교/논리 연산자가 반환한다.
+
+```typescript
+export class WhereExprUnit {
+  constructor(readonly expr: WhereExpr);
+}
+```
+
+### `ExprInput<TPrimitive>`
+
+`ExprUnit` 또는 리터럴 값을 모두 받는 입력 타입. `expr.*` 함수의 파라미터에 사용된다.
+
+```typescript
+export type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```
+
+## Usage
+
+```typescript
+// ExprUnit은 주로 Queryable 콜백의 column 프록시에서 만남
+db.user().where((u) => [
+  // u.isActive 가 ExprUnit<boolean>
+  expr.eq(u.isActive, true),
+]);
+
+// ExprInput 덕분에 리터럴 값도 직접 전달 가능
+expr.eq(u.age, 18)         // ExprInput<number> → 18 (리터럴)
+expr.eq(u.age, u.minAge)   // ExprInput<number> → ExprUnit<number>
+
+// .n 으로 nullable 제거 후 연산
+const nonNullName: ExprUnit<string> = u.name.n;
+```

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

@@ -0,0 +1,198 @@
+# expr
+
+Dialect 독립적 SQL 표현식 빌더 네임스페이스. SQL 문자열 대신 JSON AST(`Expr`)를 생성하며, `QueryBuilder`가 각 DBMS(MySQL, MSSQL, PostgreSQL)로 변환한다.
+
+```typescript
+export const expr: { ... };
+```
+
+## 값 생성
+
+| 함수 | 시그니처 | 설명 |
+|------|----------|------|
+| `val(dataType, value)` | `(TStr, T) => ExprUnit<T>` | 리터럴 값을 ExprUnit으로 래핑 |
+| `col(dataType, ...path)` | `(ColumnPrimitiveStr, ...string[]) => ExprUnit<...>` | Column 참조 생성 (내부 사용) |
+| `raw(dataType)` | `(TStr) => (strings, ...values) => ExprUnit<...>` | Raw SQL 태그드 템플릿. 보간 값은 자동 파라미터화 |
+| `toExpr(value)` | `(ExprInput<T>) => Expr` | ExprInput을 Expr AST로 변환 (내부/커스텀 빌더용) |
+
+## WHERE 조건 — 비교
+
+| 함수 | 설명 |
+|------|------|
+| `eq(source, target)` | `=` (NULL 안전 비교. MySQL: `<=>`, MSSQL/PG: `IS NULL OR =`) |
+| `gt(source, target)` | `>` 초과 |
+| `lt(source, target)` | `<` 미만 |
+| `gte(source, target)` | `>=` 이상 |
+| `lte(source, target)` | `<=` 이하 |
+| `between(source, from?, to?)` | `BETWEEN`. `from`/`to` undefined 시 해당 방향 제한 없음 |
+
+## WHERE 조건 — NULL 검사
+
+| 함수 | 설명 |
+|------|------|
+| `null(source)` | `IS NULL` |
+
+## WHERE 조건 — 문자열 검색
+
+| 함수 | 설명 |
+|------|------|
+| `like(source, pattern)` | `LIKE` 패턴 매칭 (`%` `_` 와일드카드) |
+| `regexp(source, pattern)` | 정규식 매칭 (DBMS별 구문 차이 있음) |
+
+## WHERE 조건 — IN
+
+| 함수 | 설명 |
+|------|------|
+| `in(source, values)` | `IN (...)` 값 목록 비교 |
+| `inQuery(source, query)` | `IN (SELECT ...)` 서브쿼리 비교. 쿼리는 단일 column SELECT 필요 |
+| `exists(query)` | `EXISTS (SELECT ...)` |
+
+## WHERE 조건 — 논리 연산자
+
+| 함수 | 설명 |
+|------|------|
+| `not(condition)` | `NOT` |
+| `and(conditions)` | `AND` 결합. 빈 배열 허용 안 함 |
+| `or(conditions)` | `OR` 결합. 빈 배열 허용 안 함 |
+
+## SELECT — 문자열
+
+| 함수 | 설명 |
+|------|------|
+| `concat(...args)` | `CONCAT(...)` — NULL은 빈 문자열 처리 |
+| `left(source, length)` | `LEFT(source, n)` |
+| `right(source, length)` | `RIGHT(source, n)` |
+| `trim(source)` | `TRIM(source)` |
+| `padStart(source, length, fillString)` | `LPAD(source, n, fill)` |
+| `replace(source, from, to)` | `REPLACE(source, from, to)` |
+| `upper(source)` | `UPPER(source)` |
+| `lower(source)` | `LOWER(source)` |
+| `length(source)` | `CHAR_LENGTH(source)` — 문자 수 |
+| `byteLength(source)` | `OCTET_LENGTH(source)` — 바이트 수 |
+| `substring(source, start, length?)` | `SUBSTRING(source, start, len)` — 1부터 시작 |
+| `indexOf(source, search)` | `LOCATE/CHARINDEX` — 1부터 시작, 없으면 0 |
+
+## SELECT — 숫자
+
+| 함수 | 설명 |
+|------|------|
+| `abs(source)` | `ABS(source)` |
+| `round(source, digits)` | `ROUND(source, n)` |
+| `ceil(source)` | `CEILING(source)` |
+| `floor(source)` | `FLOOR(source)` |
+| `add(source, target)` | `source + target` |
+| `sub(source, target)` | `source - target` |
+| `mul(source, target)` | `source * target` |
+| `div(source, target)` | `source / target` |
+| `mod(source, target)` | `source % target` |
+
+## SELECT — 날짜
+
+| 함수 | 설명 |
+|------|------|
+| `year(source)` | `YEAR(source)` |
+| `month(source)` | `MONTH(source)` (1~12) |
+| `day(source)` | `DAY(source)` (1~31) |
+| `hour(source)` | `HOUR(source)` (0~23) |
+| `minute(source)` | `MINUTE(source)` (0~59) |
+| `second(source)` | `SECOND(source)` (0~59) |
+| `dateDiff(unit, from, to)` | `DATEDIFF(unit, from, to)` — 두 날짜 차이 |
+| `dateAdd(unit, source, amount)` | `DATEADD(unit, n, source)` — 날짜 더하기 |
+
+## SELECT — 집계 함수
+
+| 함수 | 설명 |
+|------|------|
+| `count(source?)` | `COUNT(source)` 또는 `COUNT(*)` |
+| `sum(source)` | `SUM(source)` |
+| `avg(source)` | `AVG(source)` |
+| `max(source)` | `MAX(source)` |
+| `min(source)` | `MIN(source)` |
+
+## SELECT — 윈도우 함수
+
+| 함수 | 설명 |
+|------|------|
+| `rowNumber(winSpec)` | `ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...)` |
+| `rank(winSpec)` | `RANK() OVER (...)` |
+| `denseRank(winSpec)` | `DENSE_RANK() OVER (...)` |
+| `lag(source, offset?, def?, winSpec?)` | `LAG(source, offset, default) OVER (...)` |
+| `lead(source, offset?, def?, winSpec?)` | `LEAD(source, offset, default) OVER (...)` |
+| `sumOver(source, winSpec)` | `SUM(source) OVER (...)` |
+| `countOver(source, winSpec)` | `COUNT(source) OVER (...)` |
+| `avgOver(source, winSpec)` | `AVG(source) OVER (...)` |
+| `maxOver(source, winSpec)` | `MAX(source) OVER (...)` |
+| `minOver(source, winSpec)` | `MIN(source) OVER (...)` |
+| `firstValue(source, winSpec)` | `FIRST_VALUE(source) OVER (...)` |
+| `lastValue(source, winSpec)` | `LAST_VALUE(source) OVER (...)` |
+| `ntile(n, winSpec)` | `NTILE(n) OVER (...)` |
+
+## SELECT — 서브쿼리
+
+| 함수 | 설명 |
+|------|------|
+| `subquery(dataType, query, fn?)` | 서브쿼리를 SELECT 표현식으로 사용. 단일 값 반환 |
+
+## SELECT — 조건부 표현식
+
+| 함수 | 설명 |
+|------|------|
+| `if(condition, then, else_)` | `IF(cond, then, else)` |
+| `switch()` | `CASE WHEN` 체이닝. `.case(cond, then).default(val)` |
+| `coalesce(...args)` | `COALESCE(...)` — 첫 번째 non-NULL 값 반환 |
+| `nullIf(source, target)` | `NULLIF(source, target)` — 같으면 NULL |
+
+## SELECT — 타입 변환
+
+| 함수 | 설명 |
+|------|------|
+| `cast(source, dataType)` | `CAST(source AS type)` |
+| `toDateOnly(source)` | DateTime → DateOnly 변환 |
+| `toDateTime(source)` | DateOnly → DateTime 변환 |
+
+## Related Types
+
+### `SwitchExprBuilder<TPrimitive>`
+
+`expr.switch()`의 체이닝 빌더 인터페이스.
+
+```typescript
+export interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
+  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
+  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
+}
+```
+
+## Usage
+
+```typescript
+import { expr } from "@simplysm/orm-common";
+
+// 비교/논리
+expr.eq(u.status, "active")
+expr.between(u.age, 18, 65)
+expr.and([expr.eq(u.isActive, true), expr.gt(u.age, 18)])
+
+// 집계/윈도우
+expr.sum(o.amount)
+expr.rowNumber({ partitionBy: [u.companyId], orderBy: [[u.createdAt, "DESC"]] })
+
+// 문자열
+expr.concat(u.firstName, " ", u.lastName)
+expr.padStart(expr.cast(o.id, { type: "varchar", length: 10 }), 8, "0")
+
+// 날짜
+expr.dateDiff("year", u.birthDate, expr.val("DateOnly", DateOnly.today()))
+
+// CASE WHEN
+const label = expr.switch<string>()
+  .case(expr.eq(u.status, "active"), "활성")
+  .case(expr.eq(u.status, "inactive"), "비활성")
+  .default("알 수 없음");
+
+// 서브쿼리
+expr.subquery("number", db.post().where((p) => [expr.eq(p.authorId, u.id)]))
+
+// Raw SQL (이스케이프 해치)
+expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`
+```

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

@@ -0,0 +1,37 @@
+# _Migration
+
+시스템 마이그레이션 테이블 정의. `DbContext`가 내부적으로 사용하며, `initialize()`가 실행된 마이그레이션 이름을 이 테이블에 기록한다.
+
+```typescript
+export const _Migration: TableBuilder<
+  { code: ColumnBuilder<string, { type: "string"; dataType: { type: "varchar"; length: 255 } }> },
+  never
+>;
+```
+
+내부 정의:
+```typescript
+export const _Migration = Table("_migration")
+  .columns((c) => ({
+    code: c.varchar(255),
+  }))
+  .description("시스템 마이그레이션 테이블")
+  .primaryKey("code");
+```
+
+## 컬럼
+
+| 컬럼 | 타입 | 설명 |
+|------|------|------|
+| `code` | `varchar(255)` (PK) | 실행된 마이그레이션 이름 |
+
+## Usage
+
+`DbContext`에서 `this._migration`으로 접근 가능하나, 일반적으로 직접 조작하지 않고 `initialize()`를 통해 자동 관리한다.
+
+```typescript
+// initialize()가 내부적으로 사용
+await db.connectWithoutTransaction(async () => {
+  await db.initialize(); // _migration 테이블 생성 + 미실행 마이그레이션 순차 실행
+});
+```

package/claude/references/sd-simplysm-v14/orm-common/query-builder/create-query-builder.md

@@ -0,0 +1,80 @@
+# createQueryBuilder
+
+주어진 Dialect에 맞는 QueryBuilder 인스턴스를 생성한다. `Queryable.execute()` 내부에서 자동 호출되며, 직접 호출은 테스트 목적에만 사용한다.
+
+```typescript
+export function createQueryBuilder(dialect: Dialect): QueryBuilderBase;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `dialect` | `Dialect` | `"mysql"` \| `"mssql"` \| `"postgresql"` |
+
+## Returns
+
+`QueryBuilderBase` — 해당 dialect의 QueryBuilder 구현체
+
+## Related Types
+
+### `QueryBuilderBase`
+
+QueryDef → SQL 문자열 변환 추상 기본 클래스. 모든 dialect에서 100% 동일한 dispatch 로직만 구현하고, dialect별 차이는 abstract 메서드로 위임한다.
+
+```typescript
+export abstract class QueryBuilderBase {
+  protected abstract expr: ExprRendererBase;
+
+  build(def: QueryDef): QueryBuildResult;
+
+  // DML
+  protected select(def: SelectQueryDef): QueryBuildResult;
+  protected insert(def: InsertQueryDef): QueryBuildResult;
+  protected update(def: UpdateQueryDef): QueryBuildResult;
+  protected delete(def: DeleteQueryDef): QueryBuildResult;
+  protected upsert(def: UpsertQueryDef): QueryBuildResult;
+  // ... 기타 DDL 메서드들
+}
+```
+
+### `ExprRendererBase`
+
+Expr AST → SQL 표현식 문자열 변환 추상 기본 클래스.
+
+```typescript
+export abstract class ExprRendererBase {
+  render(expr: Expr): string;
+  renderWhere(expr: WhereExpr): string;
+  // ... dialect별 abstract 메서드들
+}
+```
+
+### Dialect별 구현체
+
+| 클래스 | 설명 |
+|--------|------|
+| `MysqlQueryBuilder` | MySQL 8.0.14+ 구현체 |
+| `MysqlExprRenderer` | MySQL 표현식 렌더러 |
+| `MssqlQueryBuilder` | MSSQL 2012+ 구현체 |
+| `MssqlExprRenderer` | MSSQL 표현식 렌더러 |
+| `PostgresqlQueryBuilder` | PostgreSQL 9.0+ 구현체 |
+| `PostgresqlExprRenderer` | PostgreSQL 표현식 렌더러 |
+
+## Usage
+
+```typescript
+// 일반적으로 직접 호출하지 않음 — Queryable.execute()가 내부적으로 처리
+
+// 테스트에서 SQL 생성 검증 시 직접 사용
+const builder = createQueryBuilder("mysql");  // | "mssql" | "postgresql"
+const { sql } = builder.build(queryDef);
+expect(sql).toBe("SELECT ...");
+
+// dialect별 테스트
+const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
+it.each(dialects)("[%s] SQL 검증", (dialect) => {
+  const { sql } = createQueryBuilder(dialect).build(queryDef);
+  expect(sql).toBe(expected[dialect]);
+});
+```