vexplor_dev/docs/yc/UML[체크]-user-mail.md

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

공정 상태

진행률: 90% (IMAP 완성, POP3 미구현)

---

구현 체크리스트

데이터베이스

• DB 마이그레이션 작성 (user_mail_accounts 테이블 생성)

패키지 설치

• npm install node-pop3 (설치됨, 서비스 미구현)

백엔드 서비스 계층

• userMailAccountService.ts (DB CRUD)
• userMailImapService.ts (IMAP 프로토콜)
• userMailSmtpService.ts (SMTP 발송)
• imapConnectionPool.ts (IMAP 연결 풀)
• mailCache.ts (메일 캐시)
• userMailPop3Service.ts (POP3 프로토콜 - 미구현)

백엔드 API 계층

• userMailController.ts (요청 처리)
• userMailRoutes.ts (라우트 정의)
• app.ts에 userMailRoutes 등록 (/api/user-mail)

프론트엔드 API 클라이언트

• frontend/lib/api/userMail.ts

프론트엔드 페이지

• frontend/app/(main)/mail/imap/page.tsx
• frontend/app/(main)/mail/imap/ComposeDialog.tsx (메일 작성)
• frontend/app/(main)/mail/pop3/page.tsx (미구현)

페이지 등록

• AdminPageRenderer.tsx에 /mail/imap 등록
• AdminPageRenderer.tsx에 /mail/pop3 등록 (미구현)

---

구현된 IMAP 기능

계정 관리

• 계정 추가 (연결 테스트 후 저장)
• 계정 수정
• 계정 삭제
• 연결 테스트 (저장 전 자동 + 수동)

메일 조회

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

메일 관리

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

첨부파일

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

발신

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

UI

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

---

검증 체크리스트

데이터베이스

• user_mail_accounts 테이블 존재 확인
• 테이블 스키마 정확성 확인

계정 관리 API

• POST /api/user-mail/accounts - 계정 생성
• GET /api/user-mail/accounts - 사용자 계정 목록
• PUT /api/user-mail/accounts/:id - 계정 수정
• DELETE /api/user-mail/accounts/:id - 계정 삭제
• POST /api/user-mail/accounts/:id/test - 연결 테스트
• POST /api/user-mail/test-connection - 직접 연결 테스트

메일 API

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

사용자 격리 검증

• 모든 쿼리에 WHERE user_id = $n 포함 (DB 레벨 강제)
• 다른 user_id로 계정 접근 시 404 반환

프론트엔드 페이지

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

---

알려진 이슈 및 주의사항

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: 아키텍처 및 설계