# filbet

**Repository Path**: keep1996/filbet

## Basic Information

- **Project Name**: filbet
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: task/TEST-297/注册登录优化
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-02
- **Last Updated**: 2025-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Filbet Client Pure React Beta 開發規則

## 專案概述

- 專案類型：菲律賓綜合盤 RWD 自適應系統
- 目標：提供高效能、可靠的投注平台
- 特點：響應式設計、多設備支援

## 技術棧概覽

- 建構工具：Vite v6.2.0
- 框架：React v19.0.0
- 語言：TypeScript v5.7.2
- 路由：React Router v7.4.0
- 狀態管理：Jotai v2.12.2
- 樣式解決方案：
    - Emotion v11.14.0
    - SASS v1.86.0
- 編譯器：SWC v7.1.0 (透過 @vitejs/plugin-react-swc v3.8.1)
- 動畫：Framer Motion v12.5.0
- HTTP 客戶端：Axios v1.8.4
- 工具庫：
    - Lodash v4.17.21
    - Day.js v1.11.13
    - qs v6.14.0

## 開發工具配置

- ESLint v9.21.0
    - eslint-plugin-react-hooks v5.1.0
    - eslint-plugin-react-refresh v0.4.19
- Prettier v3.5.3
- TypeScript v5.7.2
    - ts-node v10.9.2
    - tsconfig-paths v4.2.0

## 專案總體結構

```txt
filbet-client-pure-react-beta/
├── src/                      # 源碼目錄
│   ├── apis/                 # 數據層：API 相關
│   │   ├── postman_api_filbet_client_v1.ts # Postman 自動生成的 API 客戶端
│   │   ├── index.ts          # API 實例化和配置
│   │   └── api_fetchers.ts   # 乾淨的數據獲取封裝
│   │   └── api_types.d.ts     # API 類型定義
│   │   └── api_utils.ts     # API 工具函數
│   │
│   ├── features/            # 業務層：功能模組
│   │   ├── auth/           # 認證相關業務
│   │   ├── account/        # 帳戶相關業務
│   │   ├── game/           # 遊戲相關業務
│   │   └── tracking/       # 埋點相關業務
│   │       ├── hooks/      # 埋點邏輯 Hooks
│   │       ├── types/      # 埋點類型定義
│   │       ├── utils/      # 埋點工具函數
│   │       ├── constants/  # 埋點事件常量
│   │       └── services/   # 埋點服務封裝
│   │
│   ├── components/          # 視圖層：UI 元件
│   │   ├── base/           # 基礎元件
│   │   │   ├── Button/
│   │   │   ├── Input/
│   │   │   └── ...
│   │   └── composite/      # 組合元件
│   │       ├── GameCard/
│   │       ├── GameList/
│   │       └── ...
│   │
│   ├── pages/              # 視圖層：頁面
│   │   ├── HomePage/
│   │   ├── GamePage/
│   │   ├── GameCategoryPage/
│   │   └── AccountPage/
│   │
│   ├── routes/             # 路由層
│   │   ├── config/        # 路由配置
│   │   └── guards/        # 路由守衛
│   │
│   ├── atoms/              # 狀態管理
│   │   ├── api_repositories.ts # API 模型 atoms
│   │   └── api_repositories_composite.ts # API 模型 atoms 的復合 atoms
│   │
│   ├── styles/             # 全局樣式
│   │   ├── base/           # 基礎樣式
│   │   │   ├── normalize.scss: 跨瀏覽器樣式重置和標準化
│   │   │   │   重置默認樣式
│   │   │   │   統一基礎元素樣式
│   │   │   │   修復常見瀏覽器差異
│   │   │   ├── fonts.scss: 字體系統設定
│   │   │   │   字體家族定義
│   │   │   │   字體大小變量
│   │   │   │   字重設定
│   │   │   │   行高規範
│   │   │   └── globals.scss: 全局樣式定義
│   │   │   │   全局變量
│   │   │   │   通用工具類
│   │   │   │   共用動畫
│   │   │   │   全局覆蓋樣式
│   │   ├── theme/          # 主題配置
│   │   ├── mixins/        # 樣式混入
│   │   └── variables/     # 樣式變量
│   │
│   └── utils/              # 全局工具函數
│
├── public/                  # 靜態資源
├── tests/                   # 測試文件
├── types/                   # 全局類型定義
├── tools/                   # 開發工具和腳本
├── docs/                    # 項目文檔
├── .swc/                    # SWC 編譯器配置
├── .cursor/                 # Cursor IDE 配置
├── .env                     # 環境變量
├── vite-env.d.ts           # Vite 環境類型定義
├── vite-env-override.d.ts   # 環境變量覆蓋定義
├── eslint.config.js         # ESLint 扁平配置
├── .prettierrc             # Prettier 配置
├── tsconfig.json           # TypeScript 基礎配置
├── tsconfig.app.json       # 應用程序 TypeScript 配置
├── tsconfig.node.json      # Node.js TypeScript 配置
├── vite.config.ts          # Vite 配置
└── package.json            # 項目配置
```

