# Debug Guide

???????????????????????????

---

## 1. ??????

???????????????????????????????

### 1.1 ????

```bash
python scripts/smoke_codes.py --exchange sz --limit 10
```

### 1.2 ? K ?

```bash
python scripts/smoke_kline.py --code sz000001 --period day --count 10
python scripts/smoke_kline.py --code sh000001 --period day --kind index --count 10
```

### 1.3 ??????

```bash
python scripts/smoke_minute.py --code sz000001 --date 2026-03-06
python scripts/smoke_trade.py --code sz000001 --date 2026-03-06 --count 50
```

### 1.4 ?????????

```bash
python scripts/smoke_call_auction.py --code sz000001
```

### 1.5 ????????

```bash
python scripts/export_live_validation.py
```

??????? `artifacts/live_validation_*` ???????????

---

## 2. `include_raw=True` ???

### 2.1 ??????

???????????

- ???????????
- ???????? / ?????????
- ?????
- ??? issue ???????????

### 2.2 ????????

| ?? | ???? |
| --- | --- |
| `get_minute()` | `raw_frame_hex`, `raw_payload_hex` |
| `get_trades()` | `raw_frame_hex`, `raw_payload_hex` |
| `get_kline()` | `raw_frame_hex`, `raw_payload_hex` |
| `get_call_auction()` | `raw_frame_hex`, `raw_payload_hex`, `items[].raw_hex` |
| `get_gbbq()` | `raw_frame_hex`, `raw_payload_hex` |

### 2.3 ????? K ?

```python
from eltdx import TdxClient

with TdxClient() as client:
    response = client.get_kline("sz000001", "day", count=10, include_raw=True)

print(response.raw_frame_hex)
print(response.raw_payload_hex)
print(response.items[0].open_price_milli, response.items[0].open_price)
```

???????

- `open_price_milli = 10960`
- `open_price = 10.96`
- `raw_payload_hex = 0a007525350190ab01721e...`

### 2.4 ?????????

```python
from eltdx import TdxClient

with TdxClient() as client:
    response = client.get_call_auction("sz000001", include_raw=True)

print(response.items[0].raw_hex)
print(response.items[0].flag)
```

???

- `raw_hex = 2b02c3f52c4113000000e8ffffff0000`
- `flag = -1` -> ????

---

## 3. ???????

### ?????

```python
from eltdx import TdxClient

with TdxClient(host="124.71.187.122:7709") as client:
    print(client.get_count("sz"))
```

### ?????

```python
from eltdx import TdxClient

hosts = [
    "124.71.187.122:7709",
    "122.51.120.217:7709",
    "111.229.247.189:7709",
]

with TdxClient(hosts=hosts, pool_size=2) as client:
    print(client.get_quote("sz000001")[0].last_price)
```

### ???????????

- ??????????????
- ??????????
- ????????????

---

## 4. ???? / ???

### 4.1 ??? `get_count("sh")` ?????

????**????????**??????????

????????????????

- `get_stock_count()`
- `get_a_share_count()`

### 4.2 `sh900xxx` ? `sz200xxx` ????

??? **B ?**?

- ????
- ??? A ?

???

- `get_stock_count()` ???????
- `get_a_share_count()` ???????

### 4.3 ????? K ??? `up_count/down_count`?

?????????

```python
kind="index"
```

?????

```python
client.get_kline("sh000001", "day", kind="index")
```

### 4.4 ??? `Quote.server_time` ? `None`?

???

- `server_time_raw` ??????????
- ????????????????
- ???? `server_time_raw`
- ?? `server_time` ?? `None`

??????????????????

### 4.5 ??? `with` ??????

???????????

- ??????????????? `with`
- ???????????????????? `connect()` / `close()`

???????????

### 4.6 ??????????????

????????????? `bj` ????????????????????????

---

## 5. ??? smoke ??

### `scripts/smoke_codes.py`

