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 마이그레이션 표시
- 주요 필드 강조

**다이어그램 생성**:
```bash
# 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` 테이블: 상세 관리 필요시만

---

## 성능 최적화 팁

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

### 추천 추가 인덱스
```sql
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);
```

### 쿼리 패턴
```sql
-- 통합 회의록 조회 (가장 흔함)
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  
**상태**: 완료 및 검증됨