demo-nanchi 邮件导入·后端对接复用文档

前置约定：前端页面、组件、交互流程均保持不变，内容已确定。
本文档面向后端/服务对接，说明为支撑现有前端所需的外部 API、配置及数据契约。

一、前端不变前提下的对接范围

项目	说明
页面	Dashboard、lead-detail、list 等保持不变
组件	导入区域、筛选卡片、背调进度等保持不变
数据流	EML 导入 → 解析 → 填充表单 → 快速筛选 → 创建 Lead → 进入看板
对接重点	外部 API 配置、数据格式约定、后端需提供的接口（若有持久化）

二、外部 API 依赖（仅配置即可）

2.1 Brainwork EML 解析（前端直接调用）

配置项	值	说明
URL	`https://eml.brainwork.club:8900/api/parse`	固定
方法	POST (FormData: `file`)	-
认证	Header: `X-API-Key: fmode_cb_tgUyPSUXWZeLCgXVoLoCfOBingKQ9yAp`	需有效
参数	Query: `analyze_attachments=true`	启用附件产品提取

返回结构（前端已按此解析）：

{
  success: boolean;
  error: string | null;
  data: {
    messageId: string;
    subject: string;
    senderName: string;
    senderEmail: string;
    toList: { name: string; email: string }[];
    ccList: { name: string; email: string }[];
    cleanedBody: string;
    customerEmail: string;
    contactName: string;
    companyName: string;
    companyDomain: string;
    title: string;
    direction: string;
    productDemands?: Array<{
      productName: string;
      quantity?: string;
      unitPrice?: string;
      totalPrice?: string;
      moq?: string;
      specifications?: string;
    }>;
    attachmentStats?: { total: number; analyzed: number; skipped: number; bodyAnalyzed: boolean };
  };
}

2.2 Generate API（server.fmode.cn）

配置项	值	说明
Base URL	`https://server.fmode.cn`	固定
认证	`Authorization: Bearer <token>`	`localStorage.fmode_auth_token`

接口	路径	用途
Google 搜索	`/api/apig/generate/plugin/google-search`	快速筛查、背调
Firecrawl 抓取	`/api/apig/firecrawl/batch/scrape`	官网内容抓取
AI 模型	`/api/apig/generate/minor/{model}`	分析推理

2.3 可选：官网产品爬虫

配置项	值	说明
URL	`https://scraper.brainwork.club:8445/api/ecommerce`	POST `{ url: string }`
用途	若后续扩展「官网产品抓取」功能时使用	当前前端未接入

三、前端已用的数据契约（不可变更）

3.1 importData（EML 解析后填充）

{
  companyName: string;
  contactName: string;
  roleDescription: string;
  email: string;
  website: string;
}

映射关系：EmlParseData.companyName/companyDomain → companyName，customerEmail → email，companyDomain → website 等（前端已实现）。

3.2 QuickScreenResult（快速筛选输出）

前端依赖 QuickScreenService.screenManual() → QuickScreenResult → createLeadFromScreen() → Lead。

QuickScreenResult 须包含：companyName, domain, country, persona, personaLabel, personaConfidence, valueGrade, productRelevance, mainBusiness, estimatedScale, certRequirements, recommendedAction, suggestedProducts, scores, demandSnapshot, credibilityDetails, recommendedActions, socialLinks, confidence, processingTime 等（参见 lead.model.ts）。

3.3 Lead（创建后的线索）

前端展示依赖 Lead 的完整结构，包括 quickScreenResult, backgroundCheckReport, aiResearchReport 等。若后端提供 Lead 持久化，返回结构须与 Lead 接口一致。

四、后端可选能力（对接时需满足的契约）

若需持久化，后端需提供以下能力，且响应格式须与前端模型一致，否则需在网关层做适配。

4.1 表/实体参考（ltc-nanchi）

表	关键字段	与 Lead 的对应
Email	messageId, subject, content, customerEmail, customerCompany, attachments	导入来源，可关联 leadId
EmailAnalysis	emailId, summary, intent, requirementExtraction, verificationInfo	可映射到 quickScreenResult 等
Lead	与 `Lead` 接口字段对齐	直接映射

4.2 接口约定（示例）

POST /api/leads：创建 Lead，请求体与 Lead 兼容，返回完整 Lead。
GET /api/leads/:id：返回与 Lead 兼容的对象。
GET /api/emails/:id：若需要，返回与 Email 兼容的对象。

具体路径和字段以实际后端设计为准，此处仅说明前端期望的结构。

五、配置 Checklist（前端不变场景）

配置	说明	必选
Brainwork API 可用	`eml.brainwork.club:8900` 可访问，Key 有效	✅
Generate API Token	`localStorage.fmode_auth_token` 已设置	✅
官网爬虫	`scraper.brainwork.club:8445`	可选

六、参考

全量能力说明：docs/email-import-module-reuse.md
前端模型：lead-discovery/src/app/models/lead.model.ts
前端服务：ai-screen.service.ts、generate-api.service.ts、quick-screen.service.ts

email-import-for-lead-discovery.md 5.3 KB Permalink Histórico Raw