Files

pkupuk e9897388dc docs: separate documentation and specs into initial commit

Establish baseline for project documentation including BMAD specs, PRD, and system architecture notes.

2026-02-11 11:49:49 +08:00

15 KiB

Raw Blame History

Story 1.4: Global Layout Components (Header/Footer)

Status: ready-for-dev Epic: Epic 1 - Webflow to Payload CMS + Astro Migration Priority: P1 (Critical - Blocks Stories 1.5-1.11) Estimated Time: 10 hours Assigned To: Dev Agent

Story

As a Developer, I want to create Header and Footer components matching Webflow design, **So that all pages have consistent navigation and branding.

Context

這是 Story 1.4 的核心實作任務！Header 和 Footer 是全站共用的基礎組件，一旦完成就能解鎖 Stories 1.5-1.11 的所有頁面開發。

當前狀態分析：

Header.astro 和 Footer.astro 已存在但需要完善
Header 和 Footer Payload CMS Globals 已配置
MainLayout.astro 已整合 Header/Footer
需要優化響應式設計和動畫效果

Story Source:

來自 docs/prd/epic-1-stories-1.3-1.17-tasks.md - Story 1.4
執行計劃: docs/prd/epic-1-execution-plan.md - Story 1.4
Sprint Status: _bmad-output/implementation-artifacts/sprint-status.yaml - Story 1-4

Acceptance Criteria

AC1 - Header Component 功能完整

Enchun logo 顯示並連結到首頁 (/)
桌面導航選單顯示所有項目（About, Solutions, Marketing Magnifier, Teams, Portfolio, Contact）
"Hot" 標籤顯示在 Solutions 連結右上角（紅色圓形徽章）
"New" 標籤顯示在 Marketing Magnifier 連結右上角（紅色圓形徽章）
手機版漢堡選單按鈕（小於 768px 顯示）
手機選單點擊展開/收合動畫流暢
Scroll 時 Header 背景從透明變為白色

AC2 - Footer Component 功能完整

Enchun logo 顯示
公司描述文字完整顯示
聯絡資訊：電話 (02 5570 0527)、Email (enchuntaiwan@gmail.com)
Facebook 連結可點擊
行銷方案連結（靜態，從 Payload CMS）
行銷放大鏡分類連結（動態從 Categories collection）
Copyright 顯示 "2018 - {currentYear}"

AC3 - Tailwind CSS 與 Webflow 顏色一致

使用 --color-enchunblue (品牌藍色)
使用 --color-tropical-blue (頁腳背景)
使用 --color-st-tropaz (頁腳文字)
使用 --color-amber (Copyright 條背景)
使用 --color-tarawera (Copyright 文字)

AC4 - 響應式設計正常

桌面版 (> 991px)：導航橫向排列
平板版 (768px - 991px)：導航適當間距
手機版 (< 768px)：漢堡選單，全螢幕覆蓋

AC5 - MainLayout 整合完成

Header 和 Footer 正確引入
main 標籤正確包裹內容
頁面結構符合 SEO 最佳實踐

AC6 - 手機選單動畫流暢

漢堡圖標轉換為 X 圖標
選單項目淡入動畫
點擊連結後選單自動關閉

Current State Analysis

已完成的部分 (Existing Implementation)

Header.astro (apps/frontend/src/components/Header.astro)

基本結構已建立
已實作 Payload CMS API 載入 (/api/globals/header)
桌面/手機導航分割存在
Badge 邏輯已實作 (Hot/New)

Footer.astro (apps/frontend/src/components/Footer.astro)

基本結構已建立
已實作 Payload CMS API 載入 (/api/globals/footer)
靜態和動態連結區塊已配置

Header Global (apps/backend/src/Header/config.ts)

navItems array 已配置
adminOnly access control 已設定
audit hooks 已整合

Footer Global (apps/backend/src/Footer/config.ts)

navItems + childNavItems 已配置
adminOnly access control 已設定
audit hooks 已整合

Layout.astro (apps/frontend/src/layouts/Layout.astro)

Header 和 Footer 已引入
基本結構正確

需要改進的部分

Header 改進項目：
- Scroll 時背景變化效果尚未實作
- 手機選單動畫需要優化
- 標籤樣式需要統一
Footer 改進項目：
- 動態分類連結需要從 Categories collection 載入
- 版權年份動態生成需要驗證
響應式斷點：
- 確認 Tailwind 斷點與 Webflow 一致
- 測試各裝置尺寸

Dev Technical Guidance

Webflow 顏色對應

Webflow 顏色名稱	CSS 變數名稱	Hex 值	用途
Enchun Blue	`--color-enchunblue`	#1E3A8A	品牌/主色
Tropical Blue	`--color-tropical-blue`	#E8F4F8	頁腳背景
St. Tropaz	`--color-st-tropaz`	#5D7285	頁腳文字
Amber	`--color-amber`	#F59E0B	CTA/強調
Tarawera	`--color-tarawera`	#2D3748	深色文字

