162 lines
5.2 KiB
Markdown
162 lines
5.2 KiB
Markdown
# 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): 아키텍처 및 설계
|