DM_NewWeb_React

🚚 ELF EXPRESS 集運管理系統

線上 Demo: https://elf-express.github.io/DM_NewWeb_React/

現代化的集運管理平台

基於 Next.js 16 + TypeScript + next-intl 構建的現代化集運管理系統。，支持多主題、多語言，完全符合官方最佳實踐。

✨ 主要特性

🎨 7 種主題風格

🔵 經典藍 - 專業穩重
⚫ 極簡黑白 - 簡約現代
💜 夢幻紫 - 優雅夢幻
💚 清新綠 - 活力清新
🧡 活力橙 - 熱情活力
💗 浪漫粉 - 溫柔浪漫
🩵 科技青 - 科技感十足

🌍 多語言支持

🇹🇼 繁體中文（預設）
🇨🇳 简體中文
🇺🇸 English

📊 功能完整

✅ 帳戶概覽統計 ✅ 包裹入庫管理 ✅ 訂單追蹤查詢
✅ 客服中心 ✅ 快捷操作面板 ✅ 實時數據圖表

🚀 技術棧

框架: Next.js 16 (App Router) + React 19 + TypeScript
國際化: next-intl (SSG 支持)
路由: Next.js App Router with Dynamic Routes
UI 組件:
- Radix UI (Headless Components)
  - Dialog/Sheet - 彈窗和側邊抽屜
  - Checkbox - 複選框
  - Radio Group - 單選按鈕
  - Label - 表單標籤
- Tailwind CSS
- shadcn/ui
動畫: Framer Motion
圖表: Recharts
圖標: Lucide React
表單: React Hooks (useState)
部署: GitHub Pages (Static Export)

📁 項目架構

src/
├── components/      # UI組件（ui/common/Dashboard）
├── contexts/       # React Context（主題管理）
新集運首頁/
├── app/                          # Next.js App Router
│   ├── [locale]/                 # 動態語言路由
│   │   ├── layout.tsx           # 語言布局
│   │   ├── page.tsx             # 首頁
│   │   └── inbound/             # 入庫頁面
│   │       └── page.tsx         # 已到站頁面
│   └── layout.tsx               # 根布局樣式

✅ 完全符合 React/TypeScript/Vite/i18next 官方標準
✅ 完整的路徑別名配置（@/）
✅ 模組化設計，易於擴展

🚀 快速開始

# 安裝依賴
npm install --legacy-peer-deps

# 開發模式
npm run dev  # http://localhost:5173/DM_NewWeb_React/

# 建置
npm run build

# 部署
npm run deploy

🌐 部署到 GitHub Pages

1. 配置並部署

git config user.name "你的用戶名"
git config user.email "你的郵箱"
npm run deploy

2. 啟用 GitHub Pages

GitHub 專案 → Settings → Pages → Source 選擇 gh-pages → Save

等待 1-2 分鐘後訪問: https://[用戶名].github.io/[專案名]/

🎯 路徑別名

@/              → src/
@/components/   → src/components/
@/types/        → src/types/
@/constants/    → src/constants/
@/utils/        → src/utils/
@/i18n/         → src/i18n/
@/contexts/     → src/contexts/
@/styles/       → src/styles/

🌍 多語言使用

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t, i18n } = useTranslation();
  
  return <h1>{t('common.search')}</h1>;
  
  // 切換語言
  i18n.changeLanguage('zh-CN');
}

🎨 主題系統

點擊導航欄的調色盤圖標切換主題，設置會自動保存到 localStorage。

自定義主題

在 src/styles/globals.css 定義CSS變量
在 src/constants/themes.ts 添加配置
在 ThemeContext 中註冊主題

📦 添加功能模組

mkdir -p src/features/my-feature/{components,hooks,types}
touch src/features/my-feature/index.tsx

🔧 環境要求

Node.js >= 16.0.1
npm >= 7.0.0

📈 開發進度

✅ 已完成

🚧 開發中

待申報功能頁面
訂單管理頁面
用戶中心頁面
支付流程

📋 計劃中

包裹詳情頁面
物流追蹤頁面
歷史記錄
優惠券管理

🛠️ 開發指令

