<!-- b5e97267-b1d5-4ef9-9217-ebd91392307c -->
---
todos:
  - id: "ddl-mail-tables"
    content: "在 slot-notification 新增 mail_config（SMTP 直字段）/ mail_template / mail_send_log 表 DDL"
    status: pending
  - id: "mail-module"
    content: "实现 app/mail 模块：Model、Entity、Cache、MailService、SmtpMail SDK"
    status: pending
  - id: "notification-api"
    content: "新增 EmailController + MailConfigAdminController 与 route 注册"
    status: pending
  - id: "sdk-client"
    content: "扩展 slot-lib / slot-sdk 的 MailService 客户端方法"
    status: pending
  - id: "console-migrate"
    content: "slot-console CommonController 改调 notification；废弃本地 MailService"
    status: pending
  - id: "admin-ui"
    content: "slot-admin 后端 + slot-admin-vue 邮件配置管理页"
    status: pending
  - id: "data-migration"
    content: "编写 mail_config 从 slot-console 配置组到表的幂等迁移脚本"
    status: pending
  - id: "verify"
    content: "跑 verify-slot-backend.sh，验证发信/验码/后台 CRUD 链路"
    status: pending
isProject: false
---
# slot-notification 邮件配置表化（对齐短信）

## 现状与结论

当前两套通知渠道配置方式不一致：

| 能力 | 短信（已收口） | SMTP 邮件（未收口） |
|---|---|---|
| 配置存储 | [`slot-notification/app/sms/model/SmsConfigModel.php`](slot-notification/app/sms/model/SmsConfigModel.php) → `sms_config` 表 | [`slot-console/app/service/lib/MailService.php`](slot-console/app/service/lib/MailService.php) → `ConfigService::getGroupData('mail_config')` |
| 发送服务 | [`slot-notification/app/sms/services/SmsService.php`](slot-notification/app/sms/services/SmsService.php) | `slot-console` 本地 `MailService` + PHPMailer |
| 验证码 API | `/innerapi/sms/sendVerifyCode` | `slot-console` `CommonController::sendEmailCode` |
| 后台管理 | slot-admin → slot-lib → notification `/innerapi/admin/*` | slot-admin 通用配置页 `email_config`（另一套） |

**结论：应该建表。** 你已选择「完整对齐短信」，建议把 SMTP 邮件作为 slot-notification 的第二条外发渠道，与短信保持同一套「配置表 + 发送日志 + innerapi + 后台管理 + SDK 客户端」模式。

注意：slot-notification 里现有 [`MailController`](slot-notification/app/innerapi/controller/MailController.php) / [`EmailService`](slot-notification/app/message/service/EmailService.php) 实际是**站内消息**兼容别名，不是 SMTP。新 SMTP 能力应使用独立命名空间（建议 `app/mail/*`）和独立路由前缀（建议 `/innerapi/email/*`），避免与 `/innerapi/mail/*`（站内消息）冲突。

```mermaid
flowchart LR
  subgraph before [当前]
    lobby1[Lobby] --> console1[slot-console CommonController]
    console1 --> config1["ConfigService mail_config"]
    console1 --> mail1[MailService PHPMailer]
  end

  subgraph after [目标]
    lobby2[Lobby] --> console2[slot-console 薄代理]
    console2 --> sdk[slot-lib MailService]
    sdk --> notif[slot-notification EmailController]
    notif --> table["mail_config 表"]
    notif --> smtp[SmtpMail PHPMailer]
    notif --> log["mail_send_log 表"]
  end
```

---

## 表结构设计（邮件用直字段，短信保留 JSON）

在 `s_message`（与 `sms_config` 同库）新增两张表。

### 为什么邮件不用 JSON、短信用 JSON？

| 对比 | 短信 `sms_config.config` | 邮件 `mail_config` |
|---|---|---|
| 字段形态 | 各平台差异大（Buka 要 appId/senderId，Ant/Chuanglan 字段不同） | SMTP 标准字段固定，截图与代码一致 |
| 后台表单 | 按 `platform` 动态展示不同表单项 | 固定 6~8 个输入框，与现有配置页一一对应 |
| 查询/校验 | 结构不统一，适合 JSON | 可直接列级校验、索引、迁移映射 |

