feat: add web market review trigger

Author: ZhuLinsen

api/v1/endpoints/analysis.py

@@ -20,10 +20,11 @@
 import json
 import logging
 import re
+import threading
 from datetime import datetime
 from typing import Optional, Union, Dict, Any
 
-from fastapi import APIRouter, HTTPException, Depends, Query
+from fastapi import APIRouter, HTTPException, Depends, Query, BackgroundTasks
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from api.deps import get_config_dep
@@ -38,6 +39,8 @@
     TaskInfo,
     TaskListResponse,
     DuplicateTaskErrorResponse,
+    MarketReviewRequest,
+    MarketReviewAccepted,
 )
 from api.v1.schemas.common import ErrorResponse
 from api.v1.schemas.history import (
@@ -69,6 +72,24 @@
 router = APIRouter()
 
 _SUPPORTED_FREE_TEXT_RE = re.compile(r"^[A-Za-z0-9.*\-+\u3400-\u9fff\s]+$")
+_market_review_lock = threading.Lock()
+_market_review_running = False
+
+
+def _run_market_review_background(send_notification: bool) -> None:
+    """Run market review after the API response has been accepted."""
+    global _market_review_running
+    try:
+        from src.core.market_review import run_market_review
+        from src.notification import NotificationService
+
+        notifier = NotificationService()
+        run_market_review(notifier, send_notification=send_notification)
+    except Exception as exc:
+        logger.error("大盘复盘后台任务失败: %s", exc, exc_info=True)
+    finally:
+        with _market_review_lock:
+            _market_review_running = False
 
 
 def _invalid_analysis_input_error() -> HTTPException:
@@ -392,6 +413,47 @@ def _handle_sync_analysis(
         )
 
 
+# ============================================================
+# POST /market-review - 触发大盘复盘
+# ============================================================
+
+@router.post(
+    "/market-review",
+    response_model=MarketReviewAccepted,
+    status_code=202,
+    responses={
+        202: {"description": "大盘复盘任务已接受", "model": MarketReviewAccepted},
+        409: {"description": "大盘复盘正在执行", "model": ErrorResponse},
+        500: {"description": "提交失败", "model": ErrorResponse},
+    },
+    summary="触发大盘复盘",
+    description="提交一个后台大盘复盘任务，复用 CLI 的大盘复盘链路并保存报告。",
+)
+def trigger_market_review(
+    request: MarketReviewRequest,
+    background_tasks: BackgroundTasks,
+) -> MarketReviewAccepted:
+    """Trigger market review from Web/API without blocking the request."""
+    global _market_review_running
+    with _market_review_lock:
+        if _market_review_running:
+            raise HTTPException(
+                status_code=409,
+                detail={
+                    "error": "duplicate_market_review",
+                    "message": "大盘复盘正在执行中，请稍后再试",
+                },
+            )
+        _market_review_running = True
+
+    background_tasks.add_task(_run_market_review_background, request.send_notification)
+    return MarketReviewAccepted(
+        status="accepted",
+        message="大盘复盘任务已提交，完成后会保存报告并按配置推送通知",
+        send_notification=request.send_notification,
+    )
+
+
 # ============================================================
 # GET /tasks - 获取任务列表
 # ============================================================

api/v1/schemas/analysis.py

@@ -87,6 +87,23 @@ class Config:
         }
 
 
+class MarketReviewRequest(BaseModel):
+    """Market review trigger parameters."""
+
+    send_notification: bool = Field(
+        True,
+        description="是否在大盘复盘完成后发送推送通知",
+    )
+
+
+class MarketReviewAccepted(BaseModel):
+    """Market review background task accepted response."""
+
+    status: str = Field("accepted", description="提交状态")
+    message: str = Field(..., description="提示信息")
+    send_notification: bool = Field(..., description="是否发送通知")
+
+
 class AnalysisResultResponse(BaseModel):
     """分析结果响应模型"""
 

apps/dsa-web/src/api/analysis.ts

@@ -6,6 +6,8 @@ import type {
   AnalyzeResponse,
   AnalyzeAsyncResponse,
   AnalysisReport,
+  MarketReviewAccepted,
+  MarketReviewRequest,
   TaskStatus,
   TaskListResponse,
 } from '../types/analysis';
@@ -87,6 +89,31 @@ export const analysisApi = {
     return toCamelCase<AnalyzeAsyncResponse>(response.data);
   },
 
