hgzero/claude/README-SCHEMA-ANALYSIS.md

Meeting Service 데이터베이스 스키마 분석 문서

생성된 문서 목록

본 분석은 Meeting Service의 데이터베이스 스키마를 전방위적으로 분석한 결과입니다.

1. SCHEMA-REPORT-SUMMARY.md (메인 보고서)

파일: /Users/jominseo/HGZero/claude/SCHEMA-REPORT-SUMMARY.md
내용:

• Executive Summary (핵심 발견사항)
• 데이터베이스 구조 개요
• 테이블별 상세 분석 (1.1~1.8)
• 회의록 작성 플로우
• 사용자별 회의록 구조
• 마이그레이션 변경사항 (V2, V3, V4)
• 성능 최적화 포인트
• 핵심 질문 답변
• 개발 시 주의사항

빠르게 읽기: Executive Summary부터 시작하세요.

---

2. database-schema-analysis.md (상세 분석)

파일: /Users/jominseo/HGZero/claude/database-schema-analysis.md
내용:

• 마이그레이션 파일 현황 (V1~V4)
• 각 테이블의 상세 구조
• minutes vs agenda_sections 비교 분석
• 회의록 작성 플로우에서의 테이블 사용
• 사용자별 회의록 저장 구조
• SQL 쿼리 패턴
• 데이터 정규화 현황
• 인덱스 최적화 방안
• 데이터 저장 크기 예상

상세 분석 필요시: 이 문서를 참고하세요.

---

3. data-flow-diagram.md (흐름도)

파일: /Users/jominseo/HGZero/claude/data-flow-diagram.md
내용:

• 전체 시스템 플로우 (7 Phase)
• 상태 전이 다이어그램
• 사용자별 회의록 데이터 구조
• 인덱스 활용 쿼리 예시
• 데이터 저장 크기 예상

시각적 이해 필요시: 이 문서를 참고하세요.

---

4. database-diagram.puml (ER 다이어그램)

파일: /Users/jominseo/HGZero/claude/database-diagram.puml
포맷: PlantUML (UML 형식)
내용:

• 모든 테이블과 관계
• V2, V3, V4 마이그레이션 표시
• 주요 필드 강조

다이어그램 생성:

# PlantUML로 PNG 생성
plantuml database-diagram.puml -o database-diagram.png

# 또는 온라인 에디터
https://www.plantuml.com/plantuml/uml/

---

핵심 발견사항 한눈에 보기

1. Minutes 테이블 구조

잘못된 이해: minutes.content ← 회의록 내용
올바른 구조: minutes_sections.content ← 회의록 내용
           minutes ← 메타데이터만 (title, status, version)

2. 사용자별 회의록 (V3)

minutes.user_id = NULL           → AI 통합 회의록
minutes.user_id = 'user@.com'   → 개인 회의록
인덱스: idx_minutes_meeting_user(meeting_id, user_id)

3. AI 분석 결과 저장 (V3, V4)

agenda_sections     → 안건별 구조화된 요약
  └─ todos (JSON)  → 추출된 Todo [V4]
ai_summaries        → 전체 AI 처리 결과 캐시
todos 테이블        → 상세 관리 필요시만

4. 정규화 (V2)

이전: meetings.participants = "user1,user2,user3"
현재: meeting_participants (테이블, 복합PK)

---

빠른 참조표

회의록 작성 플로우

단계	API	데이터베이스 변화
1	CreateMeeting	meetings INSERT
2	StartMeeting	meetings.status = IN_PROGRESS
3	CreateMinutes	minutes INSERT (통합 + 개인)
4	UpdateMinutes	minutes_sections.content UPDATE
5	EndMeeting	meetings.status = COMPLETED, ended_at [V3]
6	FinalizeMinutes	minutes.status = FINALIZED, sections locked
7	AI 분석	agenda_sections, ai_summaries, todos INSERT

테이블별 핵심 필드

meetings          : meeting_id, status, ended_at [V3]
minutes           : id, meeting_id, user_id [V3], status
minutes_sections  : id, minutes_id, content ★
agenda_sections   : id, minutes_id, agenda_number, todos [V4]
ai_summaries      : id, meeting_id, result (JSON)
todos             : todo_id, extracted_by [V3], extraction_confidence [V3]

인덱스

PRIMARY:
  idx_minutes_meeting_user (meeting_id, user_id) [V3]
  idx_sections_meeting (meeting_id) [V3]
  idx_sections_agenda (meeting_id, agenda_number) [V3]

SECONDARY:
  idx_todos_extracted (extracted_by) [V3]
  idx_todos_meeting (meeting_id) [V3]
  idx_summaries_type (meeting_id, summary_type) [V3]

---

마이그레이션 타임라인

V1 (초기)
├─ meetings, minutes, minutes_sections
├─ todos, meeting_analysis
└─ JPA Hibernate로 자동 생성

V2 (2025-10-27)
├─ meeting_participants 테이블 생성
├─ meetings.participants (CSV) 마이그레이션
└─ 정규화 완료

V3 (2025-10-28) ★ 주요 변경
├─ minutes.user_id 추가 (사용자별 회의록)
├─ agenda_sections 테이블 신규 (AI 요약)
├─ ai_summaries 테이블 신규 (AI 결과 캐시)
└─ todos 테이블 확장 (extracted_by, extraction_confidence)

