feat: show home setup status hint

Author: ZhuLinsen

apps/dsa-web/src/api/__tests__/systemConfig.test.ts

@@ -1,18 +1,20 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { systemConfigApi } from '../systemConfig';
 
+const get = vi.hoisted(() => vi.fn());
 const post = vi.hoisted(() => vi.fn());
 
 vi.mock('../index', () => ({
   default: {
-    get: vi.fn(),
+    get,
     post,
     put: vi.fn(),
   },
 }));
 
 describe('systemConfigApi', () => {
   beforeEach(() => {
+    get.mockReset();
     post.mockReset();
     post.mockResolvedValue({
       data: {
@@ -111,4 +113,33 @@ describe('systemConfigApi', () => {
     expect(result.attempts[0].errorCode).toBeNull();
     expect(result.attempts[0].httpStatus).toBe(200);
   });
+
+  it('loads first-run setup status with camelCase fields', async () => {
+    get.mockResolvedValueOnce({
+      data: {
+        is_complete: false,
+        ready_for_smoke: false,
+        required_missing_keys: ['llm_primary'],
+        next_step_key: 'llm_primary',
+        checks: [
+          {
+            key: 'llm_primary',
+            title: 'LLM 主渠道',
+            category: 'ai_model',
+            required: true,
+            status: 'needs_action',
+            message: '缺少主模型配置',
+            next_step: '打开系统设置',
+          },
+        ],
+      },
+    });
+
+    const result = await systemConfigApi.getSetupStatus();
+
+    expect(get).toHaveBeenCalledWith('/api/v1/system/config/setup/status');
+    expect(result.isComplete).toBe(false);
+    expect(result.nextStepKey).toBe('llm_primary');
+    expect(result.checks[0].nextStep).toBe('打开系统设置');
+  });
 });

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

@@ -6,6 +6,7 @@ import type {
   DiscoverLLMChannelModelsResponse,
   ExportSystemConfigResponse,
   ImportSystemConfigRequest,
+  SetupStatusResponse,
   SystemConfigConflictResponse,
   SystemConfigResponse,
   SystemConfigSchemaResponse,
@@ -144,6 +145,11 @@ export const systemConfigApi = {
     return toCamelCase<SystemConfigSchemaResponse>(response.data);
   },
 
+  async getSetupStatus(): Promise<SetupStatusResponse> {
+    const response = await apiClient.get<Record<string, unknown>>('/api/v1/system/config/setup/status');
+    return toCamelCase<SetupStatusResponse>(response.data);
+  },
+
   async validate(payload: ValidateSystemConfigRequest): Promise<ValidateSystemConfigResponse> {
     const response = await apiClient.post<Record<string, unknown>>(
       '/api/v1/system/config/validate',

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

@@ -1,19 +1,22 @@
 import type React from 'react';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
+import { systemConfigApi } from '../api/systemConfig';
 import { ApiErrorAlert, ConfirmDialog, Button, EmptyState, InlineAlert } from '../components/common';
 import { DashboardStateBlock } from '../components/dashboard';
 import { StockAutocomplete } from '../components/StockAutocomplete';
 import { HistoryList } from '../components/history';
 import { ReportMarkdown, ReportSummary } from '../components/report';
 import { TaskPanel } from '../components/tasks';
 import { useDashboardLifecycle, useHomeDashboardState } from '../hooks';
+import type { SetupStatusResponse } from '../types/systemConfig';
 import { getReportText, normalizeReportLanguage } from '../utils/reportLanguage';
 
 const HomePage: React.FC = () => {
   const navigate = useNavigate();
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
+  const [setupStatus, setSetupStatus] = useState<SetupStatusResponse | null>(null);
 
   const {
     query,
@@ -55,8 +58,38 @@ const HomePage: React.FC = () => {
   useEffect(() => {
     document.title = '每日选股分析 - DSA';
   }, []);
+
+  useEffect(() => {
+    let active = true;
+    systemConfigApi.getSetupStatus()
+      .then((status) => {
+        if (active) {
+          setSetupStatus(status);
+        }
+      })
+      .catch(() => {
+        if (active) {
+          setSetupStatus(null);
+        }
+      });
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
   const reportLanguage = normalizeReportLanguage(selectedReport?.meta.reportLanguage);
   const reportText = getReportText(reportLanguage);
+  const setupNeedsAction = setupStatus ? !setupStatus.isComplete : false;
+  const setupMissingLabels = useMemo(() => {
+    if (!setupStatus) {
+      return '';
+    }
+    const requiredNeedsAction = setupStatus.checks
+      .filter((check) => check.required && check.status === 'needs_action')
+      .map((check) => check.title);
+    return requiredNeedsAction.slice(0, 3).join('、');
+  }, [setupStatus]);
 
   useDashboardLifecycle({
     loadInitialHistory,
@@ -235,6 +268,31 @@ const HomePage: React.FC = () => {
           </div>
         ) : null}
 
+        {setupNeedsAction ? (
+          <div className="px-3 pb-2 md:px-4">
+            <InlineAlert
+              variant="warning"
+              title="基础配置未完成"
+              message={
+                setupMissingLabels
+                  ? `还缺少 ${setupMissingLabels}，完成后即可开始最小可用分析。`
+                  : '还缺少基础配置，完成后即可开始最小可用分析。'
+              }
+              action={(
+                <Button
+                  type="button"
+                  variant="secondary"
+                  size="sm"
+                  onClick={() => navigate('/settings')}
+                >
+                  去配置
+                </Button>
+              )}
+              className="rounded-xl px-3 py-2 text-xs shadow-none"
+            />
+          </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

@@ -3,6 +3,7 @@ import { MemoryRouter } from 'react-router-dom';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { analysisApi, DuplicateTaskError } from '../../api/analysis';
 import { historyApi } from '../../api/history';
+import { systemConfigApi } from '../../api/systemConfig';
 import { useStockPoolStore } from '../../stores';
 import { getReportText, normalizeReportLanguage } from '../../utils/reportLanguage';
 import HomePage from '../HomePage';
@@ -37,6 +38,12 @@ vi.mock('../../api/analysis', async () => {
   };
 });
 
+vi.mock('../../api/systemConfig', () => ({
+  systemConfigApi: {
+    getSetupStatus: vi.fn(),
+  },
+}));
+
 vi.mock('../../hooks/useTaskStream', () => ({
   useTaskStream: vi.fn(),
 }));
@@ -74,6 +81,13 @@ describe('HomePage', () => {
     vi.clearAllMocks();
     navigateMock.mockReset();
     useStockPoolStore.getState().resetDashboardState();
+    vi.mocked(systemConfigApi.getSetupStatus).mockResolvedValue({
+      isComplete: true,
+      readyForSmoke: true,
+      requiredMissingKeys: [],
+      nextStepKey: null,
+      checks: [],
+    });
   });
 
   it('renders the dashboard workspace and auto-loads the first report', async () => {
@@ -157,6 +171,50 @@ describe('HomePage', () => {
     expect(screen.getByText(/股票 600519 正在分析中/).closest('[role="alert"]')).toBeInTheDocument();
   });
 
+  it('shows first-run setup gaps and links to settings', async () => {
+    vi.mocked(historyApi.getList).mockResolvedValue({
+      total: 0,
+      page: 1,
+      limit: 20,
+      items: [],
+    });
+    vi.mocked(systemConfigApi.getSetupStatus).mockResolvedValue({
+      isComplete: false,
+      readyForSmoke: false,
+      requiredMissingKeys: ['llm_primary', 'stock_list'],
+      nextStepKey: 'llm_primary',
+      checks: [
+        {
+          key: 'llm_primary',
+          title: 'LLM 主渠道',
+          category: 'ai_model',
+          required: true,
+          status: 'needs_action',
+          message: '缺少主模型配置',
+        },
+        {
+          key: 'stock_list',
+          title: '自选股',
+          category: 'base',
+          required: true,
+          status: 'needs_action',
+          message: '缺少自选股',
+        },
+      ],
+    });
+
+    render(
+      <MemoryRouter>
+        <HomePage />
+      </MemoryRouter>,
+    );
+
+    expect(await screen.findByText('基础配置未完成')).toBeInTheDocument();
+    expect(screen.getByText(/LLM 主渠道、自选股/)).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: '去配置' }));
+    expect(navigateMock).toHaveBeenCalledWith('/settings');
+  });
+
   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/systemConfig.ts

@@ -84,6 +84,24 @@ export interface SystemConfigResponse {
   updatedAt?: string;
 }
 
+export interface SetupStatusCheck {
+  key: string;
+  title: string;
+  category: 'base' | 'ai_model' | 'agent' | 'notification' | 'system';
+  required: boolean;
+  status: 'configured' | 'inherited' | 'optional' | 'needs_action';
+  message: string;
+  nextStep?: string | null;
+}
+
+export interface SetupStatusResponse {
+  isComplete: boolean;
+  readyForSmoke: boolean;
+  requiredMissingKeys: string[];
+  nextStepKey?: string | null;
+  checks: SetupStatusCheck[];
+}
+
 export interface ExportSystemConfigResponse {
   content: string;
   configVersion: string;

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 首页接入首次启动配置状态，基础配置未完成时提示缺口并引导进入系统设置。
 
 ## [3.15.0] - 2026-05-05
 

docs/full-guide.md

@@ -1077,6 +1077,7 @@ FastAPI 提供 RESTful API 服务，支持配置管理和触发分析。
 
 - 📝 **配置管理** - 查看/修改自选股列表
 - 🚀 **快速分析** - 通过 API 接口触发分析
+- 🧭 **首次配置提示** - 首页会读取只读配置状态，缺少 LLM 主渠道、自选股等基础项时提示缺口并引导进入系统设置
 - 📊 **实时进度** - 分析任务状态实时更新，支持多任务并行；普通分析链路在进入 LLM 阶段后会优先尝试 LiteLLM 流式生成，并通过任务 SSE 回灌更细粒度的 `message/progress`
 - 📈 **回测验证** - 评估历史分析准确率，查询方向胜率与模拟收益
 - 🔗 **API 文档** - 访问 `/docs` 查看 Swagger UI

docs/full-guide_EN.md

@@ -923,6 +923,7 @@ FastAPI provides RESTful API service for configuration management and triggering
 
 - **Configuration Management** - View/modify watchlist
 - **Quick Analysis** - Trigger analysis via API
+- **First-run Setup Hint** - The Home page reads the read-only setup status and points users to Settings when required items such as the primary LLM channel or watchlist are missing
 - **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