refactor(meeting): 회의 원본을 MongoDB로 저장하고, redis는 캐시로만 유지 (#21)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: yuchem2

CODEBASE_GUIDE.md

@@ -46,10 +46,18 @@ packages/shared-interfaces/src/   meeting.ts · mediasoup.ts · reports.ts · ev
 4. **Ctrl** `meeting.controller.createMeeting`
 5. **Svc** `meeting.service.createMeeting`
    — Meeting.create · repo.save · ⇢ `meeting.created`
-6. **Repo** `redis-meeting.repository.save`
+6. **Repo** `cached-meeting.repository.save` — Mongo(원본) + redis(캐시)
 
 « 응답 `{ code, source, startedAt, hostToken }` — hostToken 보유자 = host 권한
 
+**회의 저장소.** 원본은 `mongo-meeting.repository`(collection `meetings`, `_id` = code), 그 앞에
+`redis-meeting.repository`가 캐시로 붙는다. 조합은 `cached-meeting.repository`가 한다.
+
+- `save` — `lastActiveAt`만 바뀐 저장(=채팅 heartbeat)은 캐시까지만. 상태 전이만 원본에 내려간다
+- `findByCode` — 캐시 miss면 원본에서 읽어 캐시를 채운다
+- `listOpenCodes` — 캐시 색인이 cold면 원본 질의(`status: 'open'`)로 재구축. redis가 전손돼도 재시작 복구가 동작한다
+- 종료된 회의의 캐시 키에는 TTL 1h. 원본에 남아 있으므로 만료돼도 조회는 된다
+
 ### 2.2 회의 입장 (닉네임 게이트)
 
 1. **View** `JoinMeetingForm` → `useJoinMeetingViewModel` (setNickname · router.push `'/meetings/{code}'`)
@@ -63,7 +71,7 @@ packages/shared-interfaces/src/   meeting.ts · mediasoup.ts · reports.ts · ev
 
 ### 2.2.1 재시작 복구 (부팅 시 1회)
 
-`meeting-recovery.service`(OnApplicationBootstrap) — 회의는 redis에 남지만 방·socket은 프로세스와 함께 사라진다.
+`meeting-recovery.service`(OnApplicationBootstrap) — 회의는 저장소에 남지만 방·socket은 프로세스와 함께 사라진다.
 
 1. `repo.listOpenCodes()` → 회의마다 ⇢ `meeting.opened` (mediasoup 방 재생성)
 2. 남아 있는 참가자 = 유령(`participantId` = socket.id) → `meeting.service.leaveMeeting` ⇢ `meeting.participant.left`

README.md

@@ -94,14 +94,15 @@ uvicorn main:app --port 8000
 ```
 
 Redis는 로컬(6379)에 떠 있어야 한다 — `docker compose -f docker-compose.local.yml up -d redis`.
-진행 중인 회의 상태가 여기에만 있으므로 AOF 영속화가 걸린 이 컨테이너를 쓴다(`down -v` 금지).
+회의 원본은 MongoDB지만 진행 중인 회의의 채팅·오디오 버퍼는 redis에만 있으므로,
+AOF 영속화가 걸린 이 컨테이너를 쓴다(`down -v` 금지).
 
 | 서비스           | 포트                    | 비고                                 |
 |---------------|-----------------------|------------------------------------|
 | backend       | 5000                  | HTTP + WebSocket(Socket.IO)        |
 | frontend      | 3000                  | Next.js dev                        |
 | ai-worker     | 8000                  | FastAPI(STT)                       |
-| redis         | 6379                  | 회의 진행 상태·오디오 버퍼                    |
+| redis         | 6379                  | 회의 캐시·채팅·오디오 버퍼 (회의 원본은 MongoDB)     |
 | mediasoup RTC | 40000–49999 (UDP/TCP) | WebRTC 미디어. `RTC_MIN/MAX_PORT`로 조정 |
 
 ### 테스트 · 빌드 · 린트

apps/backend/src/meeting/infrastructure/cached-meeting.repository.spec.ts

@@ -0,0 +1,175 @@
+import type Redis from 'ioredis';
+import RedisMock from 'ioredis-mock';
+
+import { Meeting, MeetingSnapshot } from '@/meeting/domain/meeting';
+import { MeetingRepository } from '@/meeting/domain/ports';
+import { IdleTimeout, MeetingCode } from '@/meeting/domain/value-objects';
+import { externalReference } from '@/shared-kernel/domain/value-objects';
+
+import { CachedMeetingRepository } from './cached-meeting.repository';
+import { RedisMeetingRepository } from './redis-meeting.repository';
+
+const t0 = new Date('2026-01-01T00:00:00Z');
+const t30s = new Date('2026-01-01T00:00:30Z');
+const t1m = new Date('2026-01-01T00:01:00Z');
+
+const makeMeeting = (codeStr: string): Meeting =>
+  Meeting.create({
+    code: MeetingCode.from(codeStr),
+    source: 'web',
+    externalReference: externalReference(),
+    idleTimeout: IdleTimeout.default(),
+    startedAt: t0,
+    hostToken: `host-${codeStr}`,
+    title: null,
+  });
+
+/** 호출을 세는 in-memory 원본. Mongo 어댑터 자리에 끼운다. */
+const makeOrigin = () => {
+  const stored = new Map<string, MeetingSnapshot>();
+  const calls = { findByCode: 0, save: 0, listOpenCodes: 0 };
+  const repository: MeetingRepository = {
+    findByCode: async (code) => {
+      calls.findByCode += 1;
+      const snapshot = stored.get(code);
+      return snapshot === undefined ? null : Meeting.fromSnapshot(snapshot);
+    },
+    save: async (meeting) => {
+      calls.save += 1;
+      stored.set(meeting.code.value, meeting.snapshot());
+    },
+    listOpenCodes: async () => {
+      calls.listOpenCodes += 1;
+      return Array.from(stored.values())
+        .filter((s) => s.status === 'open')
+        .map((s) => s.code);
+    },
+  };
+  return { repository, calls, stored };
+};
+
+describe('CachedMeetingRepository', () => {
+  let redis: Redis;
+  let cache: RedisMeetingRepository;
+  let origin: ReturnType<typeof makeOrigin>;
+  let repo: CachedMeetingRepository;
+
+  beforeEach(() => {
+    redis = new RedisMock() as unknown as Redis;
+    cache = new RedisMeetingRepository(redis);
+    origin = makeOrigin();
+    repo = new CachedMeetingRepository(cache, origin.repository);
+  });
+
+  afterEach(async () => {
+    await redis.flushall();
+    await redis.quit();
+  });
+
+  describe('save', () => {
+    it('캐시에 없던 회의는 원본에 기록한다', async () => {
+      await repo.save(makeMeeting('abc12xyz'));
+
+      expect(origin.calls.save).toBe(1);
+    });
+
+    it('lastActiveAt만 바뀐 저장은 원본을 건드리지 않는다', async () => {
+      const meeting = makeMeeting('abc12xyz');
+      await repo.save(meeting);
+
+      meeting.markActive(t30s);
+      await repo.save(meeting);
+
+      expect(origin.calls.save).toBe(1);
+    });
+
+    it('lastActiveAt만 바뀐 저장도 캐시에는 반영한다', async () => {
+      const meeting = makeMeeting('abc12xyz');
+      await repo.save(meeting);
+
+      meeting.markActive(t30s);
+      await repo.save(meeting);
+
+      const cached = await cache.findByCode('abc12xyz');
+      expect(cached!.lastActiveAt).toEqual(t30s);
+    });
+
+    it('참가자가 바뀌면 원본에 기록한다', async () => {
+      const meeting = makeMeeting('abc12xyz');
+      await repo.save(meeting);
+
+      meeting.addParticipant('socket-a', '가', t30s);
+      await repo.save(meeting);
+
+      expect(origin.calls.save).toBe(2);
+    });
+
+    it('회의가 종료되면 원본에 기록한다', async () => {
+      const meeting = makeMeeting('abc12xyz');
+      await repo.save(meeting);
+
+      meeting.close(t1m);
+      await repo.save(meeting);
+
+      expect(origin.calls.save).toBe(2);
+    });
+  });
+
+  describe('findByCode', () => {
+    it('캐시에 있으면 원본을 읽지 않는다', async () => {
+      await repo.save(makeMeeting('abc12xyz'));
+      origin.calls.findByCode = 0;
+
+      const found = await repo.findByCode('abc12xyz');
+
+      expect(found!.code.value).toBe('abc12xyz');
+      expect(origin.calls.findByCode).toBe(0);
+    });
+
+    it('캐시에 없으면 원본에서 읽어 온다', async () => {
+      await origin.repository.save(makeMeeting('abc12xyz'));
+
+      const found = await repo.findByCode('abc12xyz');
+
+      expect(found!.code.value).toBe('abc12xyz');
+    });
+
+    it('원본에서 읽어 온 회의는 캐시에 채워 둔다', async () => {
+      await origin.repository.save(makeMeeting('abc12xyz'));
+
+      await repo.findByCode('abc12xyz');
+
+      expect(await cache.findByCode('abc12xyz')).not.toBeNull();
+    });
+
+    it('원본에도 없으면 null을 돌려준다', async () => {
+      await expect(repo.findByCode('missing0')).resolves.toBeNull();
+    });
+  });
+
+  describe('listOpenCodes', () => {
+    it('캐시 색인이 비어 있으면 원본 질의로 재구축한다', async () => {
+      await origin.repository.save(makeMeeting('abc12xyz'));
+
+      await expect(repo.listOpenCodes()).resolves.toEqual(['abc12xyz']);
+    });
+
+    it('재구축 이후에는 원본을 다시 질의하지 않는다', async () => {
+      await origin.repository.save(makeMeeting('abc12xyz'));
+      await repo.listOpenCodes();
+      origin.calls.listOpenCodes = 0;
+
+      await repo.listOpenCodes();
+
+      expect(origin.calls.listOpenCodes).toBe(0);
+    });
+
+    it('열린 회의가 없는 것과 캐시가 비어 있는 것을 구분한다', async () => {
+      await repo.listOpenCodes();
+      origin.calls.listOpenCodes = 0;
+
+      await expect(repo.listOpenCodes()).resolves.toEqual([]);
+      expect(origin.calls.listOpenCodes).toBe(0);
+    });
+  });
+});

apps/backend/src/meeting/infrastructure/cached-meeting.repository.ts

@@ -0,0 +1,52 @@
+import { Injectable } from '@nestjs/common';
+
+import { Meeting } from '@/meeting/domain/meeting';
+import { MeetingRepository } from '@/meeting/domain/ports';
+
+import { RedisMeetingRepository } from './redis-meeting.repository';
+
+/** `lastActiveAt`을 뺀 나머지 상태. 두 스냅숏의 이 값이 같으면 실질 변화는 heartbeat뿐이다. */
+const fingerprint = (meeting: Meeting): string =>
+  JSON.stringify({ ...meeting.snapshot(), lastActiveAt: null });
+
+/**
+ * 회의 저장소. 원본은 Mongo, redis는 그 앞의 캐시다.
+ *
+ * 쓰기는 상태 전이(생성·입장·퇴장·종료)에서만 원본까지 내려간다. 채팅은 메시지마다
+ * `markActive` + `save`를 하는데(`meeting.service.postChat`) 이건 heartbeat일 뿐이라
+ * 원본 쓰기를 유발하면 안 된다 — 낡은 `lastActiveAt`은 idle 판정을 캐시로 하는 한 무해하고,
+ * 캐시가 통째로 날아간 경우엔 재시작 복구가 `markActive(now)`로 다시 잡아 준다.
+ */
+@Injectable()
+export class CachedMeetingRepository implements MeetingRepository {
+  constructor(
+    private readonly cache: RedisMeetingRepository,
+    private readonly origin: MeetingRepository,
+  ) {}
+
+  async findByCode(code: string): Promise<Meeting | null> {
+    const cached = await this.cache.findByCode(code);
+    if (cached !== null) return cached;
+    const found = await this.origin.findByCode(code);
+    if (found !== null) await this.cache.save(found);
+    return found;
+  }
+
+  async save(meeting: Meeting): Promise<void> {
+    const previous = await this.cache.findByCode(meeting.code.value);
+    // 캐시에 직전 상태가 없으면 무엇이 바뀌었는지 판단할 수 없다 — 원본에 쓰는 쪽이 안전하다.
+    if (previous === null || fingerprint(previous) !== fingerprint(meeting)) {
+      await this.origin.save(meeting);
+    }
+    await this.cache.save(meeting);
+  }
+
+  async listOpenCodes(): Promise<string[]> {
+    if (await this.cache.isOpenIndexWarm()) {
+      return this.cache.listOpenCodes();
+    }
+    const codes = await this.origin.listOpenCodes();
+    await this.cache.primeOpenIndex(codes);
+    return codes;
+  }
+}

apps/backend/src/meeting/infrastructure/meeting.schema.ts

@@ -0,0 +1,33 @@
+import { Schema } from 'mongoose';
+
+/**
+ * Meeting의 mongoose Schema.
+ *
+ * `_id`는 ObjectId가 아니라 `MeetingCode`를 그대로 저장한다 — 회의 조회는 전부 code 기준이다.
+ * nested 구조는 `Schema.Types.Mixed`로 둬서 domain 검증과 schema 검증이 중복되지 않게 한다.
+ * `status`는 `listOpenCodes`의 질의 키라 인덱스를 둔다.
+ */
+
+export const MEETING_COLLECTION = 'meetings';
+
+export const meetingSchema = new Schema(
+  {
+    _id: { type: String, required: true },
+    source: { type: String, required: true },
+    meetingType: { type: String, required: true },
+    externalReference: { type: Schema.Types.Mixed, default: {} },
+    idleTimeoutMs: { type: Number, required: true },
+    status: { type: String, required: true, index: true },
+    startedAt: { type: Date, required: true },
+    endedAt: { type: Date, default: null },
+    lastActiveAt: { type: Date, required: true },
+    participants: { type: [Schema.Types.Mixed], default: [] },
+    hostToken: { type: String, default: '' },
+    title: { type: String, default: null },
+  },
+  {
+    collection: MEETING_COLLECTION,
+    minimize: false,
+    versionKey: false,
+  },
+);