# 网页邮箱执行扩展安装说明

适用版本：`1.2.1`，Chrome 和 Edge 共用同一个 ZIP。

## 安装

1. 下载 `webmail-sender-extension-1.2.1.zip`，核对同名 `.sha256` 文件中的 SHA-256。
2. 解压 ZIP，不要直接选择 ZIP 文件。
3. 为每个发件邮箱创建一个独立的浏览器 Profile。一个 Profile 不能混用多个邮箱。
4. Chrome 打开 `chrome://extensions/`，Edge 打开 `edge://extensions/`。
5. 开启“开发者模式”，点击“加载已解压的扩展程序”，选择解压目录。

## 配对与登录

1. 在这个 Profile 中登录线上邮件发送助手。
2. 在“网页版发送邮件”中点击对应账号的“登录邮箱”。
3. 扩展完成一次性配对后会打开该服务商的官方邮箱。
4. 请使用 Chrome/Edge 密码管理器保存和填充密码。扩展只检查密码框是否已非空，不会读取、保存、记录或上传密码。
5. 当账号完全匹配、密码已填充、登录按钮可用且没有验证码/MFA/扫码/风控时，扩展最多自动点击一次登录。
6. 扩展通过 `/api/executor/v2/account-status` 回传检测结果；只有邮箱主页、实际账号和写信入口全部通过，线上账号才会显示“已登录，可发送”。

## 安全和运行规则

- 服务器不安装、不运行 Chromium、Xvfb、Playwright 或 noVNC。
- 服务器只保存邮箱账号配置、任务、租约和结果；邮箱密码不上传。
- 扩展 Token 只在 Service Worker 内使用，不会发送到邮箱 Content Script。
- 验证码、MFA、扫码或风控页面必须由用户自己处理。
- 扩展心跳每 30 秒一次；离线超过 90 秒后，服务器不再把该账号当作可用执行器。
- 定时任务遇到离线账号时，服务器只会在同一任务已选账号中查找在线且可用的替代账号；不会跨项目或跨任务借用账号。
- 已取得发送授权后无法确认结果时，任务进入 `unknown/VERIFY_PENDING`，不会自动重发。

## 更新

线上提示版本过旧时，下载新 ZIP，解压到新目录，然后在扩展管理页移除旧版并加载新目录。绑定失效时重新点击“登录邮箱”配对。

## 服务器部署检查（由运维执行）

服务器不需要安装浏览器。部署环境应保持：

```env
WEBMAIL_EXTENSION_EXECUTOR_ENABLED=true
REMOTE_WEBMAIL_BROWSER_ENABLED=false
WEBMAIL_LOCAL_BROWSER_ENABLED=false
WEBMAIL_EXTENSION_MINIMUM_VERSION=1.2.1
```

同时按已验收范围配置 `WEBMAIL_SENDER_ENABLED`、各邮箱服务商开关和独立的 `WEBMAIL_EXTENSION_BCC_*_ENABLED` 开关。所有扩展密送开关默认必须是 `false`，实机完成 1 人、10 人、11 人拆组及目标上限测试后，才能逐个开启。

不要因为部署扩展架构而执行 `20261110_001_remote_webmail_credentials` 或 `20261110_002_remote_webmail_browser_lease`；这两项属于已停用的服务器浏览器方案。扩展复用以下已有结构，不新增迁移：

- `20260928_001_local_executor_control_plane`
- `20261006_001_webmail_pages`
- `20261009_001_browser_mailbox_batches`
- `20261016_001_sina_bcc_groups`（仅启用多人密送时需要）
- `20261109_003_webmail_login_handoffs`

如果生产库出现“字段已经存在，但 `schema_migrations` 没有记录”的情况，不能直接重跑整批迁移：

1. 先做数据库备份。
2. 只读核对对应 SQL 涉及的表、字段和索引是否全部存在且定义一致。
3. 结构完全一致时，才由 DBA 单独补写该迁移版本记录。
4. 结构不完整时，只执行确认缺失且幂等的那一项迁移。
5. 重启后检查 `/api/health`：`webmailExtension.enabled=true`、`webmailExtension.serverBrowserRequired=false`，并确认 `buildCommit` 与服务器实际提交号一致。

不允许通过删除字段、清空 `schema_migrations` 或强制重放所有迁移来“修复”记录不一致。