## 目錄內容規範

### 1. 數據層 (`src/apis/`)

- `postman_api_filbet_client_v1.ts`
    - Postman 自動生成的 API 客戶端代碼
    - API 請求和響應的類型定義
    - API 端點配置
    - HTTP 客戶端實現
- `index.ts`
    - API 實例化和配置
    - 請求攔截器配置
    - 統一的 API 導出
- `api_getters.ts`
    - 封裝乾淨的數據獲取方法
    - 重用或重新定義數據類型
    - 處理數據轉換和格式化
    - 提供強型別的數據介面

### 2. 業務層 (`src/features/`)

- `auth/`

    - `hooks/`: 登入、註冊等認證邏輯
    - `types/`: 認證相關類型
    - `utils/`: Token 處理、加密等工具
    - `constants/`: 認證相關常量
    - `models/`: 用戶數據模型

- `account/`

    - `hooks/`: 帳戶管理邏輯
    - `types/`: 帳戶相關類型
    - `utils/`: 帳戶資料處理工具
    - `constants/`: 帳戶相關常量

- `game/`

    - `hooks/`: 遊戲邏輯處理
    - `types/`: 遊戲相關類型
    - `utils/`: 遊戲數據處理
    - `constants/`: 遊戲配置常量

- `tracking/`
    - `hooks/`: 埋點邏輯 Hooks
        - `usePageTracking`: 頁面訪問追蹤
        - `useEventTracking`: 用戶行為追蹤
        - `usePerformanceTracking`: 性能指標追蹤
    - `types/`: 埋點相關類型定義
        - 事件類型定義
        - 埋點數據結構
        - 追蹤參數類型
    - `utils/`: 埋點工具函數
        - 數據處理工具
        - 埋點過濾器
        - 批次處理工具
    - `constants/`: 埋點事件常量
        - 頁面事件定義
        - 用戶行為事件
        - 錯誤事件類型
    - `services/`: 埋點服務封裝
        - 數據上報服務
        - 緩存策略
        - 失敗重試機制

### 3. 視圖層

#### `src/components/`

- `base/`
    - `Button/`: 按鈕元件及其變體
    - `Input/`: 輸入框元件及其變體
    - `Select/`: 選擇器元件
    - `Modal/`: 彈窗元件
    - `Table/`: 表格元件
- `composite/`
    - `GameCard/`: 遊戲卡片組件
    - `GameList/`: 遊戲列表組件
    - `UserPanel/`: 用戶面板組件
    - `WalletInfo/`: 錢包資訊組件

#### `src/pages/`

- `Home/`: 首頁相關組件和邏輯
- `Game/`: 遊戲頁面組件
- `Account/`: 帳戶管理頁面
- `Auth/`: 登入註冊頁面

### 4. 路由層 (`src/routes/`)

- `config/`
    - 路由配置文件
    - 路由映射定義
    - 路由參數配置
- `guards/`
    - 路由守衛邏輯
    - 權限檢查
    - 路由重定向規則

### 5. 狀態管理 (`src/store/`)

- `atoms/`
    - 原子狀態定義
    - 持久化配置
    - 狀態初始值
- `selectors/`
    - 計算狀態定義
    - 狀態組合邏輯
    - 數據轉換規則

### 6. 樣式系統 (`src/styles/`)

