meeting-minutes/docs/ROADMAP.md

Meeting Minutes — ROADMAP

노션의 AI Meeting Notes 기능을 참고한 단계별 개발 계획. 개인/소규모 팀 사용 기준으로 범위 조정됨.

---

✅ Phase 0 — 기반 (완료)

구현됨

• Web Speech API 기반 실시간 전사 (Chrome ko-KR)
• 파일 업로드 검증 (MP3/WAV/WebM/M4A/OGG/FLAC, 최대 500MB)
• 단순 변환 / Gemini AI 요약 두 모드
• Markdown / HTML 내보내기, 클립보드 복사
• Gemini 롤링 실시간 요약 (30초 간격, 25/40단어 게이트)
• 녹음 종료 시 최종 회의록 자동 생성
• 429 쿼터 초과 자동 쿨다운 + 지수 백오프
• Gemini 실패 시 단순 변환 자동 폴백
• 네트워크 에러 자동 재연결 (최대 8회)
• 좌우 분할 UI (실시간 텍스트 / 실시간 회의록)
• 자동 스크롤, 진행률 바, 쿨다운 카운터
• Docker Compose (app + db + test profile)
• 단위 테스트 38개 통과
• Prisma 7 호환 스키마 (아직 미사용)

알려진 제약

• Chrome 전용 (Web Speech API)
• 화자 구분 불가 — 의도적 비지원 (Non-goal)
• 녹음 저장/조회 불가 (DB 미사용)
• Web Speech 세션이 가끔 끊김 → 자동 재연결로 완화

---

✅ 보안 강화 — 공개 저장소 전환 준비 (완료)

회사 직원이 각자 로컬에서 사용할 수 있도록 보안 검토 및 강화 작업.

구현됨

• C-1 대응: 발급된 Gemini 키 .env에서 제거하도록 사용자 안내 (Google AI Studio 폐기 + .env 정리)
• C-2 대응: docker-compose의 DB 비밀번호 fallback 제거 → :? 강제 환경변수
• C-3 대응: Postgres 포트 5432 호스트 노출 제거 (컨테이너 내부 네트워크 전용)
• H-1 대응: App 포트 127.0.0.1:3000로 바인딩 (LAN 노출 차단)
• H-2 대응: /api/summarize에 transcript 100,000자 상한 추가
• H-4 대응: next.config.ts에 보안 응답 헤더 4종 적용
• H-5 대응: /settings 페이지에 공유 PC 경고 + Web Speech 외부 송출 안내 추가
• H-6 대응: db.ts에서 DATABASE_URL 누락 시 명시적 경고 로그
• M-3 대응: DOMPurify에 FORBID_TAGS: ['style'], FORBID_ATTR: ['style'] 추가
• 문서화: SECURITY.md 작성 (위협 모델, 신뢰 모델, 한계, 신고 방법)
• MIT LICENSE 추가

확인됨 (현재 비목표)

• M-1 (Web Speech → Google) — 구조적 한계, 문서화로 처리
• M-2 (npm audit moderate 6건) — dev 의존성, 자동 수정 가능한 것 0건
• H-3 (파일 업로드 매직 바이트) — 업로드된 파일 미사용/미서빙으로 위험 낮음
• 인증 시스템 — 단일 사용자 가정 (의도된 비목표)

---

✅ Phase 0.5 — 템플릿 + 강도 조절 (완료)

사용자가 회의록 외 다양한 용도로 쓸 수 있도록 템플릿 시스템과 강도 조절 도입.

구현됨

• 6개 프리셋 템플릿 (회의록, 강의·세미나, 1:1 미팅, 브레인스토밍, 인터뷰, 원문 정리)
• 커스텀 프롬프트 옵션 (파워 유저용 자유 입력)
• 3단계 강도 조절 (간결 / 표준 / 상세)
• 템플릿별 기본 강도 프리셋 (예: 강의는 상세, 회의록은 표준)
• 템플릿별 라이브 요약 지원 플래그 (raw/interview는 종료 시 한 번만)
• Gemini 모드에서만 노출, 단순 변환은 기존 동작 유지
• 라이브 요약도 동일 템플릿/강도 적용
• 프롬프트 빌더 단위 테스트 19개

