demo-nanchi/docs/email-import-module-reuse.md

Email Import 模块复用文档

本文档总结 nanchi/ltc-nanchi 项目中 email-import 组件的邮件解析和 AI 分析所用到的服务、API、数据表和字段，供另一项目复用参考。

---

一、整体流程概览

EML 文件 → 解析 → 保存 Email + EmailAnalysis → 联网验证（可选）→ 产品提取 → Agent 价值分析 → 背调

---

二、邮件解析相关

2.1 核心服务

服务	路径	职责
EmlImportService	shared/services/eml-import.service.ts	EML 解析主入口，整合云端 API + 本地解析
BrainworkEmlService	shared/services/brainwork-eml.service.ts	云端智能解析（元数据 + 正文 + 产品需求）
AttachmentUploaderService	shared/services/attachment-uploader/attachment-uploader.service.ts	附件上传到云存储

2.2 邮件解析 API

API	地址	方法	用途
Brainwork 解析	https://eml.brainwork.club:8900/api/parse	POST (FormData)	解析 EML，提取元数据、正文、产品需求等
认证方式	Header: X-API-Key	-	fmode_cb_tgUyPSUXWZeLCgXVoLoCfOBingKQ9yAp
深度分析参数	analyze_attachments=true	Query	启用附件产品需求提取

请求示例：

POST /api/parse?analyze_attachments=true
Headers: X-API-Key: <API_KEY>
Body: FormData { file: <EML File> }

返回结构 (BrainworkParseData)：

• messageId, subject, date, senderEmail, senderName
• toList, ccList - { name, email }[]
• cleanedBody - 清洗后的正文
• customerEmail, contactName, companyName, companyDomain, title
• direction: 'inbound' | 'outbound' | 'unknown'
• productDemands - 产品需求数组（含 productName, quantity, unitPrice, totalPrice, moq, specifications 等）

2.3 本地解析

• 使用 postal-mime 库解析 EML 获取附件二进制，用于上传
• 使用 EmlImportService 中的 buildParticipantsFromApi 等辅助方法构建参与人、线程信息

2.4 附件上传

• 存储：NovaStorage（fmode-ng）
• 服务：AttachmentUploaderService.uploadMultiple()
• 附件分析：可选 AI 分析，EML 导入时通常 enableAIAnalysis: false，直接使用 Brainwork 结果

---

三、AI 分析相关

3.1 核心服务

服务	路径	职责
EmailImportWorkflowService	shared/services/agent/email-import-workflow.service.ts	统一工作流：解析 → 保存 → 联网验证
GenerateApiService	shared/services/agent/generate-api.service.ts	调用 server.fmode.cn 的 Google Search、AI、Firecrawl
AiTaskFlowService	shared/services/agent/ai-task-flow.service.ts	AI 任务流编排
AgentValueAnalysisService	shared/services/agent/agent-value-analysis.service.ts	线索价值分析（五维度评估）

3.2 Generate API（server.fmode.cn）

Base URL: https://server.fmode.cn
认证: Authorization: Bearer <sessionToken> 或 localStorage.fmode_auth_token

接口	路径	方法	用途
Google 搜索	/api/apig/generate/plugin/google-search	POST	公司验证、市场情报
AI 模型	/api/apig/generate/minor/{model}	POST	分析、推理（如 gemini-2.5-flash）
Firecrawl 批量抓取	/api/apig/firecrawl/batch/scrape	POST	抓取官网等网页 Markdown/JSON

Google Search 请求：

{ "query": "string", "num": 5, "page": 1 }

AI Model 请求：

{ "content": "用户消息", "role_content": "系统角色" }

Firecrawl 批量抓取请求：

{
  "urls": ["https://example.com"],
  "formats": ["markdown", { "type": "json", "prompt": "...", "schema": {...} }],
  "pollInterval": 2,
  "timeout": 120
}

3.3 产品提取相关 API

API	地址	方法	用途
官网爬虫	https://scraper.brainwork.club:8445/api/ecommerce	POST	从官网 URL 提取产品列表

请求示例：

{ "url": "https://example.com" }

返回字段（产品相关）：products[] 含 name, price, category, description, specifications, certifications；另有 success, method, storeUrl, domainCorrected, socialLinks 等

3.4 产品提取逻辑（email-import 组件内）

