ERP-node/메일관리_기능_리스트.md

# 메일 관리 시스템 - 구현된 기능 리스트

## 📅 작성일: 2025-10-01

---

## 🎯 전체 개요

메일 관리 시스템은 **발송**과 **수신** 두 가지 주요 기능을 제공합니다.
- 저장 방식: **파일 시스템 기반** (DB 사용 안 함)
- 보안: AES-256 암호화, XSS 방지
- 프로토콜: SMTP (발송), IMAP (수신)

---

## 📤 메일 발송 시스템

### 1. 메일 계정 관리 (`/admin/mail/accounts`)
**기능:**
- ✅ SMTP 계정 CRUD (생성/조회/수정/삭제)
- ✅ 계정 활성화/비활성화
- ✅ SMTP 연결 테스트
- ✅ 일일 발송 제한 설정
- ✅ 비밀번호 암호화 저장

**주요 파일:**
- Frontend: `frontend/app/(main)/admin/mail/accounts/page.tsx`
- Frontend: `frontend/components/mail/MailAccountModal.tsx`
- Frontend: `frontend/components/mail/MailAccountTable.tsx`
- Backend: `backend-node/src/services/mailAccountFileService.ts`
- Backend: `backend-node/src/controllers/mailAccountFileController.ts`
- Backend: `backend-node/src/routes/mailAccountFileRoutes.ts`
- 저장소: `uploads/mail-accounts/*.json`

**API 엔드포인트:**
- `GET /api/mail/accounts` - 계정 목록
- `GET /api/mail/accounts/:id` - 계정 상세
- `POST /api/mail/accounts` - 계정 생성
- `PUT /api/mail/accounts/:id` - 계정 수정
- `DELETE /api/mail/accounts/:id` - 계정 삭제
- `POST /api/mail/accounts/:id/test-connection` - 연결 테스트

---

### 2. 메일 템플릿 관리 (`/admin/mail/templates`)
**기능:**
- ✅ 드래그 앤 드롭 템플릿 디자이너
- ✅ 컴포넌트 기반 템플릿 (텍스트/버튼/이미지/여백)
- ✅ 실시간 미리보기
- ✅ 템플릿 CRUD
- ✅ 템플릿 복사 기능
- ✅ 카테고리별 분류
- ✅ 동적 변수 지원 (예: `{customer_name}`)

**주요 파일:**
- Frontend: `frontend/app/(main)/admin/mail/templates/page.tsx`
- Frontend: `frontend/components/mail/MailDesigner.tsx`
- Frontend: `frontend/components/mail/MailTemplateCard.tsx`
- Frontend: `frontend/components/mail/MailTemplatePreviewModal.tsx`
- Frontend: `frontend/components/mail/MailTemplateEditorModal.tsx`
- Backend: `backend-node/src/services/mailTemplateFileService.ts`
- Backend: `backend-node/src/controllers/mailTemplateFileController.ts`
- Backend: `backend-node/src/routes/mailTemplateFileRoutes.ts`
- 저장소: `uploads/mail-templates/*.json`

**API 엔드포인트:**
- `GET /api/mail/templates-file` - 템플릿 목록
- `GET /api/mail/templates-file/:id` - 템플릿 상세
- `POST /api/mail/templates-file` - 템플릿 생성
- `PUT /api/mail/templates-file/:id` - 템플릿 수정
- `DELETE /api/mail/templates-file/:id` - 템플릿 삭제

---

### 3. 메일 발송 (`/admin/mail/send`)
**기능:**
- ✅ 단일 메일 발송
- ✅ 계정 선택
- ✅ 템플릿 선택
- ✅ 수신자 입력 (다중 수신자 지원)
- ✅ 동적 변수 입력
- ✅ 실시간 미리보기
- ✅ 발송 전 미리보기
- ✅ 제목 편집

**주요 파일:**
- Frontend: `frontend/app/(main)/admin/mail/send/page.tsx`
- Backend: `backend-node/src/services/mailSendSimpleService.ts`
- Backend: `backend-node/src/controllers/mailSendSimpleController.ts`
- Backend: `backend-node/src/routes/mailSendSimpleRoutes.ts`

**API 엔드포인트:**
- `POST /api/mail/send` - 메일 발송

---

### 4. 메일 대시보드 (`/admin/mail/dashboard`)
**기능:**
- ✅ 통계 대시보드
- ✅ 계정 상태 요약
- ✅ 템플릿 개수
- ✅ 빠른 접근 링크

**주요 파일:**
- Frontend: `frontend/app/(main)/admin/mail/dashboard/page.tsx`

---

## 📥 메일 수신 시스템

### 5. 메일 수신함 (`/admin/mail/receive`)

#### 5-1. 메일 목록 (Step 2)
**기능:**
- ✅ IMAP 프로토콜 연결
- ✅ 받은 메일 목록 조회 (최근 50개)
- ✅ 메일 제목/발신자/날짜 표시
- ✅ 텍스트 미리보기 (최대 150자)
- ✅ 읽음/안읽음 상태 표시
- ✅ 첨부파일 유무 표시
- ✅ IMAP 연결 테스트

