docs: 更新文档和技能

2025-12-17 20:27:57 +08:00 · 2025-12-17 20:27:57 +08:00 · 924b651e34
parent cdc404f66f
commit 924b651e34
2 changed files with 413 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -21,7 +21,6 @@
 -->
 <!-- 项目状态徽章 -->
 <p>
-  <a href="https://github.com/tukuaiai/vibe-coding-cn/actions"><img src="https://img.shields.io/github/actions/workflow/status/tukuaiai/vibe-coding-cn/main.yml?label=%E6%9E%84%E5%BB%BA%E7%8A%B6%E6%80%81&style=for-the-badge" alt="构建状态"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/tukuaiai/vibe-coding-cn?label=%E8%AE%B8%E5%8F%AF%E8%AF%81&style=for-the-badge" alt="许可证"></a>
  <a href="https://github.com/tukuaiai/vibe-coding-cn"><img src="https://img.shields.io/github/languages/top/tukuaiai/vibe-coding-cn?label=%E4%B8%BB%E8%A6%81%E8%AF%AD%E8%A8%80&style=for-the-badge" alt="主要语言"></a>
  <a href="https://github.com/tukuaiai/vibe-coding-cn"><img src="https://img.shields.io/github/languages/code-size/tukuaiai/vibe-coding-cn?label=%E4%BB%A3%E7%A0%81%E9%87%8F&style=for-the-badge" alt="代码量"></a>
