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

1API Service
2    ↓
3Async Action / Store
4    ↓
5資料轉換
6    ↓
7Component Props / Selector
8    ↓
9圖表或表格

1畫面看起來正常
2↓
3測試環境可以使用
4↓
5合併正式環境
6↓
7另一個共用頁面壞掉

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

1{
2  "compilerOptions": {
3    "target": "ES2020",
4    "lib": ["DOM", "DOM.Iterable", "ES2020"],
5    "module": "ESNext",
6    "moduleResolution": "Bundler",
7    "jsx": "react-jsx",
8    "strict": true,
9    "noEmit": true,
10    "allowJs": true,
11    "checkJs": false,
12    "esModuleInterop": true,
13    "skipLibCheck": true,
14    "resolveJsonModule": true
15  },
16  "include": ["src"]
17}

1{
2  "allowJs": true,
3  "checkJs": false
4}

1export type StockDividendApiResponse = {
2  cash_dividend: number | string | null;
3  dividend_yield: number | string | null;
4  release_date: string | null;
5};
6
7export async function fetchStockDividend(
8  stockCode: string
9): Promise<unknown> {
10  const response = await fetch(`/api/stocks/${stockCode}/dividend`);
11
12  if (!response.ok) {
13    throw new Error("取得股利資料失敗");
14  }
15
16  return response.json();
17}

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

1type LegacyChartProps = {
2  stockCode: string;
3  rows: StockDividendRow[];
4  onReload?: () => void;
5};
6
7type LegacyChartState = {
8  selectedYear: number | null;
9  isExpanded: boolean;
10};
11
12class LegacyChart extends React.Component<
13  LegacyChartProps,
14  LegacyChartState
15> {
16  state: LegacyChartState = {
17    selectedYear: null,
18    isExpanded: false,
19  };
20
21  render() {
22    return null;
23  }
24}

1{
2  "scripts": {
3    "typecheck": "tsc --noEmit"
4  }
5}

1npm run typecheck

1允許 JavaScript 與 TypeScript 並存
2↓
3新檔案一律使用 TypeScript
4↓
5先遷移 API、Adapter 與商業邏輯
6↓
7修改既有功能時順便遷移相關檔案
8↓
9逐步加入 @ts-check 或改成 .ts/.tsx
10↓
11縮小 any、@ts-ignore 與 @ts-nocheck 的範圍
12↓
13最後再評估是否全面啟用 checkJs 或移除 allowJs

1type StockStore = {
2  stockData: StockData[];
3  isLoading: boolean;
4  error: string | null;
5  selectedTab: string;
6  isTooltipOpen: boolean;
7  lastFetchedAt: number | null;
8  fetchStockData: (stockCode: string) => Promise<void>;
9};

1type StockCacheItem = {
2  data: StockData[];
3  updatedAt: number;
4};
5
6type StockStore = {
7  cache: Record<string, StockCacheItem>;
8  loadingKeys: Record<string, boolean>;
9  errors: Record<string, string | null>;
10  fetchStockData: (
11    stockCode: string,
12    options?: {
13      force?: boolean;
14      staleTime?: number;
15    }
16  ) => Promise<void>;
17};

1const useStockStore = create<StockStore>((set, get) => ({
2  cache: {},
3  loadingKeys: {},
4  errors: {},
5
6  fetchStockData: async (
7    stockCode,
8    {
9      force = false,
10      staleTime = 5 * 60 * 1000,
11    } = {}
12  ) => {
13    const cachedItem = get().cache[stockCode];
14    const isFresh =
15      cachedItem &&
16      Date.now() - cachedItem.updatedAt < staleTime;
17
18    if (!force && isFresh) {
19      return;
20    }
21
22    if (get().loadingKeys[stockCode]) {
23      return;
24    }
25
26    set((state) => ({
27      loadingKeys: {
28        ...state.loadingKeys,
29        [stockCode]: true,
30      },
31      errors: {
32        ...state.errors,
33        [stockCode]: null,
34      },
35    }));
36
37    try {
38      const data = await fetchStockData(stockCode);
39
40      set((state) => ({
41        cache: {
42          ...state.cache,
43          [stockCode]: {
44            data,
45            updatedAt: Date.now(),
46          },
47        },
48      }));
49    } catch {
50      set((state) => ({
51        errors: {
52          ...state.errors,
53          [stockCode]: "取得股票資料失敗",
54        },
55      }));
56    } finally {
57      set((state) => ({
58        loadingKeys: {
59          ...state.loadingKeys,
60          [stockCode]: false,
61        },
62      }));
63    }
64  },
65}));

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

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

1const {
2  data = [],
3  isPending,
4  isFetching,
5  isError,
6} = useStockData(stockCode);

1staleTime: 5 * 60 * 1000

1gcTime: 30 * 60 * 1000

1const queryClient = useQueryClient();
2
3await updateStockDividend(input);
4
5await queryClient.invalidateQueries({
6  queryKey: ["stock-data", input.stockCode],
7});

1TanStack Query
2負責 API、Cache、Cache 失效、Loading、Error、Retry、Refetch
3
4Zustand
5負責真正需要跨元件共享的 UI 狀態
6
7Local State
8負責單一元件內部互動

1<TableCell>{item.field_01}</TableCell>
2<TableCell>{item.field_02}</TableCell>
3<TableCell>{item.field_03}</TableCell>

