1. 页面概览
邮件设置页是 AIP 管理后台配置 SMTP 邮件发送服务的入口，路由 /admin/email，需管理员角色。它以 EMAIL_ 前缀的 key 读写系统设置（system_settings 表），覆盖启用开关、SMTP 服务器/端口、账号密码、发件人信息与加密方式等 9 项配置。页面顶部提供「运行状态」卡（配置/启用两态），底部提供「发送测试邮件」卡，用当前保存的 SMTP 配置验证连通性。
配置采用"整页表单 + 顶部保存"模式：一次「保存」把全部字段逐项 PUT 到设置表，修改后重启 AIP 生效。邮件服务是工作流 send_notification 节点 channel=email 通知渠道的底层实现，凭证齐全且未显式禁用时默认启用。
2. 访问入口
2.1 路由与菜单
path /admin/email、name EmailSettings、title 邮件设置；挂载在父路由 /admin（AdminLayout）下，侧边栏菜单项「邮件设置」。源码 action/web/src/views/EmailSettingsPage.vue（懒加载注册）。
2.2 认证与权限
该子路由 meta 显式 requiresAuth: true, requiresAdmin: true；后端 GET /email/status、POST /email/test 与 PUT /settings 均在 admin 组。请求经 aipClient.js 附带 aip_token。
2.3 端口与 API 前缀
AIP 后端 18080，前缀 /aip-api（baseURL /aip-api/v1，Vite 代理重写为 /api/v1）。
3. 界面布局
邮件设置 [保存]
[操作结果提示 alert（可关闭）]
[提示：EMAIL_ 前缀配置项存入系统设置，修改后重启 AIP 生效]
运行状态：配置状态(已配置 SMTP 服务器+发件人/未配置) |
启用状态(已启用/未启用) [刷新状态]
配置表单：启用邮件服务(开关) | SMTP 服务器 | SMTP 端口 | SMTP 账号 |
SMTP 密码/授权码 | 发件人邮箱 | 发件人名称 |
STARTTLS(25/587)(开关) | SSL(465，TLS直连)(开关)
发送测试邮件：收件邮箱[____] [发送测试邮件]- 运行状态卡：展示
/email/status配置与启用状态，附按状态切换的引导提示。 - 配置表单：9 个字段按类型渲染（开关/文本/密码），key 旁标注
EMAIL_*原名。 - 发送测试邮件卡：输入收件邮箱后调
POST /email/test，验证服务器、账号与安全方式。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 保存按钮 | 页面头部 | 逐项 PUT /settings（Promise.all 并行）保存全部字段，保存中禁用表单 |
| 刷新状态按钮 | 运行状态卡 | 重新请求 /email/status |
| 启用邮件服务 | 表单 | EMAIL_ENABLED 总开关，关闭后工作流 email 渠道不再发送 |
| SMTP 服务器 | 表单 | EMAIL_SERVER，如 smtp.qq.com / smtp.exmail.qq.com |
| SMTP 端口 | 表单 | EMAIL_PORT：25（普通）/ 587（STARTTLS）/ 465（SSL/TLS 直连） |
| SMTP 账号 / 密码 | 表单 | EMAIL_USERNAME/EMAIL_PASSWORD（密码框），授权码用服务商生成 |
| 发件人邮箱 / 名称 | 表单 | EMAIL_FROM/EMAIL_FROM_NAME，邮件头显示的发件人信息 |
| STARTTLS / SSL 开关 | 表单 | EMAIL_STARTTLS（25/587）、EMAIL_SSL（465 直连）两个加密开关 |
| 发送测试邮件按钮 | 测试卡 | POST /email/test body {to}，发送中显示"发送中..."，未填邮箱禁用 |
5. 后端关联
5.1 端点表
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /email/status | 返回邮件服务配置与可用状态：{enabled, configured, server, from, port} |
| PUT | /settings | 逐字段 upsert，body {key, value, type, description} |
| POST | /email/test | 向 {to} 发一封测试邮件验证连通性 |
5.2 请求与响应
GET /email/status 的 configured 由 server/username/password 三者齐全决定，enabled 取服务配置。 POST /email/test 成功返回 {"success": true, "to": ...}；mailer 未配置或 to 为空返回 400。布尔字段存储为字符串 "true"/"false"。
5.3 关键机制
- 邮件发送为纯标准库实现（
net/smtp+crypto/tls），支持 SSL 直连（465）/ STARTTLS（25·587）/ 明文三模式，含超时与重试 2 次、HTML 正文与 header 防注入。配置优先级为 config.yaml / 环境变量 / system_settings 表（DB 覆盖优先）。 - 后端位置：
handleEmailStatus/handleEmailTest在action/products/aip/server/handlers_email.go；发送器在action/platform/mailer/，工作流send_notification节点经通知中心支持channel=email。
6. 权限与安全
- 认证：JWT Bearer Token（
aip_token），401 自动登出跳登录页。 - 管理员专属：前端
requiresAdmin守卫 + 后端 admin 组双重校验，测试邮件接口同样仅管理员可用。 - 敏感凭证：
EMAIL_PASSWORD密码框输入，仅写入设置表；测试邮件目标须管理员显式填写，避免开放转发。
7. 常见问题与排错
问题 1：运行状态显示"未配置（需填 SMTP 服务器、账号、密码）"
- 现象：
configured=false，配置状态灰点。 - 原因：
EMAIL_SERVER/EMAIL_USERNAME/EMAIL_PASSWORD三者未齐。 - 处理：补全三项并保存、重启 AIP，再「刷新状态」确认。
问题 2：发送测试邮件报"邮件服务未配置"或失败
- 现象：点「发送测试邮件」提示失败。
- 原因：后端 mailer 为 nil（服务未配置）返回 400；或服务器/账号/端口/加密方式不匹配（465 需开 SSL、587 需开 STARTTLS）。
- 处理：核对端口与加密开关组合，保存重启后再测；查后端日志
邮件服务测试发送失败的 error 详情。
问题 3：已配置但启用状态为"未启用"
- 现象：
configured=true但enabled=false。 - 原因：
EMAIL_ENABLED开关未打开。 - 处理：打开「启用邮件服务」开关并保存、重启 AIP。
问题 4：工作流 email 通知节点直接失败
- 现象：
send_notification节点channel=email执行失败。 - 原因：邮件服务未配置或未启用时，节点明确报错而非静默丢弃。
- 处理：先在本页完成配置并通过测试邮件验证，再重跑工作流；这是设计行为（失败可见）。
8. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 重启生效 | 全部配置修改重启 AIP 后生效，无热更新 |
| 单发件箱 | 支持单一 SMTP 发件账号，无多账号轮换 |
| 无收件人白名单 | 测试邮件地址由管理员自由填写，无内置限制 |
| 布尔存字符串 | 设置表以 "true"/"false" 文本存储 |
| 明文存储密码 | EMAIL_PASSWORD 明文存设置表，需保管好数据库权限 |