docs: [email] features/email 기능 문서 추가

- features/email/README.md 신규 생성 (기능 개요, 아키텍처, 테이블, 서비스, 라우트) - INDEX.md features 섹션에 이메일 시스템 항목 추가
2026-03-12 07:56:03 +09:00
parent 73d64d4b03
commit e7bc9232fa
2 changed files with 150 additions and 1 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -1,7 +1,7 @@
 # SAM 문서 인덱스 (Claude Code용)

 > 작업 유형에 맞는 문서를 먼저 읽고 시작하세요.
-> 최종 갱신: 2026-03-11
+> 최종 갱신: 2026-03-12

 ---

@@ -152,6 +152,7 @@ DB 도메인별:
 | [quality-management/README.md](features/quality-management/README.md) | 품질관리 (제품검사, 실적신고) |
 | [approvals/README.md](features/approvals/README.md) | 결재관리 시스템 |
 | [approvals/mng-api-comparison.md](features/approvals/mng-api-comparison.md) | 결재관리 MNG↔API 비교 분석 및 React 구현 가이드 |
+| [email/README.md](features/email/README.md) | 이메일 시스템 (테넌트별 SMTP 설정, 프리셋, 연결 테스트) |

 ---

--- a/features/email/README.md
+++ b/features/email/README.md
@@ -0,0 +1,148 @@
+# 이메일 시스템 (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