记账机器人 – 智能自动化记账解决方案-码农很忙

这是一个功能完整的自动化记账系统，通过读取银行发送到电子邮箱的消费信息，自动解析交易明细并同步到挖财记账应用。项目提供了一个基于 Web 的管理界面和完整的挖财 API SDK，支持多种银行邮件格式解析、基于 Jieba 分词的 AI 智能分类预测和自动化流水管理。

核心特性

🌐 Web 管理界面

账户管理：管理多个挖财账号，支持独立配置
数据源管理：配置和管理多个邮箱数据源
流水管理：查看、编辑和管理解析后的交易流水
AI 训练与预测：训练和使用 AI 模型进行交易分类
自动化任务：定时自动拉取邮件、解析和同步到挖财

📧 智能邮件处理

IMAP 协议支持：目前支持 163 邮箱
多银行支持：内置招商银行、交通银行等多种银行邮件解析器
智能解析：自动提取交易时间、金额、商户、余额等信息
HTML/文本双支持：支持 HTML 和纯文本格式的邮件

🤖 AI 智能分类

Jieba 分词：基于结巴分词的中文文本处理
智能过滤：自动过滤无效词汇，提取关键特征
金额范围识别：智能识别交易金额范围
可训练模型：支持基于历史数据训练分类模型

☁️ 完整的挖财 SDK

认证管理：Cookie-based 身份认证
账本操作：账本的创建、查询和管理
流水同步：批量上传交易流水到挖财
分类管理：获取和管理收入/支出分类
项目管理：项目（标签）的创建和管理

技术栈

后端技术

.NET 8.0：现代化的开发框架
ASP.NET Core MVC：Web 应用框架
NewLife.XCode：强大的 ORM 框架，提供实体管理和数据持久化
MailKit：邮件协议处理（IMAP）
Jieba.NET：中文分词处理，用于 AI 智能分类
HtmlAgilityPack：HTML 邮件解析
Newtonsoft.Json：JSON 序列化和反序列化

前端技术

NewLife.Cube：快速后台管理框架，提供开箱即用的 CRUD 界面
jQuery：JavaScript 库
Bootstrap：响应式 UI 框架（通过 Cube 集成）

项目结构

wacai-robot/
├── src/
│   ├── WaCai.Sdk/              # 挖财 API SDK
│   │   ├── Auth/               # 认证相关
│   │   ├── Books/              # 账本管理
│   │   ├── Categories/         # 分类管理
│   │   ├── Flows/              # 流水管理
│   │   ├── Projects/           # 项目管理
│   │   └── WaCaiApiClient.cs   # API 客户端
│   │
│   ├── WaCaiRobot.Core/        # 核心业务逻辑
│   │   ├── AI/                 # AI 相关功能
│   │   │   ├── AIHelper.cs     # AI 辅助工具（Jieba 分词）
│   │   │   └── FlowData.cs     # 训练数据模型
│   │   ├── Common/             # 公共组件
│   │   │   ├── Parsers/        # 银行邮件解析器
│   │   │   │   ├── _95555TextParser1.cs  # 招商银行解析器1
│   │   │   │   ├── _95555TextParser2.cs  # 招商银行解析器2
│   │   │   │   ├── _95559SmsParser.cs    # 招行短信解析
│   │   │   │   ├── CcsvcHtmlParser.cs    # 交行HTML解析
│   │   │   │   └── SmsParser.cs          # 通用短信解析
│   │   │   ├── FlowItem.cs     # 流水项
│   │   │   └── FlowType.cs     # 流水类型
│   │   ├── Config/             # 配置管理
│   │   ├── Entities/           # 数据实体
│   │   │   ├── 挖财账号.cs      # 账号实体
│   │   │   ├── 数据源.cs        # 数据源实体
│   │   │   ├── 流水消息.cs      # 消息实体
│   │   │   ├── 流水项.cs        # 流水实体
│   │   │   ├── 训练数据.cs      # 训练数据
│   │   │   └── 预测模型.cs      # 预测模型
│   │   ├── Auto.cs             # 自动化任务（定时15分钟）
│   │   └── FlowSaveItemBuilder.cs  # 流水构建器
│   │
│   ├── WaCaiRobot.Website/     # Web 管理界面
│   │   ├── Areas/WaCai/        # 管理区域
│   │   │   └── Controllers/    # 控制器
│   │   │       ├── WaCaiAccountController.cs    # 账户管理
│   │   │       ├── FlowSourceController.cs      # 数据源管理
│   │   │       ├── FlowMessageController.cs     # 消息管理
│   │   │       ├── FlowItemController.cs        # 流水管理
│   │   │       ├── WaCaiTrainController.cs      # 训练数据管理
│   │   │       └── WaCaiPredictController.cs    # 预测模型管理
│   │   └── Program.cs          # 应用入口
│   │
│   └── Tests/                  # 测试项目
│       ├── WaCai.Sdk.Test/     # SDK 测试
│       └── WaCaiRobot.Tests/   # 核心功能测试
│
├── docs/                       # 文档
│   ├── ARCHITECTURE.md         # 架构设计
│   ├── DEPLOYMENT.md           # 部署指南
│   └── EMAIL_PARSING.md        # 邮件解析指南
│
└── README.md