響應式斷點

/* Webflow 斷點對應 Tailwind */
@media (max-width: 991px)  /* Tablet and below */
@media (max-width: 767px)  /* Mobile landscape */
@media (max-width: 479px)  /* Mobile portrait */

/* Tailwind 對應 */
md:hidden      /* < 768px */
lg:            /* >= 1024px */

Header 組件架構

// apps/frontend/src/components/Header.astro

interface NavItem {
  link: {
    type: "reference" | "custom";
    label: string;
    url?: string;
    reference?: {
      slug: string;
    };
    newTab?: boolean;
  };
}

// 載入 Payload Header Global
const apiUrl = `/api/globals/header?depth=2&draft=false&locale=undefined&trash=false`;

Header 需要的功能：

Sticky 定位 (已有)
Scroll 背景變化 (需要新增)
手機選單切換 (已有，需要優化)
Badge 顯示 (已有)

Footer 組件架構

// apps/frontend/src/components/Footer.astro

interface FooterData {
  navItems: Array<{
    link: {
      url?: string;
      label?: string;
    };
    childNavItems: Array<{
      link: {
        url?: string;
        label?: string;
      };
    }>;
  }>;
}

// 載入 Payload Footer Global
const apiUrl = `/api/globals/footer?depth=2&draft=false&locale=undefined&trash=false`;

Footer 需要的功能：

靜態行銷方案連結 (已有)
動態分類連結 (需要改進 - 從 Categories collection)
Copyright 年份 (已有)

Payload CMS Globals 結構

Header Global:

{
  navItems: [
    {
      link: {
        type: "custom" | "reference",
        label: "關於恩群",
        url: "/about-enchun" // 或 reference.slug
      }
    },
    // ... 更多選單項目
  ]
}

Footer Global:

{
  navItems: [
    {
      link: { label: "行銷方案" },
      childNavItems: [
        { link: { label: "Google 商家關鍵字", url: "..." } },
        // ... 更多子項目
      ]
    },
    {
      link: { label: "行銷放大鏡" },
      childNavItems: [
        // 動態從 Categories 載入
      ]
    }
  ]
}

Tasks / Subtasks

Task 1.4.1: Design Component Architecture Review (1.5h)
- Review existing Header.astro and Footer.astro implementation
- Verify Payload CMS Globals structure matches requirements
- Document responsive breakpoints strategy
- Plan scroll-based header background effect
- Plan mobile menu animations
Task 1.4.2: Verify Header Global in Payload CMS (1.5h)
- Verify Header global has all navItems configured
- Test API endpoint /api/globals/header
- Confirm navItems includes all required links
- Verify adminOnly access control
Task 1.4.3: Verify Footer Global in Payload CMS (1h)
- Verify Footer global has navItems with childNavItems
- Test API endpoint /api/globals/footer
- Confirm structure matches frontend expectations
- Plan dynamic Categories integration
Task 1.4.4: Enhance Header.astro Component (2h)
- Add scroll-based background change effect
- Enhance mobile menu animations
- Ensure Hot/New badges display correctly
- Test navigation on all breakpoints
- Verify active page highlighting
Task 1.4.5: Enhance Footer.astro Component (1.5h)
- Add dynamic Categories loading from /api/categories
- Verify copyright year displays correctly
- Ensure social links work (Facebook)
- Test footer layout on mobile
Task 1.4.6: Verify Integration with MainLayout (1h)
- Confirm Header/Footer properly integrated
- Test all pages use MainLayout
- Verify no visual issues on any page
- Check for console errors
Task 1.4.7: Testing and Validation (1.5h)
- Manual responsive testing (desktop, tablet, mobile)
- Test all navigation links
- Verify badges display correctly
- Test scroll behavior
- Test mobile menu open/close
- Cross-browser testing (Chrome, Firefox, Safari)

File Structure

apps/
├── backend/src/
│   ├── Header/
│   │   ├── config.ts           ✅ EXISTS - Header Global configuration
│   │   ├── hooks/
│   │   │   └── revalidateHeader.ts
│   │   ├── RowLabel.tsx
│   │   ├── Nav/index.tsx
│   │   └── Component.tsx
│   ├── Footer/
│   │   ├── config.ts           ✅ EXISTS - Footer Global configuration
│   │   ├── hooks/
│   │   │   └── revalidateFooter.ts
│   │   ├── RowLabel.tsx
│   │   └── Component.tsx
│   └── access/
│       └── adminOnly.ts        ✅ EXISTS - Access control function
│
└── frontend/src/
    ├── components/
    │   ├── Header.astro        ⚠️ EXISTS - Needs enhancements
    │   └── Footer.astro        ⚠️ EXISTS - Needs enhancements
    └── layouts/
        └── Layout.astro        ✅ EXISTS - MainLayout with Header/Footer

Testing Requirements

Manual Testing Checklist

