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

14 KiB
Raw Blame History

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