# playground-server 리라이트 계획: SQLite 기반 전체 DB 영속화

## 배경

현재 playground-server는 완전히 stateless(DB 없음, 메모리 전용). hackathon-server의 영속화 기능을 SQLite 기반 로컬/개인용으로 재구현해야 함. 인증 불필요. 벤더 관리(암호화된 API 키 포함) 필수. 각 세션이 어떤 벤더로 진행되었는지 추적 필수.

---

## 1. 새 인터페이스 타입 (`packages/interface/src/playground/`)

### `IAutoBePlaygroundStoredVendor.ts` (신규)
```typescript
export interface IAutoBePlaygroundStoredVendor {
  id: string;            // UUID
  name: string;          // 사람이 읽을 수 있는 라벨 ("My OpenAI", "로컬 Ollama")
  model: string;         // "gpt-4.1", "claude-3-sonnet" 등
  baseURL: string | null;
  semaphore: number;     // 기본값 16
  created_at: string;    // ISO datetime
}
export namespace IAutoBePlaygroundStoredVendor {
  export interface ICreate {
    name: string;
    model: string;
    apiKey: string;       // 평문으로 보내면 서버가 암호화하여 저장
    baseURL?: string | null;
    semaphore?: number;
  }
  export interface IUpdate {
    name?: string;
    model?: string;
    apiKey?: string;      // 선택사항, 제공 시 재암호화
    baseURL?: string | null;
    semaphore?: number;
  }
}
```

### `IAutoBePlaygroundSession.ts` (신규)
`IAutoBeHackathonSession`을 기반으로 하되 participant/hackathon 제거:
```typescript
export interface IAutoBePlaygroundSession extends IAutoBePlaygroundSession.ISummary {
  histories: AutoBeHistory[];
  event_snapshots: AutoBeEventSnapshot[];
}
export namespace IAutoBePlaygroundSession {
  export interface ISummary {
    id: string;
    vendor: IAutoBePlaygroundStoredVendor;  // 사용된 벤더 설정
    title: string | null;
    locale: string;
    timezone: string;
    phase: AutoBePhase | null;
    token_usage: IAutoBeTokenUsageJson;
    created_at: string;   // ISO datetime
    completed_at: string | null;
  }
  export interface ICreate {
    vendor_id: string;    // 저장된 벤더 참조
    locale: string;
    timezone: string;
    title?: string | null;
  }
  export interface IUpdate {
    title: string | null;
  }
}
```

`packages/interface/src/playground/index.ts`에서 export 추가.

---

## 2. Prisma 스키마 (`apps/playground-server/prisma/schema/main.prisma`)

```prisma
datasource db {
  provider = "sqlite"
  url      = env("PLAYGROUND_DATABASE_URL")
}

generator client {
  provider     = "prisma-client"
  output       = "../../src/prisma"
  moduleFormat = "cjs"
}

model autobe_playground_vendors {
  id                String    @id
  name              String
  model             String
  encrypted_api_key String    // AES-256-GCM 암호화
  base_url          String?
  semaphore         Int       @default(16)
  created_at        DateTime
  deleted_at        DateTime?

  sessions autobe_playground_sessions[]
  @@index([created_at])
}

model autobe_playground_sessions {
  id                          String    @id
  autobe_playground_vendor_id String
  locale                      String
  timezone                    String
  title                       String?
  created_at                  DateTime
  completed_at                DateTime?
  deleted_at                  DateTime?

  vendor      autobe_playground_vendors              @relation(fields: [autobe_playground_vendor_id], references: [id])
  connections autobe_playground_session_connections[]
  histories   autobe_playground_session_histories[]
  events      autobe_playground_session_events[]
  aggregate   autobe_playground_session_aggregates?

  @@index([autobe_playground_vendor_id, created_at])
}

model autobe_playground_session_connections {
  id                           String    @id
  autobe_playground_session_id String
  created_at                   DateTime
  disconnected_at              DateTime?

  session    autobe_playground_sessions              @relation(fields: [autobe_playground_session_id], references: [id], onDelete: Cascade)
  histories  autobe_playground_session_histories[]
  events     autobe_playground_session_events[]

  @@index([autobe_playground_session_id, created_at])
}

model autobe_playground_session_histories {
  id                                      String   @id
  autobe_playground_session_id            String
  autobe_playground_session_connection_id String
  type                                    String
  data                                    String   // JSON
  created_at                              DateTime

  session    autobe_playground_sessions             @relation(fields: [autobe_playground_session_id], references: [id], onDelete: Cascade)
  connection autobe_playground_session_connections   @relation(fields: [autobe_playground_session_connection_id], references: [id], onDelete: Cascade)

  @@index([autobe_playground_session_id, created_at])
  @@index([autobe_playground_session_connection_id, created_at])
}

model autobe_playground_session_events {
  id                                      String   @id
  autobe_playground_session_id            String
  autobe_playground_session_connection_id String
  type                                    String
  data                                    String   // JSON
  created_at                              DateTime

  session    autobe_playground_sessions             @relation(fields: [autobe_playground_session_id], references: [id], onDelete: Cascade)
  connection autobe_playground_session_connections   @relation(fields: [autobe_playground_session_connection_id], references: [id], onDelete: Cascade)

  @@index([autobe_playground_session_id, created_at])
  @@index([autobe_playground_session_connection_id, created_at])
}

model autobe_playground_session_aggregates {
  id                           String  @id
  autobe_playground_session_id String  @unique
  phase                        String?
  enabled                      Boolean
  token_usage                  String  // JSON

  session autobe_playground_sessions @relation(fields: [autobe_playground_session_id], references: [id], onDelete: Cascade)
}
```

