# AIMail

**Repository Path**: wangshujin/aimail

## Basic Information

- **Project Name**: AIMail
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-20
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIMail - 智能邮件管理系统

## 项目概览
AIMail 是一个基于 Python 的后端应用，旨在利用人工智能自动化并增强邮件管理。它能监控用户邮箱，执行增量邮件抓取，并利用大语言模型 (LLM) 对邮件进行分类、重要性评分以及生成合适的回复草稿。

### 主要技术
- **框架：** Flask (Python)
- **数据库：** MySQL (PyMySQL)
- **AI 集成：** OpenAI 协议兼容 API (支持 Qwen, Moonshot 等)
- **数据校验：** Pydantic (强类型 DTO & 自动入参校验)
- **可观测性：** 全链路 Trace ID 日志追踪 & 动态级别控制 (新)
- **文档：** Flasgger (Swagger UI)

---

## 🏗️ 系统架构图

```text
aimail/
├── App.py                  # 应用入口：初始化 Flask、蓝图注册、全局异常拦截、Trace ID 生成
├── controllers/            # 【Controller 层】接口适配：入参自动校验 (Pydantic)、Swagger 定义
│   ├── config_controller.py#   - 配置管理接口 (/config_add, /config_query)
│   ├── mail_controller.py  #   - 邮件核心接口 (/get_emails, /query_mail_results, /delete_mail)
│   └── user_controller.py  #   - 用户认证接口 (/user/login, /user/agree_protocol)
├── services/               # 【Service 层】业务逻辑：负责核心规则、流程编排、强类型 DTO 传递
│   ├── mail_service.py     #   - 统筹抓取、AI 分类、自动回复及入库的完整流程
│   ├── user_service.py     #   - 处理登录逻辑、MD5 校验、Token 生成
│   ├── config_service.py   #   - 处理复杂的配置字段映射与转换
│   └── task_service.py     #   - 封装后台定时监测任务，自动分配 Task-ID
├── models/                 # 【Model 层】数据访问：纯粹的数据库交互，管理 SQL 语句
│   ├── config_model.py     #   - 对应配置表、模型配置、邮箱账号表
│   ├── mail_result_model.py#   - 对应邮件处理结果表 (deal_mail_result)
│   └── user_model.py       #   - 对应用户信息表 (userInfo)
├── Ai/                     # 【基础设施】AI 核心：大模型接口调用、Prompt 管理
│   ├── prompts/            #   - 外部 Prompt 提示词库 (txt/jinja2)
│   └── Processor.py        #   - 封装 OpenAI SDK，处理分类和回复生成
├── Mail/                   # 【基础设施】邮件协议：底层通信实现
│   ├── Fetch.py            #   - IMAP 协议：增量抓取、附件处理
│   └── Send.py             #   - SMTP 协议：单发、回复、抄送
├── Filter/                 # 【基础设施】规则引擎
│   └── Core.py             #   - 邮件预处理：黑白名单拦截、关键词初步过滤
├── Common/                 # 【通用工具】
│   ├── Constants.py        #   - 枚举类 (Enum) 与业务常量管理
│   ├── Exceptions.py       #   - 自定义业务异常类
│   ├── Schemas.py          #   - Pydantic DTO 数据模型定义（核心校验源）
│   ├── Response.py         #   - 统一 API 返回结构工具
│   ├── Encryption.py       #   - 凭据加解密 (AES/Base64)
│   └── Utils.py            #   - 环境感知型日志配置、Trace ID 过滤器、通用工具
├── TokenAuth.py            # JWT 认证工具类 (已接入环境变量配置)
├── DBManager.py            # 数据库连接池管理
└── SQL/                    # 数据库初始化及升级脚本
```

---

## 🔍 全链路追踪：给日志发“身份证”

具体查看 ../Docs/日志追踪.md

### 1. 为什么需要它？
想象一下：你的后端服务像一家极其忙碌的医院。每秒钟有 100 个病人（请求）进来。
如果没有“挂号单”，医生（代码逻辑）随口喊一句：“测体温正常”、“开药失败”，你根本不知道这个结论是针对哪个病人的。
**Trace ID（请求身份证）** 就是这张挂号单。

### 2. 它的生命周期（原理过程）
1.  **出生 (Arrival)**：请求到达 `App.py` 时，系统生成一个唯一编号，如 `req-85d49fa`。
2.  **流动 (Flow)**：ID 被存放在 Flask 的 `g` 对象中。代码执行到哪，ID 跟着到哪。
3.  **打印 (Logging)**：在 `Common/Utils.py` 中，重写的日志处理器会自动提取 ID 塞进日志最前面。
4.  **告别 (Departure)**：ID 会被塞进响应头的 `X-Request-ID` 还给前端。

### 3. 如何排查问题？
如果用户反馈报错，获取其 `X-Request-ID`。在服务器输入：
```bash
grep "req-85d49fa" app.log
```
你就能**瞬间**看到该请求从“进门”到“出门”的所有轨迹。

---

## ⚙️ 环境感知：灵活控制日志级别

为了兼顾“开发时的详尽”和“生产时的整洁”，系统支持通过环境变量动态调整日志级别。

### 1. 如何设置？
在项目根目录的 `.env` 文件中修改 `LOG_LEVEL` 变量：
*   **开发环境 (Local)**: `LOG_LEVEL=DEBUG` (打印所有细节，包括调试信息)
*   **生产环境 (Prod)**: `LOG_LEVEL=INFO` 或 `LOG_LEVEL=WARNING` (只打印重要节点或警告/错误)

### 2. 级别对照表
| 级别 | 适用场景 | 说明 |
| :--- | :--- | :--- |
| **DEBUG** | 线下调试 | 记录代码运行的最细枝末节 |
| **INFO** | 日常监控 | 记录“邮件抓取成功”、“用户登录”等关键逻辑 |
| **WARNING** | 风险预警 | 记录“网络抖动导致重试”等不影响运行但需注意的问题 |
| **ERROR** | 故障排障 | 记录“AI 调用崩溃”、“数据库断开”等严重问题 |

---

## 开发规范

### 1. 统一返回结构
所有接口必须使用 `Common.Response` 提供的 `success_res` 或 `fail_res`。

### 2. Swagger 文档规范
所有对外接口必须通过 `@swag_from(dict)` 装饰器显式定义文档。

### 3. 统一异常处理
严禁手动返回错误 JSON。请直接 `raise BusinessError("错误信息")` 或让 Pydantic 校验自然触发。

---

## 运行与维护
- **启动项目**: `python App.py`
- **环境变量**: 
  - `LOG_LEVEL`: 控制日志详细程度
  - `JWT_SECRET`: JWT 加密密钥