mass_mail_engine/docs/INSTALL.md

Install

• 需求：.NET SDK 8.x, PostgreSQL
• 設定：複製 .env.example → .env
• AWS Credential（SQS/SES）：
  • Local / Docker 開發：
  • 設定 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY（若為臨時憑證再加 AWS_SESSION_TOKEN）
  • 設定 AWS__Region（或 Sqs__Region / Ses__Region）
  • 建議設 AWS_EC2_METADATA_DISABLED=true，避免本機誤打 EC2 metadata
  • ECS 正式環境（建議）：
  • 不要放 Access Key，改用 ECS Task Role（taskRoleArn）
  • Task Role 至少授權：
  • sqs:ReceiveMessage
  • sqs:DeleteMessage
  • sqs:GetQueueAttributes
  • ses:SendEmail（raw_bulk）
  • ses:SendBulkEmail（bulk_template，若有使用）
  • ECS Task Definition 可設定環境變數：
  • AWS_REGION=ap-northeast-1（或直接用 .env 的 AWS__Region）
• Migration：
  • 預設由 API 啟動時自動執行（Db__AutoMigrate=true）
  • 需要關閉時請設定 Db__AutoMigrate=false
  • 手動執行可用 dotnet run --project src/SendEngine.Installer -- migrate
• Webhook Auth 初始化（不使用 SQL 檔，改用 Installer）：
  • 若僅需先建立 tenant 基本資料：
  • dotnet run --project src/SendEngine.Installer -- ensure-tenant --tenant-id <tenant_uuid> [--tenant-name <name>]
  • 使用 Installer 建立 webhook client（id 自動隨機產生）：
  • dotnet run --project src/SendEngine.Installer -- add-webhook-client --tenant-id <tenant_uuid> [--tenant-name <name>] --client-id <client_id> --name <display_name> --scopes <scope1,scope2>
  • 例如：dotnet run --project src/SendEngine.Installer -- add-webhook-client --tenant-id 11111111-1111-1111-1111-111111111111 --tenant-name "Tenant A" --client-id member-center-webhook --name "Member Center Webhook" --scopes newsletter:events.write
  • 若 client_id 已存在且屬於同一 tenant，Installer 會重用既有 webhook client（不重複建立），可直接搭配 --upsert-member-center 做同步
  • 若 client_id 已存在但屬於不同 tenant，Installer 會中止並回報錯誤
  • 若 tenant 不存在，Installer 會先自動建立 tenants 基本資料，避免 webhook 出現 tenant_not_found
  • 建立成功後，Member Center webhook header X-Client-Id 請帶回傳的 id
  • 若要自動同步到 Member Center POST /integrations/send-engine/webhook-clients/upsert（保留原手動流程）：
  • dotnet run --project src/SendEngine.Installer -- add-webhook-client --tenant-id <tenant_uuid> --client-id <client_id> --name <display_name> --scopes <scope1,scope2> --upsert-member-center --mc-base-url <member_center_base_url> --mc-client-id <oauth_client_id> --mc-client-secret <oauth_client_secret> --mc-scope newsletter:events.write.global
  • 可選參數：
  • --mc-token-path（預設 /oauth/token）
  • --mc-upsert-path（預設 /integrations/send-engine/webhook-clients/upsert）
  • --mc-token-url / --mc-upsert-url（使用完整 URL 時可覆蓋 path 組合）
  • Webhook 驗證規則為 tenant 綁定：auth_clients.tenant_id 必須等於 payload tenant_id
  • 不支援 X-Client-Id fallback
  • 預設拒絕 tenant_id = NULL 的通用 client（Webhook__AllowNullTenantClient=false）
• Member Center 回寫授權（建議）：
  • MemberCenter__BaseUrl（建議）
  • MemberCenter__DisableSubscriptionPath（預設 /subscriptions/disable）
  • MemberCenter__TokenPath（預設 /oauth/token）
  • MemberCenter__OneClickUnsubscribeTokensPath（預設 /newsletter/one-click-unsubscribe-tokens）
  • MemberCenter__ClientId
  • MemberCenter__ClientSecret
  • MemberCenter__Scope=newsletter:events.write
  • MemberCenter__ApiToken 僅作暫時 fallback（非首選）
