Grid_Trading/docs/superpowers/specs/2026-07-08-tencent-quotes-design.md

# Tencent Realtime Quotes Design

Date: 2026-07-08

## Goal

Add Tencent A-share quote integration so the GUI holdings table displays realtime prices from `http://qt.gtimg.cn/q=<symbol>`.

The first implementation is manual refresh only. It does not auto-refresh, generate buy/sell grid orders, persist quote prices, or use trade-entry prices as current prices.

## Confirmed Decision

Use Tencent's quote endpoint directly. Example:

```text
http://qt.gtimg.cn/q=sz000001
```

The response is GBK/GB18030 encoded and shaped like:

```text
v_sz000001="51~平安银行~000001~10.60~10.47~10.44~...";
```

The parser will use these fields:

- `1`: name
- `2`: code
- `3`: current price
- `4`: previous close
- `5`: open
- `30`: quote time
- `31`: price change
- `32`: change percent
- `33`: high
- `34`: low

## Design

Add a `market` package with a Tencent quote client. The client converts local instrument codes into Tencent symbols:

- Already prefixed `sh` or `sz`: keep as-is.
- Codes starting with `6`, `5`, or `9`: use `sh`.
- Codes starting with `0`, `1`, `2`, or `3`: use `sz`.

`TradingService` keeps an in-memory quote cache. When the user clicks refresh in the GUI, the service fetches quotes for all active instruments and stores them in memory.

Position calculations will treat Tencent quotes as the only current-price source:

1. Tencent realtime quote
2. Empty value

The holdings table and account summary will immediately reflect quote prices after refresh. Quote prices are not persisted to SQLite in this step, so stale prices do not silently survive app restarts. Trade-entry prices remain historical成交价 only and never become current-price fallbacks.

## Error Handling

- If one symbol fails, the refresh reports the error and keeps existing data unchanged.
- Empty or malformed Tencent responses raise a quote-specific error.
- A zero or missing current price is ignored for that symbol.
- Network timeouts use a short timeout so the GUI does not hang for long.

## Testing

- Unit-test Tencent response parsing with a fixture response.
- Unit-test symbol inference.
- Unit-test position calculations with a realtime quote supplying current price and a missing quote leaving current price empty.
- Unit-test service quote refresh using a fake quote provider.
- Keep existing GUI smoke tests passing.