**API 엔드포인트:**
- `GET /api/mail/receive/:accountId` - 메일 목록
- `POST /api/mail/receive/:accountId/test-imap` - IMAP 연결 테스트

#### 5-2. 메일 상세보기 (Step 3)
**기능:**
- ✅ 메일 상세 조회
- ✅ HTML 본문 렌더링 (XSS 방지)
- ✅ 텍스트 본문 보기
- ✅ HTML/텍스트 토글
- ✅ 자동 읽음 처리
- ✅ CC/BCC 표시
- ✅ 첨부파일 목록
- ✅ 답장/전달 버튼 (UI만)

**주요 파일:**
- Frontend: `frontend/components/mail/MailDetailModal.tsx`

**API 엔드포인트:**
- `GET /api/mail/receive/:accountId/:seqno` - 메일 상세
- `POST /api/mail/receive/:accountId/:seqno/mark-read` - 읽음 표시

#### 5-3. 첨부파일 다운로드 (Step 4)
**기능:**
- ✅ 첨부파일 다운로드
- ✅ 안전한 파일명 생성
- ✅ 파일 크기 표시
- ✅ 파일 타입별 아이콘
- ✅ 임시 저장 (`uploads/mail-attachments/`)

**API 엔드포인트:**
- `GET /api/mail/receive/:accountId/:seqno/attachment/:index` - 첨부파일 다운로드

#### 5-4. 고급 기능 (Step 5)
**기능:**
- ✅ 통합 검색 (제목/발신자/내용)
- ✅ 필터링 (전체/읽지않음/읽음/첨부파일)
- ✅ 정렬 (날짜↓/날짜↑/발신자↑/발신자↓)
- ✅ 검색 결과 카운트
- ✅ 자동 새로고침 (30초마다)

**주요 파일:**
- Frontend: `frontend/app/(main)/admin/mail/receive/page.tsx`
- Backend: `backend-node/src/services/mailReceiveBasicService.ts`
- Backend: `backend-node/src/controllers/mailReceiveBasicController.ts`
- Backend: `backend-node/src/routes/mailReceiveBasicRoutes.ts`
- 저장소: `uploads/mail-attachments/`

---

## 🔒 보안 기능

### 암호화
- ✅ AES-256 암호화 (SMTP 비밀번호)
- ✅ 환경변수로 암호화 키 관리
- 파일: `backend-node/src/services/encryptionService.ts`

### XSS 방지
- ✅ DOMPurify로 HTML sanitization
- ✅ 허용된 태그/속성만 렌더링
- 라이브러리: `isomorphic-dompurify`

### 파일 보안
- ✅ 파일명 특수문자 제거
- ✅ 파일명 길이 제한 (200자)
- ✅ 타임스탬프 기반 중복 방지

---

## 🗂️ 파일 저장 구조

```
uploads/
├── mail-accounts/          # 메일 계정 (JSON)
│   ├── account-123.json
│   └── account-456.json
├── mail-templates/         # 메일 템플릿 (JSON)
│   ├── template-123.json
│   └── template-456.json
└── mail-attachments/       # 첨부파일 (원본 파일)
    ├── account123-45-1696123456789-document.pdf
    └── account123-45-1696123457890-image.jpg
```

---

## 📚 공통 API 클라이언트

**파일:** `frontend/lib/api/mail.ts`

**제공 함수:**
- 계정 관리: `getMailAccounts`, `createMailAccount`, `updateMailAccount`, `deleteMailAccount`, `testMailConnection`
- 템플릿 관리: `getMailTemplates`, `createMailTemplate`, `updateMailTemplate`, `deleteMailTemplate`
- 발송: `sendMail`, `extractTemplateVariables`, `renderTemplateToHtml`
- 수신: `getReceivedMails`, `getMailDetail`, `markMailAsRead`, `testImapConnection`

---

## 🔧 환경 설정

### 필수 환경변수
```bash
ENCRYPTION_KEY=ilshin-plm-mail-encryption-key-32characters-2024-secure
```

### 필수 디렉토리
```bash
mkdir -p uploads/mail-accounts
mkdir -p uploads/mail-templates
mkdir -p uploads/mail-attachments
```

### NPM 패키지
**Backend:**
- `nodemailer` - SMTP 메일 발송
- `imap`, `mailparser` - IMAP 메일 수신
- `@types/imap`, `@types/mailparser` - TypeScript 타입

**Frontend:**
- `isomorphic-dompurify` - HTML sanitization

---

## 📊 구현 통계

- **Frontend 페이지**: 5개
- **Frontend 컴포넌트**: 8개
- **Backend 서비스**: 5개
- **Backend 컨트롤러**: 5개
- **Backend 라우트**: 5개
- **API 엔드포인트**: 20개
- **총 파일 수**: ~30개

---

## 🎯 완성도

✅ **100% 완료**

모든 핵심 기능이 구현되었으며, 실제 운영 환경에서 사용 가능한 수준입니다.