@simplysm/sd-claude 14.0.50 → 14.0.52

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

@@ -0,0 +1,54 @@
+# Executable
+
+Stored Procedure 실행 래퍼 클래스. `DbContext.executable()`로 등록된 프로퍼티를 호출하면 반환된다.
+
+```typescript
+export class Executable<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
+  constructor(
+    db: DbContextBase,
+    builder: ProcedureBuilder<TParams, TReturns>,
+  );
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `execute(params)` | method | `Promise<InferColumnExprs<TReturns>[][]>` | 프로시저 실행. 결과는 결과 셋 배열의 배열 |
+| `getExecProcQueryDef(params?)` | method | `ExecProcQueryDef` | 실행 없이 QueryDef만 반환 |
+
+## Related Types
+
+### `executable` (팩토리 함수)
+
+`DbContext.executable()`이 내부적으로 사용하는 팩토리 함수.
+
+```typescript
+export function executable<
+  TParams extends ColumnBuilderRecord,
+  TReturns extends ColumnBuilderRecord,
+>(
+  db: DbContextBase,
+  builder: ProcedureBuilder<TParams, TReturns>,
+): () => Executable<TParams, TReturns>;
+```
+
+## Usage
+
+```typescript
+// 프로시저 정의
+const GetUserById = Procedure("GetUserById")
+  .database("mydb")
+  .params((c) => ({ userId: c.bigint() }))
+  .returns((c) => ({ id: c.bigint(), name: c.varchar(100) }))
+  .body("SELECT id, name FROM User WHERE id = userId");
+
+// DbContext에 등록
+class MyDb extends DbContext {
+  getUserById = this.executable(GetUserById);
+}
+
+// 실행
+const [[user]] = await db.getUserById().execute({ userId: 1n });
+```

package/claude/references/sd-simplysm-v14/orm-common/queryable-executable/parse-search-query.md

@@ -0,0 +1,75 @@
+# parseSearchQuery
+
+사용자 입력 검색 텍스트를 파싱하여 SQL LIKE 패턴으로 변환한다. `Queryable.search()`가 내부적으로 사용한다.
+
+```typescript
+export function parseSearchQuery(searchText: string): ParsedSearchQuery;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `searchText` | `string` | 검색 쿼리 문자열 |
+
+## Returns
+
+`ParsedSearchQuery` — 파싱된 검색 쿼리 객체
+
+## Related Types
+
+### `ParsedSearchQuery`
+
+```typescript
+export interface ParsedSearchQuery {
+  /** 일반 검색어 (OR 조건) - LIKE 패턴 */
+  or: string[];
+  /** 필수 검색어 (AND 조건, + 접두사 또는 따옴표) - LIKE 패턴 */
+  must: string[];
+  /** 제외 검색어 (NOT 조건, - 접두사) - LIKE 패턴 */
+  not: string[];
+}
+```
+
+## 검색 구문
+
+| 구문 | 의미 | 예시 |
+|------|------|------|
+| `term1 term2` | OR (하나 이상 일치) | `apple banana` |
+| `+term` | 필수 포함 (AND) | `+apple +banana` |
+| `-term` | 제외 (NOT) | `apple -banana` |
+| `"exact phrase"` | 정확한 구문 일치 (필수) | `"맛있는 과일"` |
+| `*` | 와일드카드 | `app*` → `app%` |
+
+## 이스케이프 시퀀스
+
+| 입력 | 의미 |
+|------|------|
+| `\\` | 리터럴 `\` |
+| `\*` | 리터럴 `*` |
+| `\%` | 리터럴 `%` |
+| `\"` | 리터럴 `"` |
+| `\+` | 리터럴 `+` |
+| `\-` | 리터럴 `-` |
+
+## Usage
+
+```typescript
+parseSearchQuery('apple "delicious fruit" -banana +strawberry')
+// {
+//   or: ["%apple%"],
+//   must: ["%delicious fruit%", "%strawberry%"],
+//   not: ["%banana%"]
+// }
+
+parseSearchQuery('app* test')
+// {
+//   or: ["app%", "%test%"],
+//   must: [],
+//   not: []
+// }
+
+// Queryable.search()와 함께 사용
+db.user()
+  .search((u) => [u.name, u.email], "John +admin -deleted")
+```

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

@@ -0,0 +1,238 @@
+# Queryable
+
+SELECT/INSERT/UPDATE/DELETE/UPSERT 체인 빌더. 메서드 체이닝으로 쿼리를 구성하고 `execute()` 계열 메서드로 실행한다. `DbContext.queryable()`로 등록된 프로퍼티를 호출하면 반환된다.
+
+```typescript
+export class Queryable<
+  TData extends DataRecord,
+  TFrom extends TableBuilder<any, any> | never,
+> {
+  constructor(readonly meta: QueryableMeta<TData>);
+}
+```
+
+`TFrom`은 CUD(INSERT/UPDATE/DELETE) 연산에 필요한 TableBuilder 타입이다. VIEW 기반이거나 `select()`로 변환된 경우 `never`가 되어 CUD 메서드를 사용할 수 없다.
+
+## Members
+
+### SELECT 옵션
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `select(fn)` | method | `Queryable<R, never>` | SELECT할 column 지정. fn이 반환한 구조로 결과 타입 변환 |
+| `distinct()` | method | `Queryable<TData, never>` | DISTINCT 중복 제거 |
+| `lock()` | method | `Queryable<TData, TFrom>` | FOR UPDATE 행 잠금 |
+
+### 범위 제한
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `top(count)` | method | `Queryable<TData, TFrom>` | 상위 N개 행만 선택 |
+| `limit(skip, take)` | method | `Queryable<TData, TFrom>` | LIMIT/OFFSET 페이지네이션. `orderBy()` 후에만 사용 가능 |
+
+### 정렬
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `orderBy(fn, direction?)` | method | `Queryable<TData, TFrom>` | 정렬 조건 추가. 여러 번 호출 시 순서대로 적용. 함수 또는 chain path 문자열 |
+
+### WHERE 조건
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `where(predicate)` | method | `Queryable<TData, TFrom>` | WHERE 조건 추가. 여러 번 호출 시 AND로 결합 |
+| `search(fn, searchText)` | method | `Queryable<TData, TFrom>` | 텍스트 검색. `parseSearchQuery` 구문 지원 |
+
+### GROUP BY / HAVING
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `groupBy(fn)` | method | `Queryable<TData, never>` | GROUP BY 절 추가 |
+| `having(predicate)` | method | `Queryable<TData, never>` | HAVING 조건 추가 |
+
+### JOIN
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `join(as, fn)` | method | `Queryable<TData & { [as]?: R[] }, TFrom>` | 1:N LEFT OUTER JOIN. 결과에 배열로 추가 |
+| `joinSingle(as, fn)` | method | `Queryable<...>` | N:1 또는 1:1 LEFT OUTER JOIN. 결과에 단일 객체로 추가 |
+| `include(fn)` | method | `Queryable<TData, TFrom>` | 테이블 관계 정의 기반 자동 JOIN. 중첩 경로 지원 (`p.user.company`) |
+
+### 서브쿼리 / UNION
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `wrap()` | method | `Queryable<TData, never>` | 현재 쿼리를 서브쿼리로 래핑. `distinct()`/`groupBy()` 후 `count()` 사용 시 필요 |
+| `static union(...queries)` | static | `Queryable<TData, never>` | 여러 Queryable을 UNION으로 결합 (중복 제거). 최소 2개 필요 |
+
+### 재귀 CTE
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `recursive(fn)` | method | `Queryable<TData, never>` | WITH RECURSIVE CTE 생성. 계층 구조 쿼리에 사용 |
+
+### SELECT 실행
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `execute()` | method | `Promise<TData[]>` | SELECT 실행, 결과 배열 반환 |
+| `single()` | method | `Promise<TData \| undefined>` | 단일 결과 반환. 2개 이상이면 에러 |
+| `first()` | method | `Promise<TData \| undefined>` | 첫 번째 결과만 반환 |
+| `count(fn?)` | method | `Promise<number>` | 행 수 반환. `distinct()`/`groupBy()` 후에는 `wrap()` 필요 |
+| `exists()` | method | `Promise<boolean>` | 조건에 일치하는 데이터 존재 여부 |
+
+### INSERT
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `insert(records)` | method | `Promise<void>` | INSERT 실행. MSSQL 1000행 제한으로 자동 청크 분할 |
+| `insert(records, outputColumns)` | method | `Promise<Pick<...>[]>` | INSERT 후 지정한 column 값 반환 |
+| `insertIfNotExists(record)` | method | `Promise<void>` | WHERE 조건에 일치하는 데이터가 없을 때만 INSERT |
+| `insertInto(targetTable)` | method | `Promise<void>` | INSERT INTO ... SELECT |
+
+### UPDATE
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `update(recordFn)` | method | `Promise<void>` | UPDATE 실행 |
+| `update(recordFn, outputColumns)` | method | `Promise<Pick<...>[]>` | UPDATE 후 지정한 column 값 반환 |
+
+### DELETE
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `delete()` | method | `Promise<void>` | DELETE 실행 |
+| `delete(outputColumns)` | method | `Promise<Pick<...>[]>` | DELETE 후 지정한 column 값 반환 |
+
+### UPSERT
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `upsert(updateFn)` | method | `Promise<void>` | WHERE 일치 시 UPDATE, 없으면 INSERT (updateFn이 두 작업에 동일 적용) |
+| `upsert(updateFn, insertFn)` | method | `Promise<void>` | UPDATE/INSERT 각각 다른 데이터로 UPSERT |
+| `upsert(updateFn, outputColumns)` | method | `Promise<Pick<...>[]>` | UPSERT 후 지정한 column 값 반환 |
+
+### QueryDef 생성기
+
+실행 없이 `QueryDef`만 반환. 테스트나 수동 실행에 사용.
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `getSelectQueryDef()` | method | `SelectQueryDef` | SELECT QueryDef 생성 |
+| `getResultMeta(outputColumns?)` | method | `ResultMeta` | SELECT 결과 변환용 메타데이터 생성 |
+| `getInsertQueryDef(records, outputColumns?)` | method | `InsertQueryDef` | INSERT QueryDef 생성 |
+| `getInsertIfNotExistsQueryDef(record)` | method | `InsertIfNotExistsQueryDef` | INSERT IF NOT EXISTS QueryDef |
+| `getInsertIntoQueryDef(targetTable)` | method | `InsertIntoQueryDef` | INSERT INTO QueryDef |
+| `getUpdateQueryDef(recordFn, outputColumns?)` | method | `UpdateQueryDef` | UPDATE QueryDef |
+| `getDeleteQueryDef(outputColumns?)` | method | `DeleteQueryDef` | DELETE QueryDef |
+| `getUpsertQueryDef(updateFn, insertFn, outputColumns?)` | method | `UpsertQueryDef` | UPSERT QueryDef |
+| `switchFk(enabled)` | method | `Promise<void>` | FK 제약조건 활성화/비활성화 |
+
+## Related Types
+
+### `queryable` (팩토리 함수)
+
+`DbContext.queryable()`이 내부적으로 사용하는 팩토리 함수. 직접 호출할 일은 드물다.
+
+```typescript
+export function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
+  db: DbContextBase,
+  tableOrView: TBuilder,
+  as?: string,
+): () => Queryable<TBuilder["$inferSelect"], ...>;
+```
+
+### `getMatchedPrimaryKeys`
+
+FK column 배열과 대상 테이블의 PK를 매칭하여 PK column 이름 배열을 반환한다.
+
+```typescript
+export function getMatchedPrimaryKeys(
+  fkCols: string[],
+  targetTable: TableBuilder<any, any>,
+): string[];
+```
+
+### `QueryableRecord<TData>`
+
+Queryable 콜백 내부에서 column을 참조할 때 사용하는 프록시 레코드 타입. 각 필드가 `ExprUnit`으로 래핑된다.
+
+```typescript
+export type QueryableRecord<TData extends DataRecord> = {
+  [K in keyof TData]: TData[K] extends ColumnPrimitive
+    ? ExprUnit<TData[K]>
+    : ...;
+};
+```
+
+### `QueryableWriteRecord<TData>`
+
+UPDATE/UPSERT에서 레코드를 작성할 때 사용하는 타입. 각 필드가 `ExprInput<T>`(ExprUnit 또는 리터럴 값)로 받는다.
+
+```typescript
+export type QueryableWriteRecord<TData> = {
+  [K in keyof TData]: TData[K] extends ColumnPrimitive ? ExprInput<TData[K]> : never;
+};
+```
+
+### `UnwrapQueryableRecord<R>`
+
+`select(fn)` 반환 타입에서 `ExprUnit<T>`를 `T`로 언래핑하여 실제 데이터 타입을 추론한다.
+
+### `PathProxy<TObject>`
+
+`include(fn)` 에서 관계 경로를 타입 안전하게 지정하기 위한 프록시 타입. `ColumnPrimitive` 필드는 접근 불가.
+
+```typescript
+export type PathProxy<TObject> = {
+  [K in keyof TObject as TObject[K] extends ColumnPrimitive ? never : K]-?: PathProxy<...>;
+};
+```
+
+## Usage
+
+```typescript
+// SELECT
+const users = await db.user()
+  .where((u) => [expr.eq(u.isActive, true), expr.gt(u.age, 18)])
+  .select((u) => ({ id: u.id, fullName: expr.concat(u.name, " (", u.email, ")") }))
+  .include((i) => i.company)
+  .orderBy((u) => u.name)
+  .limit(0, 20)
+  .execute();
+
+// INSERT
+await db.user().insert([{ name: "Alice", createdAt: DateTime.now() }]);
+
+// INSERT with output
+const [inserted] = await db.user().insert([{ name: "Bob" }], ["id"]);
+
+// UPDATE (column 참조)
+await db.product()
+  .update((p) => ({
+    price: expr.mul(p.price, expr.val("number", 1.1)),
+  }));
+
+// UPSERT
+await db.user()
+  .where((u) => [expr.eq(u.email, "test@test.com")])
+  .upsert(
+    () => ({ loginCount: expr.val("number", 1) }),
+    (update) => ({ ...update, email: expr.val("string", "test@test.com") }),
+  );
+
+// UNION
+const combined = Queryable.union(
+  db.user().where((u) => [expr.eq(u.type, "admin")]),
+  db.user().where((u) => [expr.eq(u.type, "manager")]),
+);
+
+// 재귀 CTE (계층 구조)
+const tree = await db.employee()
+  .where((e) => [expr.null(e.managerId)])
+  .recursive((cte) =>
+    cte.from(Employee)
+      .where((e) => [expr.eq(e.managerId, e.self[0].id)])
+  )
+  .execute();
+```

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/column-builder.md

@@ -0,0 +1,63 @@
+# ColumnBuilder
+
+Column 타입, nullable, autoIncrement, default, description을 정의하는 빌더. `TableBuilder.columns()` 및 `ProcedureBuilder.params()`/`returns()` 콜백에서 `createColumnFactory()`가 반환하는 팩토리 객체를 통해 생성된다.
+
+```typescript
+export class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
+  constructor(readonly meta: TMeta);
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `meta` | property | `TMeta` | Column 메타데이터 |
+| `autoIncrement()` | method | `ColumnBuilder<TValue, ...>` | AUTO_INCREMENT 설정. INSERT 타입에서 optional |
+| `nullable()` | method | `ColumnBuilder<TValue \| undefined, ...>` | NULL 허용. 값 타입에 `undefined` 추가 |
+| `default(value)` | method | `ColumnBuilder<TValue, ...>` | 기본값 설정. INSERT 타입에서 optional |
+| `description(desc)` | method | `ColumnBuilder<TValue, ...>` | Column 설명 (DDL Comment) |
+
+## Related Types
+
+### `createColumnFactory`
+
+`TableBuilder.columns()`, `ProcedureBuilder.params()`/`returns()` 콜백에서 자동으로 제공되는 팩토리.
+
+```typescript
+export function createColumnFactory(): { ... };
+```
+
+#### 지원 Column 타입
+
+| 메서드 | SQL 타입 | TypeScript 타입 | 비고 |
+|--------|----------|-----------------|------|
+| `int()` | INT | `number` | 4바이트 |
+| `bigint()` | BIGINT | `number` | 8바이트 |
+| `float()` | FLOAT | `number` | 4바이트 단정밀도 |
+| `double()` | DOUBLE | `number` | 8바이트 배정밀도 |
+| `decimal(precision, scale?)` | DECIMAL(p,s) | `number` | 고정 소수점 |
+| `varchar(length)` | VARCHAR(n) | `string` | 가변 길이 |
+| `char(length)` | CHAR(n) | `string` | 고정 길이 |
+| `text()` | TEXT/LONGTEXT | `string` | 대용량 |
+| `binary()` | LONGBLOB/VARBINARY(MAX)/BYTEA | `Bytes` | 바이너리 |
+| `boolean()` | TINYINT(1)/BIT/BOOLEAN | `boolean` | DBMS별 다름 |
+| `datetime()` | DATETIME | `DateTime` | |
+| `date()` | DATE | `DateOnly` | |
+| `time()` | TIME | `Time` | |
+| `uuid()` | BINARY(16)/UNIQUEIDENTIFIER/UUID | `Uuid` | |
+
+## Usage
+
+```typescript
+Table("User")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),          // bigint, AUTO_INCREMENT, INSERT optional
+    name: c.varchar(100),                    // varchar(100), 필수
+    email: c.varchar(200).nullable(),        // varchar(200), NULL 허용
+    status: c.varchar(20).default("active"), // varchar(20), 기본값 "active", INSERT optional
+    createdAt: c.datetime().description("생성일시"),
+    price: c.decimal(10, 2),
+    data: c.binary(),
+  }));
+```

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/foreign-key-builder.md