---

✅ Phase 1.5 — 웹 기반 API 키 설정 (완료)

.env를 만지지 않고도 브라우저에서 Gemini 키를 설정할 수 있도록 함.

구현됨

• /settings 페이지 — 키 입력 / 저장 / 삭제 / 마스킹된 현재 키 표시
• LocalStorage 저장 (서버 DB에 보관 X — 개인용/단일 인스턴스 가정)
• /api/settings/status — 환경변수 키 존재 여부 (값 노출 X)
• /api/settings/test — 키로 가벼운 Gemini 호출 시도 → 200/401/429 등 분류
• resolveGeminiApiKey() 우선순위: 요청 body 키 → 환경변수 → null
• summarize / summarize-live 라우트가 body의 apiKey 사용
• 단위 테스트 14개 (api-keys 7 + api-key-storage 7)

의도된 비목표

• 다중 사용자 / 권한 관리 — 개인용 단일 인스턴스
• 키 암호화 — 평문 LocalStorage (현재 .env 신뢰 모델과 동일)

---

✅ Phase 1 — 회의 저장/조회 (완료)

노션의 Meeting Database 수준. 생성한 회의록을 저장하고 다시 찾아볼 수 있음.

Issues

• #1 Prisma 연결 + 마이그레이션 파이프라인 — PR feat/phase-1-foundation
  • src/lib/db.ts 싱글톤 Prisma 클라이언트 (Prisma 7 driver adapter 경유)
  • 첫 마이그레이션 생성 (prisma migrate dev)
  • docker-compose tools 프로필에 migrate 서비스 추가
  • Meeting 스키마 확장 (attendees/tags/template/depth/summaryMode/customPrompt)
• #2 회의 저장 API — PR feat/phase-1-foundation
  • POST /api/meetings — transcript + markdown 저장
  • GET /api/meetings — 목록 조회 (최신순, 페이지네이션, q 부분검색)
  • GET /api/meetings/[id] — 상세
  • PUT /api/meetings/[id] — markdown/title/attendees/tags 편집
  • DELETE /api/meetings/[id]
• #3 MinutesViewer에 "저장" 버튼 — PR feat/phase-1-ui
  • 생성된 회의록 세션에서 저장 → 배너 + 상세 링크
  • 미리보기 / 원문 토글
• #4 회의 목록 페이지 (/meetings) — PR feat/phase-1-ui
  • 카드 그리드 (제목, 날짜, preview, 태그, 참석자, 템플릿 배지)
  • 빈 상태 UI
  • 페이지네이션
• #5 회의 상세 페이지 (/meetings/[id]) — PR feat/phase-1-ui
  • Markdown 렌더링 (sanitize)
  • 인라인 편집 (제목/본문/참석자/태그) + 좌우 미리보기
  • 삭제 버튼
• #6 Markdown 렌더링 라이브러리 도입 — PR feat/phase-1-ui
  • marked + isomorphic-dompurify
  • src/lib/markdown.ts 공용 유틸
  • 기존 커스텀 파서 교체, .prose-minutes 공통 스타일
• #7 전역 검색 — PR feat/phase-1-ui
  • 검색 바 (debounce 300ms, URL query 동기화)
  • /api/meetings?q=... 부분 검색 (title/transcript/markdown)
  • Postgres tsvector GIN 인덱스 — 현재 ILIKE로 개인용 규모 충분, 필요 시 후속

---

✅ Phase 2 — 구조화된 액션 아이템 (완료)

회의가 끝나면 "내 할 일"이 자동으로 추출되어 체크리스트로 남음.

구현됨

