overview.md

# 邮件智能分类 & Google Sheets 自动回填系统 — 交付概览

## 项目结构

```
wellfound-feedback/
├── app.py                    # Gradio 前端界面（入口）
├── src/
│   ├── config.py             # 环境变量配置管理
│   ├── email_parser.py       # .msg 邮件解析
│   ├── ai_classifier.py      # AI 分类（OpenAI/DeepSeek）
│   ├── sheets_updater.py     # Google Sheets 模糊匹配 + 写入
│   └── processor.py          # 处理管线（协调各模块）
├── requirements.txt          # Python 依赖
├── .env.example              # 环境变量模板（含详细注释）
├── .gitignore                # 安全排除 .env、密钥文件
├── space_config.md           # Hugging Face Space 元数据
└── README.md                 # 完整部署文档 + 用户操作手册
```

## 核心功能实现

### 📧 邮件解析（email_parser.py）
- extract-msg 解析 .msg 文件
- 提取：发件人邮箱、日期、主题、正文
- HTML 正文自动转纯文本（html2text）
- 从发件人域名提取备用公司名

### 🤖 AI 分类（ai_classifier.py）
- 支持 OpenAI（gpt-4o-mini）和 DeepSeek（deepseek-chat）
- 强制 JSON 输出，严格校验 8 种分类标签
- asyncio 异步 + Semaphore 并发控制
- tenacity 自动重试（3次，指数退避）
- 置信度评估（high / medium / low）

### 📊 Google Sheets 回填（sheets_updater.py）
- rapidfuzz token_sort_ratio 模糊匹配
- 可配置阈值（默认 85%）+ 歧义间隔（默认 3%）
- 三种匹配状态：exact / fuzzy / ambiguous / not_found
- 优先级覆盖策略：HIGH > LOW，同级保留最早数据
- 批量写入 AA/AB/AC/AD 列

### 🖥️ Gradio 界面（app.py）
- 拖拽多文件上传（.msg）
- 实时进度显示
- 结果表格（8列）
- ⚠️ 待确认区：下拉选框选择候选公司，一键确认回填
- 日志输出区（50行滚动）
- Google Sheets 连接状态测试

## 部署步骤（Hugging Face Spaces）

1. GitHub 新建仓库，推送此代码
2. HF Spaces 创建（SDK: Gradio），关联 GitHub 仓库
3. Settings → Secrets 配置：
   - `LLM_PROVIDER` = `openai` 或 `deepseek`
   - `OPENAI_API_KEY` 或 `DEEPSEEK_API_KEY`
   - `GOOGLE_SERVICE_ACCOUNT_JSON`（整个 JSON 内容）
   - `GOOGLE_SHEET_ID`
   - `GOOGLE_SHEET_NAME`
4. 等待自动部署，访问 Space URL

## 关键设计决策

| 问题 | 解决方案 |
|------|---------|
| 公司名提取不准确 | AI 提取 + 发件人域名双重后备 |
| 表格名称不统一 | rapidfuzz 模糊匹配（85% 阈值） |
| 同一公司多封回复 | 优先级矩阵（真人回复 > 自动回复） |
| API 调用失败 | tenacity 3次重试 + 友好错误提示 |
| 大批量并发 | asyncio.Semaphore(5) 排队处理 |
| 密钥安全 | 全部通过环境变量，.gitignore 排除 .env |