From f755f76ed12872282a91ec3349980fb960347a09 Mon Sep 17 00:00:00 2001
From: Rekey <rekey@Mac-mini.internal>
Date: Mon, 15 Jun 2026 23:25:06 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20pair.ts=20=E5=87=BD?=
 =?UTF-8?q?=E6=95=B0=20JSDoc=20=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 data/service/pair.ts | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/data/service/pair.ts b/data/service/pair.ts
index 9287e22..d02fed0 100644
--- a/data/service/pair.ts
+++ b/data/service/pair.ts
@@ -3,11 +3,23 @@ import { TradingPair } from "../db/entities/trading-pair.entity";
 
 const repo = AppDataSource.getRepository(TradingPair);
 
+/**
+ * 获取所有交易对列表。
+ *
+ * 从 trading_pairs 表中查询全部记录，返回完整交易对信息，
+ * 常用于行情拉取时遍历所有币种、或管理界面展示。
+ */
 export async function getAllPairs() {
     const pairs = await repo.find({});
     return pairs;
 }
 
+/**
+ * 获取指定交易对的历史 K 线最后补全时间。
+ *
+ * @param symbol - 交易对名称（如 "BTCUSDT"）
+ * @returns 最后补全时间（UTC），若交易对不存在返回 undefined
+ */
 export async function getPairLastBackfillTime(symbol: string) {
     const pair = await repo.findOneBy({
         symbol
@@ -15,6 +27,16 @@ export async function getPairLastBackfillTime(symbol: string) {
     return pair?.last_backfill_time;
 }
 
+/**
+ * 更新指定交易对的历史 K 线最后补全时间。
+ *
+ * 在批量回补 K 线数据后调用，记录已补全的时间断点，
+ * 下次回补时从该时间点之后开始拉取，避免重复。
+ *
+ * @param symbol - 交易对名称（如 "BTCUSDT"）
+ * @param time   - 新的最后补全时间（UTC）
+ * @returns 保存后的交易对实体，若交易对不存在返回 undefined
+ */
 export async function updatePairLastBackfillTime(symbol: string, time: Date) {
     const pair = await repo.findOneBy({
         symbol