---
title: "Sales Data Extraction Agent"
type: source
tags: [Agent, Sales, Data-Extraction]
date: 2026-04-30
---

## Source File
- [[raw/Agent/agency-agents/specialized/sales-data-extraction-agent.md]]

## Summary（用中文描述）
- 核心主题：Sales Data Extraction Agent — 一个专注于监控 Excel 文件并提取销售指标（MTD、YTD、Year End）的 AI Agent
- 问题域：企业销售数据的实时采集与下游报表分发，需处理多种格式的 Excel 文件并保证数据完整性
- 方法/机制：文件系统监控 → 灵活列名映射 → 指标类型自动识别 → PostgreSQL 事务持久化 → 下游事件通知
- 结论/价值：实现销售数据的全自动化采集，100% 无人工干预，完整审计追踪

## Key Claims（用中文描述）
- Agent 通过文件系统监控（filesystem watcher）实时检测指定目录中的 .xlsx/.xls 文件（忽略 `~$` 临时锁文件），等待写入完成后触发处理流程
- Agent 使用模糊列名匹配（fuzzy matching）处理灵活多变的 Excel schema，支持 `revenue/sales/total_sales`、`units/qty/quantity` 等多种列名变体
- Agent 从工作表名称自动推断指标类型（MTD / YTD / Year End），并在 quota 和 revenue 同时存在时自动计算配额达成率
- Agent 以事务方式批量插入提取的指标到 PostgreSQL，每条记录附有源文件信息以支持完整审计追踪
- Agent 从不覆盖已有指标数据，仅在新文件版本出现时才更新；所有导入操作均记录文件名、处理行数、失败行数和时间戳

## Key Quotes
> "Never overwrite existing metrics without a clear update signal (new file version)" — 核心数据保护规则
> "Match representatives by email or full name; skip unmatched rows with a warning" — 数据匹配策略
> "Detect metric type from sheet names (MTD, YTD, Year End) with sensible defaults" — 指标类型推断逻辑

## Key Concepts
- [[FileSystemWatcher]]：通过文件系统监控检测新 Excel 文件，忽略 `~$` 临时锁文件，等待写入完成后触发处理
- [[FuzzyColumnMatching]]：使用模糊列名匹配处理 Excel schema 变化，支持 `revenue/sales/total_sales`、`units/qty/quantity` 等变体
- [[MetricTypeDetection]]：根据工作表名称（MTD / YTD / Year End）自动推断指标类型并设置默认值
- [[QuotaAttainment]]：当 quota 和 revenue 同时存在时自动计算配额达成率 = revenue / quota
- [[AtomicDataPersistence]]：使用 PostgreSQL 事务进行批量插入，保证数据原子性；每条记录附源文件审计字段
- [[AuditTrail]]：每次导入记录文件名、处理行数、失败行数和时间戳，支持下游追溯

## Key Entities
- [[PostgreSQL]]：目标持久化数据库，Agent 将提取的指标批量写入其中
- [[ReportDistributionAgent]]：下游消费 Agent，接收 Agent 发送的完成事件并分发报告

## Connections
- [[SalesDataExtractionAgent]] ← feeds ← Excel Files (source input)
- [[ReportDistributionAgent]] ← depends_on ← [[SalesDataExtractionAgent]]
- [[DataConsolidationAgent]] ← aggregates ← [[SalesDataExtractionAgent]] (推测：多个提取 Agent 向上游聚合)

## Contradictions
- 当前页面无冲突内容