> For the complete documentation index, see [llms.txt](https://docs.bsc.lista.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bsc.lista.org/zh-cn/kai-fa-zhe/services/position-data-maintenance.md).

# 位置数据维护

本文档描述 **MoolahUserPosition** 实体，以及为 Lista Lending 维护和消费该实体的**各项服务**。它是风险监控、清算预警、排放（奖励）与借款历史的数据基础。

***

## 1. 概述

**MoolahUserPosition** 是 Moolah 借贷协议中**用户仓位**的核心实体。它按「每个用户、每个市场」存储：

* 抵押品与借款数量
* 清算价格（或清算价格比）
* 相关标识符（链、市场、用户地址）

该实体支撑：

* **风险监控** — 追踪接近清算的仓位。
* **清算预警** — 识别达到或超过清算阈值的仓位并推送预警。
* **排放（奖励）** — 按市场汇总抵押品，作为奖励分配的权重。
* **借款 / 利率统计** — 每日与每小时的借款与利率报表。

***

## 2. 实体定义

**每个（用户地址，市场）组合有且仅有一条仓位记录**。

典型字段（实际实现中的命名可能不同）：

| 字段                      | 说明                      |
| ----------------------- | ----------------------- |
| `userAddress`           | 钱包地址                    |
| `marketId`              | 市场标识符（或等效字段）            |
| `chainId`               | 链（例如 BSC、Ethereum）      |
| `collateralAmount`      | 已提供的抵押品（可读格式，例如 18 位小数） |
| `borrowShares`          | 链上的借款份额（原始 Wei）         |
| `borrowedAmount`        | 实际借款金额（由份额与市场状态推导）      |
| `liquidationPriceRatio` | 使该仓位变为可清算的抵押品/借款资产价格比   |
| `updatedAt`             | 最后更新时间                  |

***

## 3. 数据流

```
                    ┌───────────────┐
                    │ On-chain      │
                    │ contract      │
                    │ events        │
                    └──────┬────────┘
                           │
               ┌───────────▼───────────┐
               │ Event-driven write    │
               │ (incremental consume) │
               └───────────┬───────────┘
                           │ UPSERT
                           ▼
               ┌───────────────────────┐     ┌───────────────────┐
               │ moolah_user_position  │◄────│ Scheduled refresh  │
               │ (user position table) │UPDATE│ (debt + liq. rate) │
               └──────────┬────────────┘     └───────────────────┘
                          │ READ
          ┌───────────────┼────────────────────┐
          ▼               ▼                    ▼
  ┌───────────────┐ ┌──────────────┐  ┌─────────────────┐
  │ Borrow history│ │ Liquidation  │  │ Emission        │
  │ (daily/hourly)│ │ risk monitor │  │ reward calc     │
  └───────────────┘ └──────────────┘  └─────────────────┘
```

***

## 4. 数据写入

### 4.1 事件驱动写入

仓位数据通过**消费 Moolah 的链上事件**（supply、withdraw、borrow、repay、liquidate 等）进行更新。对每个相关事件：

1. **获取事件** — 使用游标（`lastId`）从事件存储中按序读取尚未处理的 Moolah 事件。
2. **读取链上状态** — 通过 multicall 查询当前市场状态、用户仓位与预言机价格。
3. **计算派生字段** — 根据市场的利率类型，计算实际借款金额与清算价格比。
4. **写入数据库** — 按 `(userAddress, marketId)`（如适用还包括 `chainId`）执行 UPSERT。
5. **写入操作日志** — 可选地写入用户操作日志表。
6. **触发预警** — 若该事件为清算事件，则触发 Telegram（或其他渠道）预警。

**幂等性：** 每个事件都会被追踪（例如使用 TTL 为 1500 秒的 Redis key），确保同一事件不会被重复应用。失败的事件会重试；达到最大重试次数后跳过并继续处理。

### 4.2 定时刷新

由于链上**利息持续累积**，即使没有新事件，借款金额与清算价格也会发生变化。**定时任务**会周期性刷新所有活跃仓位：

* **浮动利率市场** — 从链上读取当前利率，在本地计算已累积利息，再将份额换算为资产，得到当前借款金额与清算价格。
* **固定利率（Broker）市场** — 向 Broker 合约查询每个用户的总债务（`getBrokerTotalDebt(borrower, market)`），再计算清算价格。

***

## 5. 数据读取

### 5.1 借款历史

* **每日** — 基于仓位表（以及各类快照）计算每个用户的日均借款金额、抵押品与美元价值；写入每日借款历史表。
* **每小时** — 每小时将所有仓位快照写入小时级借款快照表。

### 5.2 清算风险监控

系统会周期性读取每个仓位的**清算价格比**，并与预言机提供的**当前市场价格比**做比较。当**清算触发价格 > 当前市场价格**（即仓位可被清算）时，生成风险摘要并发送预警（例如 Telegram）。

### 5.3 排放（奖励）

排放逻辑按市场汇总用户抵押品（取自仓位表），并以此作为奖励分配的权重。

***

## 6. 关联数据

* **市场配置** — 链、资产、预言机、LLTV、利率类型（浮动或固定）。
* **事件日志** — 用于重放与审计的原始合约事件。
* **用户操作日志** — 每个用户的操作历史（supply、borrow、repay 等）。

***

## 7. 关键概念

### 7.1 借款份额 vs 实际借款金额

* **借款份额**是链上的表示形式，仅在用户操作（借款、还款、清算）时发生变化。
* **实际借款金额**由份额与市场状态（总资产、总份额，固定利率场景下还可能包括 Broker 状态）推导得出，并随利息**随时间增长**。定时刷新任务负责保持该字段同步。

### 7.2 清算价格比

**清算价格比**是使该仓位变为可清算的抵押品/借款资产价格比。当预言机的当前价格比跌破该值时，该仓位即可被清算。它由抵押品、借款金额与该市场的 LLTV 推导得出。

### 7.3 多链

Moolah 运行在 **BSC 与 Ethereum** 上。仓位数据通常存储在单张表中并带有链标识符（例如 `chainId`），以便下游任务与 API 按链过滤。

***

## 8. 任务清单

| 任务        | 说明                      |
| --------- | ----------------------- |
| 事件消费者     | 消费 Moolah 事件并 UPSERT 仓位 |
| 定时刷新      | 刷新所有活跃仓位的借款金额与清算价格      |
| 借款历史（每日）  | 计算并存储每日借款/抵押品统计         |
| 借款快照（每小时） | 为小时级统计对仓位做快照            |
| 清算监控      | 将清算价格与预言机价格比较并发送预警      |
| 排放汇总      | 按市场汇总抵押品作为奖励权重          |

***

## 9. 注意事项

* **精度：** 抵押品与借款金额通常以可读形式存储（例如 18 位小数）；借款份额通常以原始 Wei 存储。
* **读写分离：** 写入走主库；读取可走只读副本。为保证一致性需考虑复制延迟。
* **幂等性：** 事件处理结合 Redis（或类似组件）与 UPSERT，确保同一事件不会被重复应用。
* **利率类型：** 浮动利率与固定利率市场在借款金额与清算价格上使用不同公式；具体走哪条路径由市场配置决定。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bsc.lista.org/zh-cn/kai-fa-zhe/services/position-data-maintenance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.