170 lines
6.0 KiB
Markdown
170 lines
6.0 KiB
Markdown
# 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 | 초안 작성 |
|