V4 (2025-10-28)
└─ agenda_sections.todos JSON 필드 추가

---

자주 묻는 질문

Q: minutes 테이블에 content 필드가 있나요?

A: 없습니다. 실제 회의록 내용은 minutes_sections.content에 저장됩니다.
minutes 테이블은 메타데이터만 보유합니다 (title, status, version 등).

Q: 사용자별 회의록은 어떻게 구분되나요?

A: minutes.user_id 컬럼으로 구분됩니다.

• NULL: AI 통합 회의록
• NOT NULL: 개인별 회의록 (각 참석자마다 생성)

Q: AI 분석은 모든 회의록을 처리하나요?

A: 아니요. 통합 회의록(user_id=NULL)만 분석합니다.
개인별 회의록(user_id NOT NULL)은 개인 기록용이며 AI 분석 대상이 아닙니다.

Q: agenda_sections와 minutes_sections의 차이는?

A:

• minutes_sections: 사용자가 작성한 순차적 회의록 섹션
• agenda_sections: AI가 분석한 안건별 구조화된 요약

Q: Todo는 어디에 저장되나요?

A: 두 곳에 저장 가능합니다.

1. agenda_sections.todos (JSON): 안건별 요약의 일부
2. todos 테이블: 상세 관리 필요시만

---

성능 최적화 팁

복합 인덱스 활용

-- 가장 중요한 쿼리 (V3)
SELECT * FROM minutes 
WHERE meeting_id = ? AND user_id = ?;
  └─ 인덱스: idx_minutes_meeting_user (meeting_id, user_id)

추천 추가 인덱스

CREATE INDEX idx_minutes_status_created 
  ON minutes(status, created_at DESC);

CREATE INDEX idx_agenda_meeting_created 
  ON agenda_sections(meeting_id, created_at DESC);

쿼리 패턴

-- 통합 회의록 조회 (가장 흔함)
SELECT m.*, ms.* FROM minutes m
LEFT JOIN minutes_sections ms ON m.id = ms.minutes_id
WHERE m.meeting_id = ? AND m.user_id IS NULL

-- 개인 회의록 조회
SELECT m.*, ms.* FROM minutes m
LEFT JOIN minutes_sections ms ON m.id = ms.minutes_id
WHERE m.meeting_id = ? AND m.user_id = ?

-- AI 분석 결과 조회
SELECT * FROM agenda_sections 
WHERE meeting_id = ? ORDER BY agenda_number

---

문서 읽기 순서 추천

1단계: 빠른 이해 (5분)

→ SCHEMA-REPORT-SUMMARY.md의 Executive Summary만 읽기

2단계: 구조 이해 (15분)

→ database-diagram.puml (다이어그램 확인)
→ data-flow-diagram.md의 Phase 1~7 읽기

3단계: 상세 이해 (30분)

→ SCHEMA-REPORT-SUMMARY.md 전체 읽기
→ database-schema-analysis.md의 핵심 섹션 읽기

4단계: 개발 참고 (필요시)

→ database-schema-analysis.md의 쿼리 예시
→ data-flow-diagram.md의 인덱스 활용 섹션

---

개발 체크리스트

회의록 작성 기능 개발시:

데이터 저장

• 회의록 내용은 minutes_sections.content에 저장
• minutes 테이블에는 메타데이터만 저장 (title, status)
• 회의 종료시 minutes.user_id 값 확인 (NULL vs 사용자ID)

AI 분석

• 통합 회의록(user_id=NULL)만 AI 분석 대상으로 처리
• agenda_sections은 통합 회의록에만 생성
• ai_summaries에 전체 결과 캐싱

쿼리 성능

• 복합 인덱스 활용: idx_minutes_meeting_user
• 조회시 WHERE meeting_id AND user_id 조건 사용
• 기존 인덱스 모두 생성 확인

데이터 무결성

• 회의 종료시 ended_at 기록 (V3)
• 최종화시 minutes_sections locked 처리
• AI 추출 Todo의 extraction_confidence 값 확인

---

관련 파일 위치

마이그레이션:

/Users/jominseo/HGZero/meeting/src/main/resources/db/migration/
├─ V2__create_meeting_participants_table.sql
├─ V3__add_meeting_end_support.sql
└─ V4__add_todos_to_agenda_sections.sql

엔티티:

/Users/jominseo/HGZero/meeting/src/main/java/.../entity/
├─ MeetingEntity.java
├─ MinutesEntity.java
├─ MinutesSectionEntity.java
├─ AgendaSectionEntity.java [V3]
├─ TodoEntity.java
└─ MeetingParticipantEntity.java [V2]

서비스:

/Users/jominseo/HGZero/meeting/src/main/java/.../service/
├─ MinutesService.java
├─ MinutesSectionService.java
└─ MinutesAnalysisEventConsumer.java (비동기 AI 분석)

---

지원

이 문서에 대한 추가 질문이나 불명확한 부분이 있으면:

1. SCHEMA-REPORT-SUMMARY.md의 "핵심 질문 답변" 섹션 확인
2. database-schema-analysis.md에서 상세 내용 검색
3. data-flow-diagram.md에서 흐름도 재확인

---

문서 작성일: 2025-10-28
분석 대상: Meeting Service (feat/meeting-ai 브랜치)
마이그레이션 버전: V1~V4
상태: 완료 및 검증됨