--- a/i18n/en/skills/telegram-dev/references/dynamic-view-alignment-implementation-document.md
+++ b/i18n/en/skills/telegram-dev/references/dynamic-view-alignment-implementation-document.md
@ -0,0 +1,413 @@
+# 📊 Dynamic View Alignment - A Guide to Data Display in Telegram
+
+> A professional solution for monospaced font data alignment and formatting
+
+---
+
+## 📑 Table of Contents
+
+- [Core Principles](#core-principles)
+- [Implementation Code](#implementation-code)
+- [Formatting System](#formatting-system)
+- [Application Examples](#application-examples)
+- [Best Practices](#best-practices)
+
+---
+
+## Core Principles
+
+### Problem Scenario
+
+When displaying leaderboards or data tables in a Telegram Bot, perfect alignment is required in a monospaced font environment (code block):
+
+**❌ Unaligned:**
+```
+1. BTC $1.23B $45000 +5.23%
+10. DOGE $123.4M $0.0789 -1.45%
+```
+
+**✅ Dynamically Aligned:**
+```
+1.   BTC      $1.23B    $45,000   +5.23%
+10.  DOGE   $123.4M   $0.0789   -1.45%
+```
+
+### Three-Step Alignment Algorithm
+
+```
+Step 1: Scan the data to calculate the maximum width of each column
+Step 2: Apply alignment rules based on the column type (text left-aligned, numbers right-aligned)
+Step 3: Concatenate into the final text
+```
+
+### Alignment Rules
+
+| Column Index | Data Type | Alignment | Example |
+|---|---|---|---|
+| Column 0 | Sequence No. | Left-aligned | `1.  `, `10. ` |
+| Column 1 | Symbol | Left-aligned | `BTC  `, `DOGE ` |
+| Column 2+ | Numeric Value | Right-aligned | `  $1.23B`, `$123.4M` |
+
+---
+
+## Implementation Code
+
+### Core Function
+
+```python
+def dynamic_align_format(data_rows):
+    """
+    Dynamically aligns and formats the view.
+
+    Args:
+        data_rows: A 2D list [["1.", "BTC", "$1.23B", ...], ...]
+
+    Returns:
+        An aligned text string.
+    """
+    if not data_rows:
+        return "No data available"
+
+    # ========== Step 1: Calculate the maximum width of each column ==========
+    max_widths = []
+    for row in data_rows:
+        for i, cell in enumerate(row):
+            # Dynamically expand the list
+            if i >= len(max_widths):
+                max_widths.append(0)
+            # Update the maximum width
+            max_widths[i] = max(max_widths[i], len(str(cell)))
+
+    # ========== Step 2: Format each row ==========
+    formatted_rows = []
+    for row in data_rows:
+        formatted_cells = []
+        for i, cell in enumerate(row):
+            cell_str = str(cell)
+
+            if i == 0 or i == 1:
+                # Sequence number and symbol columns - left-aligned
+                formatted_cells.append(cell_str.ljust(max_widths[i]))
+            else:
+                # Numeric columns - right-aligned
+                formatted_cells.append(cell_str.rjust(max_widths[i]))
+
+        # Join all cells with a space
+        formatted_line = ' '.join(formatted_cells)
+        formatted_rows.append(formatted_line)
+
+    # ========== Step 3: Concatenate into the final text ==========
+    return '\n'.join(formatted_rows)
+```
+
+### Usage Example
+
+```python
+# Prepare the data
+data_rows = [
+    ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"],
+    ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"],
+    ["10.", "DOGE", "$123.4M", "$0.0789", "-1.45%"]
+]
+
+# Call the alignment function
+aligned_text = dynamic_align_format(data_rows)
+
+# Output to Telegram
+text = f"""
+📊 Leaderboard
+```
+{aligned_text}
+```
+💡 Explanatory text"""
+```
+
+---
+
+## Formatting System
+
+### 1. Smart Abbreviation for Trading Volume
+
+```python
+def format_volume(volume: float) -> str:
+    """Intelligently formats trading volume."""
+    if volume >= 1e9:
+        return f"${volume/1e9:.2f}B"    # Billions → $1.23B
+    elif volume >= 1e6:
+        return f"${volume/1e6:.2f}M"    # Millions → $890.5M
+    elif volume >= 1e3:
+        return f"${volume/1e3:.2f}K"    # Thousands → $123.4K
+    else:
+        return f"${volume:.2f}"          # Decimals → $45.67
+```
+
+**Example:**
+```python
+format_volume(1234567890)  # → "$1.23B"
+format_volume(890500000)   # → "$890.5M"
+format_volume(123400)      # → "$123.4K"
+```
+
+### 2. Smart Precision for Price
+
+```python
+def format_price(price: float) -> str:
+    """Intelligently formats price - automatically adjusts decimal places based on value."""
+    if price >= 1000:
+        return f"${price:,.0f}"      # Above 1000 → $45,000
+    elif price >= 1:
+        return f"${price:.3f}"       # 1-1000 → $2.500
+    elif price >= 0.01:
+        return f"${price:.4f}"       # 0.01-1 → $0.0789
+    else:
+        return f"${price:.6f}"       # <0.01 → $0.000123
+```
+
+### 3. Formatting for Price Change Percentage
+
+```python
+def format_change(change_percent: float) -> str:
+    """Formats price change percentage - adds a '+' sign for positive numbers."""
+    if change_percent >= 0:
+        return f"+{change_percent:.2f}%"
+    else:
+        return f"{change_percent:.2f}%"
+```
+
+**Example:**
+```python
+format_change(5.234)   # → "+5.23%"
+format_change(-1.456)  # → "-1.46%"
+format_change(0)       # → "+0.00%"
+```
+
+### 4. Smart Display for Fund Flow
+
+```python
+def format_flow(net_flow: float) -> str:
+    """Formats net fund flow."""
+    sign = "+" if net_flow >= 0 else ""
+    abs_flow = abs(net_flow)
+
+    if abs_flow >= 1e9:
+        return f"{sign}{net_flow/1e9:.2f}B"
+    elif abs_flow >= 1e6:
+        return f"{sign}{net_flow/1e6:.2f}M"
+    elif abs_flow >= 1e3:
+        return f"{sign}{net_flow/1e3:.2f}K"
+    else:
+        return f"{sign}{net_flow:.0f}"
+```
+
+---
+
+## Application Examples
+
+### Complete Leaderboard Implementation
+
+```python
+def get_volume_ranking(data, limit=10):
+    """Gets the trading volume leaderboard."""
+
+    # 1. Data processing and sorting
+    sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit]
+
+    # 2. Prepare data rows
+    data_rows = []
+    for i, item in enumerate(sorted_data, 1):
+        symbol = item['symbol']
+        volume = item['volume']
+        price = item['price']
+        change = item['change_percent']
+
+        # Format each column
+        volume_str = format_volume(volume)
+        price_str = format_price(price)
+        change_str = format_change(change)
+
+        # Add to data rows
+        data_rows.append([
+            f"{i}.",      # Sequence No.
+            symbol,       # Coin
+            volume_str,   # Volume
+            price_str,    # Price
+            change_str    # Change %
+        ])
+
+    # 3. Dynamic alignment and formatting
+    aligned_data = dynamic_align_format(data_rows)
+
+    # 4. Build the final message
+    text = f"""
+🎪 Hot Coins - Volume Ranking 🎪
+⏰ Updated {datetime.now().strftime('%Y-%m-%d %H:%M')}
+📊 Sorted by 24h Volume (USDT) / Descending
+Rank/Coin/24h Vol/Price/24h Change
+```
+{aligned_data}
+```
+💡 Volume reflects market activity and liquidity."""
+
+    return text
+```
+
+### Output Effect
+
+```
+🎪 Hot Coins - Volume Ranking 🎪
+⏰ Updated 2025-10-29 14:30
+📊 Sorted by 24h Volume (USDT) / Descending
+Rank/Coin/24h Vol/Price/24h Change
+
+1.   BTC      $1.23B    $45,000   +5.23%
+2.   ETH    $890.5M     $2,500   +3.12%
+3.   SOL    $567.8M       $101   +8.45%
+4.   BNB    $432.1M       $315   +2.67%
+5.   XRP    $345.6M     $0.589   -1.23%
+
+💡 Volume reflects market activity and liquidity.
+```
+
+---
+
+## Best Practices
+
+### 1. Data Preparation Standards
+
+```python
+# ✅ Recommended: Use a nested list structure
+data_rows = [
+    ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"],
+    ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"]
+]
+
+# ❌ Not recommended: Use a dictionary (requires extra conversion)
+data_rows = [
+    {"rank": 1, "symbol": "BTC", ...},
+]
+```
+
+### 2. Formatting Order
+
+```python
+# ✅ Recommended: Format first, then align
+for i, item in enumerate(data, 1):
+    volume_str = format_volume(item['volume'])      # Format
+    price_str = format_price(item['price'])         # Format
+    change_str = format_change(item['change'])      # Format
+
+    data_rows.append([f"{i}.", symbol, volume_str, price_str, change_str])
+
+aligned_data = dynamic_align_format(data_rows)  # Align
+```
+
+### 3. Embedding in Telegram Messages
+
+```python
+# ✅ Recommended: Wrap aligned data in a code block
+text = f"""
+📊 Leaderboard Title
+⏰ Update Time {time}
+```
+{aligned_data}
+```
+💡 Explanatory text"""
+
+# ❌ Not recommended: Direct output (Telegram's auto-wrapping will break alignment)
+text = f"""
+📊 Leaderboard Title
+{aligned_data}
+💡 Explanatory text"""
+```
+
+### 4. Handling Empty Data
+
+```python
+# ✅ Recommended: Check at the beginning of the function
+def dynamic_align_format(data_rows):
+    if not data_rows:
+        return "No data available"
+    # ... Normal processing logic ...
+```
+
+### 5. Performance Optimization
+
+```python
+# ✅ Recommended: Limit the amount of data
+sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit]
+aligned_data = dynamic_align_format(data_rows)
+
+# ❌ Not recommended: Process all data then truncate (wastes resources)
+aligned_data = dynamic_align_format(all_data_rows)
+final_data = aligned_data.split('\n')[:limit]
+```
+
+### 6. Chinese Character Support (Optional)
+
+```python
+def get_display_width(text):
+    """Calculates the display width of text (Chinese=2, English=1)."""
+    width = 0
+    for char in text:
+        if ord(char) > 127:  # Non-ASCII characters
+            width += 2
+        else:
+            width += 1
+    return width
+
+# Use in dynamic_align_format
+max_widths[i] = max(max_widths[i], get_display_width(str(cell)))
+```
+
+---
+
+## Design Advantages
+
+### Comparison with Hardcoding
+
+| Feature | Traditional Hardcoding | Dynamic Alignment |
+|---|---|---|
+| Column Width Adaptation | Manual specification | Automatic calculation |
+| Maintenance Cost | High (requires multiple modifications) | Low (write once) |
+| Alignment Precision | Prone to deviation | Character-level precision |
+| Scalability | Requires refactoring | Supports any number of columns automatically |
+| Performance | O(n) | O(n×m) |
+
+### Technical Highlights
+
+- **Adaptive Width**: Perfect alignment regardless of data changes
+- **Smart Alignment Rules**: Conforms to human reading habits (text left, numbers right)
+- **Perfect Monospaced Font Support**: Space padding ensures alignment
+- **High Reusability**: One function for all leaderboard scenarios
+
+---
+
+## Quick Reference
+
+### Function Signatures
+
+```python
+dynamic_align_format(data_rows: list[list]) -> str
+format_volume(volume: float) -> str
+format_price(price: float) -> str
+format_change(change_percent: float) -> str
+format_flow(net_flow: float) -> str
+```
+
+### Time Complexity
+
+- Width Calculation: O(n × m)
+- Formatted Output: O(n × m)
+- Total Complexity: O(n × m) - Linear time, highly efficient
+
+### Performance Benchmarks
+
+- Processing 100 rows × 5 columns: ~1ms
+- Processing 1000 rows × 5 columns: ~5-10ms
+- Memory Usage: Minimal
+
+---
+
+**This guide provides a complete solution for professional data display in Telegram Bots!**
+
+```