快速开始

前置要求

软件环境

.NET 8.0 SDK 或更高版本
支持的操作系统：Windows、Linux、macOS

账号准备

邮箱账号：支持 IMAP 的邮箱（如 163 邮箱、QQ 邮箱、Gmail 等）
需开启 IMAP 服务
建议使用应用专用密码（授权码）
挖财账号：用于同步记账数据
需要有效的挖财账号和密码
系统会自动获取并管理 Cookie

安装和运行

1. 克隆仓库

cd wacai-robot

2. 配置数据库

项目使用 NewLife.XCode ORM，默认使用 SQLite 数据库。首次运行会自动创建数据库和表结构。

3. 构建并运行

# 构建整个解决方案
dotnet build

# 运行 Web 应用
cd src/WaCaiRobot.Website
dotnet run

4. 访问管理界面

打开浏览器访问：http://localhost:5000（或控制台显示的地址）

5. 配置系统

5.1 添加挖财账号

进入 “挖财账号” 管理页面
点击 “添加” 创建新账号
填写以下信息：

账号名称：用于标识的名称
登录账号：挖财登录账号
登录密码：挖财登录密码
自动接收：是否自动从邮箱获取消息
自动提交：是否自动提交到挖财
提交开始时间：只提交此时间之后的流水

保存后，系统会自动后台登录并保存 Cookie

5.2 添加数据源

进入 “数据源” 管理页面
点击 “添加” 创建新数据源
填写邮箱配置：

数据源名称：如 “工商银行邮件”
所属账号：选择关联的挖财账号
类型：选择”邮件”
是否启用：勾选
密码/授权码：邮箱的应用专用密码

5.3 启动自动化任务

配置完成后，系统会每 15 分钟自动执行一次：

从邮箱拉取新消息
自动解析邮件内容
使用 AI 进行分类预测（如已训练模型）
同步到挖财

使用说明

Web 界面管理

挖财账号管理

在 Web 界面管理挖财账号：

账号信息：账号、密码会自动转换为 Cookie
自动接收：启用后会自动从数据源获取消息
自动提交：启用后会自动提交流水到挖财
提交开始时间：只提交此时间之后的流水记录
获取训练数据：从挖财拉取历史流水作为训练数据
训练模型：基于训练数据训练 AI 分类模型

数据源配置

支持多种数据源类型：

邮件数据源：

数据源名称：工商银行邮件
所属账号：选择挖财账号
类型：邮件
是否启用：√

短信数据源（如果使用短信转发）：

设置短信转发规则
配置短信解析器

流水管理

查看消息：

查看从邮箱或其他数据源获取的原始消息
查看解析状态（未解析、已解析、解析失败、已提交）
可手动触发重新解析

查看流水：

查看解析后的交易流水详情
包含时间、金额、商户、分类等信息
可手动编辑修正错误数据

流水操作：

手动编辑流水信息
重新解析消息
查看提交状态

AI 模型管理

系统使用基于 Jieba 分词的智能分类：

准备训练数据：

在 “挖财账号” 页面点击 “获取训练数据”
系统会从挖财拉取历史流水作为训练样本
查看和管理训练数据（”训练数据” 菜单）

训练模型：

在 “挖财账号” 页面点击 “训练”
系统会基于训练数据生成预测模型
使用 Jieba 分词进行商户名称特征提取
结合金额范围进行分类预测

使用预测：

训练后的模型会自动应用到新流水
在 “预测模型” 菜单查看模型详情
可查看预测准确率和使用情况

自动化任务

系统内置定时任务（每 15 分钟执行一次），自动完成以下流程：

循环账户：遍历所有启用自动接收的挖财账号
获取消息：从配置的数据源拉取新消息
解析流水：使用对应的解析器自动解析邮件内容
AI 分类：如已训练模型，使用 AI 预测交易分类
同步挖财：将流水自动提交到挖财（如启用自动提交）

邮箱配置说明

163 邮箱配置

登录 163 邮箱
进入 “设置” → “POP3/SMTP/IMAP”
开启 “IMAP/SMTP 服务”
获取授权码（应用专用密码）
使用配置：

