# storlead-mail 子模块说明

邮件服务拆为四个 Maven 子模块，避免 CRM 与营销业务混在一起，调度统一编排。

## 模块

| 模块 | Artifact | 职责 |
|------|----------|------|
| common | `storlead-mail-common` | 账户、SMTP/IMAP、公共投递、`MailReceiveEngine` 收信引擎、`MailSceneEnum` |
| crm | `storlead-mail-crm` | CRM 个人邮箱：`emails` / `client_sent_emails`、收信、文件夹、CRM 集成任务 |
| mkt | `storlead-mail-mkt` | 营销投递：`mkt_mail_message` / `mkt_mail_attachment`、草稿、附件、延时、打开追踪 |
| dispatch | `storlead-mail-dispatch` | **统一调度**：定时发送（CRM+MKT）、CRM 收信拉取、服务器邮件延迟删除 |

依赖方向：

```
crm → common
mkt → common
dispatch → crm + mkt
api → dispatch
```

**crm 与 mkt 互不依赖**；调度放在 dispatch，避免任务只挂在 crm 里。

## 包名

- `com.storlead.sales.mail.common.*`
- `com.storlead.sales.mail.crm.*`
- `com.storlead.sales.mail.mkt.*`
- `com.storlead.sales.mail.dispatch.*`

API：

- `com.storlead.mail.common` — 账户配置
- `com.storlead.mail.crm` — CRM 邮件接口（原 `/mail/**`）
- `com.storlead.mail.mkt` — 营销接口（`/mail/mkt/**`）
  - `POST /mail/mkt/receive_mail?accountId=` — 异步收信（INBOX+Sent Items → `mkt_mail_message.folder`，`reply_msg_id` 绑定原信）
  - `POST /mail/mkt/file/cache_mail_file` — 上传临时附件（`scene=MKT`，需 `accountId`）
  - `POST /mail/mkt/file/list` — 按邮件查正式附件 `mkt_mail_attachment`
  - `POST /mail/mkt/file/download` — 下载正式附件
  - `POST /mail/mkt/file/download_temp` — 下载临时附件
  - `POST /mail/mkt/save_draft` — 保存草稿（`status=-2`，绑定 `fileIds`/`oldFileIds`）
  - `POST /mail/mkt/send` — 发送（CID 内嵌图、附件、延时、追踪像素；`isTrack=1` 需配置 `storlead.mail.track-base-url`）
  - `POST /mail/mkt/page_list` — 分页（支持 `opened` / `isTrack` / `bizBatchNo`）
  - `POST /mail/mkt/detail` — 详情（草稿带临时附件，成功带正式附件）
  - `POST /mail/mkt/open_stats?bizRef=` — 按业务单号汇总打开情况
  - `GET /mail/mkt/track/{token}` — 打开追踪像素（免登录，白名单）

### 打开追踪说明

1. 发信 `isTrack=1` → 生成 `track_token`，HTML 注入 1x1 像素  
2. 收件端加载图片 → `opened=1`，`first_open_time`，`open_count++`  
3. 可实现 `MktMailOpenCallback` 做业务侧「客户已打开」通知  
4. 像素仅为弱信号（网关预取/禁图会导致偏差）

临时附件共用 `mail_temp_attachment`（`scene` 默认 `CRM`）；正式附件 CRM/MKT 分表。

## 调度任务

| Job | 覆盖范围 |
|-----|----------|
| `DelaySendEmailTaskJob` | CRM 延时发信 + 营销延时发信 |
| `EmailPullHeadContentTaskJob` | 仅 CRM 收信（营销账户默认不收） |
| `DelayDeleteServerEmailTaskJob` | 仅 CRM IMAP 服务器删除 |

## 库表变更

执行：`storlead-mail-common/src/main/resources/sql/mail_scene_and_mkt.sql`  
状态表：`storlead-mail-common/src/main/resources/sql/mkt_mail_status.sql`  
黑名单：`storlead-mail-common/src/main/resources/sql/mkt_mail_blacklist.sql`

- `smtp_pop_settings` 增加 `scene` / `account_scope` / `org_id` 等
- 新建 `mkt_mail_message`、`mkt_mail_attachment`、`mkt_mail_status`、`mkt_mail_blacklist`
- `mail_temp_attachment` 增加 `scene`（默认 `CRM`）

### 营销黑名单

| 能力 | 说明 |
|------|------|
| 发信拦截 | `/mkt/send` 校验 TO/CC/BCC，命中则返回「无法发送 + 黑名单理由」 |
| 退信入黑 | INBOX 识别 mailer-daemon/undeliverable 等，提取失败地址写入黑名单 |
| SMTP 失败入黑 | `SendFailedException`/550 将收件人写入黑名单 |
| 管理接口 | `POST /mkt/blacklist/page_list`、`/save`、`/deleteIds`、`/enabled` |

### mkt_mail_status 埋点

| 事件 | 更新字段 |
|------|----------|
| 草稿/发送落库 | `ensureStatus` 初始化行，`status_updated_at=now`，`synced_at=null` |
| SMTP 成功/失败 | `send_status` = 1 / 2，刷新 `status_updated_at` |
| 像素打开 | `opened=1`，`open_count+1`，`first_open_time`（仅首次），`last_open_time=now`，同步 `is_read` / `first_read_time`，刷新 `status_updated_at` |
| 收信绑定回复 | 原信 `replied` / `first_reply_time`，刷新 `status_updated_at` |
| 业务同步完成 | 回写 `synced_at=now`（不改 `status_updated_at`） |

- `status_updated_at`：业务状态变更时间（打开/回复/发送态等）
- `synced_at`：业务侧最后同步时间
- 待同步条件：`synced_at IS NULL OR synced_at < status_updated_at`

存量升级执行：`storlead-mail-common/src/main/resources/sql/mkt_mail_status_add_synced_at.sql`