???

- ?????????
- ??? `get_count()` / `get_codes()` ????

```bash
python scripts/smoke_codes.py --exchange sh --limit 10
```

### `scripts/smoke_kline.py`

???

- ???? / ?? K ?
- ? `raw_payload_hex`

```bash
python scripts/smoke_kline.py --code sz000001 --period day --count 10
python scripts/smoke_kline.py --code sh000001 --period day --kind index --count 10
```

### `scripts/smoke_minute.py`

???

- ??????
- ??????????

```bash
python scripts/smoke_minute.py --code sz000001 --date 2026-03-06
```

### `scripts/smoke_trade.py`

???

- ???????
- ? `status -> side` ??

```bash
python scripts/smoke_trade.py --code sz000001 --date 2026-03-06 --count 50
```

### `scripts/smoke_call_auction.py`

???

- ??????
- ??????????? `raw_hex`

```bash
python scripts/smoke_call_auction.py --code sz000001
```

### `scripts/smoke_adjustment.py`

???

- ????????? K ???

```bash
python scripts/smoke_adjustment.py --code sz000001 --period day --adjust qfq
python scripts/smoke_adjustment.py --code sz000001 --factors-only
```

### `scripts/smoke_live_all.py`

???

- ??????????? smoke

```bash
python scripts/smoke_live_all.py --deep
```

### `scripts/export_live_validation.py`

???

- ??? API ??????? JSON / TXT / REPORT
- ?????????????????????

```bash
python scripts/export_live_validation.py
```

?????

- `summary.json`
- `REPORT.md`
- `quote_single_sz000001.json`
- `kline_day_page_sz000001.json`
- `kline_day_page_sh000001_index.json`
- `call_auction_sz000001.json`
- ...

### `scripts/smoke_isolated_install.py`

???

- ?? wheel ???????????????

```bash
python scripts/smoke_isolated_install.py --build
```

---

## 6. ??????? vs ??????

???????

### 6.1 Quote

??

- `server_time_raw -> server_time`
- `last_price_milli -> last_price`
- `buy_levels[0].price_milli -> buy_levels[0].price`

?????

- `server_time_raw = 15330719`
- `server_time = 2026-03-07T15:33:07.190000+08:00`
- `last_price_milli = 10810 -> last_price = 10.81`

### 6.2 Minute

??

- `price_milli -> price`
- `time`
- `volume`

?????

- `price_milli = 10820 -> price = 10.82`
- `time = 2026-03-06T09:31:00+08:00`

### 6.3 Trade

??

- `price_milli -> price`
- `status -> side`

?????

- `status = 0 -> side = buy`

### 6.4 Kline

??

- `open_price_milli -> open_price`
- `amount_milli -> amount`
- ????? `up_count/down_count`

???????

- `open_price_milli = 10960 -> open_price = 10.96`
- `amount_milli = 607501376000 -> amount = 607501376.0`

???????

- `up_count = 619`
- `down_count = 1677`

### 6.5 Call Auction

??

- `raw_hex`
- `price_milli -> price`
- `flag`

?????

- `raw_hex = 2b02c3f52c4113000000e8ffffff0000`
- `flag = -1 -> ????`

---

## 7. ???????

### ?????

```bash
python -m pytest -q
```

### ??????

#### PowerShell

```powershell
$env:ELTDX_RUN_LIVE='1'
python -m pytest -q -m integration
```

#### bash

```bash
ELTDX_RUN_LIVE=1 python -m pytest -q -m integration
```

???

- ???????????????
- ???????????????????

---

## 8. ????? GitHub ? issue????????

??????

1. ??????
2. ???? / ?? / ??
3. ???? `kind="index"`
4. ???? `include_raw=True`
5. `raw_payload_hex` ? `raw_hex`
6. ???????????

????????

- `scripts/export_live_validation.py` ????? JSON
- ?? smoke ???????

?????????