- `base/`

    - `normalize.scss`: 跨瀏覽器樣式重置和標準化
        - 重置默認樣式
        - 統一基礎元素樣式
        - 修復常見瀏覽器差異
    - `fonts.scss`: 字體系統設定
        - 字體家族定義
        - 字體大小變量
        - 字重設定
        - 行高規範
    - `globals.scss`: 全局樣式定義
        - 全局變量
        - 通用工具類
        - 共用動畫
        - 全局覆蓋樣式

- `theme/`

    - 主題配置文件
    - 調色板定義
    - 響應式斷點配置

- `mixins/`

    - 通用樣式混入
    - 動畫效果
    - 佈局模板

- `variables/`
    - 全局樣式變量
    - 主題變量
    - 媒體查詢斷點

### 7. 工具函數 (`src/utils/`)

- 日期時間處理
- 數字格式化
- 字符串處理
- 數據驗證
- 本地存儲處理
- 瀏覽器相容性處理

### 8. 配置文件（根目錄）

- `package.json`: 項目依賴和腳本配置
- `tsconfig.json`: TypeScript 編譯配置
- `vite.config.ts`: Vite 建構配置
- `.env`: 環境變量配置
- `.eslintrc`: ESLint 規則配置
- `.prettierrc`: 代碼格式化配置

### 9. 靜態資源 (`public/`)

- 圖標文件
- 圖片資源
- 字體文件
- 靜態 JSON 配置
- 第三方腳本

### 10. 測試文件 (`tests/`)

- 單元測試
- 集成測試
- E2E 測試
- 測試工具和配置

## 目錄職責說明

1. **數據層 (`src/apis/`)**

    - 處理所有外部數據交互
    - 封裝 API 請求和響應
    - 實現數據轉換和格式化
    - 管理數據緩存策略

2. **業務層 (`src/features/`)**

    - 實現核心業務邏輯
    - 按功能模組組織代碼
    - 提供業務邏輯 Hooks
    - 處理業務數據轉換

3. **視圖層 (`src/components/`, `src/pages/`)**

    - 實現用戶界面
    - 管理用戶交互
    - 組織頁面佈局
    - 處理視覺效果

4. **路由層 (`src/routes/`)**

    - 管理路由配置
    - 實現權限控制
    - 處理頁面導航
    - 管理路由守衛

5. **狀態管理 (`src/store/`)**

    - 管理全局狀態
    - 處理狀態持久化
    - 實現狀態計算
    - 提供狀態訂閱

6. **工具和配置**
    - 全局工具函數
    - 環境配置
    - 建構配置
    - 類型定義

## 系統架構分層

### 1. 數據層 (Data Layer)

```txt
src/
├── apis/          # API 請求封裝
│   ├── postman_api_filbet_client_v1.ts  # Postman 生成的 API 客戶端
│   ├── index.ts   # API 實例化和配置
│   └── api_getters.ts  # 乾淨的數據獲取封裝
├── store/         # Jotai 狀態管理
│   ├── atoms/     # 原子狀態定義
│   └── selectors/ # 計算衍生狀態
```

### 2. 業務層 (Business Layer)

```txt
src/
├── features/      # 業務功能模組
│   ├── auth/      # 認證相關
│   ├── account/   # 帳戶相關
│   └── game/      # 遊戲相關
├── hooks/         # 業務邏輯 Hooks
└── utils/         # 業務工具函數
```

### 3. 視圖層 (View Layer)

```txt
src/
├── components/    # 共用元件
│   ├── base/      # 基礎元件
│   └── composite/ # 組合元件
├── pages/        # 頁面元件
└── styles/       # 樣式定義
```

### 4. 路由層 (Router Layer)

```txt
src/
└── routes/       # 路由配置
    ├── config/   # 路由定義
    └── guards/   # 路由守衛
```

## 分層互動規範

1. **數據層規範**

    - 使用 Postman 生成的 API 客戶端作為基礎
    - 在 index.ts 中統一配置和實例化 API
    - 在 api_getters.ts 中提供乾淨的數據獲取方法
    - 確保數據類型定義清晰且強型別
    - 視需求重用或重新定義數據類型

