vexplor_dev/docs/yc/UML[계획]-user-mail.md

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 테이블

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	초안 작성