# 開發模式
npm run dev
# 訪問: http://localhost:3000/zh-TW

# 類型檢查
npm run typecheck

# 構建生產版本 (使用生產配置)
npm run build

# 啟動生產服務器
npm run start

# 部署到 GitHub Pages
npm run deploy

🎨 設計系統規範

📐 佈局與間距

容器寬度

最大寬度: max-w-7xl (1280px)
容器內距: px-4 (左右各 16px)
響應式斷點: 2xl 最大 1400px

主要間距系統

頁面級: gap-4 (16px) - 主要區塊之間
卡片級: gap-3 (12px) - 卡片內部元素
組件級: gap-2 (8px) - 小組件如按鈕內的圖標
頂部導航: py-3 (上下 12px)
卡片內距: p-4 或 p-6 (16px 或 24px)

網格佈局

// 三欄佈局 (桌面版)
<div className="grid gap-4 lg:grid-cols-12">
  {/* 左側主內容區 - 8 欄 */}
  <div className="lg:col-span-8 space-y-4">
  
  {/* 右側邊欄 - 4 欄 */}
  <div className="lg:col-span-4 space-y-4">
</div>

🎴 卡片設計

基礎卡片結構

<Card>
  <CardHeader>
    <CardTitle>標題</CardTitle>
  </CardHeader>
  <CardContent>
    內容區域
  </CardContent>
</Card>

卡片樣式規範

背景: 白色 bg-white
邊框: 淺灰邊框 border
圓角: 0.5rem (由 CSS 變量 --radius 控制)
陰影: 無默認陰影，使用邊框區分
內距: Header p-6, Content p-6 pt-0

卡片變體

數據卡片 - 顯示統計數字
- 圖標 + 標題 + 數值
- gap-2 圖標間距
表格卡片 - 包含數據表格
- 使用 <Table> 組件
- 斑馬紋效果 (自動)
圖表卡片 - 包含可視化圖表
- ResponsiveContainer 自適應
- 高度通常 h-[200px] 或 h-[300px]

🎨 顏色系統

CSS 變量架構

所有顏色使用 HSL 格式定義在 CSS 變量中：

--primary: 221.2 83.2% 53.3%;  /* 主色 */
--secondary: 210 40% 96.1%;     /* 次要色 */
--muted: 210 40% 96.1%;         /* 柔和色 */
--accent: 210 40% 96.1%;        /* 強調色 */
--destructive: 0 84.2% 60.2%;   /* 危險色 */

7 種主題變體

經典藍 (default) - 主色: #3b82f6 (藍)
極簡黑白 (minimal) - 主色: #171717 (黑)
夢幻紫 (purple) - 主色: #a855f7 (紫)
清新綠 (green) - 主色: #22c55e (綠)
活力橙 (orange) - 主色: #f97316 (橙)
浪漫粉 (rose) - 主色: #f43f5e (粉)
科技藍 (cyan) - 主色: #06b6d4 (青)

語義化顏色使用

Primary: 主要操作按鈕、重要圖標
Secondary: 次要內容區背景
Muted: 次要文字、禁用狀態
Destructive: 刪除、警告操作
Border: 所有邊框統一使用

📱 響應式設計

斷點系統

sm: '640px'   // 手機橫屏
md: '768px'   // 平板
lg: '1024px'  // 筆電
xl: '1280px'  // 桌面
2xl: '1400px' // 大屏

佈局適配

// 手機: 單欄
// 桌面: 左右 8:4 分欄
<div className="grid gap-4 lg:grid-cols-12">
  <div className="lg:col-span-8">主內容</div>
  <div className="lg:col-span-4">側邊欄</div>
</div>

🔤 文字系統

字體大小

大標題: text-2xl font-semibold (24px)
標題: text-lg font-semibold (18px)
小標題: text-sm font-medium (14px)
正文: text-base (16px)
說明文字: text-sm text-muted-foreground (14px)
小字: text-xs (12px)

字重

Bold: font-bold (700) - 很少使用
SemiBold: font-semibold (600) - 標題、重要內容
Medium: font-medium (500) - 次標題、標籤
Normal: font-normal (400) - 正文