@@ -0,0 +1,137 @@
+# ForeignKeyBuilder
+
+FK/역참조/논리적 관계 빌더들. `TableBuilder.relations()` 및 `ViewBuilder.relations()` 콜백에서 `createRelationFactory()`가 반환하는 팩토리 객체를 통해 생성된다.
+
+**주의**: description/single 설정은 반드시 팩토리 함수의 `opts` 파라미터로 전달해야 한다. 메서드 체이닝(`.description()`, `.single()`)은 TypeScript 순환 참조(TS7022)를 유발하므로 제거되었다.
+
+## 빌더 종류
+
+| 클래스 | 관계 방향 | DB FK 생성 | 사용 가능 위치 |
+|--------|-----------|------------|----------------|
+| `ForeignKeyBuilder` | N:1 | O | Table |
+| `ForeignKeyTargetBuilder` | 1:N 또는 1:1 | O (역참조) | Table |
+| `RelationKeyBuilder` | N:1 | X | Table, View |
+| `RelationKeyTargetBuilder` | 1:N 또는 1:1 | X (역참조) | Table, View |
+
+## ForeignKeyBuilder
+
+```typescript
+export class ForeignKeyBuilder<
+  TOwner extends TableBuilder<any, any>,
+  TTargetFn extends () => TableBuilder<any, any>,
+> {
+  constructor(
+    readonly meta: {
+      ownerFn: () => TOwner;
+      columns: string[];
+      targetFn: TTargetFn;
+      description?: string;
+    },
+  );
+}
+```
+
+팩토리 시그니처:
+```typescript
+r.foreignKey(columns, targetFn, opts?: { description?: string }): ForeignKeyBuilder<...>
+```
+
+## ForeignKeyTargetBuilder
+
+```typescript
+export class ForeignKeyTargetBuilder<
+  TTargetTableFn extends () => TableBuilder<any, any>,
+  TIsSingle extends boolean,
+> {
+  constructor(
+    readonly meta: {
+      targetTableFn: TTargetTableFn;
+      relationName: string;
+      description?: string;
+      isSingle?: TIsSingle;
+    },
+  );
+}
+```
+
+팩토리 시그니처 (오버로드):
+```typescript
+// 배열 관계 (1:N)
+r.foreignKeyTarget(targetTableFn, relationName, opts?: { single?: false, description?: string }):
+  ForeignKeyTargetBuilder<..., false>
+
+// 단일 관계 (1:1)
+r.foreignKeyTarget(targetTableFn, relationName, opts: { single: true, description?: string }):
+  ForeignKeyTargetBuilder<..., true>
+```
+
+## RelationKeyBuilder
+
+`ForeignKeyBuilder`와 동일하지만 DB에 FK 제약조건을 생성하지 않는다. View에서도 사용 가능하다.
+
+팩토리 시그니처:
+```typescript
+r.relationKey(columns, targetFn, opts?: { description?: string }): RelationKeyBuilder<...>
+```
+
+## RelationKeyTargetBuilder
+
+`ForeignKeyTargetBuilder`와 동일하지만 DB에 FK를 생성하지 않는다.
+
+팩토리 시그니처 (오버로드):
+```typescript
+r.relationKeyTarget(targetTableFn, relationName, opts?: { single?: false, description?: string })
+r.relationKeyTarget(targetTableFn, relationName, opts: { single: true, description?: string })
+```
+
+## Related Types
+
+### `createRelationFactory`
+
+```typescript
+export function createRelationFactory<
+  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TColumnKey extends string,
+>(ownerFn: () => TOwner): RelationFactory;
+```
+
+TableBuilder → FK + RelationKey 모두 사용 가능.
+ViewBuilder → RelationKey만 사용 가능 (`foreignKey`/`foreignKeyTarget` 없음).
+
+## Usage
+
+```typescript
+const Post = Table("Post")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    authorId: c.bigint(),
+    title: c.varchar(200),
+  }))
+  .primaryKey("id")
+  .relations((r) => ({
+    // N:1: Post → User (DB FK 생성)
+    author: r.foreignKey(["authorId"], () => User, { description: "작성자" }),
+  }));
+
+const User = Table("User")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+  }))
+  .primaryKey("id")
+  .relations((r) => ({
+    // 1:N 역참조 (배열)
+    posts: r.foreignKeyTarget(() => Post, "author"),
+    // 1:1 역참조 (단일 객체)
+    profile: r.foreignKeyTarget(() => Profile, "user", { single: true }),
+    // 설명 포함
+    comments: r.foreignKeyTarget(() => Comment, "user", { description: "댓글목록" }),
+  }));
+
+// View에서는 relationKey만 사용
+const UserSummary = View("UserSummary")
+  .query((db: MyDb) => db.user().select(...))
+  .relations((r) => ({
+    company: r.relationKey(["companyId"], () => Company, { description: "소속회사" }),
+  }));
+```

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/index-builder.md

