# 产品需求文档 (PRD)：ProjectMoneyX

## 1. 产品概述

**ProjectMoneyX** 是一款专为 FireFlyIII 设计的个人财务自动化数据清洗与导入中间件。它通过统一的数据标准，将分散在支付平台、银行、生活服务及加密货币交易所的零散账单，转化为结构化的财务数据，并无缝对接至 FireFlyIII 的 DataImporter，实现全资产的自动化流转与管理。

## 2. 核心痛点与解决思路

* **痛点**：多平台账单格式各异，手动整理耗时且易错；跨账户转账（如从建行转入支付宝）容易被重复记账（一笔支出，一笔收入）。
* **解决思路 (核心价值)**：
* **标准化**：将千奇百怪的源数据映射为统一的内部数据模型（Standard Schema）。
* **智能化去重与合并**：识别跨账户转账，将单边记录闭环为完整的复式记账流（Double-Entry Journal）。
* **无缝对接**：作为前置清洗层，让 FireFlyIII 专注财务分析，而非脏数据处理。



## 3. 产品架构与数据流转规则

### 3.1 规则映射策略：两段式分离（解答您的疑问）

强烈建议**不要**在 ProjectMoneyX 中做业务类的分类映射（如“买菜”映射到“餐饮”），这会与 FireFlyIII 的 Rule Engine 功能重叠且难以维护。

* **第一阶段（ProjectMoneyX 负责 - 数据对齐）**：负责**字段级映射**。将各平台的异构字段（如支付宝的“交易对方”、银行的“附言”）统一映射为标准数据字段（Date, Amount, Payee, Description, Source Account）。
* **第二阶段（FireFlyIII 负责 - 业务分类）**：利用 FireFlyIII 本身的规则引擎，基于整理好的 Payee 和 Description，自动分配 Budget、Category 和 Tags。

### 3.2 数据流转拓扑

`多源账单导入` -> `解析器 (Parser)` -> `标准化入库 (SQLite)` -> `链路合并与去重 (Deduplication)` -> `格式化输出 (API)` -> `DataImporter / FireFlyIII`

## 4. 核心功能需求

### 4.1 多源数据接入 (Data Ingestion)

系统需支持通过插件化/模块化的方式接入各类账单文件（CSV/Excel/API）：

* **支付平台**：支付宝（Alipay）、微信支付（WeChat Pay）。
* **传统银行**：建设银行、工商银行、中信银行、汇丰银行（需考虑不同语言/地区的账单格式兼容）。
* **电商/生活平台**：美团、京东（主要用于细化支付平台的笼统账单，例如将微信支付的“美团订单”替换为具体的“外卖-商家名”）。
* **加密货币**：Binance、ByBit（需支持将 Crypto 交易折算为基础法币，或保留原始币种对接 FireFlyIII 的多货币系统，需考虑手续费剥离）。

### 4.2 本地数据清洗与存储 (Cleanse & Store)

* **统一数据模型**：所有解析后的数据写入本地 SQLite。核心字段应包含：`Original_ID`, `Platform`, `Transaction_Time`, `Amount`, `Currency`, `Transaction_Type` (入账/出账), `Opposite_Party` (交易对手), `Remark`。
* **数据幂等性校验**：基于平台提供的唯一交易流水号（Original_ID）进行绝对去重，确保同一份账单多次上传不会重复落库。

### 4.3 智能去重与链路合并 (Deduplication & Linkage)

这是本系统的**核心亮点**。针对跨账户资金流动，进行模糊匹配与链路合并：

* **时间与金额双重校验（Time-Amount Window）**：
* 设置可配的时间容差（如 $\pm 5$ 分钟）。
* 金额精准匹配（考虑可能存在的手续费，可设置极小金额容差）。


* **转账链路闭环**：
* *场景*：银行卡支出 1000 元（流向支付宝），支付宝收入 1000 元。
* *动作*：系统在 SQLite 中扫描到这两笔符合“时间窗+金额”匹配的相反流水，将其从“两笔独立的支出和收入”合并为“一笔内部转账 (Transfer)”，源账户为银行卡，目标账户为支付宝。



### 4.4 自动化导出与推送 (Export & Integration)

* **标准 CSV 生成**：基于 SQLite 中已清洗且合并的数据，生成完全符合 FireFlyIII DataImporter 规范的 CSV 文件。
* **API 推送集成**：支持通过 Webhook 或直接调用 DataImporter 的 API 接口，实现“本地清洗完毕 -> 自动触发 DataImporter 导入任务”的丝滑体验。

## 5. 非功能需求与产品设计优化建议

* **本地优先原则**：鉴于财务数据的极度敏感性，项目应完全采用本地化部署（Docker/本地命令行），SQLite 数据库仅存在于本地。
* **插件化架构**：银行和平台的账单格式随时可能变更。建议在代码架构上将“解析器(Parser)”设计为独立模块。未来当某银行格式改变时，只需更新对应 Parser 脚本，而无需重构主程序。
* **对账可视化（可选进阶）**：提供一个简单的本地 Web UI 页面，展示“未成功匹配的孤儿转账记录”，允许用户手动干预合并。