# 이메일 시스템 (Tenant Email)

> **상태**: Phase 1~2 구현 완료
> **최종 갱신**: 2026-03-12

---

## 1. 개요

SAM 멀티테넌시 환경에서 테넌트별 이메일 발송을 관리하는 시스템.
본사(코드브릿지엑스)가 MNG 관리 화면에서 각 테넌트의 메일 설정을 대행 관리한다.

**핵심 기능:**
- 테넌트별 SMTP 설정 및 발송 격리
- 한국 메일 제공자 프리셋 (Gmail, 네이버, 네이버웍스, 다음, MS365, 카페24, 가비아)
- SMTP 연결 테스트 (SmtpConnectionTester)
- 발송 기록 및 일일 쿼터 관리
- Fallback: 자체 SMTP 실패 시 플랫폼 기본 SMTP로 재시도

---

## 2. 아키텍처 (3-Layer)

```
┌─────────────────────────────────────────────────────────┐
│  Layer 1: 테넌트 메일 설정 (tenant_mail_configs)          │
│  SMTP 설정, 발신자 주소, 브랜딩 정보                       │
├─────────────────────────────────────────────────────────┤
│  Layer 2: 메일 발송 서비스 (TenantMailService)             │
│  테넌트 설정 자동 적용, 큐 발송, Fallback                   │
├─────────────────────────────────────────────────────────┤
│  Layer 3: 발송 기록 (mail_logs)                            │
│  발송 이력, 상태 추적, 일일 쿼터 관리                       │
└─────────────────────────────────────────────────────────┘
```

---

## 3. 테이블

| 테이블 | 설명 | 주요 컬럼 |
|--------|------|----------|
| `tenant_mail_configs` | 테넌트별 메일 설정 (1:1) | `tenant_id`, `provider`, `from_address`, `from_name`, `is_verified`, `daily_limit`, `options` |
| `mail_logs` | 발송 기록 | `tenant_id`, `mailable_type`, `to_address`, `from_address`, `subject`, `status`, `sent_at`, `options` |

**마이그레이션 위치**: `api/database/migrations/2026_03_12_*`

---

## 4. 모델

| 모델 | 위치 | Traits |
|------|------|--------|
| `TenantMailConfig` | API + MNG | BelongsToTenant, SoftDeletes, Auditable |
| `MailLog` | API + MNG | BelongsToTenant |

**`tenant_mail_configs.options` JSON 구조:**

| 키 | 설명 |
|----|------|
| `smtp.*` | SMTP 접속 정보 (host, port, username, password, encryption) |
| `preset` | 프리셋 식별자 (gmail, naver, custom 등) |
| `branding.*` | 메일 템플릿 브랜딩 (로고, 컬러, 회사명, 푸터) |
| `connection_test.*` | 마지막 SMTP 연결 테스트 결과 |

---

## 5. 서비스 (MNG)

| 서비스 | 설명 |
|--------|------|
| `TenantMailService` | 메일 발송 (설정 조회 → 쿼터 확인 → SMTP 구성 → 발송 → 로그) |
| `SmtpConnectionTester` | SMTP 연결 테스트 (TCP → TLS → AUTH → 테스트 메일) |

**에러 코드:**

| 코드 | 설명 |
|------|------|
| `CONN_REFUSED` | SMTP 서버 접속 거부 |
| `TLS_FAILED` | TLS 핸드셰이크 실패 |
| `AUTH_FAILED` | 인증 실패 (앱 비밀번호 확인) |
| `TIMEOUT` | 연결 시간 초과 |

---

## 6. MNG 파일 구조

```
mng/
├── app/Http/Controllers/System/
│   └── TenantMailConfigController.php
├── app/Services/Mail/
│   ├── TenantMailService.php
│   └── SmtpConnectionTester.php
├── config/
│   └── mail-presets.php
└── resources/views/system/tenant-mail/
    ├── index.blade.php       (테넌트 목록)
    └── edit.blade.php        (설정 폼)
```

---

## 7. MNG 라우트

| Method | Path | 설명 |
|--------|------|------|
| `GET` | `/system/tenant-mail` | 테넌트 메일 설정 목록 |
| `GET` | `/system/tenant-mail/presets` | SMTP 프리셋 JSON |
| `GET` | `/system/tenant-mail/{tenant}/edit` | 설정 폼 |
| `PUT` | `/system/tenant-mail/{tenant}` | 설정 저장 |
| `POST` | `/system/tenant-mail/{tenant}/test` | SMTP 연결 테스트 |

---

## 8. 연동 방식 (3단계 전략)

| Phase | 방식 | 설명 | 상태 |
|-------|------|------|------|
| Phase 1 | 플랫폼 발송 + Reply-To | SAM 공용 SMTP로 발송, 테넌트 Reply-To 적용 | ✅ 구현 완료 |
| Phase 2 | SMTP 릴레이 + 프리셋 | 테넌트 자체 SMTP로 발송, 프리셋 자동 채움 | ✅ 구현 완료 |
| Phase 3 | OAuth2 연동 | Google/MS OAuth2 토큰 기반 발송 | 🟢 향후 |

---

## 9. 보안 규칙

```
✅ SMTP 비밀번호: encrypt()/decrypt()로 암호화 저장
✅ mail_logs에 메일 본문 저장 금지 (메타데이터만)
✅ API 응답에 SMTP 비밀번호 노출 금지 (hidden 처리)
✅ TenantScope 자동 적용 (테넌트 격리)
❌ Mail::to() 직접 호출 금지 → TenantMailService 사용
```

---

## 관련 문서

- [이메일 발송 정책](../../dev/standards/email-policy.md) — 내부 발송 아키텍처, 테이블 설계, 쿼터 관리, 서비스 설계
- [테넌트 이메일 연동 가이드](../../dev/guides/tenant-email-integration-guide.md) — SMTP 프리셋, MNG 관리 화면, 연결 테스트, 테넌트 사전 준비 안내
- [테넌트 DB 구조](../../system/database/tenants.md)
- [options JSON 컬럼 정책](../../dev/standards/options-column-policy.md)
- [전자서명 기능](../esign/README.md) — 메일 발송이 많은 주요 기능

---

**최종 업데이트**: 2026-03-12