@@ -0,0 +1,54 @@
+# IndexBuilder
+
+Index 정의 빌더. `TableBuilder.indexes()` 콜백에서 `createIndexFactory()`가 반환하는 팩토리 객체를 통해 생성된다.
+
+```typescript
+export class IndexBuilder<TKeys extends string[]> {
+  constructor(
+    readonly meta: {
+      columns: TKeys;
+      name?: string;
+      unique?: boolean;
+      orderBy?: { [K in keyof TKeys]: "ASC" | "DESC" };
+      description?: string;
+    },
+  );
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `meta` | property | `{ columns, name?, unique?, orderBy?, description? }` | Index 메타데이터 |
+| `name(name)` | method | `IndexBuilder<TKeys>` | Index 이름 설정 |
+| `unique()` | method | `IndexBuilder<TKeys>` | UNIQUE 인덱스 설정 |
+| `orderBy(...orderBy)` | method | `IndexBuilder<TKeys>` | 각 컬럼별 정렬 순서 설정 |
+| `description(desc)` | method | `IndexBuilder<TKeys>` | Index 설명 (DDL Comment) |
+
+## Related Types
+
+### `createIndexFactory`
+
+```typescript
+export function createIndexFactory<TColumnKey extends string>(): {
+  index<TKeys extends TColumnKey[]>(...columns: [...TKeys]): IndexBuilder<TKeys>;
+};
+```
+
+## Usage
+
+```typescript
+Table("User")
+  .columns((c) => ({
+    id: c.bigint(),
+    email: c.varchar(200),
+    name: c.varchar(100),
+    createdAt: c.datetime(),
+  }))
+  .indexes((i) => [
+    i.index("email").unique(),
+    i.index("name", "createdAt").orderBy("ASC", "DESC"),
+    i.index("createdAt").name("IX_User_CreatedAt").orderBy("DESC"),
+  ]);
+```

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/procedure.md

@@ -0,0 +1,67 @@
+# Procedure
+
+Fluent API로 Stored Procedure 스키마를 정의하는 빌더 팩토리 함수.
+
+```typescript
+export function Procedure(name: string): ProcedureBuilder<never, never>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Procedure 이름 |
+
+## Returns
+
+`ProcedureBuilder<never, never>` — 빈 ProcedureBuilder 인스턴스
+
+## Related Types
+
+### `ProcedureBuilder<TParams, TReturns>`
+
+```typescript
+export class ProcedureBuilder<
+  TParams extends ColumnBuilderRecord,
+  TReturns extends ColumnBuilderRecord,
+> {
+  readonly $params!: TParams;
+  readonly $returns!: TReturns;
+}
+```
+
+#### 빌더 메서드
+
+| 메서드 | 설명 |
+|--------|------|
+| `description(desc)` | Procedure 설명 설정 (DDL Comment) |
+| `database(db)` | Database 이름 설정 |
+| `schema(schema)` | Schema 이름 설정 |
+| `params(fn)` | 입력 파라미터 정의. `fn(c) => ({ userId: c.bigint(), ... })` |
+| `returns(fn)` | 반환 컬럼 정의. `fn(c) => ({ id: c.bigint(), ... })` |
+| `body(sql)` | Procedure 본문 SQL 설정 |
+
+## Usage
+
+```typescript
+const GetUserById = Procedure("GetUserById")
+  .database("mydb")
+  .params((c) => ({
+    userId: c.bigint(),
+  }))
+  .returns((c) => ({
+    id: c.bigint(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+  }))
+  .body("SELECT id, name, email FROM User WHERE id = userId");
+  // MSSQL: .body("SELECT id, name, email FROM [User] WHERE id = @userId")
+
+// DbContext에 등록
+class MainDb extends DbContext {
+  getUserById = this.executable(GetUserById);
+}
+
+// 실행
+const [[user]] = await db.getUserById().execute({ userId: 1n });
+```