던플 개발기 (6): TypeORM에서 Prisma로, 그리고 item·market 컨텍스트 분리

// 이전 — libs/market/data-access/src/lib/entities/item.entity.ts (TypeORM)
@Entity({ name: 'items' })
export class ItemEntity {
  @PrimaryColumn({ name: 'item_id', type: 'varchar', length: 64 })
  itemId!: string;
 
  @Column({ name: 'name', type: 'varchar', length: 255 })
  name!: string;
 
  @Column({ name: 'rarity', type: 'varchar', length: 32, nullable: true })
  rarity!: string | null;
  // item_type, item_type_detail, image_url ...
 
  @CreateDateColumn({ name: 'created_at' })
  createdAt!: Date;
 
  @UpdateDateColumn({ name: 'updated_at' })
  updatedAt!: Date;
}

// 이전 — TypeOrmItemRepository
export class TypeOrmItemRepository {
  private readonly repository: Repository<ItemEntity>;
  constructor(dataSource: DataSource) {
    this.repository = dataSource.getRepository(ItemEntity);
  }
  // save(): PK가 새로우면 insert, 아니면 in-place update
  async upsert(item: Item): Promise<void> {
    await this.repository.save(itemToEntity(item));
  }
  async findById(id: ItemId): Promise<Item | null> {
    const entity = await this.repository.findOne({ where: { itemId: id } });
    return entity === null ? null : itemEntityToDomain(entity);
  }
}
 
// 이후 — PrismaItemRepository (같은 포트를 구조적으로 만족)
export class PrismaItemRepository {
  constructor(private readonly prisma: MarketPrismaClient) {}
  async upsert(item: Item): Promise<void> {
    const data = itemToWriteData(item);
    await this.prisma.item.upsert({
      where: { itemId: item.id },
      create: { itemId: item.id, ...data },
      update: data,
    });
  }
  async findById(id: ItemId): Promise<Item | null> {
    const row = await this.prisma.item.findUnique({ where: { itemId: id } });
    return row === null ? null : itemRowToDomain(row);
  }
}

flowchart TB
  subgraph assembly["market-api · layer:app · 유일한 조립 지점"]
    B["DI 바인딩: 포트 ← 구현체"]
  end
  P["ItemRepository 포트<br/>market-application · layer:application"]
  I["PrismaItemRepository<br/>market-data-access · layer:data-access"]
  B --> P
  B --> I
  I -. "포트를 import하지 않고<br/>구조적으로 만족" .-> P

// 이후 — libs/market/data-access/prisma/schema.prisma
model Item {
  itemId    String   @id @map("item_id") @db.VarChar(64)
  name      String   @db.VarChar(255)
  rarity    String?  @db.VarChar(32)
  imageUrl  String?  @map("image_url") @db.Text
  createdAt DateTime @default(now())   @map("created_at") @db.Timestamptz(6)
  updatedAt DateTime @updatedAt        @map("updated_at") @db.Timestamptz(6)
 
  trackedItem TrackedItem?
  @@map("items")
}

// libs/market/data-access/src/cli/migrate.ts
// run   -> prisma migrate deploy : 모든 pending migration 적용. 멱등·프로덕션용.
// reset -> prisma migrate reset  : Prisma엔 단건 down이 없으므로 스키마를 drop 후
//                                  전부 재적용. 파괴적이라 로컬 개발 전용.
const prismaArgs =
  command === 'reset'
    ? ['exec', 'prisma', 'migrate', 'reset', '--force', '--skip-generate']
    : ['exec', 'prisma', 'migrate', 'deploy'];
 
execFileSync('pnpm', [...prismaArgs, '--schema', schemaPath], {
  stdio: 'inherit',
  env: { ...process.env, DATABASE_URL: buildDatabaseUrl(loadDatabaseConfig()) },
});

// libs/market/data-access/src/lib/config/database-config.ts
export function buildDatabaseUrl(config = loadDatabaseConfig()): string {
  const user = encodeURIComponent(config.username);
  const password = encodeURIComponent(config.password);
  const database = encodeURIComponent(config.database);
  const base = `postgresql://${user}:${password}@${config.host}:${config.port}/${database}`;
  return config.ssl ? `${base}?sslmode=require` : base;
}

