Add Tencent quote design spec

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

@@ -0,0 +1,70 @@
+# 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, or overwrite user-entered manual 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 prefer prices in this order:
+
+1. Tencent realtime quote
+2. Manual price
+3. Last trade price
+4. 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.
+
+## 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 overriding manual price.
+- Unit-test service quote refresh using a fake quote provider.
+- Keep existing GUI smoke tests passing.