vexplor_dev/docs/yc/UML[맥락]-user-mail.md

UML[맥락] - 사용자 메일 관리 시스템

프로젝트 배경

추진 이유

• 팀장 지시로 POP3 구현 필요
• IMAP 허용 여부 확인 대기 중
• 두 프로토콜 모두 구현 후 비교하여 최적 솔루션 채택

---

핵심 기술 결정 사항

1. 페이지 등록 방식: 하드코딩

선택: 하드코딩 (AdminPageRenderer.tsx에 직접 등록)

사유:

• 컴포넌트 레지스트리에 추가할 권한 없음
• 간단한 추가 작업으로 빠른 구현 가능

구현:

// AdminPageRenderer.tsx에 2줄 추가
{path: '/mail/imap', label: '메일(IMAP)', component: () => <IMapPage /> },
{path: '/mail/pop3', label: '메일(POP3)', component: () => <Pop3Page /> },

---

2. 저장소: PostgreSQL (Admin 메일과 완전 분리)

선택: PostgreSQL user_mail_accounts 테이블

사유:

• Admin 메일 시스템(JSON 파일 기반)과 완전 독립
• 사용자별 격리 용이 (user_id 기반)
• 확장성 및 성능 이점

결과:

• 기존 Admin 메일: JSON 파일 유지
• 신규 사용자 메일: PostgreSQL 관리

---

3. POP3 메일 삭제 정책: 서버 유지

선택: DELE 명령 미호출 (서버 메일 유지)

사유:

• 데이터 손실 방지
• 사용자 실수로 인한 피해 최소화
• 벡스플로우는 조회만 수행

구현:

• userMailPop3Service.ts에서 RETR 후 DELE 호출 안 함
• 서버의 자동 정리 정책에 의존

---

4. 페이지별 프로토콜 고정

선택: 페이지당 프로토콜 1개로 제한

구현:

• /mail/imap → IMAP 계정만 표시/관리
• /mail/pop3 → POP3 계정만 표시/관리

사유:

• UI 단순화
• 프로토콜별 메일 구조 차이 처리 용이
• 사용자 혼동 최소화

---

관련 기존 코드 참조

mailReceiveBasicService.ts

• IMAP 연결 및 메일 조회 로직
• 메일 파싱 및 저장 방식
• Error handling 패턴

참조 사항:

// IMAP 연결 구조, 메일 검색 쿼리, 메일 수신 처리 방식

encryptionService.ts

• 비밀번호 암호화/복호화
• DB 저장 시 암호화, 조회 시 복호화

사용 방식:

// 저장: encryptionService.encrypt(password)
// 조회: encryptionService.decrypt(encrypted_password)

AdminPageRenderer.tsx

• 기존 페이지 하드코딩 구조
• 페이지 등록 형식 및 라벨 지정 방식

추가 위치:

// 기존 페이지 목록에 /mail/imap, /mail/pop3 추가

---

기술 스택 및 패키지

기존 패키지 (재활용)

패키지	버전	용도
imap	-	IMAP 연결
mailparser	-	메일 파싱
pg	-	PostgreSQL 클라이언트

신규 패키지

패키지	버전	용도
node-pop3	latest	POP3 연결

---

핵심 고려 사항

보안

1. 메일 계정 비밀번호는 항상 암호화 상태로 저장
2. 사용자 격리: user_id 기반 접근 제어
3. 외부 서버 연결 정보는 민감: 환경변수 활용

성능

1. 메일 조회는 페이지네이션 처리
2. 연결 테스트는 별도 API (현재 메일 검색과 분리)
3. 대량 메일 처리 시 비동기 처리

에러 처리

1. 네트워크 오류: 재시도 로직
2. 인증 실패: 명확한 에러 메시지 제공
3. DB 오류: 트랜잭션 롤백

---

변경 이력

날짜	내용
2026-03-27	초안 작성