flowchart LR
  subgraph before["전환 전 — 하나의 market 컨텍스트"]
    M0["market-data-access"]
    M0 --> T0["items · tracked_items"]
    M0 --> T1["auction_* · *_aggregates"]
    M0 --> T2["item spec / catalog refresh<br/>(들어갈 자리)"]
  end
  subgraph after["전환 후 — item · market 두 컨텍스트"]
    I1["item-data-access"] --> IT["items (호환) · item_spec_revisions<br/>item_catalog_refresh_runs"]
    M1["market-data-access"] --> MT["tracked_items · auction_*<br/>*_aggregates · provider_*"]
  end

// 초기 추출 — item_spec_revisions 가 items 를 FK cascade 로 참조
model ItemSpecRevision {
  itemId   String   @map("item_id") @db.VarChar(64)
  revision Int
  // spec, spec_hash, captured_at ...
  item Item @relation(fields: [itemId], references: [itemId], onDelete: Cascade)
 
  @@id([itemId, revision])
  @@map("item_spec_revisions")
}

// FK 제거 후 — 평범한 인덱스 컬럼
model ItemSpecRevision {
  itemId   String   @map("item_id") @db.VarChar(64)
  revision Int
  // spec, spec_hash, captured_at ...
 
  @@id([itemId, revision])
  @@index([itemId], map: "idx_item_spec_revisions_item")
  @@map("item_spec_revisions")
}

flowchart TB
  subgraph naive["순진하게 짰다면"]
    a_items[("items")]
    a_spec[("item_spec_revisions")]
    a_spec ==>|"FK · ON DELETE CASCADE"| a_items
  end
  subgraph real["실제 결정"]
    b_items[("items · market 물리 소유")]
    b_spec[("item_spec_revisions · item 소유")]
    b_spec -. "item_id 인덱스 참조만<br/>FK 없음" .-> b_items
  end

-- libs/item/data-access/prisma/migrations/20260623000000_init_item_catalog/migration.sql
-- 이 마이그레이션은 item 소유 테이블만 만든다. `items`는 만들지 않는다
-- (추출 단계에선 market 마이그레이션이 물리 소유하는 compatibility layer).
-- prisma migrate diff 를 `items` 포함 baseline에서 오프라인 생성했다.
-- item_spec_revisions.item_id 는 items 에 FK를 두지 않는다(schema.prisma 참조).
 
CREATE TYPE "catalog_refresh_trigger" AS ENUM ('MAINTENANCE_RECOVERY', 'MANUAL');
CREATE TYPE "catalog_refresh_status"  AS ENUM ('RUNNING', 'SUCCEEDED', 'FAILED');
 
CREATE TABLE "item_spec_revisions" (
  "item_id"     VARCHAR(64) NOT NULL,
  "revision"    INTEGER     NOT NULL,
  "spec_hash"   VARCHAR(64) NOT NULL,
  "spec"        JSONB       NOT NULL,
  "captured_at" TIMESTAMPTZ(6) NOT NULL,
  "created_at"  TIMESTAMPTZ(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT "item_spec_revisions_pkey" PRIMARY KEY ("item_id","revision")
);
CREATE TABLE "item_catalog_refresh_runs" ( /* ... */ );
CREATE INDEX "idx_item_spec_revisions_item" ON "item_spec_revisions"("item_id");
-- items 는 여기 없다.

flowchart TB
  RUN1["market-api:migration:run<br/>= prisma migrate deploy"] --> mm
  RUN2["item-api:migration:run<br/>= prisma migrate deploy"] --> im
  subgraph pg["하나의 PostgreSQL 인스턴스 · 공유 _prisma_migrations"]
    subgraph mm["market/prisma/migrations"]
      m1["create_catalog_tables<br/>→ items 생성"]
    end
    subgraph im["item/prisma/migrations"]
      i1["init_item_catalog<br/>→ item_spec_revisions·refresh_runs 생성<br/>items 는 만들지 않음"]
    end
  end

// apps/item-api/src/database/item-catalog.integration-spec.ts
it('upserts an item, reads it back, and lists its id', async () => {
  const item: Item = {
    id: toItemId('itest-item-1'),
    name: '테스트 아이템',
    rarity: '레어',
    availableLevel: 100,
  };
  await items.upsert(item);
  expect(await items.findById(item.id)).toEqual(item);
});
 
it('runs RefreshItemCatalog end to end and persists a run + revision', async () => {
  // ... 첫 refresh 는 revision 1 을 만든다 ...
  const second = await useCase.execute({ trigger: 'MANUAL', itemIds: ['itest-item-3'] });
  // spec 이 같으면 두 번째 refresh 는 새 revision 을 만들지 않는다
  expect(second.revisionsCreated).toBe(0);
});