baiyue-firstleg/firstleg/docs/terminal-drayage-mail.md

码头车队邮件

行为

• 首次选择车队只保存车队；列表“发送邮件”提交当前版本和幂等键，向供应商资料中的单个邮箱发送提柜请求。
• 更换为另一车队时，以该柜、原车队是否存在 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% 缩放下截图确认。