+  /**
+   * Trigger market review in background mode.
+   */
+  triggerMarketReview: async (data: MarketReviewRequest = {}): Promise<MarketReviewAccepted> => {
+    const response = await apiClient.post<Record<string, unknown>>(
+      '/api/v1/analysis/market-review',
+      {
+        send_notification: data.sendNotification ?? true,
+      },
+      {
+        validateStatus: (status) => status === 202 || status === 409,
+      }
+    );
+
+    if (response.status === 409) {
+      const detail = response.data?.detail;
+      const message = detail && typeof detail === 'object' && 'message' in detail
+        ? String((detail as { message?: unknown }).message || '')
+        : String(response.data?.message || '');
+      throw new Error(message || '大盘复盘正在执行中，请稍后再试');
+    }
+
+    return toCamelCase<MarketReviewAccepted>(response.data);
+  },
+
   /**
    * Get async task status.
    * @param taskId Task ID

apps/dsa-web/src/pages/HomePage.tsx

@@ -1,6 +1,8 @@
 import type React from 'react';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
+import { getParsedApiError, type ParsedApiError } from '../api/error';
+import { analysisApi } from '../api/analysis';
 import { ApiErrorAlert, ConfirmDialog, Button, EmptyState, InlineAlert } from '../components/common';
 import { DashboardStateBlock } from '../components/dashboard';
 import { StockAutocomplete } from '../components/StockAutocomplete';
@@ -10,10 +12,19 @@ import { TaskPanel } from '../components/tasks';
 import { useDashboardLifecycle, useHomeDashboardState } from '../hooks';
 import { getReportText, normalizeReportLanguage } from '../utils/reportLanguage';
 
+type MarketReviewNotice = {
+  variant: 'success' | 'warning' | 'danger';
+  title: string;
+  message: string;
+} | null;
+
 const HomePage: React.FC = () => {
   const navigate = useNavigate();
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
+  const [isSubmittingMarketReview, setIsSubmittingMarketReview] = useState(false);
+  const [marketReviewNotice, setMarketReviewNotice] = useState<MarketReviewNotice>(null);
+  const [marketReviewError, setMarketReviewError] = useState<ParsedApiError | null>(null);
 
   const {
     query,
@@ -113,6 +124,25 @@ const HomePage: React.FC = () => {
     });
   }, [selectedReport, submitAnalysis]);
 
+  const handleTriggerMarketReview = useCallback(async () => {
+    setIsSubmittingMarketReview(true);
+    setMarketReviewNotice(null);
+    setMarketReviewError(null);
+    try {
+      const result = await analysisApi.triggerMarketReview({ sendNotification: notify });
+      setMarketReviewNotice({
+        variant: 'success',
+        title: '大盘复盘已提交',
+        message: result.message,
+      });
+    } catch (err: unknown) {
+      setMarketReviewError(getParsedApiError(err));
+      setMarketReviewNotice(null);
+    } finally {
+      setIsSubmittingMarketReview(false);
+    }
+  }, [notify]);
+
   const handleDeleteSelectedHistory = useCallback(() => {
     void deleteSelectedHistory();
     setShowDeleteConfirm(false);
@@ -193,6 +223,17 @@ const HomePage: React.FC = () => {
               />
               推送通知
             </label>
+            <Button
+              type="button"
+              variant="home-action-report"
+              size="md"
+              isLoading={isSubmittingMarketReview}
+              loadingText="提交中"
+              onClick={() => void handleTriggerMarketReview()}
+              className="h-10 flex-shrink-0 whitespace-nowrap"
+            >
+              大盘复盘
+            </Button>
             <button
               type="button"
               onClick={() => handleSubmitAnalysis()}
@@ -235,6 +276,27 @@ const HomePage: React.FC = () => {
           </div>
         ) : null}
 
+        {marketReviewNotice ? (
+          <div className="px-3 pb-2 md:px-4">
+            <InlineAlert
+              variant={marketReviewNotice.variant}
+              title={marketReviewNotice.title}
+              message={marketReviewNotice.message}
+              className="rounded-xl px-3 py-2 text-xs shadow-none"
+            />
+          </div>
+        ) : null}
+
+        {marketReviewError ? (
+          <div className="px-3 pb-2 md:px-4">
+            <ApiErrorAlert
+              error={marketReviewError}
+              className="mb-1"
+              onDismiss={() => setMarketReviewError(null)}
+            />
+          </div>
+        ) : null}
+
         <div className="flex-1 flex min-h-0 overflow-hidden">
           <div className="hidden min-h-0 w-64 shrink-0 flex-col overflow-hidden pl-4 pb-4 md:flex lg:w-72">
             {sidebarContent}

apps/dsa-web/src/pages/__tests__/HomePage.test.tsx

@@ -33,6 +33,7 @@ vi.mock('../../api/analysis', async () => {
     ...actual,
     analysisApi: {
       analyzeAsync: vi.fn(),
+      triggerMarketReview: vi.fn(),
     },
   };
 });
@@ -157,6 +158,33 @@ describe('HomePage', () => {
     expect(screen.getByText(/股票 600519 正在分析中/).closest('[role="alert"]')).toBeInTheDocument();
   });
 
+  it('submits market review from the home toolbar', async () => {
+    vi.mocked(historyApi.getList).mockResolvedValue({
+      total: 0,
+      page: 1,
+      limit: 20,
+      items: [],
+    });
+    vi.mocked(analysisApi.triggerMarketReview).mockResolvedValue({
+      status: 'accepted',
+      sendNotification: true,
+      message: '大盘复盘任务已提交',
+    });
+
+    render(
+      <MemoryRouter>
+        <HomePage />
+      </MemoryRouter>,
+    );
+
+    fireEvent.click(await screen.findByRole('button', { name: '大盘复盘' }));
+
+    await waitFor(() => {
+      expect(analysisApi.triggerMarketReview).toHaveBeenCalledWith({ sendNotification: true });
+    });
+    expect(await screen.findByText('大盘复盘已提交')).toBeInTheDocument();
+  });
+
   it('navigates to chat with report context when asking a follow-up question', async () => {
     vi.mocked(historyApi.getList).mockResolvedValue({
       total: 1,

apps/dsa-web/src/types/analysis.ts

@@ -17,6 +17,16 @@ export interface AnalysisRequest {
   notify?: boolean;
 }
 
+export interface MarketReviewRequest {
+  sendNotification?: boolean;
+}
+
+export interface MarketReviewAccepted {
+  status: 'accepted';
+  message: string;
+  sendNotification: boolean;
+}
+
 // ============ Report Types ============
 
 export type ReportLanguage = 'zh' | 'en';

docs/CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [测试] 补充设置项帮助元数据、API schema、前端弹窗交互测试，并修复 Bot 名称路由与调度时间 provider 测试的离线 CI 稳定性问题。
 - [修复] 港股日线跳过不支持港股的内置历史数据源，避免港股代码错配到非港股市场数据。
 - [修复] 修正分析 API 对北交所 `BJ` 前缀与 `.BJ` 后缀股票代码的校验，保持前端自动补全与 Tushare `ts_code` 调用格式一致。
+- [新功能] Web 首页新增“大盘复盘”按钮，通过 `POST /api/v1/analysis/market-review` 后台触发复盘并沿用通知配置。
 
 ## [3.15.0] - 2026-05-05
 

docs/full-guide.md

@@ -1076,7 +1076,7 @@ FastAPI 提供 RESTful API 服务，支持配置管理和触发分析。
 ### 功能特性
 
 - 📝 **配置管理** - 查看/修改自选股列表
-- 🚀 **快速分析** - 通过 API 接口触发分析
+- 🚀 **快速分析** - 通过 API 接口触发个股分析；首页也提供“大盘复盘”按钮，可在 Docker/server 模式下后台触发大盘复盘
 - 📊 **实时进度** - 分析任务状态实时更新，支持多任务并行；普通分析链路在进入 LLM 阶段后会优先尝试 LiteLLM 流式生成，并通过任务 SSE 回灌更细粒度的 `message/progress`
 - 📈 **回测验证** - 评估历史分析准确率，查询方向胜率与模拟收益
 - 🔗 **API 文档** - 访问 `/docs` 查看 Swagger UI
@@ -1086,6 +1086,7 @@ FastAPI 提供 RESTful API 服务，支持配置管理和触发分析。
 | 接口 | 方法 | 说明 |
 |------|------|------|
 | `/api/v1/analysis/analyze` | POST | 触发股票分析 |
+| `/api/v1/analysis/market-review` | POST | 后台触发大盘复盘；请求体可传 `{"send_notification": true}` |
 | `/api/v1/analysis/tasks` | GET | 查询任务列表 |
 | `/api/v1/analysis/tasks/stream` | GET (SSE) | 订阅任务实时状态流 |
 | `/api/v1/analysis/status/{task_id}` | GET | 查询任务状态 |

docs/full-guide_EN.md

@@ -922,7 +922,7 @@ FastAPI provides RESTful API service for configuration management and triggering
 ### Features
 
 - **Configuration Management** - View/modify watchlist
-- **Quick Analysis** - Trigger analysis via API
+- **Quick Analysis** - Trigger stock analysis via API; the Home page also provides a Market Review button that starts a background market recap in Docker/server mode
 - **Real-time Progress** - Analysis task status updates in real-time, supports parallel tasks; the regular stock-analysis path now prefers LiteLLM streaming during the LLM stage and pushes finer-grained `message/progress` updates through task SSE
 - **Backtest Validation** - Evaluate historical analysis accuracy, query direction win rate and simulated returns
 - **API Documentation** - Visit `/docs` for Swagger UI
@@ -932,6 +932,7 @@ FastAPI provides RESTful API service for configuration management and triggering
 | Endpoint | Method | Description |
 |------|------|------|
 | `/api/v1/analysis/analyze` | POST | Trigger stock analysis |
+| `/api/v1/analysis/market-review` | POST | Trigger a background market review; request body may pass `{"send_notification": true}` |
 | `/api/v1/analysis/tasks` | GET | Query task list |
 | `/api/v1/analysis/tasks/stream` | GET (SSE) | Subscribe to realtime task updates |
 | `/api/v1/analysis/status/{task_id}` | GET | Query task status |