Files

김보곤 e7bc9232fa docs: [email] features/email 기능 문서 추가

- features/email/README.md 신규 생성 (기능 개요, 아키텍처, 테이블, 서비스, 라우트)
- INDEX.md features 섹션에 이메일 시스템 항목 추가

2026-03-12 12:19:28 +09:00

5.7 KiB

Raw Blame History

이메일 시스템 (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 사용

5.7 KiB Raw Blame History