舊專案翻新實戰：React Legacy 專案的漸進式重構策略

npm install --save-dev typescript @types/react @types/react-dom

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ES2020"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "allowJs": true,
    "checkJs": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src"]
}

{
  "allowJs": true,
  "checkJs": false
}

export type StockDividendApiResponse = {
  cash_dividend: number | string | null;
  dividend_yield: number | string | null;
  release_date: string | null;
};

export async function fetchStockDividend(
  stockCode: string
): Promise<unknown> {
  const response = await fetch(`/api/stocks/${stockCode}/dividend`);

  if (!response.ok) {
    throw new Error("取得股利資料失敗");
  }

  return response.json();
}

return response.json() as Promise<StockDividendApiResponse>;

type LegacyChartProps = {
  stockCode: string;
  rows: StockDividendRow[];
  onReload?: () => void;
};

type LegacyChartState = {
  selectedYear: number | null;
  isExpanded: boolean;
};

class LegacyChart extends React.Component<
  LegacyChartProps,
  LegacyChartState
> {
  state: LegacyChartState = {
    selectedYear: null,
    isExpanded: false,
  };

  render() {
    return null;
  }
}

{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}

npm run typecheck

type StockStore = {
  stockData: StockData[];
  isLoading: boolean;
  error: string | null;
  selectedTab: string;
  isTooltipOpen: boolean;
  lastFetchedAt: number | null;
  fetchStockData: (stockCode: string) => Promise<void>;
};

type StockCacheItem = {
  data: StockData[];
  updatedAt: number;
};

type StockStore = {
  cache: Record<string, StockCacheItem>;
  loadingKeys: Record<string, boolean>;
  errors: Record<string, string | null>;
  fetchStockData: (
    stockCode: string,
    options?: {
      force?: boolean;
      staleTime?: number;
    }
  ) => Promise<void>;
};

const useStockStore = create<StockStore>((set, get) => ({
  cache: {},
  loadingKeys: {},
  errors: {},

  fetchStockData: async (
    stockCode,
    {
      force = false,
      staleTime = 5 * 60 * 1000,
    } = {}
  ) => {
    const cachedItem = get().cache[stockCode];
    const isFresh =
      cachedItem &&
      Date.now() - cachedItem.updatedAt < staleTime;

    if (!force && isFresh) {
      return;
    }

    if (get().loadingKeys[stockCode]) {
      return;
    }

    set((state) => ({
      loadingKeys: {
        ...state.loadingKeys,
        [stockCode]: true,
      },
      errors: {
        ...state.errors,
        [stockCode]: null,
      },
    }));

    try {
      const data = await fetchStockData(stockCode);

      set((state) => ({
        cache: {
          ...state.cache,
          [stockCode]: {
            data,
            updatedAt: Date.now(),
          },
        },
      }));
    } catch {
      set((state) => ({
        errors: {
          ...state.errors,
          [stockCode]: "取得股票資料失敗",
        },
      }));
    } finally {
      set((state) => ({
        loadingKeys: {
          ...state.loadingKeys,
          [stockCode]: false,
        },
      }));
    }
  },
}));

export function useStockData(stockCode: string) {
  return useQuery({
    queryKey: ["stock-data", stockCode],
    queryFn: () => fetchStockData(stockCode),
    enabled: Boolean(stockCode),
    staleTime: 5 * 60 * 1000,
    gcTime: 30 * 60 * 1000,
  });
}

["stock-data", "2330"]
["stock-data", "2317"]

const {
  data = [],
  isPending,
  isFetching,
  isError,
} = useStockData(stockCode);

staleTime: 5 * 60 * 1000

gcTime: 30 * 60 * 1000

const queryClient = useQueryClient();

await updateStockDividend(input);

await queryClient.invalidateQueries({
  queryKey: ["stock-data", input.stockCode],
});

<TableCell>{item.field_01}</TableCell>
<TableCell>{item.field_02}</TableCell>
<TableCell>{item.field_03}</TableCell>

import { z } from "zod";

const nullableNumberSchema = z
  .union([z.number(), z.string(), z.null()])
  .transform((value, context): number | null => {
    if (value === null || value === "") {
      return null;
    }

    const parsedValue =
      typeof value === "number" ? value : Number(value);

    if (!Number.isFinite(parsedValue)) {
      context.addIssue({
        code: z.ZodIssueCode.custom,
        message: "必須是有效數值",
      });

      return z.NEVER;
    }

    return parsedValue;
  });

