# UML[체크] - 사용자 메일 관리 시스템

## 공정 상태
**진행률: 90%** (IMAP 완성, POP3 미구현)

---

## 구현 체크리스트

### 데이터베이스
- [x] DB 마이그레이션 작성 (user_mail_accounts 테이블 생성)

### 패키지 설치
- [ ] npm install node-pop3 (설치됨, 서비스 미구현)

### 백엔드 서비스 계층
- [x] userMailAccountService.ts (DB CRUD)
- [x] userMailImapService.ts (IMAP 프로토콜)
- [x] userMailSmtpService.ts (SMTP 발송)
- [x] imapConnectionPool.ts (IMAP 연결 풀)
- [x] mailCache.ts (메일 캐시)
- [ ] userMailPop3Service.ts (POP3 프로토콜 - 미구현)

### 백엔드 API 계층
- [x] userMailController.ts (요청 처리)
- [x] userMailRoutes.ts (라우트 정의)
- [x] app.ts에 userMailRoutes 등록 (`/api/user-mail`)

### 프론트엔드 API 클라이언트
- [x] frontend/lib/api/userMail.ts

### 프론트엔드 페이지
- [x] frontend/app/(main)/mail/imap/page.tsx
- [x] frontend/app/(main)/mail/imap/ComposeDialog.tsx (메일 작성)
- [ ] frontend/app/(main)/mail/pop3/page.tsx (미구현)

### 페이지 등록
- [x] AdminPageRenderer.tsx에 /mail/imap 등록
- [ ] AdminPageRenderer.tsx에 /mail/pop3 등록 (미구현)

---

## 구현된 IMAP 기능

### 계정 관리
- [x] 계정 추가 (연결 테스트 후 저장)
- [x] 계정 수정
- [x] 계정 삭제
- [x] 연결 테스트 (저장 전 자동 + 수동)

### 메일 조회
- [x] SSE 스트리밍으로 메일 목록 로드 (20개씩)
- [x] 이전 메일 더 보기 (무한 스크롤 방식)
- [x] 메일 상세 조회 (HTML/텍스트 본문)
- [x] 폴더별 메일 조회 (INBOX, 휴지통, 스팸 등)
- [x] 새로고침 버튼

### 메일 관리
- [x] 읽음 처리 (클릭 시 자동, IMAP \Seen 플래그)
- [x] 메일 삭제 (\Trash 특수 폴더로 이동 - Gmail 호환)
- [x] 메일 이동 (폴더 간 이동)

### 첨부파일
- [x] 첨부파일 목록 표시 (pill 형태)
- [x] 첨부파일 다운로드 (ReadableStream 진행바 표시)
- [x] Content-Length 헤더 지원 (정확한 진행률)

### 발신
- [x] 메일 작성 / 발송 (SMTP)
- [x] 답장 (Re: 제목, inReplyTo 헤더)
- [x] 전달 (Fwd: 제목, 원본 본문 인용)

### UI
- [x] 3단 패널 레이아웃 (계정 / 메일 목록 / 상세)
- [x] 폴더 목록 (unseen 카운트 표시)
- [x] 읽음/삭제 후 unseen 카운트 자동 갱신
- [x] 검색 (제목/발신자 클라이언트 필터)

---

## 검증 체크리스트

### 데이터베이스
- [x] `user_mail_accounts` 테이블 존재 확인
- [x] 테이블 스키마 정확성 확인

### 계정 관리 API
- [x] POST `/api/user-mail/accounts` - 계정 생성
- [x] GET `/api/user-mail/accounts` - 사용자 계정 목록
- [x] PUT `/api/user-mail/accounts/:id` - 계정 수정
- [x] DELETE `/api/user-mail/accounts/:id` - 계정 삭제
- [x] POST `/api/user-mail/accounts/:id/test` - 연결 테스트
- [x] POST `/api/user-mail/test-connection` - 직접 연결 테스트

### 메일 API
- [x] GET `/api/user-mail/accounts/:id/mails/stream` - 스트리밍 목록
- [x] GET `/api/user-mail/accounts/:id/mails/:seqno` - 상세 조회
- [x] POST `/api/user-mail/accounts/:id/mails/:seqno/mark-read` - 읽음 처리
- [x] DELETE `/api/user-mail/accounts/:id/mails/:seqno` - 삭제 (휴지통 이동)
- [x] POST `/api/user-mail/accounts/:id/mails/:seqno/move` - 이동
- [x] GET `/api/user-mail/accounts/:id/folders` - 폴더 목록
- [x] GET `/api/user-mail/accounts/:id/folders/:folder/mails/stream` - 폴더별 스트리밍
- [x] GET `/api/user-mail/accounts/:id/mails/:seqno/attachments` - 첨부파일 목록
- [x] GET `/api/user-mail/accounts/:id/mails/:seqno/attachment/:partId` - 첨부파일 다운로드
- [x] POST `/api/user-mail/accounts/:id/send` - 메일 발송

### 사용자 격리 검증
- [x] 모든 쿼리에 WHERE user_id = $n 포함 (DB 레벨 강제)
- [x] 다른 user_id로 계정 접근 시 404 반환

### 프론트엔드 페이지
- [x] `/mail/imap` 페이지 접속 및 동작
- [x] Gmail IMAP 연동 확인
- [x] 메일 목록 → 상세 → 읽음 처리
- [x] 첨부파일 다운로드 진행바
- [x] 메일 삭제 → Gmail 휴지통 이동 확인
- [x] 답장/전달 발송 확인

---

## 알려진 이슈 및 주의사항

### 1. 메일 삭제 방식
- `\Trash` 특수 폴더로 이동 (EXPUNGE 아님)
- Gmail 호환: `[Gmail]/휴지통`으로 자동 라우팅
- 폴더 없으면 `messageDelete` fallback (영구 삭제 주의)

### 2. 첨부파일 진행바
- Content-Length 헤더 기반 진행률 계산
- imapflow `meta.size`로 헤더 설정
- totalSize fallback: `getUserMailAttachments`의 size 필드 사용

### 3. IMAP 연결 풀
- 계정당 1개 연결 유지 (maxIdleMs: 5분)
- busy 상태 시 큐잉 처리
- 연결 끊김 시 자동 재연결

### 4. 캐시
- 메일 목록: 60초 TTL
- 메일 상세: 5분 TTL
- 읽음/삭제/이동 시 해당 캐시 무효화

### 5. POP3 미구현
- `node-pop3` 패키지 설치됨
- 서비스 파일 미작성
- 팀장 지시 후 구현 예정

---

## 변경 이력

| 날짜 | 버전 | 내용 |
|------|------|------|
| 2026-03-27 | v1.0 | 초안 작성 |
| 2026-03-30 | v2.0 | IMAP 전 기능 구현 완료 (메일 조회/삭제/이동/첨부/발송/답장/전달/폴더/진행바) |

---

## 관련 문서

- [UML[계획]-user-mail.md](./UML[계획]-user-mail.md): 아키텍처 및 설계