4.9 KiB
4.9 KiB
产品需求文档 (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 页面，展示“未成功匹配的孤儿转账记录”，允许用户手动干预合并。