zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ed945abdf124967662f416396e4bc90e515af83c
ProjectAGiPrompt/17-ProjectMoneyX/2-概要详细设计/prd-claude.md
zeaslity ed945abdf1 大量更新
2026-03-18 16:16:47 +08:00

23 KiB
Raw Blame History

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 复式记账生成工具，核心参考项目
Firefly III 目标对接的个人财务管理系统
Data Importer Firefly III 的数据导入器
Firefly III Docs Firefly III 官方文档

16. 总结

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

其核心价值可以浓缩为：

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

核心产品决策：

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