---

## 3. 소스 파일 구조 (`apps/playground-server/src/`)

### 핵심 인프라

| 파일 | 기반 | 용도 |
|------|------|------|
| `AutoBePlaygroundConfiguration.ts` | `AutoBeHackathonConfiguration.ts` | 환경설정 (포트, 컴파일러 수, 암호화 키, DB URL) |
| `AutoBePlaygroundGlobal.ts` | `AutoBeHackathonGlobal.ts` | Prisma 싱글톤 (SQLite, 어댑터 불필요) |
| `AutoBePlaygroundModule.ts` | 재작성 | 새 컨트롤러 등록 |
| `AutoBePlaygroundServer.ts` | 재작성 | 설정에서 포트 읽기 |

### 컨트롤러

| 파일 | 기반 | 용도 |
|------|------|------|
| `controllers/HealthCheckController.ts` | 기존 유지 | 헬스체크 |
| `controllers/AutoBePlaygroundVendorController.ts` | 신규 | 벤더 CRUD REST API |
| `controllers/AutoBePlaygroundSessionController.ts` | 해커톤 참가자 세션 컨트롤러 | 세션 CRUD REST API (인증 데코레이터 없음) |
| `controllers/AutoBePlaygroundSessionSocketController.ts` | 해커톤 참가자 세션 소켓 컨트롤러 | WS connect/replay |

### 프로바이더

| 파일 | 기반 | 용도 |
|------|------|------|
| `providers/AutoBePlaygroundVendorProvider.ts` | 신규 | 벤더 CRUD + API 키 암호화/복호화 |
| `providers/sessions/AutoBePlaygroundSessionProvider.ts` | `AutoBeHackathonSessionProvider.ts` | 세션 CRUD (hackathon/participant 없음, 모델 제한 없음) |
| `providers/sessions/AutoBePlaygroundSessionConnectionProvider.ts` | `AutoBeHackathonSessionConnectionProvider.ts` | 연결 추적 |
| `providers/sessions/AutoBePlaygroundSessionEventProvider.ts` | `AutoBeHackathonSessionEventProvider.ts` | 이벤트 영속화 |
| `providers/sessions/AutoBePlaygroundSessionHistoryProvider.ts` | `AutoBeHackathonSessionHistoryProvider.ts` | 히스토리 영속화 |
| `providers/sessions/AutoBePlaygroundSessionSocketProvider.ts` | `AutoBeHackathonSessionSocketProvider.ts` | WS 오케스트레이션 (인증 없이 세션만 조회) |
| `providers/sessions/acceptors/AutoBePlaygroundSessionSocketAcceptor.ts` | `AutoBeHackathonSessionSocketAcceptor.ts` | 핵심 WS 로직 (connect, replay) |
| `providers/sessions/acceptors/AutoBePlaygroundSessionCompiler.ts` | `AutoBeHackathonSessionCompiler.ts` | 컴파일러 워커 풀 |

