Alphea App

SMS 채널 — AWS SNS provider 구현¶

commit:server|f6217a8

#426 의 SMS 발송 채널 (AWS SNS) 부분만 우선 구현. Kakao / SES / 배치 / 감사 테이블 등은 후속 작업.

이번 commit 에서 처리한 것¶

1. Provider abstraction (이미 #420 Phase A 에서 도입됨, 본 commit 에서 SNS 구현 추가)

• SmsClient trait + OutgoingMms / SmsSendOutcome / SmsError
• 신규 AwsSnsSmsClient (src/domain/sms/sns.rs)

2. AWS SNS Publish 호출

• AWS SDK default credential chain (env / shared / IAM Role 모두 지원)
• MessageAttribute 로 AWS.SNS.SMS.SMSType=Transactional 강제 — 한국 보상 코드 알림 용도라 거래성으로 발송
• 응답의 message_id 를 provider_message_id 로 반환

3. SNS 의 MMS 미지원 대응

• OutgoingMms.image_png 가 있으면 silently drop + debug 로그
• send_sms handler 가 본문에 항상 QR: https://... URL 을 포함시켜 수신자가 탭하여 QR 이미지 확인 가능 (MMS 지원 provider 든 아니든 동일)
• URL prefix 는 Config.public_admin_url (env PUBLIC_ADMIN_URL)

4. 한국 번호 → E.164 자동 변환

• to_e164_korea("010-1234-5678") → "+821012345678"
• 이미 + 로 시작하면 그대로 (국제번호 passthrough)
• 그 외 형식은 InvalidPhone 에러

5. 환경변수

SMS_PROVIDER=sns                     # "stub" (default) | "sns"
PUBLIC_ADMIN_URL=https://edge-admin.alphea.ai
AWS_REGION=ap-northeast-2
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
# 또는 IAM Role 사용 시 위 두 개 비움

docker-compose.yml 의 app 컨테이너에 위 env forward 완료.

발송 본문 예시¶

[Alphea] $1000 사용권이 발급되었습니다.

코드: ALPHEA-XXXX-XXXX-XXXX
유효기간: 2026-12-31

QR: https://edge-admin.alphea.ai/api/redeem-codes/ALPHEA-XXXX-XXXX-XXXX/qr.png

운영 적용 방법¶

1. AWS 콘솔에서 SNS SMS 활성화 + (운영 시) sender ID 사전 등록
2. .env 에 SMS_PROVIDER=sns + AWS_* 자격 증명 + PUBLIC_ADMIN_URL=https://edge-admin.alphea.ai 설정
3. docker compose up -d --build app
4. Dev Console → Redeem 탭 → Detail 에서 phone 등록 + Send SMS 클릭 → 실제 SMS 발송 확인

검증¶

• cargo build 성공 (AWS SDK ~30s)
• cargo test --lib 45 passed (sms 신규 3: E.164 변환 / passthrough / reject)
• cargo clippy --all-targets clean

본 commit 에서 미완료된 #426 범위 (후속 작업)¶

Provider 추가 가이드 (Kakao / SES 도 같은 패턴)¶

1. src/domain/sms/{kakao,ses}.rs 신설
2. SmsClient trait 구현
3. main::build_sms_client 의 match 에 분기 추가
4. config / .env / docker-compose 에 provider 별 env 추가

Email 채널 — AWS SES provider 구현 (default channel)¶

commit:server|49543d4

#426 의 email 채널 부분 구현. redeem 코드의 기본 발송 채널 로 email 도입 (SMS 는 optional secondary).

변경 요약¶

DB (migrations/0012_redeem_codes_email.sql) — additive

• redeem_codes.email TEXT (수령자 이메일)
• redeem_codes.last_email_sent_at TIMESTAMPTZ

Domain (src/domain/email/)

• EmailClient trait + OutgoingEmail (HTML / text / inline_png) + EmailSendOutcome / EmailError
• StubEmailClient — dev 용, 로그만
• AwsSesEmailClient (ses.rs):
  • SES v2 SendEmail with EmailContent::Raw
  • 직접 MIME 빌더: multipart/related → multipart/alternative (text/plain + text/html base64) + image/png inline (Content-ID: <qr@alphea>)
  • Subject 의 non-ASCII 는 RFC 2047 base64 encoded-word 로 감쌈 (=?UTF-8?B?...?=)
  • 본문은 모두 base64 인코딩하여 UTF-8 8bit 안전 회피
  • looks_like_email() 단순 검증

Config / 인프라

• email_provider: String (env EMAIL_PROVIDER, default "stub")
• email_from: String (env EMAIL_FROM, ses 일 때 필수)
• AppState.email: Arc<dyn EmailClient>
• main::build_email_client(provider, from) — ses/stub/unknown→stub fallback

Admin REST

• IssueCodesReq.email, UpdateCodeReq.email
• POST /api/redeem-codes/{code}/send-email:
  • Korean HTML body (코드 박스 + 만료일 + inline QR + fallback URL)
  • Plain text body (HTML 미지원 클라이언트용)
  • QR PNG attached as inline image (cid:qr@alphea)
  • 성공 시 stamp_email_sent

Dev Console UI

• Issue 폼: email 필드를 default channel 로 상단 배치, phone 은 grid 하단으로 optional secondary 로 강등
• Detail 편집기: email/note/phone 편집 + Save / Send Email / Send SMS 3 버튼 + last email/SMS 시각 표시
• JS: rcSendEmail() 신규, rcFillEditor 가 last_email_sent_at 표시

Email 본문 (HTML, 한국어)

• Subject: [Alphea] $1000 사용권 코드
• Body: 코드 박스 + 유효기간 + inline QR (240px) + fallback link
• Plain text fallback 동봉

Provider 선택¶

EMAIL_PROVIDER=ses        → AwsSesEmailClient (EMAIL_FROM 필수)
EMAIL_PROVIDER=stub       → StubEmailClient (default)
EMAIL_PROVIDER=<unknown>  → fallback to stub + warn 로그

운영 적용 체크리스트¶

1. AWS SES 셋업 — sandbox 모드면 sender + recipient 모두 verify. Production access 별도 신청.
2. DKIM / SPF — alphea.io DNS 레코드 (운영 권장)
3. .env:

   EMAIL_PROVIDER=ses
   EMAIL_FROM=noreply@alphea.io
   AWS_REGION=ap-northeast-2
   AWS_ACCESS_KEY_ID=...
   AWS_SECRET_ACCESS_KEY=...
   

4. docker compose up -d --build app
5. Dev Console → Redeem 탭 → Issue 시 email 입력 → Detail 의 Send Email 클릭 → 실수신 확인

검증¶

• cargo build 성공 (SES SDK 컴파일 ~17s)
• cargo test --lib 53 passed (email 신규 8: trait 동작, MIME 빌드, RFC 2047, base64 line breaks 등)
• cargo clippy --all-targets clean

#426 잔여 범위 (후속)¶

운영 배포 가이드 — Office 365 + AWS SES dual-sender 셋업¶

본 노트는 코드 변경이 아닌 운영 환경 배포 가이드. alphea.ai 도메인이 이미 Office 365 (Exchange Online) 에서 메일을 받고 있는 상황에서, 외부 송신만 SES 로 추가하는 방법.

핵심: 공유 mailbox 발신은 그대로 가능¶

support@alphea.ai 가 O365 의 공유 mailbox (실제 사용자 계정 아님) 인 환경에서도 SES 발송 가능. SES 는 O365 권한 체계와 완전히 독립 — 도메인 자체를 인증 받으므로 local part 가 무엇이든 (또는 O365 에 mailbox 가 존재하지 않더라도) 발송 가능.

→ 공유 mailbox 라는 점은 오히려 장점 — 답장은 자연스럽게 지원팀으로, bounce 노이즈는 SES 가 따로 관리.

Office 365 측 — 변경 거의 없음¶

• 기존 SPF / DKIM (selector1._domainkey, selector2._domainkey) 그대로 유지. SES DKIM 은 다른 selector 라 충돌 없음.
• 공유 mailbox support@alphea.ai 자체는 그대로 유지 (수신자 reply 받기 위해)
• O365 admin 작업 불필요 — Send As / Send on behalf 같은 권한 부여도 무관

AWS SES 측 (서울 region 권장: ap-northeast-2)¶

1. Identities → Create identity → Domain: alphea.ai
2. SES 가 보여주는 DNS 레코드 Route 53 에 추가:
   • 소유권 확인 TXT: _amazonses.alphea.ai
   • DKIM CNAME × 3 (Easy DKIM)
3. (선택, 운영 권장) MAIL FROM Domain: mail.alphea.ai 설정 → bounce/complaint 가 별도 처리
4. Sandbox → Production access 신청 (SES 콘솔 → Account dashboard). 사용 사례 명시, 보통 24h 내 승인.
5. (선택) Configuration set + SNS topic — bounce/complaint/delivery 이벤트 처리 자동화

Route 53 (Hosted Zone: alphea.ai) 변경¶

신규 추가:

SPF 수정 — ⚠ 가장 흔한 함정:

# 변경 전 (O365 만)
alphea.ai. TXT  "v=spf1 include:spf.protection.outlook.com -all"

# 변경 후 (둘 다 — 한 줄에 합쳐야 함, 두 개 TXT 는 invalid)
alphea.ai. TXT  "v=spf1 include:spf.protection.outlook.com include:amazonses.com ~all"

테스트 단계는 ~all (softfail), 안정화 후 -all (hardfail) 권장.

DMARC — 기존 유지 OK. SES DKIM 이 d=alphea.ai 로 서명되어 자동 align.

alphea-ai-edge .env ¶

EMAIL_PROVIDER=ses
EMAIL_FROM=support@alphea.ai
AWS_REGION=ap-northeast-2
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

또는 IAM Role 사용 시 access key 비우고 다음 정책 attach:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["ses:SendEmail", "ses:SendRawEmail"],
    "Resource": ["arn:aws:ses:ap-northeast-2:<account-id>:identity/alphea.ai"]
  }]
}

검증¶

# DNS propagation
dig +short TXT _amazonses.alphea.ai
dig +short TXT alphea.ai
dig +short CNAME <selector>._domainkey.alphea.ai

# SES 콘솔: domain status "Verified" + DKIM "Successful"

# Test 발송 (sandbox 동안은 verified address 만)
aws ses send-email --from support@alphea.ai \
  --destination ToAddresses=<verified> \
  --message Subject={Data="SES test"},Body={Text={Data="hi"}}

# Gmail "원본 보기" 또는 mail-tester.com — SPF/DKIM/DMARC 모두 PASS 확인

자주 빠뜨리는 것¶

1. SPF 두 개로 분리 등록 (반드시 한 줄로 합쳐야 함)
2. Production access 신청 안 함 → sandbox 에서 verified recipient 에만 발송
3. MAIL FROM domain 미사용 → bounce 가 support@ 메일박스로 들어와 노이즈
4. SES Region 불일치 — DKIM CNAME 은 SES active region 의 키여야 함