对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

离线优先钱包

了解 MongoDB Atlas 和 ObjectBox 如何让个人钱包及其 AI 助手在零连接的情况下保持工作。

使用案例: 边缘和移动, 智能搜索, 支付

行业: 金融服务

产品和工具: MongoDB Atlas 数据库、MongoDB Atlas Vector Search、MongoDB MCP 服务器、MongoDB Search、MongoDB 触发、Voyage AI

合作伙伴: ObjectBox, LangChain

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

用户需要一个在短暂断开连接期间仍然有用的钱包。用户应该能够访问其钱包并完成财务任务,而不会因临时的服务中断而受阻。当连接恢复时,钱包应同步用户的账户。

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

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

Leafy Wallet 概览图

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

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

参考架构概述

图 2。参考架构概述

在边缘,移动应用程序在本地 ObjectBox 数据库中存储数据,并运行 Ollama 进行设备端推理。Voyage AI 模型与之并行运行,在设备上嵌入事务备注,以便在无网络状态下也可以持续进行语义回忆。ObjectBox Sync 服务器镜像 MongoDB Atlas 模式,因此应用程序可以在线和离线读取和写入相同的逻辑结构。

MongoDB Atlas 保存运营钱包数据:事务、联系、请求、通知和聊天。以下 Atlas 功能在该数据之上构建:

  • MongoDB Atlas Vector Search:根据含义检索事务备注,使用 Voyage AI 嵌入。

  • MongoDB Atlas 中的混合搜索:在单个 $rankFusion 管道中,将向量结果与词汇搜索查询融合。这种安排将根据准确的商家名称和模糊的说明返回对应的事务。

  • Atlas Triggers:对 transactions 集合中的每次插入和更新做出反应,并更新或插入(upsert)一条持久性历史记录,该记录以 PSP 转账参考为键。

  • MongoDB MCP 服务器: 公开读取工具,使 AI 助手能够直接查询 MongoDB Atlas。

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

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

这些流程演示了子系统如何交互以提供架构弹性和智能协助。离线支付流程可确保在网络连接中断时,关键的财务操作仍能持续进行,从而维护钱包的可靠性。聊天机器人辅助流程借助本地智能简化交互,表明会话界面可以在无需持续依赖云的情况下保持响应迅速。这些过程合在一起,可以在任何网络环境中提供一致的用户体验。

此流程通过将用户交互与实时网络可用性解耦,确保了财务可靠性。通过在本地排队事务,系统即使在受限环境中也能保持跨实例和区域的横向扩展实现无缝的支付体验,仅在恢复连接时才与中央平台同步。

离线支付序列

图 3。 离线支付序列

当设备丢失连接时,应用会保持运行。在离线支付流程中:

  1. 用户发起付款。

  2. 应用程序会根据存储在 ObjectBox 中的最后同步余额来验证金额。

  3. 该事务在本地排队,状态为 local_pending。

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

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

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

  7. ObjectBox 同步服务器将更新后的事务状态传播到 MongoDB Atlas。

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

这种对话流程使用本地端侧 AI 提供智能协助,而不依赖持久的云连接。它在本地处理用户意图,从而实现付款草拟和联系解析,然后,当系统重新连接时,它会安全地执行已确认的事务。

聊天机器辅助支付序列

图 5。聊天机器辅助支付序列

该解决方案基于 LangGraph 代理构建 AI 助手。聊天机器人的工作流运行方式如下:

  1. 用户发送请求,例如 发送 20 给 Luis 吃晚饭。

  2. 代理确定预期的联系:

    • 在线时,它通过 MongoDB MCP 服务器查询 MongoDB Atlas。

    • 当处于离线状态时,它会直接从 ObjectBox 解析联系。

  3. 代理处理付款,并向用户出示一张确认卡。

  4. 资金不会转移,直到用户明确确认该事务。

  5. 确认后,它将执行以下操作:

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

    • 在离线模式下,应用程序将事务在本地排队,以便以后重播。

  6. 一旦付款已发送或已排队,用户就会收到通知。

这种交互模型结合了自然语言支付发起和明确的用户批准,同时保留了由核心架构定义的相同在线和离线执行边界。

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

PSP 依然是支付执行和身份的记录系统,同时,应用程序存储引用和应用程序层面的增强,以支持用户体验。这种增强包括注释、语义嵌入、和同步或生命周期省/市/自治区。在 MongoDB Atlas 和 ObjectBox 中使用相同的逻辑模式,可以使应用程序在线和离线状态下都能一致地工作。

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

Collection
说明

walletTransactions

存储已完成和待处理的资金流动,通过引用将其关联到 PSP,而不是直接存储余额或凭证。

walletTransactionsHistory

