# UML[계획] - 사용자 메일 관리 시스템

## 개요

벡스플로우(Vexflow) 사용자 메일 관리 페이지 구현 프로젝트입니다. 외부 메일 서버(POP3/IMAP)와 연동하여 사용자가 본인의 메일 계정을 등록하고 벡스플로우 내에서 메일을 조회할 수 있는 기능을 제공합니다.

### 현재 동작
- Admin 메일 시스템만 존재
- JSON 파일 기반 저장소
- 사용자 구분 없음

### 변경 후 동작
- 사용자가 외부 메일 계정(IMAP 또는 POP3) 등록
- 벡스플로우에서 해당 계정의 메일 조회
- PostgreSQL 기반 계정 저장 및 관리
- 사용자별 격리(user_id 기반)

---

## 아키텍처

```
┌─────────────┐
│   사용자     │
│  (Frontend)  │
└──────┬──────┘
       │
       ├─→ /mail/imap 페이지
       └─→ /mail/pop3 페이지
              │
              ↓
       ┌──────────────────┐
       │   userMail.ts    │ (API 클라이언트)
       │  (lib/api/)      │
       └────────┬─────────┘
                │
                ↓
       ┌────────────────────────────┐
       │  /api/user-mail/* 라우트   │
       │  (userMailController)      │
       └────────┬───────────────────┘
                │
        ┌───────┴────────┐
        │                │
        ↓                ↓
   ┌────────────────┐  ┌──────────────┐
   │ userMailAccount│  │ userMailImap │
   │  Service       │  │ Service      │
   │ (PostgreSQL)   │  │ (IMAP)       │
   └────────────────┘  │              │
                       └──────────────┘
                              │
                              ↓
                       ┌──────────────────┐
                       │  외부 IMAP 서버   │
                       └──────────────────┘

   또는

                       ┌──────────────────┐
                       │ userMailPop3     │
                       │ Service          │
                       │ (POP3)           │
                       └──────────────────┘
                              │
                              ↓
                       ┌──────────────────┐
                       │  외부 POP3 서버   │
                       └──────────────────┘
```

---

## 신규 파일 목록

### 백엔드 (Node.js/Express)

| 파일 경로 | 역할 |
|----------|------|
| `src/services/userMailAccountService.ts` | DB 계정 관리 (생성, 조회, 삭제, 수정) |
| `src/services/userMailImapService.ts` | IMAP 프로토콜 연결 및 메일 조회 |
| `src/services/userMailPop3Service.ts` | POP3 프로토콜 연결 및 메일 조회 |
| `src/controllers/userMailController.ts` | API 엔드포인트 처리 |
| `src/routes/userMailRoutes.ts` | 라우트 정의 |

### 프론트엔드 (React/TypeScript)

| 파일 경로 | 역할 |
|----------|------|
| `frontend/lib/api/userMail.ts` | API 클라이언트 |
| `frontend/app/(main)/mail/imap/page.tsx` | IMAP 메일 관리 페이지 |
| `frontend/app/(main)/mail/pop3/page.tsx` | POP3 메일 관리 페이지 |

---

## 수정 파일 목록

| 파일 경로 | 변경 사항 |
|----------|---------|
| `src/runMigration.ts` | 마이그레이션 스크립트에 user_mail_accounts 테이블 추가 |
| `src/app.ts` | userMailRoutes 등록 |
| `src/components/AdminPageRenderer.tsx` | /mail/imap, /mail/pop3 페이지 하드코딩 등록 (2줄) |

---

## 데이터베이스 스키마

### user_mail_accounts 테이블

```sql
CREATE TABLE user_mail_accounts (
  id SERIAL PRIMARY KEY,
  user_id INT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  protocol VARCHAR(10) NOT NULL CHECK (protocol IN ('imap', 'pop3')),
  host VARCHAR(255) NOT NULL,
  port INT NOT NULL DEFAULT 993,
  use_tls BOOLEAN DEFAULT TRUE,
  username VARCHAR(255) NOT NULL,
  password TEXT NOT NULL, -- 암호화됨 (encryptionService 사용)
  status VARCHAR(20) DEFAULT 'active' CHECK (status IN ('active', 'inactive')),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id, protocol, host, username)
);
```

---

## 설계 원칙

### 1. 사용자 격리
- 모든 API 요청에서 현재 사용자의 user_id 검증
- 다른 사용자의 계정/메일 접근 불가

### 2. 프로토콜별 서비스 분리
- userMailImapService.ts: IMAP 전용
- userMailPop3Service.ts: POP3 전용
- 각 서비스는 독립적으로 동작

### 3. 기존 기능 재활용
- `encryptionService`: 비밀번호 암호화/복호화
- `mailparser`: 메일 본문 파싱
- `imap` 패키지: IMAP 연결(기존 mailReceiveBasicService 참조)

### 4. 기존 Admin 메일 시스템과 분리
- 새로운 테이블, 서비스, 라우트로 완전 독립
- JSON 파일 기반 방식 미사용

---

## 주요 API 엔드포인트

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/user-mail/accounts` | 새 계정 등록 |
| GET | `/api/user-mail/accounts` | 사용자 계정 목록 |
| GET | `/api/user-mail/accounts/:id` | 계정 상세 조회 |
| PUT | `/api/user-mail/accounts/:id` | 계정 수정 |
| DELETE | `/api/user-mail/accounts/:id` | 계정 삭제 |
| POST | `/api/user-mail/accounts/:id/test` | 연결 테스트 |
| GET | `/api/user-mail/accounts/:id/mails` | 메일 목록 조회 |

---

## 변경 이력

| 날짜 | 버전 | 내용 |
|------|------|------|
| 2026-03-27 | v1.0 | 초안 작성 |