# ProjectMoneyX — 产品需求文档（PRD）

> **版本**：v1.0 | **日期**：2026-03-03 | **状态**：综合定稿

---

## 1. 产品概述

### 1.1 产品名称

**ProjectMoneyX**

### 1.2 产品定位

ProjectMoneyX 是一款面向 Firefly III 生态的**本地化多源账单数据治理中间件**。
它并非简单的"导入工具"，而是 Firefly III 的前置**数据治理层**——负责将分散在支付平台、银行、生活服务及加密货币交易所的零散账单，经过标准化清洗、智能去重与链路合并后，无缝推送至 Firefly III / Data Importer，实现全资产的自动化流转与管理。

### 1.3 产品愿景

让用户可以将来自多源账单**一键汇总**为统一结构，经过规则映射与去重合并后，稳定导入 Firefly III，形成**可持续、可审计、可复用**的个人财务数据资产。

---

## 2. 背景与核心痛点

### 2.1 当前问题

| # | 痛点 | 说明 |
|---|------|------|
| 1 | **数据源分散** | 账单来源覆盖支付宝、微信、银行、生活服务平台、交易所，导出格式各异 |
| 2 | **字段不统一** | 不同平台对时间、金额、收支方向、交易类型、对手方、备注等字段定义不同 |
| 3 | **重复与链路拆分** | 同一笔真实交易可能在多个来源中出现（如银行卡转支付宝同时出现在两方账单），或在单一来源中拆成多条流水（下单、支付、退款、手续费） |
| 4 | **导入链路复杂** | Data Importer 偏重"导入"，并不擅长承担复杂的本地多源清洗编排 |
| 5 | **规则分散** | 若完全依赖 Data Importer 进行规则映射，会导致多来源规则难以统一沉淀和复用 |

### 2.2 真实需求意图

从原始需求分析，用户真正需要的是一个完整的：

