email-invoice-fetcher

name	Email Invoice Fetcher
description	自动提取邮箱中的未读发票并下载为 PDF。支持附件型发票和百望云等纯链接发票。 触发关键词："拉取发票"、"提取发票"、"下载发票"、"fetch invoices"、"download invoices"。

Email Invoice Fetcher

扫描邮箱未读邮件 → 识别发票 → 智能命名 → 下载 PDF → 标记已读。全程自动化。

所有路径相对于本文件所在目录。脚本已内置 .env 自动定位，无需担心工作目录问题。

前置检查

首次使用前必须完成：

1. 检查项目根目录是否有 .env 文件。如无，将 .env.example 复制为 .env。
2. 提示用户在 .env 中填写 EMAIL_ACCOUNT（邮箱地址）和 EMAIL_PASSWORD（IMAP 授权码，不是登录密码）。
3. 确保已执行 pip install -r requirements.txt。

---

第一步：扫描未读邮件

python ./scripts/scan_invoices.py

返回格式

{"status": "success"|"error", "message": "...", "data": [...]}

异常处理：

• status 为 "error" → 向用户报告 message 中的错误原因，终止流程。
• data 为空数组 → 回复"当前无新发票"，结束流程。

data 中每封邮件的字段

字段	类型	用途
uid	string	邮件唯一 ID。必须原样传给第二步
date	string	邮件日期
subject	string	邮件主题，用于判断发票类型
pdf_attachments	string[]	PDF 附件名列表。非空 → 可用附件方式下载
pdf_links	string[]	正文中的 PDF 相关链接
baiwang_download_url	string|null	已拼好的百望云下载直链。非 null → 可直接用于 URL 下载
body_snippet	string	正文前 200 字摘要，用于提取商家名称和金额

AI 决策规则

逐封邮件判断：

1. 是否为发票：根据 subject + body_snippet 综合判断。广告、通知等非发票邮件直接跳过。
2. 确定下载方式：
   • pdf_attachments 非空 → download_type: "attachment"
   • baiwang_download_url 非 null → download_type: "url"，url 字段填入该值
   • pdf_links 中有可用链接 → download_type: "url"，url 字段填入对应链接
3. 智能命名：根据 subject 和 body_snippet 生成可读的中文文件名。

命名规则：{商家名称}_{发票类型}_{金额}元.pdf

示例：

• 老乡鸡_餐饮发票_31.6元.pdf
• 滴滴出行_交通发票_25元.pdf
• 华为云_云服务发票_199元.pdf

金额无法确定时可省略：某商家_电子发票.pdf

---

第二步：生成下载清单并执行

无需征求用户确认，直接将规划结果写入 ./scripts/targets.json：

[
  {
    "uid": "15302",
    "filename": "老乡鸡_餐饮发票_31.6元.pdf",
    "download_type": "attachment"
  },
  {
    "uid": "15301",
    "filename": "乡村基_餐饮发票_28元.pdf",
    "download_type": "url",
    "url": "https://pis.baiwang.com/bwmg/mix/bw/downloadFormat?param=02DA...&formatType=PDF"
  }
]

targets.json 字段规范

字段	必填	说明
uid	✅	来自扫描结果的邮件 UID（字符串类型）
filename	✅	保存的文件名，必须以 .pdf 结尾
download_type	✅	"attachment" = 从邮件附件提取；"url" = 从指定地址下载
url	仅 url 类型必填	当 download_type 为 "url" 时的下载地址

执行下载

python ./scripts/download_invoices.py

脚本行为：

• 逐个处理 targets.json 中的任务
• 下载成功 → 自动将该邮件标记为已读 (\Seen)
• 下载失败 → 保持邮件未读，不影响下次重试

汇报结果

向用户展示下载结果清单。文件默认保存在 .env 中配置的 DOWNLOAD_DIR 目录（默认 ./downloads）。