feat(core): Event Bus · Service Registry 구현 및 AppServices 연동

- EventBus 싱글턴: 타입-안전 emit/on/once/off, 리스너 자동 해제 지원
- 이벤트 타입: subscription:payment · subscription:price-changed · ledger:created
- ServiceRegistry 싱글턴: 모듈 간 직접 import 없이 서비스 인스턴스 공유
- AppServices에 eventBus · serviceRegistry 추가, initServices()에서 초기화

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SOIV

apps/api/src/app.ts

@@ -20,7 +20,9 @@ import type { SharedLinkRenderer } from '@fieldstack/core' with { "resolution-mo
 import { validateEnv } from './config/env';
 import { errorHandler } from './middleware/error';
 import { requestLogger } from './middleware/logger';
+import { EventBus } from './event-bus';
 import { ModuleRegistry } from './module-registry';
+import { ServiceRegistry } from './service-registry';
 import { createAdminRouter } from './routes/admin';
 import { createAuthRouter } from './routes/auth';
 import { createCoreRouter } from './routes/core';
@@ -41,6 +43,8 @@ export interface AppServices {
   settings: SystemSettingsService;
   // 모듈 라우터에서 사용할 DB 프로바이더 (모듈이 @fieldstack/core를 직접 import하지 않아도 되도록)
   db: DbProvider;
+  eventBus: EventBus;
+  serviceRegistry: ServiceRegistry;
 }
 
 export function createApp(services?: AppServices) {
@@ -190,5 +194,8 @@ export async function initServices(db: DbProvider): Promise<AppServices> {
   const settings = new SystemSettingsService(db);
   const sharedLink = new SharedLinkService(db, settings, env.PUBLIC_URL ?? null);
 
-  return { jwtManager, whitelist, adminPin, totpService, userAuth, sharedLink, settings, db };
+  const eventBus = EventBus.getInstance();
+  const serviceRegistry = ServiceRegistry.getInstance();
+
+  return { jwtManager, whitelist, adminPin, totpService, userAuth, sharedLink, settings, db, eventBus, serviceRegistry };
 }

apps/api/src/event-bus.ts

@@ -0,0 +1,99 @@
+import { EventEmitter } from 'node:events';
+
+// ── 이벤트 페이로드 타입 정의 ────────────────────────────────────
+//
+// 새 이벤트 추가 시 이 인터페이스에만 추가하면 emit/on/once 전체에 자동 반영.
+
+export interface EventPayloads {
+  /** 구독 결제일 도래 — Scheduler가 매일 자정 발행 */
+  'subscription:payment': {
+    subscriptionId: string;
+    userId: string;
+    serviceName: string;
+    amount: number;
+    currency: string;
+    date: string;           // YYYY-MM-DD
+    priceHistoryId: string | null;
+  };
+  /** 구독 가격 변경 */
+  'subscription:price-changed': {
+    subscriptionId: string;
+    userId: string;
+    previousAmount: number;
+    newAmount: number;
+    currency: string;
+    effectiveDate: string;  // YYYY-MM-DD
+  };
+  /** 가계부 항목 생성 완료 */
+  'ledger:created': {
+    entryId: string;
+    userId: string;
+  };
+}
+
+export type EventName = keyof EventPayloads;
+
+type Handler<K extends EventName> = (payload: EventPayloads[K]) => void;
+
+// ── EventBus 싱글턴 ───────────────────────────────────────────────
+//
+// Node.js EventEmitter 위에 타입-안전 래퍼를 얹은 구조.
+// 모든 모듈은 services.eventBus를 통해 접근한다.
+//
+// on() 반환값(unsubscribe 함수)을 모듈 종료 시 반드시 호출해
+// 메모리 누수를 방지할 것.
+
+export class EventBus {
+  private static _instance: EventBus | null = null;
+  private readonly emitter = new EventEmitter();
+
+  private constructor() {
+    // EventEmitter 기본 리스너 한도(10)를 늘려 대규모 모듈 환경 대비
+    this.emitter.setMaxListeners(100);
+  }
+
+  public static getInstance(): EventBus {
+    if (!EventBus._instance) {
+      EventBus._instance = new EventBus();
+    }
+    return EventBus._instance;
+  }
+
+  /** 이벤트 발행 */
+  public emit<K extends EventName>(event: K, payload: EventPayloads[K]): void {
+    this.emitter.emit(event, payload);
+  }
+
+  /**
+   * 이벤트 구독.
+   * @returns unsubscribe 함수 — 모듈 종료 시 반드시 호출할 것.
+   */
+  public on<K extends EventName>(event: K, handler: Handler<K>): () => void {
+    this.emitter.on(event, handler as (...args: unknown[]) => void);
+    return () => this.off(event, handler);
+  }
+
+  /**
+   * 단발 이벤트 구독 (한 번 수신 후 자동 해제).
+   * @returns unsubscribe 함수
+   */
+  public once<K extends EventName>(event: K, handler: Handler<K>): () => void {
+    this.emitter.once(event, handler as (...args: unknown[]) => void);
+    return () => this.off(event, handler);
+  }
+
+  /** 특정 핸들러 해제 */
+  public off<K extends EventName>(event: K, handler: Handler<K>): void {
+    this.emitter.off(event, handler as (...args: unknown[]) => void);
+  }
+
+  /** 특정 이벤트의 모든 리스너 해제 (모듈 언로드 시 활용) */
+  public removeAllListeners(event?: EventName): void {
+    this.emitter.removeAllListeners(event);
+  }
+
+  /** 현재 등록된 리스너 수 (디버깅용) */
+  public listenerCount(event: EventName): number {
+    return this.emitter.listenerCount(event);
+  }
+}

apps/api/src/service-registry.ts

@@ -0,0 +1,62 @@
+import { log } from './middleware/logger';
+
+// ── ServiceRegistry 싱글턴 ───────────────────────────────────────
+//
+// 모듈이 공개한 서비스 인스턴스를 중앙에서 관리한다.
+// 모듈 간 직접 import 금지 원칙을 지키면서 서비스를 공유할 수 있게 해준다.
+//
+// 사용 예:
+//   // 등록 (모듈 초기화 시)
+//   services.serviceRegistry.register('ledger', ledgerService);
+//
+//   // 조회 (다른 모듈에서)
+//   const ledger = services.serviceRegistry.getService<LedgerPublicApi>('ledger');
+//
+// ⚠️ getService()는 모듈이 로드되기 전이면 undefined를 반환한다.
+//    의존 모듈이 아직 없을 수 있으므로 항상 존재 여부를 확인할 것.
+
+export class ServiceRegistry {
+  private static _instance: ServiceRegistry | null = null;
+  private readonly services = new Map<string, unknown>();
+
+  private constructor() {}
+
+  public static getInstance(): ServiceRegistry {
+    if (!ServiceRegistry._instance) {
+      ServiceRegistry._instance = new ServiceRegistry();
+    }
+    return ServiceRegistry._instance;
+  }
+
+  /** 서비스 인스턴스 등록 */
+  public register(name: string, service: unknown): void {
+    if (this.services.has(name)) {
+      log.warn('service-registry', `service "${name}" already registered — overwriting`);
+    }
+    this.services.set(name, service);
+    log.info('service-registry', `service "${name}" registered`);
+  }
+
+  /**
+   * 등록된 서비스 조회.
+   * @returns 등록된 서비스 또는 undefined (미등록 시)
+   */
+  public getService<T>(name: string): T | undefined {
+    return this.services.get(name) as T | undefined;
+  }
+
+  /** 서비스 해제 (모듈 언로드 시 호출) */
+  public unregister(name: string): boolean {
+    const existed = this.services.has(name);
+    if (existed) {
+      this.services.delete(name);
+      log.info('service-registry', `service "${name}" unregistered`);
+    }
+    return existed;
+  }
+
+  /** 등록된 서비스 이름 목록 (디버깅용) */
+  public list(): string[] {
+    return Array.from(this.services.keys());
+  }
+}