v4.0.4

Signed-off-by: Dinger <quantdinger@gmail.com>

Author: quantdinger-lab

CONTRIBUTING.md

@@ -121,6 +121,19 @@ For local iteration without publishing, clone the Vue repo into `./QuantDinger-V
 
 ---
 
+## Code Organization
+
+Read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/EXTENSION_GUIDE.md`](docs/EXTENSION_GUIDE.md), and [`docs/MODULE_BOUNDARIES.md`](docs/MODULE_BOUNDARIES.md) before larger backend changes.
+
+- Keep routes thin: validate input, call a service, return JSON.
+- Put exchange, broker, market data, and strategy behavior behind small services or adapters.
+- Avoid growing legacy hotspot files when a focused sibling module can hold new behavior.
+- Keep code comments, docstrings, and log messages in English unless a user-facing translation or external provider field requires another language.
+- Prefer simple, readable code over clever abstractions.
+- Ask for clarification before changing unclear product behavior.
+
+---
+
 ## 🌿 Branching & Pull Requests
 
 ### Branch naming
@@ -205,4 +218,4 @@ What is guaranteed:
 - your name will be attached to it
 - your contribution will remain yours
 
-Build carefully. Build openly. Build things that last.
+Build carefully. Build openly. Build things that last.

README.md

@@ -424,12 +424,12 @@ The backend entrypoint auto-generates a random `SECRET_KEY` on first start and a
 
 ```env
 # Common case: lockstep both sides to one tag
-IMAGE_TAG=4.0.3
+IMAGE_TAG=4.0.4
 
 # Advanced (opt-in): decouple sides. Either var alone overrides only
 # that side; the other still follows IMAGE_TAG.
-# BACKEND_TAG=4.0.3
-# FRONTEND_TAG=4.0.3
+# BACKEND_TAG=4.0.4
+# FRONTEND_TAG=4.0.4
 # MOBILE_TAG=4.0.3
 
 # BACKEND_IMAGE=ghcr.io/<your-fork>/quantdinger-backend     # optional, for forks
@@ -441,7 +441,7 @@ Tag resolution: `BACKEND_TAG` / `FRONTEND_TAG` / `MOBILE_TAG` → `IMAGE_TAG` 
 
 #### Version stamping
 
-Published backend images are stamped from the Git release tag automatically. A `v4.0.3` tag becomes `APP_VERSION=4.0.3`, which is what OpenAPI metadata and the UI brand config expose. Local source runs fall back to `git describe` and then the repo-root `VERSION` file; local Docker builds can override explicitly:
+Published backend images are stamped from the Git release tag automatically. A `v4.0.4` tag becomes `APP_VERSION=4.0.4`, which is what OpenAPI metadata and the UI brand config expose. Local source runs fall back to `git describe` and then the repo-root `VERSION` file; local Docker builds can override explicitly:
 
 ```bash
 APP_VERSION=$(git describe --tags --abbrev=0 | sed 's/^v//') docker compose up -d --build backend
@@ -718,6 +718,9 @@ Economic calendar data is free-first: QuantDinger uses the no-key AkShare/Wallst
 | Doc | Notes |
 |-----|--------|
 | [Human Web API (OpenAPI)](docs/api/openapi.yaml) | flask-smorest spec — browse with [`docs/api/index.html`](docs/api/index.html) (HTTP server required) |
+| [Backend architecture](docs/ARCHITECTURE.md) | Runtime surfaces, ownership boundaries, and refactor rules |
+| [Extension guide](docs/EXTENSION_GUIDE.md) | How to add APIs, adapters, data sources, workers, and strategy features |
+| [Module boundaries](docs/MODULE_BOUNDARIES.md) | Deeper backend module ownership notes |
 | [API conventions](docs/API_CONVENTIONS.md) | Auth, envelopes, visibility tiers |
 | [Changelog](docs/CHANGELOG.md) | Releases & migrations |
 | [README (Chinese)](docs/README_CN.md) | Chinese overview |

VERSION

@@ -1 +1 @@
-4.0.3
+4.0.4

backend_api_python/VERSION

@@ -1 +1 @@
-4.0.3
+4.0.4

backend_api_python/app/config/__init__.py

@@ -1,7 +1,4 @@
-"""
-配置模块
-统一导出所有配置
-"""
+"""Configuration package exports."""
 from app.config.settings import Config
 from app.config.api_keys import APIKeys
 from app.config.database import RedisConfig, CacheConfig

backend_api_python/app/config/api_keys.py