• 邮件产品：优先用 aiClassification.requirementExtraction._rawDemands（Brainwork）+ 附件 productMentions + 关键词匹配（First Aid Kit, IFAK, Trauma Kit 等）
• 官网产品：调用爬虫 API，映射为 ProductItem

---

四、数据表与字段

4.1 Email

字段	类型	说明
messageId	string	消息 ID
inReplyTo, references, threadKey	string/array	线程
fromEmail, fromName, toEmails, ccEmails, bccEmails	string/array	收发件人
participants	array	参与人 { email, name, type, side }
subject, content, html	string	主题、正文
receivedAt	Date	接收时间
direction	string	inbound/outbound/unknown
status	string	unread 等
customerEmail, customerName, ourEmail, ourName	string	客户/我方识别
customerCompany	string	客户公司
priority	string	high/medium/low
source	string	imported_eml / imported_eml_email_import
suggestedRoleDescription	string	角色推断
customerType, country, region, isGovernment	string/boolean	AI 画像
companyScale, decisionMakerLevel, buyingPower	string	公司规模等
attachments	array	附件列表
aiAnalysis	Pointer→EmailAnalysis	关联分析对象

4.2 EmailAnalysis

字段	类型	说明
email	Pointer→Email	关联邮件
summary	string	摘要
intent	string	意图分类
requirementExtraction	object	需求提取 { productCategory, budget, quantity, urgency, _rawDemands }
customerProfile	object	客户画像
sentimentScore, confidence, leadPotential	number	情绪、置信度、线索潜力
nextSteps	array	建议行动
comprehensiveAnalysis	object	综合分析（含 verification）
verificationInfo	object	联网验证结果
attachmentAnalysis	object	附件分析
attachments	array	附件列表

4.3 Enterprise

字段	类型	说明
email	string	唯一标识（客户邮箱）
name	string	公司名称
industry, status	string	行业、状态
basic_info	object	domain, country, address, foundedYear, employeeCount, revenue 等
enterpriseProfile	object	企业画像、可信度
verificationData	object	联网验证数据 sources, companyProfile, keyFindings 等
marketIntelligence	object	市场情报（可选）

4.4 ContactInfo

字段	类型	说明
contactEmail, contactName	string	联系方式
phone, title	string	电话、职位
enterprise	Pointer→Enterprise	关联企业

---

五、联网验证流程（EmailImportWorkflowService）

1. 从 customerEmail / fromEmail 提取域名
2. 构建官网 URL：https://{domain}, https://www.{domain}
3. 调用 GenerateApiService.firecrawlBatchScrape() 抓取 + 结构化提取（JSON schema 含 company_name, industry, country, founded_year, employee_count 等）
4. 调用 GenerateApiService.callAIModel('gemini-2.5-flash', ...) 分析抓取内容，得到 WebSearchVerificationResult
5. 更新 EmailAnalysis.verificationInfo 和 comprehensiveAnalysis.verification
6. 调用 EnterpriseContactService.createOrUpdateEnterprise() 更新/创建 Enterprise

---

六、Agent 价值分析（AgentValueAnalysisService）

1. 快速背调：Google Search + Firecrawl 抓取公司官网
2. 结构化提取：从抓取内容中提取 country, industry, employee_count, founded_year, certifications 等
3. AI 五维度评估：completionJSON（fmode-1.6-cn）结合线索信息 + 背调数据输出：
   • recommendation: 'continue' | 'abandon'
   • confidence, valueLevel
   • dimensions: match, opportunity, urgency, credibility, risk
   • reportMarkdown, nextActions
   • quickBgCheck: 快速背调摘要

---

七、依赖与包

• fmode-ng：Parse、FmodeParse、completionJSON、NovaStorage、FmodeChatCompletion
• postal-mime：本地 EML 解析
• Angular：HttpClient、Material 组件等

---

八、复用 Checklist

• 配置 Brainwork API Key（eml.brainwork.club）
• 配置 Generate API BaseUrl + 认证（server.fmode.cn）
• 配置官网爬虫 API（scraper.brainwork.club）
• 创建 Parse/后端表：Email, EmailAnalysis, Enterprise, ContactInfo
• 实现或复用 EmlImportService、EmailImportWorkflowService、AgentValueAnalysisService
• 实现附件上传存储（NovaStorage 或等价方案）
• 可选：调整产品匹配关键词、公司域名白名单（OUR_COMPANY_DOMAINS）