
# 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 不仅是缓存，更是清洗结果与审计链路的核心数据底座。**

