fix: 分析后无报告生成 (#2201) (#2211)

* fix(issue-2201): [bug]-分析后无报告生成

* fix(review-feedback-2211): Keep the TTM cutoff anchored to the as-of date and Propagate report

* fix(review-feedback-2211): Move the empty-watchlist check before the trading-day return

* fix(review-feedback-2211): preserve the failure status, but defer returning until after the and

* fix(review-feedback-2211): preserve the failure result, but defer returning until after the

* fix(review-feedback-2211): Handle failures in the market-review-only CLI branch

Author: ZhuLinsen

data_provider/yfinance_fundamental_adapter.py

@@ -268,6 +268,7 @@ def get_fundamental_bundle(self, stock_code: str) -> Dict[str, Any]:
 
         # ---------------- dividend block ----------------
         events: List[Dict[str, Any]] = []
+        as_of_date = datetime.now(timezone.utc).date()
         try:
             div_series = ticker.dividends
         except Exception as exc:
@@ -281,8 +282,7 @@ def get_fundamental_bundle(self, stock_code: str) -> Dict[str, Any]:
             if hasattr(div_series, "columns"):
                 div_series = div_series.iloc[:, 0]
             try:
-                # Index is timezone-aware (ex-dividend date)
-                cutoff = pd.Timestamp.now(tz=div_series.index.tz) - pd.Timedelta(days=365)
+                cutoff = pd.Timestamp(as_of_date).tz_localize(div_series.index.tz) - pd.Timedelta(days=365)
                 for ts, value in div_series.items():
                     per_share = _safe_float(value)
                     if per_share is None or per_share <= 0:
@@ -325,7 +325,7 @@ def get_fundamental_bundle(self, stock_code: str) -> Dict[str, Any]:
                 "ttm_cash_dividend_per_share": round(ttm_cash, 6) if ttm_cash is not None else None,
                 "coverage": "cash_dividend_pre_tax",
                 "currency": dividend_currency,
-                "as_of": datetime.now(timezone.utc).date().isoformat(),
+                "as_of": as_of_date.isoformat(),
             }
 
             # Yield: prefer recomputing from TTM cash / latest price so the

docs/CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 <!-- 新条目格式：- [类型] 描述（类型取值：新功能/改进/修复/文档/测试/chore）-->
 <!-- 每条独立一行追加到本段末尾，无需分类标题，合并时冲突最小 -->
 - [改进] AIHubMix 注册与引流链接统一使用 inferera.com，改善中国大陆网络直连体验。
+- [修复] 单股推送模式在未配置通知渠道时仍会落盘本地个股报告；CLI 启动分析若因空股票列表、个股结果全失败或本地报告保存失败而未生成报告，会显式返回失败并记录原因。
+- [修复] 合并推送模式下即使个股汇总报告落盘失败，仍会先发送已有的合并通知；仅启用大盘复盘但最终未生成任何复盘内容时，分析任务会显式返回失败。
 
 ## [3.30.0] - 2026-08-09
 

docs/FAQ.md

@@ -166,9 +166,22 @@ PROXY_PORT=10809
 1. **自动分块**：最新版本已实现长消息自动切割
 2. **单股推送模式**：设置 `SINGLE_STOCK_NOTIFY=true`，每分析完一只股票立即推送
 3. **精简报告**：设置 `REPORT_TYPE=simple` 使用精简格式
+4. **仅落盘本地报告**：即使未配置任何通知渠道，`SINGLE_STOCK_NOTIFY=true` 仍会把单股报告保存到 `reports/report_YYYYMMDD_<股票代码>.md`
 
 ---
 
+### Q8.1: 分析结束了，但 `reports/` 里没有生成报告文件？
+
+**常见原因**：
+1. `STOCK_LIST` 为空，且本轮未启用大盘复盘
+2. 股票列表非空，但个股分析全部失败，最终没有成功结果
+3. 个股结果已生成，但写入 `reports/` 时失败（如目录权限或挂载问题）
+
+**现在的行为**：
+1. CLI 启动分析会对上述场景显式记录失败原因
+2. 非 `--serve` 的独立运行模式会返回非零退出码，避免工作流把“未生成报告”误判为成功
+3. 若是单股推送模式且通知未配置，仍会继续保存本地 Markdown 报告用于排查
+
 ### Q9: Telegram 推送收不到消息？
 
 **解决方案**：

docs/FAQ_EN.md

@@ -164,9 +164,22 @@ First confirm whether `LITELLM_CONFIG` or `LLM_CHANNELS` is active, because eith
 1. **Auto-chunking**: Latest version implements automatic long message splitting
 2. **Single stock push mode**: Set `SINGLE_STOCK_NOTIFY=true`, push immediately after each stock analysis
 3. **Brief report**: Set `REPORT_TYPE=simple` for simplified format