Header 測試：

Logo 點擊導向首頁
桌面版所有導航項目顯示
"Hot" 標籤顯示在 "行銷方案" 右上角
"New" 標籤顯示在 "行銷放大鏡" 右上角
手機版顯示漢堡選單圖標
點擊漢堡選單展開全螢幕選單
選單項目點擊後選單關閉
Scroll 時 Header 背景變化
導航連結全部可點擊

Footer 測試：

Logo 顯示正確
公司描述文字完整
電話號碼顯示正確
Email 連結 (mailto:) 可用
Facebook 連結可點擊
行銷方案連結顯示正確
行銷放大鏡分類動態載入
Copyright 年份正確 (2018 - 2026)

響應式測試：

1920x1080 (Desktop)
1024x768 (Tablet landscape)
768x1024 (Tablet portrait)
375x667 (Mobile)
無水平滾動條
觸控目標足夠大 (44x44px min)

Visual Regression Testing

對比 Webflow 設計稿：

Header 高度和間距一致
Footer 佈局一致
顏色精確匹配
字體大小一致
標籤樣式一致

Risk Assessment

Risk	Probability	Impact	Mitigation
Payload API 連線失敗	Low	High	添加 fallback 靜態導航
響應式斷點不一致	Medium	Medium	使用 Tailwind 預設斷點
動畫效能問題	Low	Low	使用 CSS transitions
Categories API 載入慢	Medium	Low	添加 loading 狀態

Definition of Done

Header 組件所有功能正常
Footer 組件所有功能正常
響應式設計測試通過
所有導航連結可運作
標籤顯示正確
手機選單動畫流暢
Scroll 效果實作
跨瀏覽器測試通過
無 console 錯誤
sprint-status.yaml 更新為 "done"

Architecture Compliance

遵循專案架構原則：

Single Responsibility: Header.astro 和 Footer.astro 各自負責單一功能
Component Isolation: 組件可獨立運作，僅依賴 Payload API
Service Layer Separation: API 呼叫在組件 script 區塊中
Modular Design: 可重用於任何頁面

Webflow Design Reference

原始 HTML 參考：

Source: research/www.enchun.tw/index.html - Header/Footer 在此頁面中
Source: research/www.enchun.tw/about-enchun.html - Header/Footer 交叉參考
Source: research/www.enchun.tw/teams.html - Header/Footer 交叉參考

Header Webflow Classes:

.navigation - 主導航容器
.navigation-item - 導航項目
.navigation-link - 導航連結
.menu-button - 漢堡選單按鈕

Footer Webflow Classes:

.footer - 頁腳主容器
.footer-column - 欄位容器
.footer-link - 連結樣式
.copyright-bar - 版權條

Dev Agent Record

Agent Model Used

Claude Opus 4.6 (claude-opus-4-6)

Debug Log References

Parallel execution using 4 subagents (Tasks A, B, C, D)
Task A (aa0803b): Webflow color variables added
Task B (abeb130): Header enhancements completed
Task C (a2bb735): Footer enhancements completed
Task D (a95e0c9): API endpoints verified

Completion Notes

Story 1-4-global-layout implementation completed using parallel execution strategy:

Completed Changes:

Webflow Colors (theme.css): Added 5 Webflow-specific CSS variables (--color-enchunblue, --color-tropical-blue, --color-st-tropaz, --color-amber, --color-tarawera)
Header.astro Enhancements:
- Scroll-based background change (transparent → white/blur at 10px)
- Enhanced mobile menu with hamburger/X icon toggle animation
- Full-screen overlay menu with staggered fade-in animations
- Hot/New badges with pulse animation
- ESC key and click-outside-to-close functionality
- Body scroll lock when menu is open
Footer.astro Enhancements:
- Dynamic Categories loading from /api/categories (sorted by order, max 6)
- Copyright year auto-updates to current year
- Facebook social link verified
- Error handling for failed category loads
API Verification:
- All three endpoints (/api/globals/header, /api/globals/footer, /api/categories) verified
- Access control properly configured (adminOnly for updates, public read)
- Audit hooks correctly integrated

Remaining Task:

Task 1.4.7: Manual responsive testing and cross-browser validation (requires user testing)

File List

Modified Files:

apps/frontend/src/styles/theme.css - Added Webflow color variables
apps/frontend/src/components/Header.astro - Scroll effect, mobile animations, badges
apps/frontend/src/components/Footer.astro - Dynamic categories, copyright year
_bmad-output/implementation-artifacts/1-4-global-layout.story.md - Updated tasks and status
_bmad-output/implementation-artifacts/sprint-status.yaml - Updated story status

Change Log

Date	Action	Author
2026-01-31	Story created (Draft)	SM Agent (Bob) via Dev Story Workflow

Status: in-progress Next Step: Manual testing (Task 1.4.7) - User to verify responsive behavior across browsers

15 KiB Raw Blame History Unescape Escape