### 유틸리티

| 파일 | 기반 | 용도 |
|------|------|------|
| `utils/PaginationUtil.ts` | 해커톤에서 복사 | 페이지네이션 유틸 |
| `utils/CryptoUtil.ts` | 신규 | AES-256-GCM API 키 암호화/복호화 |
| `structures/IEntity.ts` | 해커톤에서 복사 | `{ id: string }` 베이스 인터페이스 |

### 실행파일

| 파일 | 기반 | 용도 |
|------|------|------|
| `executable/server.ts` | 재작성 | 설정 사용 |
| `executable/compiler.ts` | 기존 유지 | 컴파일러 워커 |
| `executable/schema.ts` | 신규 | SQLite 마이그레이션 셋업 |

---

## 4. 삭제할 파일

- `src/controllers/AutoBePlaygroundController.ts` → 세션 소켓 컨트롤러로 대체
- `src/controllers/AutoBePlaygroundReplayController.ts` → 세션 소켓 replay로 대체
- `src/providers/AutoBePlaygroundProvider.ts` → 세션 프로바이더들로 대체
- `src/providers/AutoBePlaygroundAcceptor.ts` → acceptor로 대체
- `src/providers/AutoBePlaygroundReplayProvider.ts` → DB 기반 replay로 대체

---

## 5. REST API 엔드포인트

### 벤더 CRUD (`/autobe/playground/vendors`)
| 메서드 | 경로 | Body | 응답 | 용도 |
|--------|------|------|------|------|
| `POST` | `/` | `ICreate` | `IAutoBePlaygroundStoredVendor` | 벤더 생성 |
| `PATCH` | `/` | `IPage.IRequest` | `IPage<IAutoBePlaygroundStoredVendor>` | 벤더 목록 (페이지네이션) |
| `GET` | `/:id` | - | `IAutoBePlaygroundStoredVendor` | 벤더 조회 |
| `PUT` | `/:id` | `IUpdate` | - | 벤더 수정 |
| `DELETE` | `/:id` | - | - | 소프트 삭제 |

**주의**: API 키는 응답에 **절대 포함되지 않음**.

### 세션 CRUD (`/autobe/playground/sessions`)
| 메서드 | 경로 | Body | 응답 | 용도 |
|--------|------|------|------|------|
| `POST` | `/` | `ICreate` | `IAutoBePlaygroundSession` | 세션 생성 |
| `PATCH` | `/` | `IPage.IRequest` | `IPage<ISummary>` | 세션 목록 |
| `GET` | `/:id` | - | `IAutoBePlaygroundSession` | 세션 상세 조회 |
| `PUT` | `/:id` | `IUpdate` | - | 제목 수정 |
| `DELETE` | `/:id` | - | - | 소프트 삭제 |

### 세션 WebSocket (`/autobe/playground/sessions`)
| 메서드 | 경로 | Header | 용도 |
|--------|------|--------|------|
| `WS` | `/:id/connect` | (없음) | 라이브 에이전트 세션 |
| `WS` | `/:id/replay` | (없음) | 세션 이벤트 재생 |

---

## 6. API 키 암호화 (`utils/CryptoUtil.ts`)

Node.js 내장 `crypto` 모듈, AES-256-GCM 사용:
```typescript
export namespace CryptoUtil {
  // 키 출처: 환경변수 PLAYGROUND_ENCRYPTION_KEY (32바이트 hex)
  export const encrypt = (plaintext: string): string => { ... }
  export const decrypt = (ciphertext: string): string => { ... }
}
```
- `iv:authTag:ciphertext` 형식으로 저장 (모두 base64)
- `PLAYGROUND_ENCRYPTION_KEY` 환경변수에서 키 로드

---

## 7. 환경설정 (`AutoBePlaygroundConfiguration.ts`)

```typescript
interface IEnvironments {
  PLAYGROUND_API_PORT: `${number}`;           // 기본값 5890
  PLAYGROUND_COMPILERS: `${number}`;          // 컴파일러 워커 풀 크기
  PLAYGROUND_TIMEOUT?: `${number}` | "NULL";
  PLAYGROUND_DATABASE_URL: string;            // "file:./autobe-playground.db"
  PLAYGROUND_ENCRYPTION_KEY: string;          // AES-256용 32바이트 hex 키
}
```

---

