静态表单升级为真实邮件与 CRM

什么时候使用这个技能

当用户提出“让表单真的工作起来”的需求时，就应考虑调用该技能。典型场景包括输入邮箱后收到 PDF 下载链接、提交咨询表单到 CRM、把订阅邮箱保存到邮件营销平台，或提交后同时自动回复并记录销售线索。

使用前需要确认的信息

正式改造前，需要先确认表单的业务承诺。业务承诺是指用户提交后页面到底承诺发生什么，例如“下载链接已发送到邮箱”“顾问将在 24 小时内联系你”或“完整 PDF 已解锁”。如果承诺不清晰，技术实现就容易和用户预期错位。

标准执行流程

技能建议先写入项目待办，再进行最小范围文件检查。通常只需要查看表单页面、路由文件、样式文件和项目配置，不应重写无关页面或大范围改造视觉系统。这个流程强调渐进改造：先稳定前端体验，再接入 API；先校验输入，再连接服务商。

前端实现规范

前端负责可访问、清晰、可信的交互体验。表单应使用明确的 label、合适的 input type、可见 focus 状态、加载状态、错误提示和成功提示。若仍停留在静态演示分支，成功提示不能声称“邮件已发送”，而应明确为演示状态或页面已展示下载链接。

后端 API 设计规范

后端 API 应围绕表单目的设计聚焦端点。例如 PDF 下载留资可使用 POST /api/leads/pdf-download。服务端需要重新校验邮箱和必填字段，避免只依赖浏览器校验，并处理限流、线索写入、邮件发送、CRM 同步、错误码返回和失败日志。

建议使用稳定错误码，例如 invalid_email、missing_consent、rate_limited、email_failed 或 crm_failed，再由前端翻译为用户可理解的中文提示。

CRM 与邮件字段映射

真实运营流程不应只保存邮箱。为了后续分群、转化分析和自动化跟进，表单需要保留上下文信息。尤其是多个页面、多个产品或多个下载资产共用同一 CRM 时，缺少来源字段会降低线索价值。

验证清单

保存检查点前，需要同时验证构建和真实线索流。如果服务商凭证尚未配置，应使用 mock、占位接口或测试模式验证代码路径，并在交付中明确说明真实投递尚未启用。

常见失败与处理方式

如果表单在本地可用但发布后失败，首先检查部署环境是否真的包含对应 API 端点，以及环境变量是否已在部署环境配置。若邮件没有投递，需要检查服务商错误、发件域名验证、模板变量、退信、垃圾邮件拦截和发送额度。

交付模板

使用该技能完成任务后，最终交付应明确区分“已真实接通”和“仍需配置”的部分。尤其是邮件服务、CRM 同步和验证结果，需要用用户能理解的语言说明实际状态。