> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tickflow.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 使用 TickFlow 过程中的常见问题和解决方法

## K 线数据

<AccordionGroup>
  <Accordion title="为什么只获取到 100 根 K 线？">
    `klines.get()` 默认返回最近 **100** 根 K 线。如需更多数据，请显式设置 `count` 参数：

    ```python theme={null}
    # 默认只返回 100 根
    df = tf.klines.get("600000.SH", period="1d", as_dataframe=True)
    print(len(df))  # 100

    # 设置 count 获取更多
    df = tf.klines.get("600000.SH", period="1d", count=10000, as_dataframe=True)
    print(len(df))  # 取决于该标的可用数据量
    ```

    也可以通过 `start_time` 和 `end_time` 指定时间范围来获取数据。
  </Accordion>

  <Accordion title="怎么获取前复权/后复权 K 线？和东方财富/同花顺一致的复权怎么取？">
    TickFlow 支持 **5 种**复权方式，通过 `adjust` 参数指定：

    | `adjust` 值            | 说明             | 算法              |
    | --------------------- | -------------- | --------------- |
    | `"none"`              | 不复权            | 原始价格            |
    | `"forward"`           | 前复权-比例（**默认**） | 乘除法，价格 × 累计复权因子 |
    | `"backward"`          | 后复权-比例         | 乘除法，价格 × 累计复权因子 |
    | `"forward_additive"`  | 前复权-差值         | 加减法，价格 ± 累计差值   |
    | `"backward_additive"` | 后复权-差值         | 加减法，价格 ± 累计差值   |

    <Warning>
      **东方财富、同花顺等软件默认使用的是差值前复权**（加减法），对应 `adjust="forward_additive"`。

      TickFlow 的默认值 `"forward"` 是比例前复权（乘除法），两者结果不同。如需与这些软件的价格对齐，请使用 `"forward_additive"`。
    </Warning>

    ```python theme={null}
    # 比例前复权（TickFlow 默认）
    df_ratio = tf.klines.get("600000.SH", period="1d", count=1000, adjust="forward", as_dataframe=True)

    # 差值前复权（东方财富/同花顺默认，价格与这些软件一致）
    df_additive = tf.klines.get("600000.SH", period="1d", count=1000, adjust="forward_additive", as_dataframe=True)

    # 不复权
    df_raw = tf.klines.get("600000.SH", period="1d", count=1000, adjust="none", as_dataframe=True)

    # 比例后复权
    df_back = tf.klines.get("600000.SH", period="1d", count=1000, adjust="backward", as_dataframe=True)

    # 差值后复权
    df_back_add = tf.klines.get("600000.SH", period="1d", count=1000, adjust="backward_additive", as_dataframe=True)
    ```

    **比例 vs 差值的区别**：比例复权保持涨跌幅不变（适合收益率计算），差值复权保持价差不变（适合与行情软件对比价格）。

    如需查看除权因子：

    ```python theme={null}
    factors = tf.klines.ex_factors(["600000.SH"], as_dataframe=True)
    print(factors)
    ```
  </Accordion>

  <Accordion title="K 线接口遇到频率限制怎么办？">
    付费订阅一般不会触发频率限制。如果遇到，大概率是**用法问题**——逐只标的循环调用单只接口会产生大量请求。

    **推荐使用批量接口**，一次请求获取多只标的的数据：

    ```python theme={null}
    # ❌ 不推荐：逐只调用，100 只标的 = 100 次请求
    for symbol in symbols:
        df = tf.klines.get(symbol, period="1d", count=1000, as_dataframe=True)

    # ✅ 推荐：批量接口，100 只标的 = 1 次请求
    dfs = tf.klines.batch(
        symbols,
        period="1d",
        count=1000,
        as_dataframe=True,
        show_progress=True,
    )
    # dfs 是 dict[str, DataFrame]
    print(dfs["600000.SH"].tail())
    ```

    日内分钟线同理：

    ```python theme={null}
    # ✅ 批量获取日内分钟 K 线
    dfs = tf.klines.intraday_batch(symbols, as_dataframe=True, show_progress=True)
    ```
  </Accordion>

  <Accordion title="支持哪些 K 线周期？">
    | 周期    | 参数值   | 说明      |
    | ----- | ----- | ------- |
    | 1 分钟  | `1m`  | 需付费订阅   |
    | 5 分钟  | `5m`  | 从 1m 聚合 |
    | 15 分钟 | `15m` | 从 1m 聚合 |
    | 30 分钟 | `30m` | 从 1m 聚合 |
    | 60 分钟 | `60m` | 从 1m 聚合 |
    | 日线    | `1d`  | 免费服务可用  |
    | 周线    | `1w`  | 从日线聚合   |
    | 月线    | `1M`  | 从日线聚合   |
    | 季线    | `1Q`  | 从日线聚合   |
    | 年线    | `1Y`  | 从日线聚合   |

    免费服务仅支持日线及以上周期，分钟级 K 线需付费订阅。
  </Accordion>
</AccordionGroup>

## 行情数据