• #8 액션 아이템 추출 — Gemini JSON 재구성 대신 마크다운 휴리스틱 채택 (모든 템플릿이 이미 - [ ] 출력 → 추가 호출 비용 0, 후속에 JSON 모드 가능)
• #9 ActionItem 테이블 — Meeting ↔ ActionItem 1:N (cascade delete)
  • 필드: id, meetingId, task, isDone, position, createdAt, updatedAt
  • assignee/dueDate는 추후 JSON 출력 모드 도입 시 추가
• #10 체크리스트 UI — 상세 페이지 별도 섹션
  • 체크박스 토글 (낙관적 업데이트) → PATCH /api/action-items/[id]
  • 개별 삭제 (hover 시 ✕ 노출)
  • 🔄 재추출 버튼 (마크다운 변경 후 수동 동기화)
• #11 대시보드 위젯 — /meetings 상단에 "내 미완료 액션 (최근 5)"
  • 회의 카드 우상단에 미완료 카운트 배지
  • 홈 페이지 자체 승격은 보류 (현재 녹음 UI 유지)
• 부가 — Google Docs 호환 서식 복사 (text/html + text/plain ClipboardItem)
  • MinutesViewer / MeetingDetail 둘 다 📋 Docs용 버튼

비목표 (이번 단계)

• Gemini JSON 출력 + zod 검증 — 정확도 부족 시 후속 도입
• assignee/dueDate 필드 — JSON 출력 도입과 함께
• 홈 페이지 대시보드 승격 — 녹음 흐름 보존이 우선

---

🔴 실사용 진단 (2026-09-08 대면 회의)

46분 대면 회의를 실제로 녹음해 본 결과다. 로드맵의 우선순위를 바꾼 근거.

지표	값
회의 길이	46분 6초
총 청크	122개
총 어절	489
분당 어절	10.6 (한국어 대화 통상 100~150)
추정 포착률	7~10%
30초 이상 공백	26곳 / 합계 26분 29초 (회의의 57%)
빈 텍스트 청크	19개 (16%)

빈 청크 19개가 결정적 증거다. Chrome이 isFinal: true에 transcript: ""를 준 경우로, "소리는 감지했으나 인식 실패"를 뜻한다. 마이크 입력 문제가 아니라 Web Speech가 원거리·다인 한국어를 못 알아듣고 버린 것이다.

결론: Web Speech API는 회의 전사에 쓸 수 없다. 재시작 갭을 메우고 interim을 flush해서 7%를 20~30%로는 올려도 90%로는 못 간다. 구현 결함이 아니라 엔진의 한계다.

---

🎯 P0 — 유실을 멈춘다

• 오디오 원본 녹음 — MediaRecorder로 회의 원음을 파일로 보관
  • 15초 조각 단위로 서버에 append → 탭/서버가 죽어도 그때까지는 남음
  • 서버 실패해도 녹음 계속 + 브라우저 사본 내려받기
  • 0바이트일 때 "보관됨"이라고 하지 않음
  • 캡처 제약에서 노이즈 억제·에코 제거 해제 (원거리 화자 보존)
  • 회의록 저장 시 audioFileName/audioMimeType/audioDuration 연결