2. **業務層規範**

    - 只能通過數據層獲取數據
    - 實現業務邏輯和狀態管理
    - 提供 Hooks 給視圖層使用
    - 處理複雜的狀態計算

3. **視圖層規範**

    - 只能調用業務層提供的 Hooks
    - 專注於 UI 渲染和用戶交互
    - 遵循 RWD 設計原則
    - 實現響應式佈局

4. **路由層規範**
    - 集中管理路由配置
    - 實現路由守衛機制
    - 處理權限控制
    - 管理頁面轉場效果

## 開發規範

### 1. TypeScript 配置規範

使用三個配置文件：

1. `tsconfig.json` - 基礎配置
    - 共享的編譯器選項
    - 專案引用設置
2. `tsconfig.app.json` - 應用程序配置
    - 繼承基礎配置
    - React 特定設置
    - 路徑別名配置
3. `tsconfig.node.json` - Node.js 環境配置
    - 用於 Vite 配置文件
    - 用於開發工具腳本

配置特點：

- 使用 ESM 模組系統
- 啟用嚴格模式
- 支持裝飾器
- 配置路徑別名

### 2. React 開發規則

- 使用函數式元件和 Hooks
- 元件檔案命名：PascalCase
- Props 型別定義：使用 interface
- 使用 React.memo() 優化渲染效能

### 3. 狀態管理 (Jotai)

- 原子化狀態管理
- 使用 computed atoms 處理衍生狀態
- 按業務模組組織原子
- 實現狀態持久化

### 4. 樣式開發規則

混合使用：

1. Emotion styled components

    - 用於元件級樣式
    - 支援主題系統
    - 動態樣式生成
    - 支援 SWC 優化

2. SASS

    - 用於全局樣式
    - 變量和混入
    - 樣式重置和標準化
    - 主題變量管理

3. Framer Motion
    - 複雜動畫效果
    - 手勢互動
    - 過渡效果
    - 性能優化

### 5. 效能優化重點

1. 編譯優化

    - 使用 SWC 加速編譯
    - 路由代碼分割
    - 動態導入優化

2. 運行時優化

    - React.memo() 優化渲染
    - Jotai 原子化狀態管理
    - Framer Motion 動畫性能

3. 打包優化
    - 模組預打包
    - 靜態資源優化
    - 代碼壓縮

## 效能優化準則

1. **數據層優化**

    - 實現數據緩存
    - 批量請求處理
    - 數據預加載

2. **業務層優化**

    - 使用 getter 計算屬性
    - 避免重複計算
    - 實現記憶化

3. **視圖層優化**
    - 元件懶加載
    - 圖片資源優化
    - 虛擬列表實現

## 開發指令

```bash
# 開發環境啟動
pnpm dev

# 型別檢查和建構
pnpm build

# 程式碼品質檢查
pnpm lint

# 預覽生產環境
pnpm preview
```

## 開發環境要求

- Node.js：建議使用 LTS 版本 (v20+)
- 套件管理器：pnpm v8+
- IDE：VS Code + 推薦插件配置
    - Cursor IDE 支援
    - ESLint v9+
    - Prettier v3+
    - TypeScript v5.7+

## 版本控制規範

- 遵循 Git Flow 工作流
- Commit Message 規範
- 代碼審查流程
- 分支管理策略

## Vite 配置特點

- 使用 SWC 替代 Babel
- 配置環境變量類型
- ESLint 整合
- 路徑別名配置
- 樣式預處理器配置
- 優化打包策略

## 持續更新

本文件將根據專案發展持續更新，團隊成員可提出修改建議。

## 埋點規範

### 1. 埋點分類

1. **頁面訪問追蹤**

    - 頁面加載時間
    - 頁面停留時間
    - 頁面跳轉來源
    - 訪問路徑追蹤

2. **用戶行為追蹤**

    - 點擊事件
    - 滾動行為
    - 表單操作
    - 功能使用頻率

3. **性能指標追蹤**

    - 首次內容繪製 (FCP)
    - 最大內容繪製 (LCP)
    - 首次輸入延遲 (FID)
    - 累積布局偏移 (CLS)