IMAP 服务器：imap.163.com
端口：993
SSL：启用

工作流程

系统自动化流程

┌─────────────────┐
│  定时任务启动    │
│  (每15分钟)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  遍历挖财账户    │
│  (启用自动接收)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  拉取邮件消息    │
│  (IMAP 协议)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  解析邮件内容    │
│  (多种解析器)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  AI 智能分类     │
│  (Jieba 分词)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  同步到挖财      │
│  (WaCai SDK)    │
└─────────────────┘

AI 分类流程

系统使用基于 Jieba 分词的智能分类：

文本预处理：

使用 Jieba 对商户名称进行中文分词
过滤停用词（如”的”、”于”、”元”等）
过滤数字和无意义词汇

特征提取：

提取清洗后的关键词
识别金额范围（如 0-10元、10-30元等）
组合多维度特征

模型预测：

基于历史训练数据进行分类
返回最匹配的分类结果
支持持续优化和重新训练

扩展开发

添加新的银行邮件解析器

在 WaCaiRobot.Core/Common/Parsers/ 目录创建新的解析器类
实现邮件解析逻辑，提取关键信息（时间、金额、商户、余额等）
参考现有的解析器实现（如 _95555TextParser1.cs）

示例代码：

public class NewBankParser
{
    public static FlowItem? Parse(string content)
    {
        // 使用正则表达式或其他方法解析邮件
        var pattern = @"您在(.+?)消费(.+?)元";
        var match = Regex.Match(content, pattern);

        if (match.Success)
        {
            return new FlowItem
            {
                Merchant = match.Groups[1].Value,
                Amount = decimal.Parse(match.Groups[2].Value),
                Type = FlowType.Expense,
                Date = DateTime.Now
            };
        }
        return null;
    }
}

优化 AI 分类模型

准备更多训练数据：

使用 “获取训练数据” 功能从挖财拉取历史流水
手动标注和修正分类错误的数据
在 “训练数据” 页面管理训练样本

重新训练模型：

数据准备好后，在 “挖财账号” 页面点击 “训练”
系统会基于新数据重新生成模型
查看训练结果和预测准确率

调整分词策略：

编辑 AIHelper.cs 中的停用词列表
添加银行、支付相关的领域词汇
优化金额范围划分

扩展挖财 SDK

如果需要使用挖财的其他 API：

在 WaCai.Sdk 项目中添加新的 API 类
参考现有的实现（如 Books/Books.cs）
使用 WaCaiApiClient 进行 HTTP 请求
添加相应的输入输出模型类

自定义数据源

除了邮件，还可以添加其他数据源：

在 WaCaiRobot.Core/Entities/数据源.cs 中扩展类型
实现对应的消息获取逻辑
添加自定义解析器处理新格式
在 Web 界面中配置新数据源

部署建议

开发环境运行

cd src/WaCaiRobot.Website
dotnet run

访问 http://localhost:5000

生产环境部署

使用 Systemd（Linux）

发布应用：

dotnet publish -c Release -o /opt/wacai-robot

创建 systemd 服务文件 /etc/systemd/system/wacai-robot.service：

[Unit]
Description=WaCai Robot Web Service
After=network.target

[Service]
Type=notify
WorkingDirectory=/opt/wacai-robot
ExecStart=/usr/bin/dotnet /opt/wacai-robot/WaCaiRobot.Website.dll
Restart=always
RestartSec=10
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable wacai-robot
sudo systemctl start wacai-robot

使用 Nginx 反向代理

配置 Nginx：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Docker 部署（可选）

创建 Dockerfile：

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["src/WaCaiRobot.Website/WaCaiRobot.Website.csproj", "WaCaiRobot.Website/"]
COPY ["src/WaCaiRobot.Core/WaCaiRobot.Core.csproj", "WaCaiRobot.Core/"]
COPY ["src/WaCai.Sdk/WaCai.Sdk.csproj", "WaCai.Sdk/"]
RUN dotnet restore "WaCaiRobot.Website/WaCaiRobot.Website.csproj"
COPY src/ .
WORKDIR "/src/WaCaiRobot.Website"
RUN dotnet build -c Release -o /app/build

FROM build AS publish
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WaCaiRobot.Website.dll"]

运行 Docker：

docker build -t wacai-robot .
docker run -d -p 5000:80 -v /path/to/data:/app/data wacai-robot

注意事项

安全建议

保护敏感信息：

不要将配置文件提交到版本控制
定期更换邮箱密码和 Cookie
使用应用专用密码而不是主密码

访问控制：

生产环境建议配置身份验证
限制 Web 界面的访问 IP
使用 HTTPS 加密传输

数据备份：

定期备份数据库文件
备份训练好的 AI 模型
备份配置文件