<AccordionGroup>
  <Accordion title="为什么获取不到某只标的的行情或 K 线？">
    请依次检查：

    **1. 确认标的代码格式正确**

    标的代码格式为 `代码.市场后缀`，例如 `600000.SH`、`AAPL.US`、`00700.HK`。

    常见错误：

    * `600000` — 缺少市场后缀
    * `SH600000` — 后缀位置错误
    * `600000.sh` — 后缀必须大写

    **2. 确认系统中存在该标的**

    使用标的信息查询接口确认：

    ```python theme={null}
    inst = tf.instruments.get("600000.SH")
    if inst:
        print(f"找到标的: {inst['symbol']} - {inst['name']}")
    else:
        print("标的不存在，请检查代码是否正确")
    ```

    **3. 确认标的属于已支持的市场**

    目前支持的市场后缀：`SH`、`SZ`、`BJ`（A 股）、`US`（美股）、`HK`（港股）。

    **4. 确认数据时段**

    * 实时行情仅在交易时段有更新
    * 免费服务的日 K 数据为盘后更新，盘中不会实时变动
  </Accordion>

  <Accordion title="实时行情和免费服务有什么区别？">
    |              | 免费服务   | 付费服务                   |
    | ------------ | ------ | ---------------------- |
    | 实时行情         | ❌      | ✅ 盘中实时更新               |
    | 分钟 K 线       | ❌      | ✅                      |
    | 日 K 线        | ✅ 盘后更新 | ✅ 盘中实时更新               |
    | WebSocket 推送 | ❌      | ✅ 需开启 WebSocket 实时行情功能 |
    | 频率限制         | 较严格    | 宽松                     |

    免费服务地址：`https://free-api.tickflow.org`

    ```python theme={null}
    tf = TickFlow.free()  # 使用免费服务
    ```
  </Accordion>
</AccordionGroup>

## 标的代码

<AccordionGroup>
  <Accordion title="怎么查看系统支持的全部标的？">
    使用标的池接口查看：

    ```python theme={null}
    # 列出所有标的池
    universes = tf.universes.list()
    for u in universes:
        print(f"{u['id']}: {u['name']} ({u['symbol_count']} 只)")

    # 获取某个标的池的全部标的
    a_shares = tf.universes.get("CN_Equity_A")
    print(f"A 股共 {len(a_shares['symbols'])} 只")
    ```
  </Accordion>

  <Accordion title="标的代码格式是什么？">
    格式为 **`代码.市场后缀`**（英文点号分隔），后缀必须大写。

    | 后缀   | 市场      | 示例          |
    | ---- | ------- | ----------- |
    | `SH` | 上海证券交易所 | `600000.SH` |
    | `SZ` | 深圳证券交易所 | `000001.SZ` |
    | `BJ` | 北京证券交易所 | `920662.BJ` |
    | `US` | 美股      | `AAPL.US`   |
    | `HK` | 港股      | `00700.HK`  |
  </Accordion>
</AccordionGroup>

## 连接问题

<AccordionGroup>
  <Accordion title="连接超时或连接被拒绝怎么排查？">
    如果在使用 TickFlow API 时遇到连接超时（timeout）、连接被拒绝（connection refused）等问题：

    推荐使用 [端点延迟测试工具](https://tickflow.org/dashboard/latency/) 快速测试各端点延迟，选择最优端点。
  </Accordion>

  <Accordion title="如何选择最优端点并切换？">
    **如何选择最优端点？**

    前往 [端点延迟测试](https://tickflow.org/dashboard/latency/) 页面，一键测试你的网络到各个端点的实时延迟，选择延迟最低的端点。

    **确定端点后如何切换？**

    <Tabs>
      <Tab title="Python SDK (base_url 参数)">
        ```python theme={null}
        from tickflow import TickFlow

        # 使用延迟最低的端点，例如香港端点
        tf = TickFlow(api_key="your-api-key", base_url="https://hk-api.tickflow.org")
        ```
      </Tab>

      <Tab title="环境变量">
        ```bash theme={null}
        # Linux / macOS
        export TICKFLOW_BASE_URL="https://api.tickflow.org"

        # Windows PowerShell
        $env:TICKFLOW_BASE_URL="https://api.tickflow.org"
        ```

        设置后 SDK 会自动使用该端点，无需修改代码：

        ```python theme={null}
        from tickflow import TickFlow
        tf = TickFlow(api_key="your-api-key")  # 自动读取 TICKFLOW_BASE_URL
        ```
      </Tab>

      <Tab title="HTTP 直接调用">
        ```bash theme={null}
        # 将请求地址替换为目标端点即可
        curl https://api.tickflow.org/v1/klines?symbol=600000.SH&period=1d \
          -H "Authorization: Bearer your-api-key"
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## WebSocket 实时行情

<AccordionGroup>
  <Accordion title="WebSocket 实时行情需要什么套餐？">
    WebSocket 实时行情是独立的付费功能，需要：

    * 订阅 **Expert** 套餐（已包含 WebSocket 实时行情），或
    * 在**自定义**套餐中单独开启「WebSocket 实时行情」功能

    每个连接的最大订阅标的数由套餐决定（Expert 默认 100 个标的）。
  </Accordion>

  <Accordion title="WebSocket 连接被拒绝（401/403）怎么办？">
    * **401**：API Key 无效或过期，请检查 Key 是否正确
    * **403**：当前套餐不包含 WebSocket 实时行情功能，需升级套餐

    遇到 401/403 时**不应自动重连**，请先检查 API Key 和套餐权限。
  </Accordion>

  <Accordion title="断线后订阅会保留吗？">
    不会。连接断开后服务端自动清除该连接的所有订阅。重连后需要重新发送 `subscribe` 恢复订阅。

    使用 Python SDK 时，SDK 会自动处理断线重连和订阅恢复。
  </Accordion>
</AccordionGroup>