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

## 프로젝트 배경

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

---

## 핵심 기술 결정 사항

### 1. 페이지 등록 방식: 하드코딩
**선택**: 하드코딩 (AdminPageRenderer.tsx에 직접 등록)

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

**구현**:
```typescript
// 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 패턴

**참조 사항**:
```typescript
// IMAP 연결 구조, 메일 검색 쿼리, 메일 수신 처리 방식
```

### encryptionService.ts
- 비밀번호 암호화/복호화
- DB 저장 시 암호화, 조회 시 복호화

**사용 방식**:
```typescript
// 저장: encryptionService.encrypt(password)
// 조회: encryptionService.decrypt(encrypted_password)
```

### AdminPageRenderer.tsx
- 기존 페이지 하드코딩 구조
- 페이지 등록 형식 및 라벨 지정 방식

**추가 위치**:
```typescript
// 기존 페이지 목록에 /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 | 초안 작성 |