163 lines
10 KiB
Markdown
163 lines
10 KiB
Markdown
## 目标与边界
|
||
|
||
将“全局功能 → Email邮件”收敛为一套真正可用的邮件系统：后台完整展示 SMTP、发件品牌、认证/账号、内容互动、审核、私信、身份/账号处理、举报，以及订单、支付、提现、返佣、分成、转账等商城/资金类邮件；模板主题和正文默认直接显示，不再用空值加 placeholder 代替；所有真实发送统一由同一服务渲染和发送。
|
||
|
||
明确排除：
|
||
|
||
- 不实现论坛、版主、论坛帖子审核、回答采纳等论坛专属邮件。
|
||
- 不实现邮箱回滚、撤销链接、回滚令牌或旧邮箱恢复流程；邮箱变更邮件只做安全通知。
|
||
- 不做旧 option 的数据迁移，不保留新旧双路，不写兼容 adapter。
|
||
- 不做浏览器或真实视觉验收，只做代码、契约、语法和构建验证。
|
||
|
||
## 1. 建立唯一邮件配置与模板目录
|
||
|
||
- 以 `aksrt_settings` 的 Email section 作为唯一配置来源；SMTP、品牌、通知开关和模板都通过 `/settings/schema/global/email` 读写。
|
||
- 在邮件域建立集中式模板目录，统一声明每个非论坛事件的事件键、后台名称、默认开关、默认主题、默认 HTML 正文、占位符及说明。
|
||
- 邮件运行时和后台 Schema 均从该目录生成，避免默认文案继续散落在业务调用点。
|
||
- 对每个事件同时声明“开关、主题模板、正文模板”；模板正文在后台直接显示为非空默认值。数据库中已有空主题/正文时，仅在读取响应和表单初始化时解析为目录默认值，不执行迁移。
|
||
- HTML 模板和 `mail_more_content` 使用 `wp_kses_post()` 清理；主题、SMTP host/username/name 等按文本清理；邮箱地址使用 `sanitize_email()`；端口限制到合法范围；加密方式只允许 `ssl`、`tls` 或空值；SMTP 密码使用 secret 掩码/清除机制。
|
||
|
||
## 2. 完整重做 Email 后台 Schema
|
||
|
||
在 `src/Admin/Schema/GlobalSchema.php` 中由集中目录生成 Email section；让 `SchemaPage.vue` 对 `global.email` 使用服务端 Schema，删除前端重复的静态 Email schema 定义，避免 PHP/JS 两份字段漂移。
|
||
|
||
页面分组与事件如下：
|
||
|
||
1. **管理员邮件推送**
|
||
- 友情链接提交
|
||
- 新订单
|
||
- 提现申请
|
||
- 投稿待审核
|
||
- 身份认证申请
|
||
- 账号封禁申诉
|
||
- 举报提交
|
||
|
||
2. **用户邮件推送**
|
||
- 注册验证码
|
||
- 注册成功
|
||
- 免密登录验证码
|
||
- 密码重置验证码
|
||
- 邮箱/敏感操作验证码
|
||
- 邮箱变更安全通知
|
||
- 新订单/支付结果
|
||
- 提现处理结果
|
||
- 返佣到账
|
||
- 创作分成到账
|
||
- 收到积分/余额转账
|
||
- 评论通过审核
|
||
- 评论回复
|
||
- 投稿发布/驳回结果
|
||
- 手机号修改通知
|
||
- 身份认证审核结果
|
||
- 账号封禁/解封通知
|
||
- 举报处理结果
|
||
- 私信通知
|
||
- 私信邮件用户组限制
|
||
- 所有用户
|
||
- 所有会员
|
||
- 二级会员及以上
|
||
- 仅管理员
|
||
|
||
3. **自定义发件人/品牌**
|
||
- `mail_showname`，默认站点名
|
||
- `mail_title_prefix`，默认 `[站点名]`
|
||
- `mail_description`，默认“此信为系统邮件，请不要直接回复。”
|
||
- `mail_more_content`，默认显示“访问网站 / 联系站长”等基础 HTML 链接
|
||
|
||
4. **SMTP 配置**（沿用参考主题语义，但使用当前主题唯一字段契约）
|
||
- `mail_smtps`
|
||
- `mail_name`
|
||
- `mail_passwd`
|
||
- `mail_smtp_name`
|
||
- `mail_host`
|
||
- `mail_port`
|
||
- `mail_smtpauth`
|
||
- `mail_smtpsecure`
|
||
- SMTP 风险提示和依赖显示
|
||
|
||
5. **测试邮件**
|
||
- Email 页面内提供测试收件地址和发送操作。
|
||
- 有未保存修改时禁止测试并提示先保存，确保测试当前生效配置。
|
||
- 测试邮件走统一 HTML 包装、品牌和 SMTP 主线。
|
||
|
||
每个事件组直接显示“启用开关 + 主题模板 + HTML 正文模板 + 可用占位符说明”。论坛事件不进入 Schema、模板目录、默认值或运行时注册。
|
||
|
||
## 3. 实现参考主题式统一邮件渲染
|
||
|
||
重构 `src/Settings/Mail.php` 和 `inc/core-hooks/part-2.php`：
|
||
|
||
- 集中服务完成事件查询、开关判断、占位符替换、主题前缀、HTML 安全处理、品牌包装和 `wp_mail()` 调用。
|
||
- 复刻参考主题邮件信封：站点 Logo、主体内容、站点名称、底部说明、附加链接及现有 `assets/img/mail-bg.png` 背景图。
|
||
- 主题前缀只添加一次，并清除 WordPress 默认重复 `[站点名]` 前缀。
|
||
- 发件人名称保留明确优先级：`mail_showname` → 站点名；SMTP 发件地址和 SMTPAuth 使用同一 Email section 的 `mail_*` 字段。
|
||
- 将 `send_event_email()` 统一为事件键、收件人、占位符（必要时允许结构化上下文），默认模板不再由调用方重复传入。
|
||
- 未知事件失败关闭；无效收件地址不发送；事件关闭时不发送。
|
||
- 统一管理员收件人获取、去重和有效邮箱过滤。
|
||
|
||
## 4. 接通所有非论坛真实业务发送点
|
||
|
||
新增聚合通知注册类，基于当前主题已有 WordPress/AKSRT action 注册邮件发送；不凭空添加论坛功能。每个事件都复用集中模板目录和统一发送服务。
|
||
|
||
### 认证与账号
|
||
|
||
- 改造 `UserControllerAuthPhoneOperations.php`：注册验证码、免密登录验证码、密码重置验证码按独立事件发送；失败时删除验证码 transient，维持现有频率限制和安全行为。
|
||
- 注册成功在用户创建成功且用户对象有效时发送，提供用户名、站点名、个人中心/站点链接等占位符。
|
||
- 改造 `account-ajax.php`：敏感操作验证码、邮箱变更通知走统一服务；删除直接 `wp_mail()` fallback；不增加邮箱回滚。
|
||
- 手机号绑定/换绑成功后向有效邮箱发送通知。
|
||
|
||
### 内容互动与审核
|
||
|
||
- 评论通过审核、评论回复：接入 WordPress 评论状态/回复钩子，避免重复状态流转、自己回复自己和无效邮箱。
|
||
- 投稿待审核与发布/驳回结果：接入现有 `aksrt_new_posts_pending` 与文章状态转换，只处理当前主题实际支持的投稿内容，防止重复通知。
|
||
- 友情链接提交：接入当前友情链接写入成功动作，向有效管理员邮箱发送。
|
||
|
||
### 身份、账号、举报和私信
|
||
|
||
- 身份认证申请/审核、封禁申诉/处理、举报提交/处理：接入现有成功动作；若成功路径缺少动作，只在事务成功点增加明确的 `aksrt_*` action。
|
||
- 私信通知：接入现有消息/通知主线，只处理 private 类型；实现参考主题的用户组限制，并过滤无效或占位邮箱。
|
||
|
||
### 订单与资金业务（保留）
|
||
|
||
- 订单创建/支付成功/支付失败或状态变化：接入当前支付订单状态 action，分别通知管理员、买家及适用的订单关联用户。
|
||
- 提现申请与处理结果：接入当前提现申请、审核/完成/拒绝路径，通知管理员和申请用户。
|
||
- 返佣通知：接入当前 referral/佣金到账 action，向推荐人发送订单和佣金信息。
|
||
- 创作分成通知：接入当前 ledger/收益分配成功 action，向分成作者发送到账明细。
|
||
- 积分/余额转账通知：接入当前资产转账完成 action，向收款用户发送转账信息。
|
||
- 上述商城/资金事件只使用仓库中已存在的订单、支付、ledger、referral、资产动作和数据结构；若某事件没有可直接监听的成功动作，在对应现有事务完成点补充 action，不复制业务逻辑、不新建第二套交易流程。
|
||
|
||
论坛/版主/回答采纳动作不注册任何邮件监听器，也不产生对应模板字段。
|
||
|
||
## 5. 删除旧接口、旧存储与绕路代码
|
||
|
||
- 删除 `GlobalController` 的 `/settings/mail` 路由和 `rest_handle_mail()`，不再使用 `aksrt_mail_config`。
|
||
- 保留 `/mail/test` 作为动作接口，但重写为统一邮件服务测试；配置读写只有 Schema 路由。
|
||
- 删除前端 `getMailSettings()` / `saveMailSettings()`，只保留测试邮件 API 方法。
|
||
- 删除 `UserController` 的 `/settings/mail-templates` 路由、`handle_mail_templates()` 和 `aksrt_mail_templates` 契约。
|
||
- 删除 `Settings::get_smtp()` 对 `aksrt_mail_smtp` 的读取，并从 standalone/secret option 注册表移除该旧 option；SMTP 只读 Email section 的统一字段。
|
||
- 删除认证、账号和各业务模块中邮件服务不存在时的直接 `wp_mail()` fallback；正常业务只允许集中邮件服务内部调用 `wp_mail()`。
|
||
- 删除旧六事件空模板回退参数、重复前端 Email Schema 及不再使用的旧字段；不读取、不转换旧 option 值。
|
||
- 不删除数据库中的旧 option 值，但代码完全停止消费它们；不执行迁移脚本或双写。
|
||
|
||
## 6. 契约测试与构建验证
|
||
|
||
新增邮件系统契约测试/harness，覆盖：
|
||
|
||
- 后端 Email Schema 包含认证、账号、内容互动、审核、私信、身份/账号处理、举报、订单、支付、提现、返佣、分成、转账等事件。
|
||
- Schema 明确不包含 `bbs`、moderator、answer-adopted 及其它论坛字段。
|
||
- 每个主题和正文默认值非空；空存储读取时后台仍返回可见模板；模板占位符替换后无未知占位符。
|
||
- HTML 邮件信封包含品牌说明、附加内容、Logo 和背景图；主题前缀不重复；发件人和 SMTP 字段优先级稳定。
|
||
- SMTP 开关、认证、host、port、encryption、secret 掩码/清除行为正确。
|
||
- 事件关闭、未知事件、无效收件地址均不发送。
|
||
- 注册/登录/重置/邮箱变更路径不再绕过集中服务，发送失败时验证码缓存处理正确；不出现邮箱回滚入口或令牌。
|
||
- 评论、投稿、友情链接、身份认证、封禁、举报、私信及所有订单/资金事件分别绑定真实 action，并覆盖去重、无效邮箱和边界条件。
|
||
- 论坛事件不注册、不发送、不出现在后台；订单/支付/提现/返佣/分成/转账事件必须存在并可配置。
|
||
- 旧 `/settings/mail`、`/settings/mail-templates`、`aksrt_mail_config`、`aksrt_mail_templates`、`aksrt_mail_smtp` 和旧前端 API 不再存在。
|
||
- 全仓库业务代码中的 `wp_mail()` 只剩集中邮件服务内部调用。
|
||
|
||
执行验证：
|
||
|
||
1. 对所有变更 PHP 文件运行 `php -l`。
|
||
2. 运行新增邮件契约测试及受影响的 admin/UI 契约测试。
|
||
3. 在 `assets/admin` 执行 `npm run build`，由 Vite 清理旧 chunk 并更新完整 `assets/admin/build/`。
|
||
4. 使用 `rg` 做最终静态检查：无论坛邮件字段、无旧 option/API、无散落直接 `wp_mail()`，且订单/支付/提现/返佣/分成/转账事件均有 Schema、模板目录和发送入口。
|
||
5. 不启动浏览器、不截图、不做真实视觉效果验收。 |