维护仅在 Atlas 中可搜索的历史记录。Atlas trigger 在此以 PSP reference 为键更新或插入每个已结算的转账,以便 hybrid search 可以在不会被 device 同步分裂的稳定语料库上运行。

walletContacts

代表用户可以向其付款或向其请求付款的人员,从 PSP 安排参考解析为钱包友好的联系记录。

walletRequests

追踪支付请求在整个生命周期内的情况,从创建到结算或争议处理。

notification

提供面向用户的支付和钱包事件,包括针对已入队和已完成的操作的状态更新。

chats, chatsMessages

存储 AI 助手的对话历史,仅限于所属用户,并链接到钱包体验。

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

下面是钱包事务的 document model,存储在 walletTransactions 集合中。它代表通过外部 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 辅助的事务检索,仅需单次读取。您可以执行这些操作,因为同步状态 (localSyncStatus)、结算状态 (leafyPayStatus)和语义搜索向量 (noteEmbedding)存储在同一个文档中。

敏感的财务执行保留在 PSP 中,而 MongoDB Atlas 和 ObjectBox 仅存储钱包应用程序数据,以满足响应能力、搜索和用户体验的需求。在生产系统中,您可以扩展这些集合,并增加更严格的验证、访问控制和Atlas 审核追踪。

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

对于本地部署,克隆这两个存储库并排:

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

1

在开始之前,请确保您的环境包含:

  • Docker Desktop

  • Node.js

  • uv

  • 一个带有 PSP 数据库、MongoDB Queryable Encryption 加密库和 Leafy Wallet 数据库的 MongoDB Atlas 集群。

2

将解决方案部署为一组容器化服务,以支持具备弹性的离线优先体验。如图所示,前端、FastAPI 后端和 MongoDB Atlas 负责处理云连接路径,而 ObjectBox Sync Server 则将设备上的 ObjectBox 存储与 Atlas 连接起来。

这种设置允许钱包在本地存储数据,以便在断开连接时实现即时响应,并在恢复连接后自动将排队的事务刷新到云端。使用此容器化模型可在边缘设备和您的 Atlas 集群之间保持一致的逻辑数据结构。

3

克隆 PSP 和 Leafy Wallet 存储库,并将其并排放。

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

在启动之前,请为前端和后端配置单独的环境文件。这些文件管理必要的连接字符串、API 凭证和服务终结点,从而实现前端、后端和外部服务之间的安全通信。

#frontendCLIENT_ID=<id>CLIENT_SECRET=<secret>PSP_BASE_URL=http://host.docker.internal:8081PSP_FRONTEND_URL=http://localhost:8083APP_BASE_URL=http://localhost:8080REDIRECT_URI=http://localhost:8080/api/auth/callbackLOOKUP_DIGEST_KEY=<key> #backendMONGODB_URI="<your-atlas-connection-string>"DATABASE_NAME="<db-name>"APP_NAME=leafy-wallet-backendOLLAMA_BASE_URL=http://localhost:11434OLLAMA_EMBEDDING_MODEL=nomic-embed-textLOOKUP_DIGEST_KEY="<key>"

前端配置必须将 PSP_BASE_URL 指向 http://host.docker.internal:8081,以便容器化应用能够访问本地运行的 PSP。

4

在原生开发模式下运行 PSP:

cd sec-fsi-pci-dssnpm run setup:dbnpm run setup:seednpm run dev

此命令在端口 8081 上启动 PSP 后端,在端口 8082 上启动商户演示,并在端口 8083 上启动登录和同意前端。

5

PSP 运行后,创建 MongoDB 向量搜索 索引并使用 Docker Compose 启动 Leafy Wallet:

cd leafy-wallet/backenduv run python scripts/create_vector_index.pycd ..docker compose up -d --build

Leafy Wallet 在 http://localhost:8080 启动,后端、ObjectBox、Ollama 和同步服务在容器中运行。

一旦两个堆栈都运行,在浏览器中打开 Leafy Wallet 并继续使用 SSO。

  • 当连接断开时保持钱包功能可用:将网络访问视为一项增强功能,而非一项要求。由 MongoDB Atlas 支持的本地存储可以在短时间断开连接期间保留余额、事务、联系、请求和聊天流程,然后在设备再次在线后进行同步。

  • 在 MongoDB Atlas 中保留应用程序上下文,将结算交由 PSP 处理: Atlas 存储别名、备注、同步状态和嵌入,这些内容形成了用户体验,而支付提供商保留为身份、授权和结算的记录系统。这种分割使体验层保持灵活性,而不会将受监管的执行拉入其中。

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

  • 在 document model 中将运行上下文和富集存储在一起:在同一个文档中存储传输详情、备注、同步状态和嵌入,以简化读取、支持原子更新并使 AI 辅助体验更容易处理数据。

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

  • Felipe Trejos, MongoDB

  • Miguel Aréjula Aísa, MongoDB