# ProjectMoneyX 产品需求文档（PRD） ## 1. 产品概述 ### 1.1 产品名称 **ProjectMoneyX** ### 1.2 产品定位 ProjectMoneyX 是一个面向个人财务与账务归集场景的**本地化账单清洗、去重、归一化与导入编排系统**。 其目标是为 **Firefly III + Data Importer** 提供自动化的数据预处理能力，解决多平台账单格式不统一、重复交易难识别、导入前数据质量差、分类规则分散等问题。 ### 1.3 产品愿景 让用户可以将来自支付平台、银行、生活服务平台、交易所等多源账单，一键汇总为统一结构，经过规则映射与去重合并后，稳定导入 Firefly III，形成可持续、可审计、可复用的个人财务数据资产。 --- ## 2. 背景与问题定义 ### 2.1 当前问题 用户当前面临的核心问题包括： 1. **数据源分散**：账单来源覆盖支付宝、微信、银行、生活服务平台、交易所，导出格式各异。 2. **字段不统一**：不同平台对时间、金额、收支方向、交易类型、对手方、备注等字段定义不同。 3. **存在重复与链路拆分**：同一笔真实交易可能在多个来源中出现，或在单一来源中拆成多条流水（如下单、支付、退款、手续费）。 4. **导入链路复杂**：Firefly III 的 Data Importer 偏重“导入”，但并不擅长承担复杂的本地多源清洗编排。 5. **分类规则分散**：若完全依赖 Data Importer 进行规则映射，会导致多来源规则难以统一沉淀和复用。 ### 2.2 真实需求意图 从初始需求看，用户真正需要的并不只是“导入工具”，而是一个完整的： * **多源账单标准化中台** * **本地清洗去重引擎** * **可配置规则映射系统** * **面向 Firefly III 的导入适配层** 也就是说，ProjectMoneyX 的核心不是替代 Firefly III，而是成为其前置的“数据治理层”。 --- ## 3. 产品目标 ### 3.1 核心目标 1. 支持多源账单文件导入并解析为统一结构。 2. 支持在本地完成清洗、标准化、规则映射、去重与链路合并。 3. 支持通过 API 或中间文件方式将数据导入 Data Importer / Firefly III。 4. 支持将清洗后的标准交易持久化到本地 SQLite，便于追溯、重跑和校验。 ### 3.2 成功标准（MVP） 1. 用户可导入至少 3 类主流账单（支付平台、银行、生活消费平台）。 2. 同一批数据可在本地完成去重并输出统一交易记录。 3. 用户可完成从“上传文件 → 预览清洗结果 → 应用规则 → 导入 Firefly III”的闭环。 4. 导入失败可追溯到原始文件、解析结果和转换结果。 --- ## 4. 目标用户 ### 4.1 核心用户 * 有多平台消费/收支记录的个人用户 * 使用 Firefly III 进行个人财务管理的进阶用户 * 有一定技术能力，希望本地掌控账单数据的用户 ### 4.2 用户特征 * 注重隐私，倾向于本地部署 * 可接受文件导入而非完全自动爬取 * 关注财务统计的一致性与长期可维护性 --- ## 5. 产品范围 ### 5.1 本期范围（In Scope） 1. 本地账单文件导入（CSV / Excel / 常见文本格式） 2. 多来源适配器解析 3. 统一交易模型转换 4. 本地规则映射 5. 去重与链路合并 6. SQLite 本地持久化 7. 导入结果预览 8. 对接 Firefly III / Data Importer 的导入能力 9. 导入任务日志与失败重试 ### 5.2 非本期范围（Out of Scope） 1. 直接登录第三方平台自动抓取账单 2. 银行/平台开放 API 的在线拉取（后续可扩展） 3. 完整 BI 分析平台 4. 替代 Firefly III 的账本能力 5. 高频实时同步（本期以“批量导入”为主） --- ## 6. 核心产品方案 ## 6.1 总体流程 **完整业务链路：** 1. 用户上传账单文件 2. 系统识别来源类型（或用户手动指定） 3. 使用对应解析器提取原始账单记录 4. 将不同来源映射为统一交易结构 5. 执行清洗规则（字段标准化、金额修正、时间格式统一、币种规范化等） 6. 执行去重与链路合并 7. 执行分类/账户/标签规则映射 8. 生成待导入数据集 9. 用户预览并确认 10. 通过 API 或导出中间格式导入 Data Importer / Firefly III 11. 写入任务结果、日志与状态 --- ## 6.2 模块设计 ### 模块 A：数据源接入模块 负责接收和管理多来源账单文件。 **功能点：** * 支持文件上传 * 支持来源类型选择/自动识别 * 支持批量文件导入 * 支持记录原始文件元信息（文件名、来源、导入时间、哈希值） **首批支持来源：** * 支付平台：支付宝、微信 * 银行：建设银行、工商银行、中信银行、汇丰银行 * 生活服务平台：美团、京东 * 交易平台：币安、ByBit（优先支持现货/资金流水，复杂交易后续逐步扩展） --- ### 模块 B：解析与标准化模块 负责将不同来源账单解析为统一数据结构。 **目标：** 建立统一交易模型，屏蔽不同平台字段差异。 **统一交易核心字段建议：** * transaction_id（系统内唯一 ID） * source_type（来源类型） * source_platform（来源平台） * source_record_id（原始记录 ID） * trade_time（交易时间） * amount（金额） * currency（币种） * direction（收入/支出/转账/退款/手续费） * counterparty（交易对手） * merchant_name（商户名） * category_raw（原始分类） * order_id（订单号） * parent_order_id（父链路号） * note（备注） * raw_payload（原始记录快照） * import_batch_id（导入批次） * status（待清洗/待导入/已导入/失败） **标准化规则：** * 时间统一为本地标准时区 * 金额统一为 decimal，高精度保存 * 正负号规则统一（支出为负/收入为正，或独立 direction + 正金额，需产品统一） * 交易类型统一到平台无关的业务枚举 --- ### 模块 C：去重与链路合并模块 负责识别重复流水与同一业务链路的多条记录。 #### 1）去重目标 解决以下问题： * 同一账单被重复导入 * 同一交易在多个来源重复出现 * 同一文件中存在重复记录 #### 2）链路合并目标 解决以下问题： * 一笔真实消费对应多条流水（支付、优惠、退款、手续费） * 同一订单在不同平台产生镜像记录（如京东订单 + 微信支付流水） #### 3）建议策略 采用“**基础去重 + 业务链路合并**”双层模型： **A. 基础去重（严格去重）** 优先使用以下唯一性组合： * 来源平台 + 原始记录 ID * 文件哈希 + 行指纹 * 订单号 / 交易单号（若可信） **B. 模糊去重（相似去重）** 当缺少唯一 ID 时，使用以下组合评分： * 时间窗（如 ±2 分钟 / 可配置） * 金额一致 * 交易方向一致 * 对手方相似 * 订单号相同或相近 * 来源平台关联规则命中 **C. 链路合并** 对疑似同一业务链路的记录进行聚合，形成主交易 + 附属事件： * 主交易：消费/收入主体 * 附属事件：手续费、退款、优惠抵扣、汇率损耗等 #### 4）产品决策 初稿中提出“通过时间窗与金额双重校验进行链路合并”，这是合理起点，但不足以覆盖真实复杂场景。应升级为： **“时间窗 + 金额 + 方向 + 订单号 + 对手方 + 来源规则”的多因子判定机制**。 --- ### 模块 D：规则映射模块 负责将标准化交易映射到最终记账语义。 #### 1）规则映射内容 * 分类映射（餐饮、交通、工资、转账等） * 账户映射（微信零钱、支付宝余额、建设银行卡等） * 对手方映射（商户标准化） * 标签映射（报销、家庭、订阅、投资） * Firefly III 目标字段映射 #### 2）关键产品决策：规则应放在哪里？ 针对初稿中的疑问：“本地进行数据规则映射，还是统一由 Data Importer 进行规则映射？” **建议结论：** > **以本地规则映射为主，Data Importer 规则映射为辅。** #### 3）原因 1. **多源统一能力更强**：本地能先统一语义，再输出稳定格式。 2. **规则可沉淀**：用户长期积累的分类规则、商户别名、账户映射，不应绑定在某个导入器实例里。 3. **可解释性更高**：用户能在导入前看到“这条为何被分到餐饮/交通”。 4. **迁移性更好**：即使未来不使用 Data Importer，也能复用规则引擎。 #### 4）保留策略 仍保留 Data Importer 的简单映射能力，用于： * 最后一层字段兼容 * 临时补充规则 * 与 Firefly III 导入格式保持兼容 --- ### 模块 E：导入编排模块 负责将清洗后的数据导入 Firefly III 生态。 #### 1）导入方式 优先支持两种模式： **模式 A：API 推送模式（优先）** * 调用 Data Importer 或 Firefly III API * 自动发起导入任务 * 可追踪返回结果 **模式 B：中间文件导出模式** * 生成 Data Importer 可接收的标准 CSV/JSON * 用户手动导入 * 适合 API 不稳定或权限受限场景 #### 2）导入前校验 * 必填字段校验 * 金额/时间格式校验 * 账户映射完整性校验 * 重复导入拦截 #### 3）导入后反馈 * 导入成功数量 * 失败数量 * 失败原因分类 * 可重试记录列表 --- ### 模块 F：本地存储与审计模块 负责数据持久化与可追溯性。 #### 存储建议 使用 SQLite 存储以下核心数据： 1. 原始文件表 2. 原始解析记录表 3. 标准交易表 4. 去重关系表 5. 规则配置表 6. 导入任务表 7. 导入结果表 8. 操作日志表 #### 设计目标 * 支持重跑 * 支持审计 * 支持回溯某条交易来自哪个文件、哪个平台、经过哪些规则处理 --- ## 7. 核心用户场景 ### 场景 1：月度账单统一入账 用户每月从支付宝、微信、招商/建行导出账单，批量上传后，系统自动清洗并去重，用户确认后导入 Firefly III。 ### 场景 2：跨平台订单去重 用户在京东下单，通过微信支付；京东账单与微信账单均包含该笔信息。系统识别为同一订单链路，仅保留主交易并记录来源关联。 ### 场景 3：交易所流水整理 用户导入币安和 ByBit 资金流水，系统将充提币、手续费、现货买卖拆分为统一的账务事件，并映射到投资类账户与标签。 --- ## 8. 功能需求清单 ## 8.1 必须有（P0） 1. 文件上传与批量导入 2. 来源类型识别/选择 3. 多来源解析器框架 4. 统一交易模型 5. 本地 SQLite 存储 6. 去重机制 7. 链路合并机制 8. 规则映射（分类/账户/标签） 9. 导入预览 10. API / 文件两种导入方式 11. 导入日志与失败重试 ## 8.2 应该有（P1） 1. 规则模板库 2. 商户别名归一化 3. 用户可配置时间窗与去重阈值 4. 导入批次管理 5. 手动合并/手动拆分疑似交易链路 ## 8.3 可以有（P2） 1. 自动来源识别增强 2. 可视化规则调试 3. 简易统计报表（导入概览、分类占比） 4. 多账本导入支持 --- ## 9. 非功能需求 ### 9.1 性能 * 单次导入 1 万条记录应可完成解析与清洗 * 去重计算应可在合理时间内完成（建议 30 秒内完成主流程，视硬件而定） ### 9.2 安全 * 本地部署优先 * 敏感账单数据默认不上传云端 * API Token 加密存储 * 操作日志不泄露敏感字段 ### 9.3 可维护性 * 解析器应插件化 * 规则引擎应可扩展 * 去重策略支持配置化 ### 9.4 可追溯性 * 任一导入结果必须可追溯至原始文件与原始记录 * 任一规则命中必须可解释 --- ## 10. 产品信息架构（建议） ### 一级模块 1. 导入中心 2. 数据清洗 3. 规则管理 4. 导入任务 5. 数据审计 6. 系统设置 ### 关键页面 * 文件上传页 * 导入批次详情页 * 清洗结果预览页 * 重复记录处理页 * 规则配置页 * 导入结果页 * 错误记录页 --- ## 11. 关键交互原则 1. **先预览，后导入**：任何清洗结果必须允许用户确认。 2. **规则可解释**：每条交易应展示命中的规则。 3. **重复可回溯**：被判定重复/合并的记录必须可查看判定依据。 4. **失败可重试**：导入失败不应要求整批重做。 --- ## 12. 技术与架构建议（产品层约束） ### 12.1 架构建议 采用分层设计： * **Adapter 层**：各平台账单解析器 * **Normalize 层**：字段标准化 * **Match 层**：去重与链路合并 * **Rule 层**：分类/账户/标签映射 * **Export 层**：导出至 Data Importer / Firefly III * **Storage 层**：SQLite 持久化 ### 12.2 设计原则 * 平台差异尽量收敛在 Adapter 层 * 统一模型要稳定，避免被单个平台格式污染 * 导入层与规则层解耦，便于未来替换 Firefly III --- ## 13. 版本规划 ### V1（MVP） * 支付宝 / 微信 / 2 家银行账单支持 * 文件导入、解析、标准化 * SQLite 持久化 * 基础去重 * 基础规则映射 * Data Importer 导入 ### V1.5 * 美团 / 京东支持 * 链路合并增强 * 批次管理与失败重试 * 手工修正与确认流程 ### V2 * 币安 / ByBit 流水适配增强 * 高级规则系统 * 可视化统计与导入质量分析 * 多账本/多环境支持 --- ## 14. 风险与产品决策说明 ### 风险 1：不同平台账单格式频繁变化 **应对：** 采用插件化解析器 + 版本化适配 ### 风险 2：去重误判 **应对：** * 采用“严格去重 + 模糊去重”分层策略 * 引入人工确认队列处理低置信度记录 ### 风险 3：交易所流水语义复杂 **应对：** V1 仅支持资金流水和基础现货场景，衍生品/复杂划转后续扩展 ### 风险 4：过度依赖 Data Importer **应对：** 将核心规则与标准化能力沉淀在本地，导入器仅作为输出目标之一 --- ## 15. 最终产品结论（精炼版） ProjectMoneyX 不是一个“简单导入工具”，而是一个面向 Firefly III 的**本地账单数据治理中台**。 它的核心价值在于： * 汇聚多源账单 * 统一交易语义 * 去重并还原真实交易链路 * 在本地完成规则映射沉淀 * 稳定输出到 Firefly III / Data Importer 其中最关键的产品决策是： > **规则映射应以本地为主，Data Importer 为辅；去重策略应从“时间窗 + 金额”升级为多因子判定；SQLite 不仅是缓存，更是清洗结果与审计链路的核心数据底座。**