## 8. WebSocket 흐름 (connect)

1. 클라이언트가 REST `POST /autobe/playground/sessions`로 세션 생성 (vendor_id 참조)
2. 클라이언트가 WS `/autobe/playground/sessions/:id/connect`로 접속
3. 서버가 세션 + 벤더 조회 (API 키 복호화)
4. connection 레코드 생성
5. 히스토리가 있으면 → 과거 이벤트 재생, 새 이벤트 폴링 (2.5초 간격)
6. 복호화된 벤더 설정으로 AutoBeAgent 생성
7. 이벤트 리스너 등록 → DB 영속화
8. RPC 연결 수락
9. 대화 완료 시 → 히스토리 저장, enabled=true 설정

---

## 9. 추가할 의존성 (`package.json`)

```json
"uuid": "...",
"dotenv": "...",
"dotenv-expand": "...",
"@nestia/e2e": "..."    // ArrayUtil, RandomGenerator용
```

Prisma는 SQLite 네이티브 프로바이더 사용 (별도 어댑터 불필요).

---

## 10. 구현 순서

1. **인터페이스 타입** — `IAutoBePlaygroundStoredVendor`, `IAutoBePlaygroundSession` (`packages/interface/src/playground/`)
2. **Prisma 스키마** — `apps/playground-server/prisma/schema/main.prisma`
3. **인프라** — Configuration, Global, CryptoUtil, PaginationUtil, IEntity
4. **벤더 프로바이더 + 컨트롤러** — 암호화 포함 CRUD
5. **세션 프로바이더 + 컨트롤러** — REST CRUD
6. **세션 하위 프로바이더** — Connection, Event, History 프로바이더
7. **소켓 acceptor + 컴파일러** — 핵심 WS 로직
8. **소켓 프로바이더 + 컨트롤러** — WS 오케스트레이션
9. **Module + Server 재작성** — 전부 와이어링
10. **기존 파일 삭제** — 대체된 컨트롤러/프로바이더 제거
11. **실행파일** — server.ts, schema.ts 업데이트

---

## 11. 설계 결정 사항

- **벤더 삭제**: Soft delete만 사용 (벤더, 세션 모두). Cascade도 Restrict도 아님. 일관된 패턴.
- **Simulate**: 제외. `connect`와 `replay` WS 엔드포인트만. 개인용이니 심플하게.
- **Report**: 제외. 개인 playground에 불필요.
- **Review 시스템**: 제외. `review_article_url`, `completed_at` 로직 없음.

---

## 12. hackathon-server와 주요 차이점

| 항목 | hackathon-server | playground-server |
|------|-----------------|-------------------|
| DB | PostgreSQL + `@prisma/adapter-pg` | SQLite (Prisma 네이티브) |
| 인증 | JWT + bcrypt | 없음 |
| Hackathon/Participant | 모든 쿼리에 필수 | 완전 제거 |
| 벤더 | 환경변수에 하드코딩 (OPENAI_API_KEY 등) | DB 저장 + 암호화된 키 |
| 모델 제한 | 모델별 10/3/1 제한 | 없음 |
| Review 시스템 | review_article_url + completed_at | 제거 |
| Simulate | 벤치마크에서 MockAgent | 제거 (심플하게) |
| 시딩 | CSV 참가자 + 예제 세션 | 불필요 |
| 리포트 | 마크다운 리포트 생성기 | 제거 |
| 세션 locale | "en-US" 하드코딩 | 세션별 저장 |

---

## 13. 검증

1. `pnpm run build` — TypeScript 컴파일 통과
2. `.env` 생성: `PLAYGROUND_DATABASE_URL`, `PLAYGROUND_ENCRYPTION_KEY`, `PLAYGROUND_API_PORT`, `PLAYGROUND_COMPILERS`
3. `ts-node src/executable/schema.ts` 실행 → SQLite DB 생성 + 마이그레이션
4. 서버 시작: `ts-node src/executable/server.ts`
5. REST로 벤더 CRUD 테스트
6. REST로 세션 생성 테스트
7. tgrid 클라이언트로 WebSocket connect 테스트
8. SQLite에 이벤트/히스토리 영속화 확인
9. replay WS 테스트
10. `nestia sdk` 실행하여 playground-api 재생성 (`src/api/functional`은 **절대 수동 편집 금지**)