wordpress-theme-aksrt/.zcode/plans/plan-sess_23082cba-edb8-4cf5-9842-07e57ac15e1f.md

目标与边界

将“全局功能 → 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. 不启动浏览器、不截图、不做真实视觉效果验收。