\App\Services\AdminMailService

邮件发送服务

职责：邮件内容由模板引擎（td_sys_template，type=email）驱动。统一入口 sendByScene 按场景 key（MailScene 注册表）取模板——场景绑定优先，绑定为空或模板被删/停用时回退内置默认模板，保证系统始终可发信；渲染走 TemplateRenderer（strict 缺参报错，渲染失败记日志放弃发送，不上抛打断业务流程）；发送通道由「站点配置 → 邮件配置」分组提供，发送前取第一个有 SMTP 主机的通道动态注入 Mail 配置。

┌────────────────── 分区导航（按此顺序阅读）──────────────────┐ 分区 1 · 发送入口 sendByScene / sendRegisterCode / sendResetPassword 分区 2 · 模板解析 boundCode / resolveTemplate / defaultTemplate 分区 3 · 通道与发件 appName / resolveChannel / applyChannelConfig └────────────────────────────────────────────────────────────┘

Summary

Methods

Properties

Constants

sendByScene()
sendRegisterCode()
sendResetPassword()

No public properties found

No constants found

No protected methods found

No protected properties found

N/A

boundCode()
resolveTemplate()
defaultTemplate()
appName()
resolveChannel()
encryptionForPort()
applyChannelConfig()

No private properties found

N/A

File: Backend-Admin-PHP/app/Services/Admin/MailService.php
Package: Application
Class hierarchy: \App\Services\Admin\MailService
Uses

Methods

sendByScene()

sendByScene(string  $sceneKey, string  $toEmail, array<string,string>  $data) : array

统一发送入口：按场景 key（MailScene 注册表）取模板并渲染发送。

流程：① 解析场景（未注册直接返回 sent=false） ② 解析发送通道并动态注入 Mail 配置（无通道则用 config/mail.php + .env 兜底） ③ 解析模板（场景绑定优先，缺失/模板不存在或停用回退内置默认） ④ 变量补全（app_name 恒补；场景 defaults 如 valid_minutes 缺省补，调用方传值优先） ⑤ 渲染主题与正文（失败返回 sent=false 不上抛，队列处理器据此落失败台账） ⑥ 经 SMTP 发送 HTML 邮件（SMTP 异常自然上抛，交队列重试/终败链路）

Parameters

string	$sceneKey
string	$toEmail
array	$data	模板变量（与场景注册表 vars 对应）

Returns

array —

sendRegisterCode()

sendRegisterCode(string  $username, string  $toEmail, string  $code) : array

发送注册邮箱验证码。

Parameters

string	$username	用户名
string	$toEmail	收件邮箱
string	$code	6 位数字验证码

Returns

array —

sendResetPassword()

sendResetPassword(string  $username, string  $toEmail, string  $resetUrl) : array

发送密码重置链接邮件。

Parameters

string	$username	用户名
string	$toEmail	收件邮箱
string	$resetUrl	重置密码链接（含一次性 token）

Returns

array —

boundCode()

boundCode(array  $scene) : string

场景当前绑定的模板 code：配置值优先，空回落默认模板 code

Parameters

array

$scene

Returns

string —

resolveTemplate()

resolveTemplate(string  $code, string  $fallbackCode) : \App\Models\SysTemplate

取启用模板：按 code 查 type=email 启用态，未命中回落内置默认模板

Parameters

string	$code
string	$fallbackCode

Returns

\App\Models\SysTemplate —

defaultTemplate()

defaultTemplate(string  $code) : \App\Models\SysTemplate

内置默认模板（与模板种子同款；模板被删/停用时的兜底，保证系统可发信）。

Parameters

string

$code

Returns

\App\Models\SysTemplate —

appName()

appName() : string

邮件模板中的应用名：优先取站点配置 site.name，未配置回落 config('app.name')

Returns

string —

resolveChannel()

resolveChannel() : ?array

当前发送通道（「邮件配置」分组 tab 列表中的第一个配了 SMTP 主机的通道）。 tab 列表为空/全未配主机 → null（用 config/mail.php + .env 兜底）；切换通道 = 调整通道列表。

Returns

?array —

encryptionForPort()

encryptionForPort(int  $port) : string

端口 → 加密方式推导单源）： 465=SSL、587=TLS、25=无加密；其余端口按 TLS 兜底（现代服务商标准）。

Parameters

int

$port

Returns

string —

applyChannelConfig()

applyChannelConfig(array  $channel) : void

按通道数组动态注入 Mail config：发送前唯一注入点；无通道时回落 config/mail.php + .env

Parameters

array

$channel