From e7bc9232faa67fa08f9978252472079eecf0c751 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Thu, 12 Mar 2026 07:56:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[email]=20features/email=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - features/email/README.md 신규 생성 (기능 개요, 아키텍처, 테이블, 서비스, 라우트) - INDEX.md features 섹션에 이메일 시스템 항목 추가 --- INDEX.md | 3 +- features/email/README.md | 148 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 features/email/README.md diff --git a/INDEX.md b/INDEX.md index cd00bb8..90cd6c7 100644 --- 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 설정, 프리셋, 연결 테스트) | --- diff --git a/features/email/README.md b/features/email/README.md new file mode 100644 index 0000000..8d50b25 --- /dev/null +++ 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