chore: 初始化文档站仓库

2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
@@ -0,0 +1,84 @@
+# 邮箱账单
+
+邮箱账单功能通过 **IMAP** 监听邮箱，当账单邮件到达时自动拉取附件，识别账单类型并进入待处理列表，由你预览后再确认导入。
+
+页面包含三个标签页：**邮箱配置**、**发件人规则**、**待处理账单**。
+
+## 邮箱配置
+
+![邮箱配置](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/email-bills-configs.png)
+
+配置用于接收账单邮件的 IMAP 邮箱：
+
+1. 点击右上角「**新增**」，填写邮箱信息：
+   - **名称**：便于识别的名称
+   - **IMAP 服务器**：可从内置列表选择或自定义（选择后自动填端口 993 并开启 SSL）
+   - **邮箱账号 / 授权码**：授权码在邮箱设置中开启 IMAP 服务后生成
+   - **监听文件夹**：默认 `INBOX`
+   - **默认归类**：默认支出/收入分类与标签
+   - **拉取范围**：仅新邮件 / 最近 N 天 / 最近 N 封
+   - **启用**：开启后持续监听
+2. 点击「保存」。
+
+![邮箱配置弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-email-config.png)
+
+- **IMAP 服务器**：可从内置列表选择（QQ、腾讯企业邮、163、126、网易企业邮、阿里云、新浪、139、189、Gmail、Outlook、iCloud）或自定义，选择内置服务器会自动填端口 993 并开启 SSL。
+- **邮箱账号 / 授权码**：授权码而非登录密码（在邮箱设置中开启 IMAP 服务后生成）。
+- **监听文件夹**：默认 `INBOX`。
+- **默认归类**：默认支出分类、收入分类与标签。
+- **拉取范围**：仅新邮件（增量）/ 最近 N 天 / 最近 N 封。
+- **启用**：开启后系统会持续监听该邮箱。
+
+行操作：
+
+- **测试连接**：验证 IMAP 配置。
+- **立即检查**：实时展示检查进度，完成后提示新增待处理账单数量。
+- **编辑 / 删除**。
+
+## 发件人规则
+
+![发件人规则](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/email-bills-sender-rules.png)
+
+根据邮件**发件人**识别账单类型与解析参数：
+
+- **发件人匹配串**：每行一个，支持完整地址、`@域名` 或关键字，包含匹配且忽略大小写。
+- **账单类型**：支付宝 / 微信 / 美团 / 淘宝 / 京东 / 招商银行 / 交通银行。
+- **解压密码**：账单压缩包加密时填写。
+- **默认归类**：默认支出分类、收入分类与标签。
+- **优先级**：值越小越优先。
+
+系统为常见账单邮箱预置了默认规则（如支付宝 `@alipay.com`、微信 `@wechatpay.com`、美团 `@meituan.com`、招行 `@message.cmbchina.com`、交行 `@bankcomm.com`）。
+
+## 待处理账单
+
+![待处理账单](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/email-bills-messages.png)
+
+展示已拉取、待处理的邮件账单，可按状态筛选（待解析 / 已导入 / 已忽略），列表每 30 秒自动刷新。
+
+行操作：
+
+- **解析**：选择账单类型与解压密码后解析，进入预览，确认后导入。
+- **忽略**：标记为已忽略，不再处理。
+- **删除**：删除该消息及本地附件。
+
+## 工作流程
+
+```text
+账单邮件到达
+   │
+   ▼
+IMAP 监听（IDLE 实时 / 轮询降级）
+   │  提取附件并保存
+   ▼
+发件人规则匹配 → 确定账单类型、解压密码、默认归类
+   │
+   ▼
+进入「待处理账单」（状态：待解析）
+   │  手动点「解析」→ 预览 → 确认导入
+   ▼
+写入收支记录（状态：已导入）
+```
+
+::: tip 先预览再导入
+邮箱账单不会自动写入账本，必须经过预览确认，避免误导入。
+:::