+4. **Local file fallback**: Even with no notification channel configured, `SINGLE_STOCK_NOTIFY=true` still saves each stock report to `reports/report_YYYYMMDD_<stock_code>.md`
 
 ---
 
+### Q8.1: Analysis finished, but no report file was created under `reports/`?
+
+**Common causes**:
+1. `STOCK_LIST` is empty and market review was not enabled for this run
+2. The stock list is non-empty, but every stock analysis failed so no successful result was produced
+3. Stock results were produced, but writing to `reports/` failed (for example due to permissions or mount issues)
+
+**Current behavior**:
+1. CLI-triggered analysis now logs the exact failure reason for these cases
+2. Standalone non-`--serve` runs now return a non-zero exit code so workflows do not treat “no report generated” as success
+3. In single-stock push mode, local Markdown report saving still happens even when notifications are not configured
+
 ### Q9: Not receiving Telegram push messages?
 
 **Solution**:

main.py

@@ -81,6 +81,7 @@
 logger = logging.getLogger(__name__)
 _RUNTIME_ENV_FILE_KEYS = set()
 _PUBLIC_BIND_HOSTS = frozenset({"0.0.0.0", "::", "[::]", "*"})
+_LAST_ANALYSIS_FAILURE_REASON: Optional[str] = None
 
 
 def _get_active_env_path() -> Path:
