# 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 请求：**
```json
{ "query": "string", "num": 5, "page": 1 }
```

**AI Model 请求：**
```json
{ "content": "用户消息", "role_content": "系统角色" }
```

**Firecrawl 批量抓取请求：**
```json
{
  "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 提取产品列表 |

**请求示例：**
```json
{ "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）