4. **錯誤追蹤**
    - API 錯誤
    - JS 運行時錯誤
    - 資源加載錯誤
    - 用戶操作異常

### 2. 埋點實現規範

1. **數據收集**

    - 統一使用 hooks 進行埋點
    - 確保數據收集的完整性
    - 實現自動化埋點
    - 支持手動埋點補充

2. **數據處理**

    - 數據脫敏處理
    - 數據格式標準化
    - 批量處理策略
    - 優先級管理

3. **上報策略**

    - 實時上報重要事件
    - 批量上報一般事件
    - 離線數據緩存
    - 失敗重試機制

4. **性能考量**
    - 控制埋點頻率
    - 優化數據包大小
    - 避免影響主業務邏輯
    - 異步處理非關鍵數據

### 3. 埋點使用示例

```typescript
// 頁面訪問追蹤
const PageComponent = () => {
  usePageTracking({
    pageId: 'home',
    source: document.referrer
  });
  return <div>Page Content</div>;
};

// 用戶行為追蹤
const Button = () => {
  const trackEvent = useEventTracking();

  const handleClick = () => {
    trackEvent({
      category: 'user_action',
      action: 'click',
      label: 'login_button'
    });
  };

  return <button onClick={handleClick}>Login</button>;
};

// 性能指標追蹤
const App = () => {
  usePerformanceTracking({
    enableFCP: true,
    enableLCP: true,
    enableFID: true,
    enableCLS: true
  });
  return <div>App Content</div>;
};
```

### 4. 埋點數據規範

1. **基礎數據結構**

    ```typescript
    interface TrackingEvent {
        eventId: string // 事件唯一標識
        timestamp: number // 事件發生時間戳
        category: string // 事件分類
        action: string // 事件動作
        label?: string // 事件標籤
        value?: number // 事件值
        extra?: Record<string, any> // 額外信息
    }
    ```

2. **用戶信息**

    ```ts
    interface UserContext {
        userId?: string // 用戶ID
        sessionId: string // 會話ID
        deviceInfo: {
            // 設備信息
            userAgent: string
            screenSize: string
            platform: string
        }
        location?: {
            // 地理位置
            country: string
            region: string
        }
    }
    ```

## 其他習慣

- 使用 `function ComponentName() { return ( ... ) }` 而不是 `const ComponentName = () => { return ( ... ) }`
- 使用 `@` 作為 src 目錄的別名，例如：

    ```ts
    // 推薦
    import { Button } from "@/components/base/Button"
    import { useAuth } from "@/features/auth/hooks/useAuth"

    // 不推薦
    import { Button } from "../../../components/base/Button"
    import { useAuth } from "../../../features/auth/hooks/useAuth"
    ```

- 圖標命名規範 例如：

    // 推荐，这种命名的方式方便维护和复制
    xxx_xxx.svg
    xxx_xxx_xxx.png

    // 不推荐驼峰，中划线
    xxxIcon.svg
    xxx-xxx.png

- 圖片统一添加在assets文件中，并使用generate-asset-keys 生成keys，使用时使用统一的方法来获取图片，src会遵循ts校验，例如：

    ```ts
    import Svg, { SvgComponent } from "@/components/base/Svg"
    import Image, { ImageComponent } from "@/components/base/Image"

    <Svg src="pages/Project/svg/xxx.svg" />
    <Image src="pages/Project/images/xxx.png" />
    const Icon = styled(SvgComponent('pages/Project/xxxx.svg'))``
    const Icon = styled(ImageComponent('pages/Project/xxxx.png'))``
    ```

- styled-components 規範 例如：

    ```ts
    // 推荐
    const StyledDiv = styled.div`
       border: 1px solid #ccc
    `;
    const StyledButton = styled.button`
       color: #fff
    `;
     <StyledDiv>
        <StyledButton />
     </StyledDiv>

    // 不推荐在使用了styled-components后任然交叉使用过多的className
    const StyledDiv = styled.div`
       border: 1px solid #ccc

       .button {
          color: #fff
       }
       .icon{
          width: 10px
       }
       .text{
          color: #fff
       }
    `;
     <StyledDiv>
        <button className="button" />
        <icon className="icon" />
        <span className="text" />
     </StyledDiv>
    ```