# 码头车队邮件

## 行为

- 首次选择车队只保存车队；列表“发送邮件”提交当前版本和幂等键，向供应商资料中的单个邮箱发送提柜请求。
- 更换为另一车队时，以该柜、原车队是否存在 `REQUEST_PICKUP` 邮件记录作为“是否已下发”的事实。已下发过时，与车队变更在同一数据库事务中依次生成原车队 `CANCEL_PICKUP`、新车队 `REQUEST_PICKUP` 两个任务，取消邮件使用原请求的收件地址快照；从未下发过时只生成新车队 `REQUEST_PICKUP`，不向原车队发送取消邮件。新车队必须为 ACTIVE/TRUCKING。
- 同一车队重复选择不发邮件、不改变版本。列表“发送邮件”允许人工重复点击，每次使用最新版本都会新增一封提柜请求，便于测试或再次通知；同一个幂等键的请求不会重复入队。
- 同柜严格顺序投递，取消未成功时新请求等待。失败不自动重发，避免 SMTP 超时后重复通知；人工核对未收到后通过邮件记录重试。进程中断超过五分钟的发送任务转为失败待核对。
- `SENT` 表示 SMTP 已接受邮件，不代表车队已阅读或执行。前端入队后只提示待发送，不伪装为成功投递。邮件记录展示最近 100 封，展示收件人、冻结主题和正文、状态及失败信息。
- 邮件发送、重试复用 `platform:firstleg:terminal-drayage:fleet:edit`，记录查看复用列表权限。已提柜、已卸柜或已还柜不再开放新的提柜邮件动作。

## 代码与存储

- `terminaldrayage/service/TerminalDrayageMailTemplates.java`：临时英文取消/提柜模板；正式文案在这里替换。已排队邮件保持原始正文快照。
- `TerminalDrayageMailService.java`：联系资料校验、邮件入队与重试；`TerminalDrayageMailDispatcher.java`：SMTP 投递。
- `terminaldrayage/mapper/TerminalDrayageMapper.java`：邮件存储与状态抢占；`fl_terminal_drayage_mail` 定义于 `src/main/resources/db/phase3-terminal-drayage-schema.sql` 和国内统一 SQL 入口。
- Warehouse `/internal/warehouse/v1/suppliers/{supplierId}/trucking-contact` 仅供内部令牌调用；地址不由浏览器提交。
- 公网接口及动作以 `src/main/resources/openapi/terminal-drayage-v1.yaml`、Warehouse `supplier-v1.yaml` 为准。

## 启用配置

Firstleg 增加 Spring Boot mail starter，仅用于 SMTP，不引入独立邮件平台。默认 `TERMINAL_DRAYAGE_MAIL_ENABLED=false`，可保存任务但不会发信。启用前需配置正式发件账号并核对待发送任务；启用后会投递已排队邮件。

| 环境变量 | 用途 |
|---|---|
| `TERMINAL_DRAYAGE_MAIL_ENABLED` | 默认 false，true 启用投递 |
| `TERMINAL_DRAYAGE_MAIL_HOST` | SMTP 主机 |
| `TERMINAL_DRAYAGE_MAIL_PORT` | 默认 587 |
| `TERMINAL_DRAYAGE_MAIL_USERNAME` | SMTP 登录账号，同时作为邮件发件地址；QQ 邮箱填写完整邮箱地址 |
| `TERMINAL_DRAYAGE_MAIL_PASSWORD` | SMTP 授权码，仅通过环境注入，不使用 QQ 登录密码 |
| `TERMINAL_DRAYAGE_MAIL_SSL` | 默认 false，强制 STARTTLS；true 使用隐式 TLS，一般配合 465 端口 |
| `TERMINAL_DRAYAGE_MAIL_SCAN_DELAY` | 默认 10000 毫秒 |

发布涉及 Admin、Firstleg、Warehouse 和新增邮件表；没有新增 IAM 权限。代码开发不授权部署、执行环境 SQL或向真实车队试发。UI 按现有列表与居中弹框承载，此新增交互依据当前用户需求，历史原型未定义邮件功能；待人工在 1920×1080、100% 缩放下截图确认。