🎯 組件規範

按鈕

// 主要按鈕
<Button>操作</Button>

// 次要按鈕
<Button variant="outline">次要操作</Button>

// 幽靈按鈕 (僅圖標)
<Button variant="ghost" size="icon">
  <Icon className="h-5 w-5"/>
</Button>

// 帶圖標的按鈕
<Button className="gap-2">
  <Icon className="h-4 w-4"/>
  文字
</Button>

徽章 (Badge)

// 狀態標籤
<Badge variant="secondary">已入庫</Badge>
<Badge variant="default">處理中</Badge>
<Badge variant="destructive">待付款</Badge>

輸入框

// 搜索框 (帶圖標)
<div className="relative">
  <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4"/>
  <Input className="pl-9" placeholder="搜索"/>
</div>

🎭 動畫效果

Framer Motion

// 淡入動畫
<motion.div
  initial=
  animate=
  transition=
>

過渡效果

按鈕懸停: 自動 (Tailwind)
卡片懸停: 可選 hover:shadow-lg transition-shadow
動畫時長: 通常 0.2s 或 0.3s

📊 圖表設計

Recharts 配置

<ResponsiveContainer width="100%" height={200}>
  <AreaChart data={data}>
    <defs>
      <linearGradient id="gradient" x1="0" y1="0" x2="0" y2="1">
        <stop offset="5%" stopColor={theme.primary} stopOpacity={0.3}/>
        <stop offset="95%" stopColor={theme.primary} stopOpacity={0}/>
      </linearGradient>
    </defs>
    <Area 
      type="monotone" 
      stroke={theme.primary}
      fill="url(#gradient)"
    />
  </AreaChart>
</ResponsiveContainer>

🌐 多語言考慮

文字空間預留

英文通常比中文長 30-50%
使用 truncate 或 line-clamp 防止溢出
按鈕寬度使用 min-w-[100px] 確保最小寬度

🎯 設計原則

一致性: 所有組件使用統一的間距、顏色、圓角
層次感: 通過字重、顏色、大小建立視覺層次
留白: 充足的空白讓界面更清晰
對齊: 嚴格的網格對齊，使用 Tailwind 的 gap 系統
可訪問性: 顏色對比度符合 WCAG AA 標準

📐 關鍵尺寸速查

導航欄高度: auto (py-3 約 60px)
頁面左右邊距: px-4 (16px)
最大內容寬度: max-w-7xl (1280px)
卡片圓角: 0.5rem (8px)
卡片間距: gap-4 (16px)
圖標大小: 
  - 小: h-4 w-4 (16px)
  - 中: h-5 w-5 (20px)  
  - 大: h-6 w-6 (24px)
按鈕內距: px-4 py-2
輸入框高度: h-10 (40px)

💡 重要提示

開發環境 vs 生產環境

開發: 使用 next.config.mjs（無 basePath，middleware 可用）
生產: 使用 next.config.production.mjs（有 basePath，靜態導出）
構建命令會自動使用正確的配置

新增頁面流程

在 app/[locale]/ 下創建新路由
在 src/components/ 下創建組件
在 messages/ 中添加翻譯文本
更新此 README 記錄進度

組件開發規範

所有客戶端組件必須添加 'use client' 指令
遵循 README 中的設計系統規範
使用 useTranslations() 處理多語言
使用 useTheme() 適配主題

📝 最近更新

2024-11-12

✨ 新增已到站入庫頁面 (/inbound)
✨ 實現包裹多選與編輯品名功能
✨ 添加發貨方式選擇（空運/海運/快遞）
✨ 實現增值服務選項（加固/防水/拍照/保險）
✨ 實時費用計算功能
🎨 新增 Sheet、Checkbox、Radio、Label UI 組件
📱 完整響應式佈局支持
🌐 更新三語翻譯文件

2024-11-11

✨ 新增未入庫包裹側邊抽屜
🎨 首頁 Dashboard 完成
🌐 完整多語言支持
🎨 7 種主題風格實現

📄 授權

MIT License

Built with ❤️ using Next.js + TypeScript + next-intl