- **多源账单标准化中台** — 屏蔽平台差异
- **本地清洗去重引擎** — 消除重复与链路碎片
- **可配置规则映射系统** — 沉淀长期积累的分类知识
- **面向 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 数据流转拓扑

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  多源账单导入  │ -> │  解析器(Parser) │ -> │ 标准化入库     │ -> │ 去重与链路合并  │ -> │  规则映射      │ -> │ 导出/推送      │
│  (文件上传)   │    │  (Adapter层)   │    │ (SQLite)      │    │ (Dedup+Link)  │    │ (Rule Engine) │    │ (API/CSV)     │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
```

### 6.2 规则映射策略：两段式分离

> **关键产品决策**：规则映射采用"本地为主，Data Importer 为辅"的两段式策略。

**第一阶段 — ProjectMoneyX 负责（数据对齐 + 业务分类）**：

- **字段级映射**：将各平台异构字段（如支付宝"交易对方"、银行"附言"）统一映射为标准数据字段
- **业务分类映射**：将交易对手、描述等信息映射到分类（餐饮、交通、工资等）、账户、标签
- **商户名归一化**：统一商户别名（如"美团外卖-xxx店"→ 统一商户名）

**第二阶段 — Firefly III / Data Importer 负责（兜底与补充）**：

- 最后一层字段兼容适配
- 临时补充规则
- 与 Firefly III 导入格式保持兼容

**选择本地规则映射为主的核心理由：**

1. **多源统一能力更强**：本地能先统一语义，再输出稳定格式
2. **规则可沉淀**：用户长期积累的分类规则、商户别名、账户映射，不应绑定在某个导入器实例里
3. **可解释性更高**：用户能在导入前看到"这条为何被分到餐饮/交通"
4. **迁移性更好**：即使未来不使用 Data Importer，也能复用规则引擎

### 6.3 分层架构

```
┌─────────────────────────────────────────────────────┐
│                   Web UI / CLI                       │
├─────────────────────────────────────────────────────┤
│  Adapter 层    │ 各平台账单解析器（插件化）             │
├─────────────────────────────────────────────────────┤
│  Normalize 层  │ 字段标准化、统一交易模型转换            │
├─────────────────────────────────────────────────────┤
│  Match 层      │ 去重与链路合并                        │
├─────────────────────────────────────────────────────┤
│  Rule 层       │ 分类/账户/标签/对手方映射              │
├─────────────────────────────────────────────────────┤
│  Export 层     │ 导出至 Data Importer / Firefly III    │
├─────────────────────────────────────────────────────┤
│  Storage 层    │ SQLite 持久化 + 审计日志               │
└─────────────────────────────────────────────────────┘
```

**设计原则：**
- 平台差异尽量收敛在 Adapter 层
- 统一模型要稳定，避免被单个平台格式污染
- 导入层与规则层解耦，便于未来替换下游系统

---

## 7. 核心功能模块

### 7.1 模块 A：数据源接入模块

负责接收和管理多来源账单文件。

**功能点：**

- 支持文件上传（CSV / Excel / 常见文本格式）
- 支持来源类型自动识别或用户手动指定
- 支持批量文件导入
- 支持记录原始文件元信息（文件名、来源、导入时间、文件哈希值）

**首批支持来源：**

| 类型 | 平台 | 备注 |
|------|------|------|
| 支付平台 | 支付宝、微信支付 | 核心优先级 |
| 传统银行 | 建设银行、工商银行、中信银行、汇丰银行 | 需考虑不同语言/地区的格式兼容 |
| 生活服务 | 美团、京东 | 用于细化支付平台的笼统账单 |
| 加密货币 | 币安(Binance)、ByBit | 优先支持现货/资金流水，衍生品后续扩展 |

> **产品建议**：电商/生活平台的账单主要用于**细化**支付平台的笼统记录。例如，将微信支付的"美团订单"替换为具体的"外卖-商家名"。

### 7.2 模块 B：解析与标准化模块

负责将不同来源账单解析为**统一交易模型**，屏蔽不同平台字段差异。

**统一交易模型核心字段：**

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `transaction_id` | String | 系统内唯一 ID（自动生成） |
| `source_platform` | Enum | 来源平台（alipay/wechat/ccb/icbc/...） |
| `source_record_id` | String | 原始记录 ID / 交易流水号 |
| `trade_time` | DateTime | 交易时间（统一为本地标准时区） |
| `amount` | Decimal | 交易金额（高精度，正数） |
| `currency` | String | 币种（CNY/USD/USDT/...） |
| `direction` | Enum | 收入 / 支出 / 转账 / 退款 / 手续费 |
| `counterparty` | String | 交易对手 |
| `merchant_name` | String | 商户名 |
| `category_raw` | String | 原始分类（平台提供） |
| `category_mapped` | String | 映射后分类（规则引擎输出） |
| `order_id` | String | 订单号 |
| `parent_order_id` | String | 父链路号（用于链路合并） |
| `note` | String | 备注 |
| `raw_payload` | JSON | 原始记录快照（完整保留） |
| `import_batch_id` | String | 导入批次 |
| `status` | Enum | 待清洗 / 待导入 / 已导入 / 失败 |

**标准化规则：**

- 时间统一为本地标准时区（UTC+8）
- 金额统一为 Decimal 高精度保存
- 正负号规则统一：独立 `direction` 字段 + 正金额值
- 交易类型统一到平台无关的业务枚举

### 7.3 模块 C：去重与链路合并模块

这是本系统的**核心亮点**，负责识别重复流水与还原真实交易链路。

#### 7.3.1 去重目标

解决以下典型问题：

- 同一账单文件被重复导入
- 同一交易在多个来源重复出现（如银行卡转支付宝同时出现在两方账单）
- 同一文件中存在重复记录

#### 7.3.2 链路合并目标

解决以下典型问题：

- 一笔真实消费对应多条流水（支付、优惠、退款、手续费）
- 同一订单在不同平台产生镜像记录（如京东订单 + 微信支付流水）
- 跨账户资金流动产生的两笔独立记录

#### 7.3.3 三层去重策略

采用"**基础去重 → 模糊去重 → 链路合并**"三层递进模型：

**A. 基础去重（严格去重 — 精确匹配）**

基于以下唯一性组合进行绝对去重，确保同一份账单多次上传不会重复落库：

- 来源平台 + 原始记录 ID（`source_platform` + `source_record_id`）
- 文件哈希 + 行指纹
- 订单号 / 交易单号（若可信）

**B. 模糊去重（相似去重 — 多因子评分）**

当缺少唯一 ID 时，使用以下组合进行评分匹配：

- 时间窗（如 ±5 分钟，可配置）
- 金额精准一致（考虑手续费设置极小金额容差）
- 交易方向一致
- 对手方相似
- 订单号相同或相近
- 来源平台关联规则命中

> **多因子判定升级**：原始需求中提出"时间窗+金额双重校验"作为起点，实际应升级为**"时间窗 + 金额 + 方向 + 订单号 + 对手方 + 来源规则"的多因子判定机制**，以覆盖真实复杂场景。

**C. 链路合并（转账闭环）**

对跨账户资金流动与同一业务链路的记录进行聚合：

- **典型场景**：银行卡支出 1000 元（流向支付宝），支付宝收入 1000 元 → 合并为一笔**内部转账(Transfer)**，源账户=银行卡，目标账户=支付宝
- **主交易 + 附属事件**：消费/收入主体 + 手续费、退款、优惠抵扣、汇率损耗

#### 7.3.4 置信度与人工干预

- 高置信度记录：自动合并
- 低置信度记录：标记为"疑似重复/疑似链路"，进入人工确认队列
- 所有合并操作可回溯、可撤销

### 7.4 模块 D：规则映射模块

负责将标准化交易映射到最终记账语义。

**规则映射内容：**

| 映射类型 | 说明 | 示例 |
|----------|------|------|
| 分类映射 | 交易 → 预设分类 | "美团外卖" → 餐饮 |
| 账户映射 | 来源 → 账户名 | 微信支付 → 微信零钱 |
| 对手方映射 | 商户名标准化 | "饿了么-xxx店" → "饿了么" |
| 标签映射 | 交易 → 标签 | 可标记为：报销、家庭、订阅、投资 |
| Firefly III 字段映射 | 内部字段 → FF3 字段 | direction → type (withdrawal/deposit/transfer) |

**规则配置能力：**

- 支持基于正则、关键词、金额范围等条件的规则定义
- 支持规则优先级排序
- 规则命中结果可精确解释（每条交易展示命中的具体规则）
- 支持规则模板库，预置常见映射

### 7.5 模块 E：导入编排模块

负责将清洗后的数据导入 Firefly III 生态。

**模式 A：API 推送模式（优先）**

- 通过 Webhook 或直接调用 Data Importer / Firefly III API
- 自动发起导入任务
- "本地清洗完毕 → 自动触发 DataImporter 导入任务"的丝滑体验
- 可追踪返回结果

**模式 B：中间文件导出模式**

- 生成完全符合 Data Importer 规范的标准 CSV / JSON
- 用户手动导入
- 适合 API 不稳定或权限受限场景

**导入前校验：**

- 必填字段完整性校验
- 金额/时间格式校验
- 账户映射完整性校验
- 重复导入拦截

**导入后反馈：**

- 导入成功/失败数量统计
- 失败原因分类展示
- 失败记录可单独重试（无需整批重做）

### 7.6 模块 F：本地存储与审计模块

负责数据持久化与全链路可追溯性。

**SQLite 核心数据表：**

| 表名 | 说明 |
|------|------|
| `source_files` | 原始文件表（文件名、哈希、来源、导入时间） |
| `raw_records` | 原始解析记录表（原始数据快照） |
| `transactions` | 标准交易表（统一模型） |
| `dedup_relations` | 去重关系表（记录合并依据） |
| `rules` | 规则配置表 |
| `import_tasks` | 导入任务表 |
| `import_results` | 导入结果表 |
| `audit_logs` | 操作日志表 |

**设计目标：**

- 支持重跑：任意阶段可重新执行
- 支持审计：完整记录每条交易的处理全过程
- 支持回溯：任一交易可追溯到来源文件、来源平台、经过的规则处理链

---

## 8. 核心用户场景

### 场景 1：月度账单统一入账

用户每月从支付宝、微信、银行导出账单，批量上传后，系统自动清洗并去重，用户预览确认后一键导入 Firefly III。

### 场景 2：跨平台订单去重

用户在京东下单，通过微信支付。京东账单与微信账单均包含该笔信息。系统识别为同一订单链路，仅保留主交易并记录来源关联。

### 场景 3：跨账户转账闭环

用户从建行卡转入 1000 元到支付宝。银行账单显示"支出 1000"，支付宝账单显示"收入 1000"。系统匹配时间窗 + 金额，将两笔记录合并为一笔内部转账。

### 场景 4：交易所流水整理

用户导入币安和 ByBit 资金流水，系统将充提币、手续费、现货买卖拆分为统一的账务事件，并映射到投资类账户与标签。支持将 Crypto 交易折算为基础法币或保留原始币种。

### 场景 5：导入失败快速修复

某次批量导入中 5 条记录因账户映射缺失而失败。用户在失败列表中查看原因，补充规则后仅重试这 5 条，无需重做整批。

---

## 9. 功能优先级

### P0 — 必须有（MVP 核心）

| # | 功能 |
|---|------|
| 1 | 文件上传与批量导入 |
| 2 | 来源类型识别/选择 |
| 3 | 多来源解析器框架（插件化） |
| 4 | 统一交易模型 |
| 5 | 本地 SQLite 持久化 |
| 6 | 基础去重（严格去重） |
| 7 | 链路合并（转账闭环） |
| 8 | 基础规则映射（分类/账户） |
| 9 | 导入预览与确认 |
| 10 | API / 文件两种导入方式 |
| 11 | 导入日志与失败重试 |

### P1 — 应该有

| # | 功能 |
|---|------|
| 1 | 模糊去重（多因子评分） |
| 2 | 规则模板库 |
| 3 | 商户别名归一化 |
| 4 | 用户可配置时间窗与去重阈值 |
| 5 | 导入批次管理 |
| 6 | 手动合并/手动拆分疑似交易链路 |
| 7 | 标签映射 |

### P2 — 可以有

| # | 功能 |
|---|------|
| 1 | 自动来源识别增强（智能推断文件类型） |
| 2 | 可视化规则调试 |
| 3 | 简易统计报表（导入概览、分类占比） |
| 4 | 多账本导入支持 |
| 5 | 对账可视化（展示未匹配的"孤儿"转账记录） |
| 6 | 加密货币多币种与法币折算 |

---

## 10. 产品信息架构

### 10.1 一级模块

```
ProjectMoneyX
├── 导入中心        # 文件上传、批次管理
├── 数据清洗        # 解析结果、标准化预览
├── 去重处理        # 重复记录、链路合并、人工确认
├── 规则管理        # 分类/账户/标签/对手方规则配置
├── 导入任务        # 导入执行、结果查看、失败重试
├── 数据审计        # 全链路追溯、操作日志
└── 系统设置        # Firefly III 连接配置、时间窗参数等
```

### 10.2 关键页面

| 页面 | 说明 |
|------|------|
| 文件上传页 | 拖拽/选择文件，选择或自动识别来源类型 |
| 导入批次详情页 | 展示批次内所有记录和处理状态 |
| 清洗结果预览页 | 展示标准化后的交易列表，支持逐条查看映射详情 |
| 重复记录处理页 | 展示疑似重复/链路合并记录，支持人工确认或拒绝 |
| 规则配置页 | 可视化配置分类、账户、标签映射规则 |
| 导入结果页 | 展示导入成功/失败统计，失败可重试 |
| 审计追溯页 | 查看任一交易的完整处理链路 |

---

## 11. 关键交互原则

1. **先预览，后导入**：任何清洗结果必须允许用户确认后再执行导入
2. **规则可解释**：每条交易应展示命中的具体规则和分类依据
3. **重复可回溯**：被判定重复/合并的记录必须可查看判定依据与原始数据
4. **失败可重试**：导入失败不应要求整批重做，支持单条/选择性重试
5. **操作可逆**：合并、分类等操作均可撤销回滚

---

## 12. 非功能需求

### 12.1 安全与隐私

- **本地优先原则**：鉴于财务数据的极度敏感性，完全采用本地化部署（Docker / 本地命令行 / 本地 Web UI）
- SQLite 数据库仅存在于本地，敏感账单数据默认不上传云端
- API Token 加密存储
- 操作日志不泄露敏感字段

### 12.2 性能

- 单次导入 1 万条记录应可完成解析与清洗
- 去重计算应在合理时间内完成（建议 30 秒内完成主流程）

### 12.3 可维护性

- **插件化架构**：解析器(Parser)设计为独立模块，银行/平台格式变更时只需更新对应 Parser，无需重构主程序
- **规则引擎可扩展**：支持新增规则类型和匹配条件
- **去重策略可配置**：时间窗、金额容差、置信度阈值均可配置

### 12.4 可追溯性

- 任一导入结果必须可追溯至原始文件与原始记录
- 任一规则命中必须可解释
- 任一合并操作必须记录判定依据

---

## 13. 版本规划

### V1.0（MVP）

- 支付宝 / 微信 / 2 家银行账单支持
- 文件导入、解析、标准化
- SQLite 持久化
- 基础去重（严格去重）
- 基础规则映射（分类/账户）
- Data Importer API 导入 + CSV 导出
- 导入预览与确认

### V1.5

- 美团 / 京东账单支持
- 链路合并增强（转账闭环 + 订单链路聚合）
- 模糊去重（多因子评分）
- 批次管理与失败重试
- 手动修正与确认流程
- 商户别名归一化

### V2.0

- 币安 / ByBit 交易所流水适配
- 高级规则系统（模板库 + 可视化调试）
- 对账可视化（孤儿记录展示 + 手动干预）
- 简易统计报表（导入概览、分类占比）
- 多账本 / 多环境支持
- 加密货币多币种管理（法币折算 / 多货币对接）

---

## 14. 风险与应对策略

| # | 风险 | 影响 | 应对策略 |
|---|------|------|----------|
| 1 | 不同平台账单格式频繁变化 | 解析器失效 | 采用插件化解析器 + 版本化适配，格式变更只需更新对应 Parser |
| 2 | 去重误判（误合并/漏合并） | 数据准确性受损 | 采用"严格+模糊"分层策略；低置信度记录进人工确认队列 |
| 3 | 交易所流水语义复杂 | 解析困难 | V1 仅支持资金流水和基础现货，衍生品/复杂划转后续扩展 |
| 4 | 过度依赖 Data Importer | 耦合风险 | 核心规则与标准化能力沉淀在本地，导入器仅作为输出目标之一 |
| 5 | 加密货币汇率波动 | 金额折算不稳定 | 支持保留原始币种，汇率折算为可选项，对接 Firefly III 多货币系统 |

---

## 15. 参考项目

| 项目 | 说明 |
|------|------|
| [double-entry-generator](https://github.com/deb-sig/double-entry-generator) | 复式记账生成工具，核心参考项目 |
| [Firefly III](https://github.com/firefly-iii/firefly-iii) | 目标对接的个人财务管理系统 |
| [Data Importer](https://github.com/firefly-iii/data-importer) | Firefly III 的数据导入器 |
| [Firefly III Docs](https://docs.firefly-iii.org/) | Firefly III 官方文档 |

---

## 16. 总结

ProjectMoneyX 不是一个"简单导入工具"，而是一个面向 Firefly III 的**本地账单数据治理中台**。

其核心价值可以浓缩为：

> 1. **汇聚多源账单** — 一站式接入支付平台、银行、生活服务、交易所
> 2. **统一交易语义** — 屏蔽平台差异，建立标准化交易模型
> 3. **智能去重合并** — 消除重复，还原真实交易链路与转账闭环
> 4. **本地规则沉淀** — 分类/账户/标签映射可长期积累、可解释、可迁移
> 5. **无缝对接导入** — 丝滑推送至 Firefly III / Data Importer

**核心产品决策：**

> - **规则映射以本地为主，Data Importer 为辅**
> - **去重策略从"时间窗+金额"升级为多因子判定**
> - **SQLite 不仅是缓存，更是清洗结果与审计链路的核心数据底座**
> - **插件化架构确保可持续维护**