**结论：邮件配置用直接字段更好；不必为了「和短信表长得像」而强行 JSON。**

### 当前邮件配置项（来自截图，仅 SMTP 连接）

截图中的 6 项即为 `mail_config` 配置组现有字段，与 [`MailService`](slot-console/app/service/lib/MailService.php) 读取项一致。**这就是邮件配置表应存的全部内容**：

| 配置项 | 列名建议 | 说明 |
|---|---|---|
| smtp host | `smtp_host` | 如 `email-smtp.us-east-1.amazonaws.com` |
| 用户名 | `username` | SMTP 登录账号 |
| 密码 | `password` | SMTP 密码/应用专用密码 |
| 端口 | `port` | 如 `587` |
| 发件人地址 | `from_address` | 原 `from` |
| 发件人名称 | `from_name` | 如 `TOGOO` |

加密方式（`tls`/`ssl`）**不单独落库**：发送时按 `port` 推断即可（`587` → STARTTLS，`465` → SSL），与现网行为一致。

### 邮件模板（独立概念，不属于 mail_config）

验证码邮件的标题/正文来自 `email_template` 配置组（`title`、`binding_email`），属于**发送模板**，不是 SMTP 连接配置。

发送邮件时需要两张表配合：

```mermaid
flowchart LR
  sendMail[MailService 发信] --> mailConfig["mail_config\nSMTP 连接"]
  sendMail --> mailTemplate["mail_template\n标题/正文模板"]
```

### `mail_config`（仅 SMTP 连接，直字段）

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint PK | 主键 |
| `platform` | varchar(32) | 渠道标识，如 `AwsSes`、`Zoho` |
| `status` | tinyint | 1 启用 / 2 禁用 |
| `num` | int | 排序，降序优先 |
| `smtp_host` | varchar(255) | SMTP 主机 |
| `username` | varchar(128) | SMTP 用户名 |
| `password` | varchar(512) | SMTP 密码 |
| `port` | int | SMTP 端口 |
| `from_address` | varchar(255) | 发件人邮箱 |
| `from_name` | varchar(128) | 发件人显示名 |
| `create_time` / `update_time` | datetime | 审计字段 |

### `mail_template`（邮件发送模板，独立表）

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint PK | 主键 |
| `template_code` | varchar(64) | 模板编码，如 `bindingEmail`、`authEmail` |
| `template_name` | varchar(128) | 模板名称 |
| `title` | varchar(255) | 邮件标题模板 |
| `body` | text | 邮件正文模板，支持 `{code}` 等变量 |
| `status` | tinyint | 1 启用 / 2 禁用 |
| `create_time` / `update_time` | datetime | 审计字段 |

首期迁移：把 `email_template` 配置组中的 `title` + `binding_email` 迁入 `mail_template`（`template_code=authEmail` 或按业务拆分）。

**注意**：`message_template` 是站内消息模板，与 SMTP 外发邮件模板是不同业务，不混用。

### `mail_send_log`（发送日志，放 `s_common`）

镜像 [`sms_send_log`](slot-notification/app/sms/model/SmsSendLogModel.php)：

- `unique_sn`, `email`, `platform`, `subject`, `content`, `status`, `type`, `retry_num`, `create_time`

---

## 后端实现（slot-notification）

### 1. 数据层

新建 `app/mail/` 模块，参照 `app/sms/`：

- `MailConfigModel` / `MailSendLogModel`
- `MailConfigEntity`（后台 CRUD，复用短信 Entity 分页模式）
- 在 [`initDB.php`](slot-notification/app/command/initDB.php) 补充 DDL；另提供 `db/mail_config.sql` 便于手工执行

### 2. 发送层