使用限制

邮箱访问频率：

避免过于频繁访问邮箱服务器
建议间隔至少 5-15 分钟（系统默认 15 分钟）
遵守邮箱服务商的使用条款

挖财 API：

注意 API 调用频率限制
Cookie 可能会过期，需要重新登录获取
批量上传建议分批处理

邮件格式兼容性：

不同银行邮件格式可能不同
需要针对性添加或调整解析规则
HTML 邮件可能包含特殊格式，需单独处理

数据库：

默认使用 SQLite，适合个人使用
生产环境建议配置 MySQL 或 SQL Server
定期备份数据库文件

贡献指南

欢迎提交 Issue 和 Pull Request！

如何贡献

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

贡献方向

添加新的银行邮件解析器
改进 AI 分类算法
完善文档和示例
修复 Bug
性能优化
界面美化

路线图

[x] 基础邮件解析功能
[x] 挖财 SDK 开发
[x] Web 管理界面
[x] AI 智能分类
[x] 自动化定时任务
[ ] 更多银行支持
[ ] 移动端 App
[ ] 微信/支付宝账单解析
[ ] 数据分析和可视化
[ ] 多语言支持

致谢

开源项目

MailKit – 优秀的 .NET 邮件处理库
ML.NET – 微软机器学习框架
Jieba.NET – .NET 版本的结巴中文分词
NewLife.XCode – 强大的 ORM 框架和开发工具
HtmlAgilityPack – HTML 解析库

服务平台

挖财 – 提供记账服务平台

常见问题

基础问题

Q: 这个项目是做什么的？
A: 这是一个自动化记账系统，通过读取银行发送的邮件，自动解析交易信息并同步到挖财记账应用，支持基于 Jieba 分词的 AI 智能分类。

Q: 需要什么技术背景才能使用？
A: 具备基本的服务器部署能力即可。系统提供 Web 管理界面，不需要编程知识就能配置和使用。

Q: 支持哪些银行？
A: 目前内置招商银行、交通银行等解析器。其他银行可以通过添加自定义解析器支持。

Q: 支持哪些邮箱？
A: 支持所有提供 IMAP 服务的邮箱，包括 163 邮箱、QQ 邮箱、Gmail、企业邮箱等。需要开启 IMAP 服务并使用应用专用密码（授权码）。

配置问题

Q: 如何获取邮箱的应用专用密码？
A:

163 邮箱：设置 → POP3/SMTP/IMAP → 开启服务并获取授权码
QQ 邮箱：设置 → 账户 → 开启 IMAP/SMTP 服务 → 生成授权码
Gmail：开启两步验证 → 生成应用专用密码

Q: 如何获取挖财的 Cookie？
A: 不需要手动获取。在添加挖财账号时输入账号密码，系统会自动后台登录并保存 Cookie 信息用于后续的 API 调用。

Q: Cookie 多久会过期？
A: Cookie 的有效期由挖财服务器决定，通常为几天到几周。过期后系统会提示重新登录。

使用问题

Q: 邮件解析失败怎么办？
A:

在 “流水消息” 页面查看原始邮件内容
根据实际格式添加或调整解析规则
添加自定义解析器

Q: AI 分类不准确怎么办？
A:

使用 “获取训练数据” 功能从挖财拉取更多历史流水
在 “训练数据” 页面检查和修正标注
重新训练模型提高准确率

Q: 可以同时监控多个邮箱吗？
A: 可以。在 “数据源” 管理中添加多个邮箱配置即可，支持不同银行的邮件。

Q: 可以不使用 AI 分类功能吗？
A: 可以。如果不训练模型，系统会使用默认分类。您也可以在流水管理中手动指定分类。

Q: 自动化任务多久执行一次？
A: 系统默认每 15 分钟自动执行一次任务，包括拉取邮件、解析和同步到挖财。

技术问题

Q: 数据存储在哪里？
A: 默认使用 SQLite 数据库，数据文件存储在应用程序目录的 data 文件夹。可以配置使用 MySQL 或 SQL Server。

Q: 可以部署到云服务器吗？
A: 可以。支持部署到任何支持 .NET 8.0 的环境，包括 Linux 服务器、Docker 容器、云平台等。

Q: 项目开源吗？
A: 是的，项目采用 MIT 许可证，可以自由使用、修改和分发。

Q: 如何备份数据？
A:

备份数据库文件（SQLite 数据库文件位于 data 目录）
备份训练好的 AI 模型
备份配置文件

免责声明

本项目仅供学习和个人使用。使用本软件时请遵守相关服务的使用条款，开发者不对使用本软件造成的任何后果负责。

一	二	三	四	五	六	日
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30