• Send Job API 驗證（JWT）：
  • Jwt__Issuer
  • Jwt__Audience
  • 建議（Member Center OIDC/JWKS）：
  • Jwt__Authority（例如 http://member-center）
  • 或 Jwt__MetadataAddress（例如 http://member-center/.well-known/openid-configuration）
  • 若兩者都未設定，會自動回退使用 MemberCenter__BaseUrl + /.well-known/openid-configuration
  • Jwt__RequireHttpsMetadata（本機可設 false）
  • 相容舊模式（不建議）：Jwt__SigningKey（HS 對稱驗簽）
• 本機測試輔助（臨時）：
  • TestFriendly__Enabled=true 時：
  • webhook 收到未知 tenant 會自動建立 tenant
  • /webhooks/ses 不做任何 DB 存取，但會保留 Member Center callback 流程（僅用於測試流程打通）
  • Dev Sender（Mock 發信）：
  • DevSender__Enabled=true：背景 worker 會處理 pending send jobs，並將每位收件人的預計發送內容寫入 events_inbox（source=dev_sender, event_type=send.preview）
  • DevSender__PollIntervalSeconds：輪詢間隔秒數（預設 5）
  • ESP__Provider=ses 時，即使 DevSender__Enabled=false，背景 sender 仍會啟動並改用 SES 發送（模式由 Ses__SendMode 決定）
  • SES 相關參數：Ses__Region、Ses__FromEmail、Ses__ConfigurationSet（可選）、Ses__SendMode、Ses__TemplateName
  • SNS 簽章驗證參數：
  • Ses__SkipSignatureValidation（建議正式環境 false）
  • Ses__AllowedTopicArns（逗號分隔 allowlist；建議正式環境必填）
  • Ses__AllowedCertHosts（逗號分隔；留空時只接受 sns.*.amazonaws.com）
  • Ses__SignatureMaxSkewSeconds（預設 300）
  • Ses__SendMode=raw_bulk（預設）：使用 SES SendEmail，依內容分組後每次最多 50 位收件者（不依賴 SES Template）
  • Ses__SendMode=bulk_template：使用 SES SendBulkEmail + Template（需提供 template.ses_template_name 或 Ses__TemplateName）
  • SES 發送時會附帶 message tags：tenant_id、list_id、campaign_id、send_job_id
  • SQS Poller（SES 事件回流）：
  • Sqs__Enabled=true
  • Sqs__QueueUrl=<aws_sqs_queue_url>
  • Sqs__Region（未設定時回退 AWS__Region 再回退 Ses__Region）
  • Sqs__PollWaitSeconds（預設 20）
  • Sqs__MaxMessages（預設 10）
  • Sqs__VisibilityTimeoutSeconds（預設 30）
  • SQS poller 目前未提供獨立 DLQ worker；可先用 AWS SQS redrive policy 管理失敗訊息
  • SendBulkEmail 會使用 SES 模板名稱：
  • 先讀 campaign.template.ses_template_name
  • 若未提供則回退 Ses__TemplateName
  • 若設定了 Member Center one-click token endpoint，sender 會在發送前批次呼叫 /newsletter/one-click-unsubscribe-tokens，僅發送 status=issued 的收件者
  • 內容替換合約（Mock 與 SES 共用）：
  • {{email}}
  • {{unsubscribe_token}}
  • {{tenant_id}} / {{list_id}} / {{campaign_id}} / {{send_job_id}}
  • 若在 campaign.template 提供：
  • list_unsubscribe_url_template
  • list_unsubscribe_mailto
  • sender 會自動加上 List-Unsubscribe 與 List-Unsubscribe-Post headers
  • 正式環境建議維持 false