1import { z } from "zod";
2
3const nullableNumberSchema = z
4  .union([z.number(), z.string(), z.null()])
5  .transform((value, context): number | null => {
6    if (value === null || value === "") {
7      return null;
8    }
9
10    const parsedValue =
11      typeof value === "number" ? value : Number(value);
12
13    if (!Number.isFinite(parsedValue)) {
14      context.addIssue({
15        code: z.ZodIssueCode.custom,
16        message: "必須是有效數值",
17      });
18
19      return z.NEVER;
20    }
21
22    return parsedValue;
23  });
24
25const stockDividendApiSchema = z.object({
26  cash_dividend: nullableNumberSchema,
27  dividend_yield: nullableNumberSchema,
28  release_date: z.string().nullable(),
29});
30
31type StockDividendApiResponse = z.infer<
32  typeof stockDividendApiSchema
33>;

1type StockDividendRow = {
2  cashDividend: number;
3  dividendYield: number | null;
4  releaseDate: string | null;
5};

1function normalizeDate(
2  value: string | null
3): string | null {
4  if (!value) {
5    return null;
6  }
7
8  const date = new Date(value);
9
10  if (Number.isNaN(date.getTime())) {
11    return null;
12  }
13
14  return date.toISOString().slice(0, 10);
15}

1export function mapStockDividendRow(
2  input: unknown
3): StockDividendRow {
4  const data = stockDividendApiSchema.parse(input);
5
6  return {
7    cashDividend: data.cash_dividend ?? 0,
8    dividendYield: data.dividend_yield,
9    releaseDate: normalizeDate(data.release_date),
10  };
11}

1<TableCell>{row.cashDividend}</TableCell>
2
3<TableCell>
4  {row.dividendYield ?? "-"}
5</TableCell>
6
7<TableCell>
8  {row.releaseDate ?? "尚未公布"}
9</TableCell>

1return {
2  cashDividend: data.cash_dividend,
3  dividendYield: data.dividend_yield,
4  releaseDate: data.release_date,
5};

1describe("mapStockDividendRow", () => {
2  it("應轉換欄位名稱與數字字串", () => {
3    expect(
4      mapStockDividendRow({
5        cash_dividend: "3.5",
6        dividend_yield: "4.2",
7        release_date: "2026-03-01T08:00:00+08:00",
8      })
9    ).toEqual({
10      cashDividend: 3.5,
11      dividendYield: 4.2,
12      releaseDate: "2026-03-01",
13    });
14  });
15
16  it("現金股息為 null 時應使用預設值", () => {
17    expect(
18      mapStockDividendRow({
19        cash_dividend: null,
20        dividend_yield: null,
21        release_date: null,
22      })
23    ).toEqual({
24      cashDividend: 0,
25      dividendYield: null,
26      releaseDate: null,
27    });
28  });
29
30  it("無效日期應轉換為 null", () => {
31    expect(
32      mapStockDividendRow({
33        cash_dividend: 2,
34        dividend_yield: 3,
35        release_date: "invalid-date",
36      })
37    ).toEqual({
38      cashDividend: 2,
39      dividendYield: 3,
40      releaseDate: null,
41    });
42  });
43
44  it("無效數值格式應拋出錯誤", () => {
45    expect(() =>
46      mapStockDividendRow({
47        cash_dividend: "not-a-number",
48        dividend_yield: 3,
49        release_date: "2026-03-01",
50      })
51    ).toThrow();
52  });
53});

1export function sortByReleaseDate<
2  T extends { releaseDate: string }
3>(rows: T[]): T[] {
4  return [...rows].sort(
5    (a, b) =>
6      new Date(b.releaseDate).getTime() -
7      new Date(a.releaseDate).getTime()
8  );
9}

1describe("sortByReleaseDate", () => {
2  it("應依發布日期由新到舊排序", () => {
3    const rows = [
4      { id: 1, releaseDate: "2026-01-01" },
5      { id: 2, releaseDate: "2026-03-01" },
6    ];
7
8    expect(sortByReleaseDate(rows)).toEqual([
9      { id: 2, releaseDate: "2026-03-01" },
10      { id: 1, releaseDate: "2026-01-01" },
11    ]);
12  });
13
14  it("不應修改原始陣列", () => {
15    const rows = [
16      { id: 1, releaseDate: "2026-01-01" },
17      { id: 2, releaseDate: "2026-03-01" },
18    ];
19
20    sortByReleaseDate(rows);
21
22    expect(rows[0].id).toBe(1);
23  });
24});

1## 修改範圍
2
3- 將現金股息資料來源切換至新版 API
4- 移除舊 CashDVDYield_byYear 資料依賴
5- 新增 API Schema、Adapter 與型別
6- 保留既有圖表 UI 與互動方式
7
8## TypeScript 遷移範圍
9
10- API Service、Adapter 與 Query Hook 已改為 TypeScript
11- 舊圖表 Component 暫時維持 JavaScript
12- 舊 Component 透過 Adapter 接收已正規化資料
13- 後續修改圖表功能時再逐步遷移為 TSX
14
15## 已知限制
16
17- 新舊 API 計算公式不同，無法直接以數值完全比對
18- 部分年度資料由後端決定是否提供
19- 本次不調整圖表共用 Component
20- 舊圖表模組缺少完整型別，暫時由包裝層隔離
21
22## 驗證方式
23
24- 驗證 API 參數
25- 驗證 Runtime Schema
26- 驗證 Response Mapping
27- 驗證 Null 與日期處理
28- 驗證年份欄位
29- 驗證排序
30- 使用 Playwright 驗證主要操作流程

1目前版本已依現有需求完成，並提供操作 Demo。
2
3若指定時間前未收到調整意見，將依目前版本提交至測試環境。
4後續若 Prototype 或需求內容變更，將另行評估修改範圍與時程。