@@ -5,7 +5,7 @@
 import os
 
 class MetaAPIKeys(type):
-    """API Keys 元类，用于支持类属性的动态获取"""
+    """Metaclass that supports dynamic class-level API key lookup."""
 
     @property
     def FINNHUB_API_KEY(cls):
@@ -226,17 +226,17 @@ def SERPAPI_KEYS(cls):
 
 
 class APIKeys(metaclass=MetaAPIKeys):
-    """API 密钥配置类"""
+    """API key configuration."""
 
     @classmethod
     def get(cls, key_name: str, default: str = '') -> str:
-        """获取 API 密钥"""
+        """Return an API key by name."""
         if hasattr(cls, key_name):
             return getattr(cls, key_name)
         return default
 
     @classmethod
     def is_configured(cls, key_name: str) -> bool:
-        """检查 API 密钥是否已配置"""
+        """Return whether an API key is configured."""
         value = cls.get(key_name)
         return bool(value and value.strip())

backend_api_python/app/config/database.py

@@ -1,10 +1,8 @@
-"""
-数据库和缓存配置
-"""
+"""Database and cache configuration."""
 import os
 
 class MetaRedisConfig(type):
-    """Redis 配置"""
+    """Redis connection settings."""
 
     @property
     def HOST(cls):
@@ -36,18 +34,18 @@ def MAX_CONNECTIONS(cls):
 
 
 class RedisConfig(metaclass=MetaRedisConfig):
-    """Redis 缓存配置"""
+    """Redis cache configuration."""
 
     @classmethod
     def get_url(cls) -> str:
-        """获取 Redis 连接 URL"""
+        """Return the Redis connection URL."""
         if cls.PASSWORD:
             return f"redis://:{cls.PASSWORD}@{cls.HOST}:{cls.PORT}/{cls.DB}"
         return f"redis://{cls.HOST}:{cls.PORT}/{cls.DB}"
 
 
 class MetaCacheConfig(type):
-    """缓存业务配置"""
+    """Business cache settings."""
 
     @property
     def ENABLED(cls):
