qlib/frontend/web/app/page.tsx

"use client";

import { useEffect, useState } from "react";
import Link from "next/link";
import { apiGet } from "@/lib/api";
import type { Stock, FactorMeta } from "@/lib/types";
import { PageHeader, Card, Metric, Banner, Loading } from "@/components/ui";
import { Icon as Ic } from "@/components/icons";

interface LoadState {
  stocks: number | null;
  factors: number | null;
  loading: boolean;
  error: string;
}

/**
 * 快速入口按**研究闭环的真实顺序**排列：
 * 出候选（筛选）→ 定规则（策略库）→ 验规则（回测）→ 复盘（实验对比）。
 * 顺序即引导：新用户按从左到右走一遍就是完整流程。
 *
 * ④ 之后是**归档回看**：每次回测（含同步接口调用）都会自动写一份完整归档，
 * 入口在实验列表的「打开归档」、以及回测跑完后的提示条里；归档页是只读快照，
 * 明确写出这次的**选股条件**与**交易执行依据**。
 */
const LINKS = [
  {
    href: "/selection",
    title: "① 股票筛选",
    desc: "因子评分 TopN 或条件选股，支持当前/历史时点，结果可解释、可查历史",
    icon: "target" as const,
    tone: "quick-card--violet",
  },
  {
    href: "/strategies",
    title: "② 策略库",
    desc: "把选股规则存成命名策略：一句话说明 + 计算公式，可一键回测、可复用对比",
    icon: "book" as const,
    tone: "quick-card--pos",
  },
  {
    href: "/backtest",
    title: "③ 选股回测",
    desc: "两级截断（候选池 n → 持仓 x）+ 择股/调仓双周期（m/y），买卖点标注在曲线上",
    icon: "gauge" as const,
    tone: "quick-card--warn",
  },
  {
    href: "/experiments",
    title: "④ 实验对比与归档",
    desc: "勾选 2~3 次回测做对比；每次回测都已完整存档，点「打开归档」可随时回看选股条件与交易执行依据",
    icon: "archive" as const,
    tone: "quick-card--violet",
  },
  {
    href: "/factors",
    title: "因子研究",
    desc: "查看行情因子目录，勾选运行 IC / RankIC 单因子测试",
    icon: "flask" as const,
    tone: "quick-card--violet",
  },
  {
    href: "/factors/compose",
    title: "因子组合",
    desc: "多因子 z-score 叠加打分，回测 Top N 等权选股组合",
    icon: "layers" as const,
    tone: "quick-card--pos",
  },
  {
    href: "/signals",
    title: "交易信号",
    desc: "按评分排名 + 趋势规则输出 BUY / WATCH / SELL 及理由",
    icon: "scale" as const,
    tone: "quick-card--pos",
  },
  {
    href: "/stocks",
    title: "股票池",
    desc: "浏览本地股票基础信息（Tushare 同步，全市场 5556 只）",
    icon: "candles" as const,
    tone: "",
  },
];

export default function DashboardPage() {
  const [st, setSt] = useState<LoadState>({
    stocks: null,
    factors: null,
    loading: true,
    error: "",
  });

  useEffect(() => {
    let alive = true;
    Promise.all([apiGet<Stock[]>("/stocks?limit=500"), apiGet<FactorMeta[]>("/factors")])
      .then(([stocks, factors]) => {
        if (!alive) return;
        setSt({
          stocks: stocks.length,
          factors: factors.length,
          loading: false,
          error: "",
        });
      })
      .catch((e: Error) => {
        if (!alive) return;
        setSt({ stocks: null, factors: null, loading: false, error: e.message });
      });
    return () => {
      alive = false;
    };
  }, []);

  return (
    <>
      <PageHeader
        title="研究总览"
        sub="个人 A 股量化研究平台：以 Tushare 行情为数据底座、Qlib 为研究引擎，覆盖选股、因子研究、组合回测与实验归档。"
      />

      {st.error ? (
        <Banner tone="error">
          后端不可达：{st.error}。请确认 FastAPI 服务已启动（scripts/dev.sh start）。
        </Banner>
      ) : null}

      {st.loading ? (
        <div className="metric-grid">
          <div className="metric">
            <Loading label="正在读取股票池…" />
          </div>
        </div>
      ) : (
        <div className="metric-grid">
          <Metric
            label="股票池"
            icon="candles"
            value={st.stocks?.toLocaleString() ?? "—"}
            sub="已建档基础信息"
          />
          <Metric
            label="内置因子"
            icon="flask"
            value={st.factors?.toLocaleString() ?? "—"}
            sub="行情因子 · 无未来函数"
          />
        </div>
      )}

      <Card title="快速开始" icon="spark" sub="按 ①→④ 走一遍即是完整闭环：出候选 → 定规则 → 验规则 → 复盘微调" flush={false}>
        <div className="quick-cards" style={{ marginBottom: 0 }}>
          {LINKS.map((l) => (
            <Link key={l.href} href={l.href} className={`quick-card ${l.tone}`}>
              <span className="quick-ic">
                <Ic name={l.icon} size={19} />
              </span>
              <span>
                <h3>{l.title}</h3>
                <p>{l.desc}</p>
                <span className="go">
                  进入 <Ic name="arrowUpRight" size={13} />
                </span>
              </span>
            </Link>
          ))}
        </div>
      </Card>

      <Card title="研究须知" icon="book">
        <ul className="steplist">
          <li>
            因子/回测请求经 <b>异步 Job</b> 后台执行并自动归档为实验（Experiment），可在「实验」页查看与复跑。
          </li>
          <li>
            数据底座为<b>MySQL + Parquet</b>：行情经 <code>sync daily --resume</code> 增量同步；
            新浪数据仅在「两边一致」校验通过后兜底入库（<code>source=sina</code>）。
          </li>
          <li>
            研究默认<b>禁止未来函数</b>：财务按公告日可见、因子按已披露数据计算；回测含手续费 / 印花税 / 涨跌停等近似约束（如实标注）。
          </li>
        </ul>
      </Card>
    </>
  );
}