离线优先钱包

解决方案概述

传统的钱包和银行应用程序通常依赖稳定的互联网连接。当用户身处交通系统、偏远地区或移动网络不稳定的场所时，可能无法查看余额、查看交易记录、管理联系人、转账，以及在最需要时访问钱包。

用户需要一个在短暂断开连接时仍然可用的钱包。用户应该能够访问权限其钱包并完成财务任务，而不会因临时网络中断而受阻。当连接恢复时，钱包应同步用户的帐户。

该解决方案旨在解决网络连接受限时无法访问钱包核心功能的问题。即使用户处于离线状态，也可以访问钱包数据，并继续执行查看交易、管理联系人和转账等核心操作，而无需立即获得网络响应。此外，该解决方案还包含 AI 助手，可帮助用户在线或离线访问钱包信息并准备支付操作。网络连接恢复后，该解决方案会将最新更改同步到后端。其核心价值在于保持服务连续性：即使暂时发生网络中断，用户仍可以管理资金并获得帮助。

MongoDB 为这种方法提供灵活的数据基础。它在统一的数据层中对钱包信息进行建模，包括余额、交易、联系人、支付请求和待处理操作。统一的数据层有助于应用程序在断开连接期间维护所需的钱包状态，并在用户重新连接后协调更新。同一数据基础还可为 AI 助手提供相关的钱包上下文，帮助其在联网和离线状态下支持这些操作。

图 1。解决方案的高级架构

参考架构

该解决方案使用边缘设备和MongoDB Atlas作为核心组件，并将其与外部 PSP 集成。每个组件在整体架构中都有明确定义的角色。边缘设备支持离线优先交互， MongoDB Atlas提供集中式持久性和AI可访问的数据服务，PSP 处理受监管的支付操作。

图 2。参考架构概述

在边缘，移动应用程序将数据存储在本地 ObjectBox数据库中，并运行 Ollama 进行设备端推断。 Voyage AI模型与它并行运行，在设备上嵌入ACID 事务注释，以便语义召回在没有网络的情况下也能正常运行。 ObjectBox Sync Server 镜像MongoDB Atlas 模式，因此应用程序在线和离线读取和写入相同的逻辑结构。

MongoDB Atlas保存可操作的钱包数据：事务、联系人、请求、通知和聊天。以下Atlas功能基于这些数据：

• MongoDB Atlas Vector Search：使用 Voyage AI嵌入按含义检索ACID 事务单据。

• MongoDB Atlas中的混合搜索：在单个 $rankFusion管道中将向量结果与词法搜索查询融合。这种安排会为确切的商户名称和模糊描述返回正确的ACID 事务。

• Atlas Triggers ：对 集合上的每次插入和更新做出反应，并更新或更新或插入（upsert）由transactions PSP 传输引用作为键控的持久性历史记录。

• MongoDB MCP Server：公开读取工具，让AI助手直接查询MongoDB Atlas 。

外部 PSP 仍然是支付执行和身份的记录系统。它授权和结算传输，而应用仅存储支持用户体验所需的引用和应用程序数据。

这种职责分离结合了本地响应能力、基于云的智能和安全支付执行。

架构处理流程

这些进程演示了子系统如何交互以提供架构弹性和智能协助。离线支付流程可确保关键的财务操作在失去连接时持续进行，从而保持钱包的可靠性。聊天机器人辅助的流程利用本地智能来简化交互，证明对话界面可以在不持续依赖云的情况下保持响应。这些进程共同在任何网络环境中提供一致的用户体验。

线下支付流程

此流程通过将用户交互与实时网络可用性解耦来确保财务可靠性。通过在本地对事务进行排队，即使在受限的环境中，系统也能保持无缝支付体验，仅在连接恢复时与中央平台同步。

图 3。离线支付顺序

当设备失去连接时，应用会继续运行。离线支付流程中：

1. 用户发起付款。

2. 应用程序会根据 ObjectBox 中存储的上次同步余额来验证该金额。

3. ACID 事务在本地排队，状态为 local_pending。

4. 当连接恢复时，应用程序会检测重新连接并检索所有待处理的事务。

5. 每笔待处理事务都会提交给 PSP 进行结算。

6. 结算后，应用程序存储 PSP 参考并将ACID 事务标记为已结算。

7. ObjectBox Sync Server 将更新的ACID 事务状态传播到MongoDB Atlas。

这种模式在连接丢失期间保持应用程序的连续性，同时确保仅通过外部 PSP 进行支付结算。

聊天机器人辅助的支付流程

这种对话流使用基于边缘的本地AI来提供智能帮助，而不依赖于持续的云连接。它在本地处理用户意图，从而支持付款起草和联系解析，然后在系统重新连接时安全地执行已确认的交易。

图 5。聊天机器人辅助的付款顺序

该解决方案在 LangGraph代理上构建AI助手。聊天机器人的工作流程如下：

1. 用户向 20Luis 发送晚餐请求，例如发送 。

2. 代理会解析预期的联系：

   • 在线时，它会通过MongoDB MCP Server 查询MongoDB Atlas 。

   • 离线时，它会直接从 ObjectBox 解析联系。

3. 代理起草付款并向用户出示确认卡。

4. 在用户明确确认ACID 事务之前，资金不会移动。

5. 确认后，执行以下操作：

   • 在在线模式下，应用程序会将传输提交给 PSP，并将富集记录写入 MongoDB Atlas。

   • 在离线模式下，应用程序会在本地对ACID 事务进行排队以供日后重放。

6. 付款发送或排队后，用户会收到通知。