const stockDividendApiSchema = z.object({
  cash_dividend: nullableNumberSchema,
  dividend_yield: nullableNumberSchema,
  release_date: z.string().nullable(),
});

type StockDividendApiResponse = z.infer<
  typeof stockDividendApiSchema
>;

type StockDividendRow = {
  cashDividend: number;
  dividendYield: number | null;
  releaseDate: string | null;
};

function normalizeDate(
  value: string | null
): string | null {
  if (!value) {
    return null;
  }

  const date = new Date(value);

  if (Number.isNaN(date.getTime())) {
    return null;
  }

  return date.toISOString().slice(0, 10);
}

export function mapStockDividendRow(
  input: unknown
): StockDividendRow {
  const data = stockDividendApiSchema.parse(input);

  return {
    cashDividend: data.cash_dividend ?? 0,
    dividendYield: data.dividend_yield,
    releaseDate: normalizeDate(data.release_date),
  };
}

<TableCell>{row.cashDividend}</TableCell>

<TableCell>
  {row.dividendYield ?? "-"}
</TableCell>

<TableCell>
  {row.releaseDate ?? "尚未公布"}
</TableCell>

return {
  cashDividend: data.cash_dividend,
  dividendYield: data.dividend_yield,
  releaseDate: data.release_date,
};

describe("mapStockDividendRow", () => {
  it("應轉換欄位名稱與數字字串", () => {
    expect(
      mapStockDividendRow({
        cash_dividend: "3.5",
        dividend_yield: "4.2",
        release_date: "2026-03-01T08:00:00+08:00",
      })
    ).toEqual({
      cashDividend: 3.5,
      dividendYield: 4.2,
      releaseDate: "2026-03-01",
    });
  });

  it("現金股息為 null 時應使用預設值", () => {
    expect(
      mapStockDividendRow({
        cash_dividend: null,
        dividend_yield: null,
        release_date: null,
      })
    ).toEqual({
      cashDividend: 0,
      dividendYield: null,
      releaseDate: null,
    });
  });

  it("無效日期應轉換為 null", () => {
    expect(
      mapStockDividendRow({
        cash_dividend: 2,
        dividend_yield: 3,
        release_date: "invalid-date",
      })
    ).toEqual({
      cashDividend: 2,
      dividendYield: 3,
      releaseDate: null,
    });
  });

  it("無效數值格式應拋出錯誤", () => {
    expect(() =>
      mapStockDividendRow({
        cash_dividend: "not-a-number",
        dividend_yield: 3,
        release_date: "2026-03-01",
      })
    ).toThrow();
  });
});

export function sortByReleaseDate<
  T extends { releaseDate: string }
>(rows: T[]): T[] {
  return [...rows].sort(
    (a, b) =>
      new Date(b.releaseDate).getTime() -
      new Date(a.releaseDate).getTime()
  );
}

describe("sortByReleaseDate", () => {
  it("應依發布日期由新到舊排序", () => {
    const rows = [
      { id: 1, releaseDate: "2026-01-01" },
      { id: 2, releaseDate: "2026-03-01" },
    ];

    expect(sortByReleaseDate(rows)).toEqual([
      { id: 2, releaseDate: "2026-03-01" },
      { id: 1, releaseDate: "2026-01-01" },
    ]);
  });

  it("不應修改原始陣列", () => {
    const rows = [
      { id: 1, releaseDate: "2026-01-01" },
      { id: 2, releaseDate: "2026-03-01" },
    ];

    sortByReleaseDate(rows);

    expect(rows[0].id).toBe(1);
  });
});

## 修改範圍

- 將現金股息資料來源切換至新版 API
- 移除舊 CashDVDYield_byYear 資料依賴
- 新增 API Schema、Adapter 與型別
- 保留既有圖表 UI 與互動方式

## TypeScript 遷移範圍

- API Service、Adapter 與 Query Hook 已改為 TypeScript
- 舊圖表 Component 暫時維持 JavaScript
- 舊 Component 透過 Adapter 接收已正規化資料
- 後續修改圖表功能時再逐步遷移為 TSX

## 已知限制

- 新舊 API 計算公式不同，無法直接以數值完全比對
- 部分年度資料由後端決定是否提供
- 本次不調整圖表共用 Component
- 舊圖表模組缺少完整型別，暫時由包裝層隔離

## 驗證方式

- 驗證 API 參數
- 驗證 Runtime Schema
- 驗證 Response Mapping
- 驗證 Null 與日期處理
- 驗證年份欄位
- 驗證排序
- 使用 Playwright 驗證主要操作流程