@@ -60,14 +58,14 @@ def DEFAULT_EXPIRE(cls):
     @property
     def KLINE_CACHE_TTL(cls):
         return {
-            '1m': 5,       # 1分钟K线缓存5秒
-            '3m': 30,      # 3分钟K线缓存30秒
-            '5m': 60,      # 5分钟K线缓存1分钟
-            '15m': 300,    # 15分钟K线缓存5分钟
-            '30m': 300,    # 30分钟K线缓存5分钟
-            '1H': 300,     # 1小时K线缓存5分钟
-            '4H': 300,     # 4小时K线缓存5分钟
-            '1D': 300,     # 日K线缓存5分钟
+            '1m': 5,       # Cache 1m K-lines for 5 seconds
+            '3m': 30,      # Cache 3m K-lines for 30 seconds
+            '5m': 60,      # Cache 5m K-lines for 1 minute
+            '15m': 300,    # Cache 15m K-lines for 5 minutes
+            '30m': 300,    # Cache 30m K-lines for 5 minutes
+            '1H': 300,     # Cache 1H K-lines for 5 minutes
+            '4H': 300,     # Cache 4H K-lines for 5 minutes
+            '1D': 300,     # Cache 1D K-lines for 5 minutes
             '1h': 300,
             '4h': 300,
             '1d': 300,
@@ -83,5 +81,5 @@ def PRICE_CACHE_TTL(cls):
 
 
 class CacheConfig(metaclass=MetaCacheConfig):
-    """缓存配置"""
+    """Cache configuration."""
     pass

backend_api_python/app/config/settings.py

@@ -1,6 +1,4 @@
-"""
-应用主配置
-"""
+"""Application settings."""
 import os
 
 class MetaConfig(type):
@@ -83,9 +81,9 @@ def ENABLE_REQUEST_LOG(cls):
         return os.getenv('ENABLE_REQUEST_LOG', 'True').lower() == 'true'
 
 class Config(metaclass=MetaConfig):
-    """应用配置类"""
+    """Application configuration."""
 
     @classmethod
     def get_log_path(cls) -> str:
-        """获取日志文件完整路径"""
+        """Return the full log file path."""
         return os.path.join(cls.LOG_DIR, cls.LOG_FILE)

backend_api_python/app/data_sources/base.py

@@ -1,6 +1,7 @@
 """
-数据源基类
-定义统一的数据源接口
+Base market data source interfaces.
+
+All market data adapters should normalize K-line rows to the shape defined here.
 """
 from abc import ABC, abstractmethod
 from typing import Dict, List, Any, Optional
@@ -25,7 +26,7 @@
 
 
 class BaseDataSource(ABC):
-    """数据源基类"""
+    """Base class for market data sources."""
 
     name: str = "base"
 
@@ -39,17 +40,17 @@ def get_kline(
         after_time: Optional[int] = None,
     ) -> List[Dict[str, Any]]:
         """
-        获取K线数据
+        Fetch K-line data.
         
         Args:
-            symbol: 交易对/股票代码
-            timeframe: 时间周期 (1m, 5m, 15m, 30m, 1H, 4H, 1D, 1W)
-            limit: 数据条数
-            before_time: 获取此时间之前的数据（Unix时间戳，秒）
-            after_time: 可选，仅保留 time >= after_time 的 K 线（Unix 秒），用于回测窗口左边界
+            symbol: Trading pair or ticker.
+            timeframe: Candle interval (1m, 5m, 15m, 30m, 1H, 4H, 1D, 1W).
+            limit: Number of rows to fetch.
+            before_time: Fetch rows before this Unix timestamp, in seconds.
+            after_time: Optional left boundary. Keep only rows with time >= after_time.
             
         Returns:
-            K线数据列表，格式:
+            K-line rows in this normalized shape:
             [{"time": int, "open": float, "high": float, "low": float, "close": float, "volume": float}, ...]
         """
         pass
@@ -72,7 +73,7 @@ def format_kline(
         close: float,
         volume: float
     ) -> Dict[str, Any]:
-        """格式化单条K线数据"""
+        """Normalize one K-line row."""
         return {
             'time': timestamp,
             'open': round(float(open_price), 4),
@@ -89,15 +90,15 @@ def calculate_time_range(
         buffer_ratio: float = 1.2
     ) -> int:
         """
-        计算获取指定数量K线所需的时间范围（秒）
+        Calculate the time range required to fetch the requested candle count.
         
         Args:
-            timeframe: 时间周期
-            limit: K线数量
-            buffer_ratio: 缓冲系数
+            timeframe: Candle interval.
+            limit: Number of candles.
+            buffer_ratio: Extra range multiplier.
             
         Returns:
-            时间范围（秒）
+            Time range in seconds.
         """
         seconds_per_candle = TIMEFRAME_SECONDS.get(timeframe, 86400)
         return int(seconds_per_candle * limit * buffer_ratio)
@@ -111,17 +112,18 @@ def filter_and_limit(
         truncate: bool = True,
     ) -> List[Dict[str, Any]]:
         """
-        过滤和限制K线数据
+        Filter and limit K-line rows.
         
         Args:
-            klines: K线数据列表
-            limit: 最大数量
-            before_time: 过滤此时间之后的数据
-            after_time: 若设置，仅保留 time >= after_time
-            truncate: 为 False 时不在末尾按 limit 截断（回测需整段 [after_time, before_time) 时避免误丢左端）
+            klines: K-line rows.
+            limit: Maximum number of rows.
+            before_time: Keep rows before this timestamp.
+            after_time: Keep rows with time >= after_time when set.
+            truncate: When False, do not trim the tail by limit. Backtests need the
+                full [after_time, before_time) window and must not lose the left edge.
             
         Returns:
-            处理后的K线数据
+            Filtered K-line rows.
         """
         klines.sort(key=lambda x: x['time'])
 
@@ -141,12 +143,14 @@ def log_result(
         klines: List[Dict[str, Any]],
         timeframe: str
     ):
-        """记录获取结果日志。
+        """Log fetch result quality.
 
-        延迟判断：
-        - K 线 time 为 Unix 秒（UTC），与 datetime.now(UTC) 比较，避免本地时区误差。
-        - 日线/周线：最后一根通常是「上一交易日收盘」，周末/节假日可达 3～4 天，
-          原先用 2×86400s（48h）会在周一早盘误报；改为日线最多容忍约 5 个自然日，周线更宽。
+        Delay checks:
+        - K-line time is a UTC Unix timestamp. Compare with datetime.now(UTC) to
+          avoid local timezone drift.
+        - Daily and weekly bars often represent the previous market close. Weekends
+          and holidays can create a 3-4 day gap, so daily bars allow about 5
+          calendar days and weekly bars allow a wider threshold.
         """
         if klines:
             latest_ts = int(klines[-1]["time"])