• 서버 STT 파이프라인 — 녹음 파일 → Whisper / Gemini audio → transcript
  • /api/upload를 막다른 길에서 본선 경로로 승격
  • 프로바이더 레이어에 /v1/audio/transcriptions 추가 (#12 구조 확장)
  • Web Speech는 "녹음 중 실시간 미리보기"로 강등, 확정본은 종료 후 재전사
  • 같은 오디오로 Web Speech vs STT 포착률 실측 비교
• 빈 청크 필터링 — 빈 발화 19개가 요약 프롬프트를 오염시키고 있음
• 타임스탬프 실측화 — useSpeechRecognition.ts의 startTime: now - 2 하드코딩 제거
• 10만 자 하드 실패 → 분할 요약 — 긴 회의가 마지막에 통째로 실패함

🎯 P1 — 입력단 개선

• 대면 회의용 USB 전방향 마이크 도입 (코드로 못 푸는 물리적 한계)
• 원격 회의용 echoCancellation 재활성 경로 분리

🎯 P2 — 화자 분리 재설계

• PR #17은 현재 형태로 머지 보류 — 실사용에서 46분 회의를 화자 1명으로 판정했고, 5개 청크는 배정조차 실패했다. assignSpeakers()가 쓰는 시간축이 가짜(now - 2)라 diarization의 실제 타임라인과 맞지 않는다
• 서버 STT 도입 후 재설계 — Whisper의 단어 단위 실제 타임스탬프 위에서 diarization을 돌리면 그때 비로소 겹침 기반 배정이 의미를 갖는다
• #17의 sherpa-onnx 래퍼·모델 셋업 스크립트는 그때 재활용
• 참석자 수 힌트는 유지 (#17 실측에서 효과 확인됨)
• PR #16(dual-stream)은 원격 회의 전용으로 분리 검증

---

🎯 Phase 3 — 참석자 + 태그 (3~5일)

Issues

• #12 참석자 입력 UI
  • 녹음 시작 전 쉼표 구분 입력 ("이름1, 이름2")
  • 회의 상세에서 편집 가능
• #13 태그 시스템
  • 프리셋: sprint, 1on1, review, planning, retro
  • 사용자 정의 태그 추가
  • 목록 페이지에 태그 필터
• #14 Gemini에 참석자 컨텍스트 주입
  • 프롬프트에 참석자 이름 포함 → 액션 아이템 담당자 배정 정확도 ↑

---

🎯 Phase 4 — 차별화 기능 (선택, 각 1~2주)

#16 Google Calendar 연동 (1~2주)

• OAuth 플로우 (next-auth + Google provider)
• 오늘 회의 목록 표시
• 캘린더 이벤트 → 회의 페이지 프리셋 (제목, 참석자 자동 채움)
• 회의 종료 시 이벤트 설명에 회의록 링크 자동 추가

#17 AI Q&A ("과거 회의 검색" - RAG) (2주)

• 회의별 embedding 생성 (Gemini embedding API 또는 OpenAI)
• pgvector 확장 설치
• /api/ask — 자연어 질문 → 관련 회의 검색 + Gemini 답변
• UI: 검색바에 "질문하기" 모드 추가

#18 후속 이메일 초안 생성 (2일)

• /api/meetings/[id]/follow-up-email — Gemini 프롬프트로 요약 이메일 생성
• 복사/Gmail 열기 버튼

#19 블록 기반 에디터 (2~4주)

• TipTap 또는 Lexical 도입
• / 슬래시 명령어, 다양한 블록 타입
• 우선순위 낮음 — 개인 사용에선 현재 markdown textarea로 충분

---

❌ 명시적 비목표 (Non-goals)

다음 기능은 개인 사용 목적에 부합하지 않아 의도적으로 범위 밖:

• 실시간 공동 편집 (CRDT) — Yjs/Liveblocks 도입 복잡도 대비 이득 없음
• 권한 관리 / 워크스페이스 — 단일 사용자 가정
• 모바일 네이티브 앱 — 웹 PWA로 충분
• 노션 수준의 전역 페이지 트리 — 회의록 전용 도구로 집중

---

진행 관리 규칙

1. Phase 단위로 GitHub Issue 생성 (각 phase를 epic issue로, 세부 #N을 task로)
2. 이슈당 1 브랜치 1 PR: feat/1-prisma-setup, feat/2-meetings-api …
3. PR 머지 전: docker compose --profile tools run --rm test 전체 통과 필수
4. 완료 시 ROADMAP 체크박스 업데이트 (이 파일을 single source of truth로 유지)

이슈 생성 커맨드는 docs/CREATE_ISSUES.sh 참고.