- `composer.json` 增加 `phpmailer/phpmailer`
- `MailService`：从 `mail_config` 取 SMTP 连接，从 `mail_template` 取标题/正文 → PHPMailer 发信 → 写 `mail_send_log`
- `app/mail/services/sdk/BaseMail.php` + `SmtpMail.php`（首期只实现 SMTP，结构与 `BaseSms` 一致，便于后续扩展 SendGrid 等）
- `MailCache`：验证码 Redis 缓存（镜像 `SmsCache`），key 规则与 slot-console [`EmailCodeLibService`](slot-console/app/service/lib/EmailCodeLibService.php) 保持一致，避免迁移期验证码失效

### 3. API 层

新增路由（[`config/route.php`](slot-notification/config/route.php)）：

- `POST /innerapi/email/send-verify-code`
- `POST /innerapi/email/verify-code`
- `POST /innerapi/admin/mail-config/index|save|update|destroy`
- `POST /innerapi/admin/mail-template/index|save|update|destroy`（模板 CRUD，与配置分开）

新建 `EmailController`（发送/校验）与 `MailConfigAdminController`（配置 CRUD），**不要**复用现有站内消息 `MailController`。

### 4. 渠道选择策略

首期与短信一致：按 `status=启用` + `num desc` 取第一条；预留后续 failover（注释掉的短信轮询逻辑可一并参考）。

---

## 跨服务改造

### slot-lib / slot-sdk

在 [`slot-lib/src/services/notification/`](slot-lib/src/services/notification/) 新增 `MailService`（或 `EmailService`）：

- `sendVerifyCode(email, type)`
- `verifyCode(email, code, type)`
- `getMailConfigPageList` / `saveMailConfig` / `updateMailConfig` / `destroyMailConfig`

同步扩展 [`slot-sdk/src/service/notification/NotificationService.php`](slot-sdk/src/service/notification/NotificationService.php)。

### slot-console（调用方改造）

[`CommonController::sendEmailCode`](slot-console/app/api/controller/CommonController.php) / `verifyEmailCode`：

- 改为调用 slot-lib `MailService`，不再直接依赖本地 `MailService` + `ConfigService`
- 本地 [`MailService`](slot-console/app/service/lib/MailService.php) 标记废弃或删除（确认无其他引用后）

限流、参数校验仍留在 slot-console Controller 层（与现有短信 napi 模式一致）。

### slot-admin + slot-admin-vue

镜像短信后台：

- 后端：[`slot-admin/app/game/controller/SmsController.php`](slot-admin/app/game/controller/SmsController.php) → 新建 `MailController`
- 前端：新建 `mail/config/` 页，仅 6 个 SMTP 字段 + platform/status/num；另建 `mail/template/` 页管理标题/正文模板
- 菜单/权限：新增 `mailConfig` 路由与按钮权限

---

## 数据迁移

新增一次性迁移脚本（建议 `slot-notification/app/command/MigrateMailConfig.php`）：

1. 从 `s_config` 读取 `mail_config` 配置组 → 写入 `mail_config` 表（6 个 SMTP 字段）
2. 从 `s_config` 读取 `email_template` 配置组 → 写入 `mail_template` 表（`title` + `binding_email`）
3. 幂等插入（已存在则跳过）

迁移完成后，`slot-console` 侧 `mail_config` / `email_template` 配置组可保留只读一段时间，确认无回退需求后再清理。

---

## 风险与边界

- **命名冲突**：`/innerapi/mail/*` 继续保留给站内消息；SMTP 统一走 `/innerapi/email/*`
- **验证码兼容**：`MailCache` 的 Redis key 必须与 slot-console 现有 `ShareRedisKeyManagerService::emailCode()` 一致
- **模板范围**：本期只迁移验证码邮件模板（`binding_email`/`title`）；充值/提现等 MQ 站内邮件模板（`message_template` 配置组）不在本次范围
- **多 SMTP  failover**：表结构支持，首期实现「取第一条启用配置」即可

---

## 验收标准

1. slot-admin 可 CRUD `mail_config`，与短信配置页体验一致
2. Lobby 发/验邮箱验证码链路走 slot-notification，功能与迁移前一致
3. 发送成功/失败均写入 `mail_send_log`
4. slot-console 不再读取 `ConfigService::getGroupData('mail_config')`
5. 执行 `verify-slot-backend.sh` 通过