@@ -750,6 +751,13 @@ def run_full_analysis(
     from src.core.market_review import run_market_review
     from src.core.pipeline import StockAnalysisPipeline
 
+    global _LAST_ANALYSIS_FAILURE_REASON
+    _LAST_ANALYSIS_FAILURE_REASON = None
+
+    def _return_with_auto_backtest(result: bool) -> bool:
+        _run_auto_backtest(config)
+        return result
+
     try:
         _refresh_stock_index_cache_for_analysis(config)
         if portfolio_stock_codes is not None:
@@ -759,8 +767,23 @@ def run_full_analysis(
         if stock_codes is None and portfolio_stock_codes is None:
             config.refresh_stock_list()
 
-        # Issue #373: Trading day filter (per-stock, per-market)
+        using_config_stock_list = stock_codes is None and portfolio_stock_codes is None
         effective_codes = stock_codes if stock_codes is not None else config.stock_list
+        # Fail fast on an empty persisted watchlist before trading-day filtering.
+        # Otherwise should_skip=True would mask the configuration error as success.
+        if (
+            not getattr(args, "dry_run", False)
+            and using_config_stock_list
+            and not effective_codes
+            and not market_review_requested
+        ):
+            _LAST_ANALYSIS_FAILURE_REASON = "empty_stock_list"
+            logger.error(
+                "本轮分析未生成报告：STOCK_LIST 为空，且未启用大盘复盘。"
+            )
+            return _return_with_auto_backtest(False)
+
+        # Issue #373: Trading day filter (per-stock, per-market)
         filtered_codes, effective_region, should_skip = _compute_trading_day_filter(
             config, args, effective_codes
         )
@@ -811,6 +834,17 @@ def run_full_analysis(
             and not args.no_market_review
             and (market_review_region or '') != ''
         )
+        if (
+            not getattr(args, "dry_run", False)
+            and not stock_codes
+            and using_config_stock_list
+            and not should_run_market_review
+        ):
+            _LAST_ANALYSIS_FAILURE_REASON = "empty_stock_list"
+            logger.error(
+                "本轮分析未生成报告：STOCK_LIST 为空，且未启用大盘复盘。"
+            )
+            return _return_with_auto_backtest(False)
         should_use_daily_market_context = (
             should_run_market_review
             and getattr(config, 'daily_market_context_enabled', True)
@@ -990,6 +1024,33 @@ def run_full_analysis(
             elif can_reuse_market_context:
                 market_report = market_context_full_report or market_context_summary
 
+        expected_stock_report = (
+            not getattr(args, "dry_run", False)
+            and bool(stock_codes)
+            and not skip_futu_stock_analysis
+        )
+        deferred_failure_result = None
+        if expected_stock_report and results and not getattr(
+            pipeline, "_last_local_report_path", None
+        ):
+            _LAST_ANALYSIS_FAILURE_REASON = "report_save_failed"
+            save_error = getattr(pipeline, "_last_local_report_error", None) or "unknown error"
+            logger.error(
+                "本轮分析已生成个股结果，但汇总报告保存失败，未生成本地报告文件: %s",
+                save_error,
+            )
+            deferred_failure_result = False
+        expected_market_report = (
+            not getattr(args, "dry_run", False)
+            and should_run_market_review
+        )
+        if (expected_stock_report or expected_market_report) and not results and not market_report:
+            _LAST_ANALYSIS_FAILURE_REASON = "no_report"
+            logger.error(
+                "本轮分析未生成任何报告：预期的个股分析或大盘复盘均未产出结果。"
+            )
+            return _return_with_auto_backtest(False)
+
         # Issue #190: 合并推送（个股+大盘复盘）
         if merge_notification and (results or market_report) and not args.no_notify:
             parts = []
@@ -1063,12 +1124,15 @@ def run_full_analysis(
         except Exception as e:
             logger.error(f"飞书文档生成失败: {e}")
 
-        # === Auto backtest ===
-        _run_auto_backtest(config)
-
-        return True
+        return _return_with_auto_backtest(
+            deferred_failure_result
+            if deferred_failure_result is not None
+            else True
+        )
 
     except Exception as e:
+        if _LAST_ANALYSIS_FAILURE_REASON is None:
+            _LAST_ANALYSIS_FAILURE_REASON = "runtime_error"
         logger.exception(f"分析流程执行失败: {e}")
         if raise_errors:
             raise
@@ -1088,19 +1152,31 @@ def _run_analysis_with_runtime_scheduler_lock(
     config: Config,
     args: argparse.Namespace,
     stock_codes: Optional[List[str]] = None,
-) -> None:
+) -> bool:
     from src.services.runtime_scheduler import run_with_global_analysis_lock
 
+    task_result: Dict[str, bool] = {"ok": True}
+
+    def _locked_task_runner(
+        locked_config: Config,
+        locked_args: argparse.Namespace,
+        locked_stock_codes: Optional[List[str]] = None,
+    ) -> bool:
+        result = run_full_analysis(locked_config, locked_args, locked_stock_codes)
+        task_result["ok"] = bool(result)
+        return task_result["ok"]
+
     # Keep startup/triggered analysis in sync with API runtime scheduler and
     # run-now entrypoint. Blocking is expected here because startup paths should
     # wait for an in-flight job before returning a response.
-    run_with_global_analysis_lock(
-        task_runner=run_full_analysis,
+    lock_acquired = run_with_global_analysis_lock(
+        task_runner=_locked_task_runner,
         config=config,
         args=args,
         stock_codes=stock_codes,
         blocking=True,
     )
+    return bool(lock_acquired and task_result["ok"])
 
 
 def start_api_server(host: str, port: int, config: Config) -> None:
@@ -1509,7 +1585,7 @@ def main() -> int:
             logger.info("模式: 仅大盘复盘")
             notifier, analyzer, search_service = build_market_review_runtime(config)
 
-            _run_market_review_with_shared_lock(
+            market_review_result = _run_market_review_with_shared_lock(
                 config,
                 run_market_review,
                 notifier=notifier,
@@ -1519,7 +1595,7 @@ def main() -> int:
                 override_region=effective_region,
                 trigger_source="cli",
             )
-            return 0
+            return 0 if market_review_result else 1
 
         # 模式2: 定时任务模式
         if args.schedule or config.schedule_enabled:
@@ -1554,7 +1630,12 @@ def main() -> int:
 
             def scheduled_task():
                 runtime_config = _reload_runtime_config()
-                run_full_analysis(runtime_config, args, scheduled_stock_codes)
+                result = run_full_analysis(runtime_config, args, scheduled_stock_codes)
+                if result is False:
+                    reason = _LAST_ANALYSIS_FAILURE_REASON or "unknown"
+                    raise RuntimeError(
+                        f"scheduled analysis reported failure: {reason}"
+                    )
 
             background_tasks = []
             if getattr(config, 'agent_event_monitor_enabled', False):
@@ -1592,14 +1673,24 @@ def event_monitor_task():
         # 模式3: 正常单次运行
         if config.run_immediately:
             try:
-                _run_analysis_with_runtime_scheduler_lock(config, args, stock_codes)
+                analysis_ok = _run_analysis_with_runtime_scheduler_lock(config, args, stock_codes)
             except FutuPortfolioError as exc:
                 if not start_serve:
                     raise
                 logger.exception(
                     "Futu 持仓导入失败，Web/API 服务继续运行: %s",
                     exc,
                 )
+            else:
+                if analysis_ok is False:
+                    if start_serve:
+                        logger.error("启动时分析执行失败，Web/API 服务继续运行。")
+                    elif _LAST_ANALYSIS_FAILURE_REASON in {
+                        "no_report",
+                        "empty_stock_list",
+                        "report_save_failed",
+                    }:
+                        return 1
         else:
             logger.info("配置为不立即运行分析 (RUN_IMMEDIATELY=false)")