Add rich token message design spec

Document unified Telegram token message format that includes all available sources (spot/future/alpha) with conditional rows. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-26 17:09:23 +07:00
parent 77036f2211
commit e565503f24
1 changed files with 130 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Token message rich design
+
+## Context
+
+Current token message flow returns early for Alpha tokens, so users cannot see Spot/Future together with Alpha when multiple sources are available. Message content is also rigid and less informative for partial-source cases.
+
+Goal: redesign Telegram token message so each available price source is shown in one rich message, with stable ordering and conditional rows.
+
+## Scope
+
+Applies to token query message rendering in Telegram bot (`OnTokenInfoByToken` flow and price view formatting).
+
+Out of scope:
+- changing market data fetch logic
+- changing command routing
+- trend arrows / historical diff
+
+## Requirements
+
+1. Rich, multi-line Telegram message format.
+2. Spot is primary source when present.
+3. Show all available sources in a single message: Spot, Future, Alpha.
+4. Hide rows for missing data.
+5. Show Basis only when both Spot and Future exist.
+6. Show Alpha 24h when Alpha data exists.
+7. No trend arrows.
+8. Preserve current behavior of no reply when no Spot/Future/Alpha data exists.
+
+## Message format
+
+Fixed row order (hide missing rows):
+
+1. `🪙 TOKEN`
+2. `💵 Spot: ...` (primary if exists)
+3. `📈 Future: ...`
+4. `🅰️ Alpha: ...`
+5. `🧭 Basis: Future-Spot` (only if Spot+Future)
+6. `💸 Funding: ... in ...` (if Future exists)
+7. `🏦 Margin: ... APR` (if margin exists)
+8. `📊 Alpha 24h: ...` (if Alpha change exists)
+
+## Fallback rules
+
+- **All three available**: render all rows above (except any missing optional fields).
+- **Spot + Future**: render Spot, Future, Basis, Funding, Margin.
+- **Alpha only**: render Alpha and Alpha 24h.
+- **Future only**: render Future, Funding, Margin.
+- **Spot only**: render Spot, Margin.
+- **No Spot/Future/Alpha**: no reply.
+
+## Data flow behavior
+
+1. Resolve token to candidate futures symbol(s) using existing resolver.
+2. Collect available values from Spot/Future/Alpha/margin sources.
+3. Build one unified message model.
+4. Render rows in fixed order; each row is conditional on availability.
+5. Send single Telegram message.
+
+Important behavioral change: remove alpha-first early-return behavior; Alpha becomes a peer data source in unified rendering.
+
+## Formatting notes
+
+- Reuse existing numeric formatter (`RenderPrice`) for price values.
+- Keep current funding icon and countdown style.
+- Basis format:
+  - absolute delta: `Future - Spot`
+  - percent delta: `(Future-Spot)/Spot*100`
+  - sign preserved (`+`/`-`)
+
+## Example outputs
+
+### A) Spot + Future + Alpha
+
+```text
+🪙 ETH
+💵 Spot: $3,245
+📈 Future: $3,251
+🅰️ Alpha: $3,248
+🧭 Basis: +$6 (+0.18%)
+💸 Funding: +0.0123% 🟢 in 05m
+🏦 Margin: 7.665% APR
+📊 Alpha 24h: 🔴 -3.21%
+```
+
+### B) Spot + Future
+
+```text
+🪙 SOL
+💵 Spot: $182.4
+📈 Future: $183.0
+🧭 Basis: +$0.6 (+0.33%)
+💸 Funding: -0.0041% 🔴 in 42m
+🏦 Margin: 5.110% APR
+```
+
+### C) Alpha only
+
+```text
+🪙 ABC
+🅰️ Alpha: $0.1234
+📊 Alpha 24h: 🟢 +12.40%
+```
+
+### D) Future only
+
+```text
+🪙 TOKEN
+📈 Future: $1,234
+💸 Funding: +0.0081% 🟢 in 17m
+🏦 Margin: 6.200% APR
+```
+
+### E) Spot only
+
+```text
+🪙 TOKEN
+💵 Spot: $1,228
+🏦 Margin: 6.200% APR
+```
+
+## Verification checklist
+
+- Token with all 3 sources -> all expected rows appear, ordered correctly.
+- Token with Spot+Future but no Alpha -> no Alpha rows.
+- Token with Alpha only -> no Spot/Future/Basis/Funding rows.
+- Token with Future only -> no Spot/Basis/Alpha rows.
+- Token with Spot only -> no Future/Basis/Funding/Alpha rows.
+- Token with no data -> no reply.
+- Basis not shown unless both Spot and Future exist.
+- No trend arrows anywhere.