这种交互模型将自然语言启动支付与显式用户批准相结合，同时保留核心架构定义的相同在线和离线执行边界。

数据模型方法

该解决方案使用镜像文档模型。这种设计模式在MongoDB Atlas和设备上的 ObjectBox存储中维护相同的钱包实体和文档结构。该模型支持基于 BIAN 兼容的外部 PSP 构建的离线钱包。

PSP 仍然是支付执行和身份的记录系统，而应用程序存储引用和应用程序级别的丰富以支持用户体验。这种丰富功能包括注释、语义嵌入和同步或生命周期状态。在MongoDB Atlas和 ObjectBox 中使用相同的逻辑模式，使应用程序在线和离线时都能一致工作。

以下集合展示了该解决方案如何对其应用程序数据进行建模以支持离线支付体验。

除 walletTransactionsHistory 之外的每个集合都镜像 ObjectBox数据库。 MongoDB Atlas保存历史数据，并为混合搜索所需的向量和文本索引提供支持。

下面是存储在 walletTransactions集合中的钱包ACID 事务的文档模型。它表示通过外部 PSP 发送或接收的单笔付款。该文档捕获追踪传输所需的操作数据以及支持搜索、离线重放和AI助手所需的丰富数据（嵌入、同步状态）。

{
   "_id": {
      "$oid": "unique_id"
   },
   "leafyPayTransferReference": "string",
   "ownerPartyRef": "string",
   "counterpartyArrangementReference": "string",
   "amount": "number",
   "currency": "string",
   "note": "string",
   "noteEmbedding": [
      "number",
      "..."
   ],
   "direction": "sent | received",
   "leafyPayStatus": "pending | settled | failed | exception",
   "localSyncStatus": "local_pending | synced",
   "createdAt": {
      "$date": "ISODate"
   },
   "settledAt": {
      "$date": "ISODate"
   }
}

该模型统一了操作上下文和丰富功能，简化了跨云和设备环境的部署。该应用程序呈现待处理的活动，重放离线写入，并支持使用单次读取进行AI辅助ACID 事务检索。您可以执行这些操作，因为同步状态 (localSyncStatus)、结算状态 (leafyPayStatus) 和语义搜索向量 (noteEmbedding) 位于同一文档中。

敏感的财务执行仍保留在 PSP 中，而MongoDB Atlas和 ObjectBox 仅存储响应、搜索和用户体验所需的钱包应用程序数据。在生产系统中，您可以通过更严格的验证、访问权限控制和Atlas 审核跟踪来扩展这些集合。

构建解决方案

分两个阶段部署解决方案，以便在本地运行。首先，启动 PSP，由其处理 SSO、同意和付款执行。然后启动 Leafy Wallet，它会运行应用程序用户界面、后端服务、ObjectBox、Ollama、Voyage AI和同步组件。

对于本地部署，请并排克隆两个存储库：

• Leafy 钱包

• 支付平台

按照 GitHub 本地部署 中的说明进行操作

git clone https://github.com/mongodb-industry-solutions/leafy-wallet.git
git clone https://github.com/mongodb-industry-solutions/sec-fsi-pci-dss.git

#frontend
CLIENT_ID=<id>
CLIENT_SECRET=<secret>
PSP_BASE_URL=http://host.docker.internal:8081
PSP_FRONTEND_URL=http://localhost:8083
APP_BASE_URL=http://localhost:8080
REDIRECT_URI=http://localhost:8080/api/auth/callback
LOOKUP_DIGEST_KEY=<key>
#backend
MONGODB_URI="<your-atlas-connection-string>"
DATABASE_NAME="<db-name>"
APP_NAME=leafy-wallet-backend
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
LOOKUP_DIGEST_KEY="<key>"

cd sec-fsi-pci-dss
npm run setup:db
npm run setup:seed
npm run dev

cd leafy-wallet/backend
uv run python scripts/create_vector_index.py
cd ..
docker compose up -d --build

关键要点

• 连接中断时保持钱包功能可用：将网络访问权限视为增强功能而不是要求。 MongoDB Atlas支持的本地存储在短暂断开连接期间保持余额、事务、联系人、请求和聊天流可用，然后在设备再次在线后进行协调。

• 在MongoDB Atlas中保存应用程序程序上下文，将结算留给 PSP： Atlas存储塑造用户体验的别名、备注、同步状态和嵌入，而支付提供商保留身份、授权和结算的记录系统。这种分割保持了体验层的灵活性，而无需将受监管的执行拉入其中。

• 在设备和云端读取和写入相同的逻辑数据模型：将 MongoDB Atlas 集合结构映射到嵌入式存储中，并在后台同步更改。两端使用相同的架构，无需离线功能通常所需的转换层，因此应用程序代码无需根据网络连接状态进行分支处理。

• 在文档模型中将操作上下文和数据丰富结合在一起：将传输详细信息、注释、同步状态和嵌入存储在同一文档中，以简化读取、支持原子更新并简化数据处理，从而实现AI辅助体验。

• 将本地响应能力与云智能相结合： MongoDB Atlas Vector Search、 MongoDB MCP 服务器和设备端存储可让助手处理自然语言ACID 事务发现和付款起草。无论设备是否在线，用户都会获得相同的行为。

作者

• Felipe Trejos, MongoDB

• Miguel Aréjula Aísa, MongoDB

了解详情

• 智能体式 AI 驱动的支付编排

• 借助 MongoDB 和 BIAN 实现核心银行业务现代化

• 支付现代化解决方案加速器