# Story 1.5: Homepage Implementation

**Status:** ready-for-dev

**Epic:** Epic 1 - Webflow to Payload CMS + Astro Migration

**Priority:** P1 (High - First public page visitors see)

**Estimated Time:** 6-8 hours

**Depends On:** Story 1.4 (Global Layout Components - Header/Footer)

---

## Story

**As a** Visitor,
**I want** to view the homepage with hero section and service features,
**so that** I can understand what Enchun Digital offers.

哇，這是我們網站的第一印象！首頁必須讓訪客一眼就知道恩群數位是做什麼的，並且想要繼續探索！

---

## Context

這是首個完整的公開頁面實作，依賴 Story 1.4 完成 Header 和 Footer 組件。首頁是網站的門面，需要完美呈現品牌形象和核心服務。

**Story Source:**
- PRD: `docs/prd/05-epic-stories.md` - Story 1.5
- Frontend route exists at: `apps/frontend/src/pages/index.astro`
- CMS Globals: Header, Footer (already configured)

**Current State:**
- Basic `index.astro` exists with hardcoded content
- `VideoHero` component exists with video background support
- Header/Footer components fetch from Payload CMS
- Layout.astro integrates Header and Footer

---

## Acceptance Criteria

### AC1: Hero Section (完整英雄區域)
- [ ] Background video with overlay (desktop + mobile variants)
- [ ] Main headline: "創造企業更多發展的可能性是我們的使命"
- [ ] Subheadline: "Its our destiny to create possibilities for your business"
- [ ] Enchun logo display
- [ ] Video fallback image for non-video browsers
- [ ] Gradient overlay for text readability (from-black/80 to-black/0)

### AC2: Service Features Grid (服務特色網格)
- [ ] 4 service cards in responsive grid (1 col mobile, 2 col tablet, 4 col desktop)
- [ ] Each card displays:
  - Icon (SVG or emoji)
  - Title (中文)
  - Description (中文)
- [ ] Card styling: white background, shadow, rounded corners
- [ ] Hover effects for interactivity

### AC3: Portfolio Preview Section (作品預覽)
- [ ] Display 3-6 portfolio items as preview cards
- [ ] Each card shows: image, title, short description
- [ ] "View All Portfolio" CTA button linking to `/website-portfolio`
- [ ] Data fetched from Portfolio collection (Payload CMS)

### AC4: CTA Section (行動呼籲)
- [ ] Headline: "準備好開始新的旅程了嗎"
- [ ] Description text
- [ ] Primary CTA button linking to `/contact-us`
- [ ] Background styling matching Webflow design

### AC5: Content from Payload CMS (內容來自 CMS)
- [ ] Hero content (headline, subheadline) from Home global or Page collection
- [ ] Service features from configurable CMS source
- [ ] Portfolio items from Portfolio collection
- [ ] CTA section text from CMS

### AC6: Visual Fidelity 95%+ (視覺保真度)
- [ ] Colors match Webflow design tokens
- [ ] Spacing and typography match original
- [ ] Responsive breakpoints align with Webflow
- [ ] Animations and transitions feel smooth

### AC7: Lighthouse Performance 90+ (效能標準)
- [ ] Performance score >= 90
- [ ] FCP < 1.5s
- [ ] LCP < 2.5s
- [ ] CLS < 0.1

---

## Tasks / Subtasks

### Task 1.5.1: Create Home Global in Payload CMS (1h)
**AC Coverage:** AC5

- [ ] **Subtask 1.5.1.1:** Create Home global config
  - File: `apps/backend/src/Home/config.ts`
  - Fields: heroHeadline, heroSubheadline, heroVideo (upload), heroOverlay (group)
- [ ] **Subtask 1.5.1.2:** Register Home global in payload.config.ts
- [ ] **Subtask 1.5.1.3:** Add access control (read: public, update: adminOnly)
- [ ] **Subtask 1.5.1.4:** Seed initial content in Payload Admin
- [ ] **Subtask 1.5.1.5:** Verify TypeScript types regenerate

### Task 1.5.2: Refactor index.astro to use Payload Data (2h)
**AC Coverage:** AC5, AC6

- [ ] **Subtask 1.5.2.1:** Create `getHomeData` utility function
  - File: `apps/frontend/src/lib/api/home.ts`
  - Fetch Home global, Portfolio items
- [ ] **Subtask 1.5.2.2:** Update index.astro to fetch data at build time
- [ ] **Subtask 1.5.2.3:** Pass props to child components
- [ ] **Subtask 1.5.2.4:** Handle data fetching errors gracefully
- [ ] **Subtask 1.5.2.5:** Test with draft=false parameter

### Task 1.5.3: Enhance Hero Section (1.5h)
**AC Coverage:** AC1, AC6

- [ ] **Subtask 1.5.3.1:** Update VideoHero to accept CMS data
  - Props: heroHeadline, heroSubheadline, heroVideoUrl
- [ ] **Subtask 1.5.3.2:** Add fallback image when video fails to load
- [ ] **Subtask 1.5.3.3:** Adjust gradient overlay for text readability
- [ ] **Subtask 1.5.3.4:** Ensure mobile video is optimized (smaller file)
- [ ] **Subtask 1.5.3.5:** Test on various devices and network speeds

### Task 1.5.4: Implement Service Features Grid (1.5h)
**AC Coverage:** AC2, AC6

- [ ] **Subtask 1.5.4.1:** Create ServiceFeatureCard component
  - File: `apps/frontend/src/components/ServiceFeatureCard.astro`
  - Props: icon, title, description
- [ ] **Subtask 1.5.4.2:** Create ServiceFeaturesGrid section
  - File: `apps/frontend/src/sections/ServiceFeatures.astro`
  - Grid layout: 1 col mobile, 2 col md, 4 col lg
- [ ] **Subtask 1.5.4.3:** Add hover effects (transform, shadow)
- [ ] **Subtask 1.5.4.4:** Configure 4 service features
  - Google Ads, 社群行銷, 論壇行銷, 網站設計
- [ ] **Subtask 1.5.4.5:** Test responsive behavior

### Task 1.5.5: Implement Portfolio Preview Section (1h)
**AC Coverage:** AC3, AC5

- [ ] **Subtask 1.5.5.1:** Create PortfolioPreviewCard component
  - File: `apps/frontend/src/components/PortfolioPreviewCard.astro`
  - Props: image, title, description, slug
- [ ] **Subtask 1.5.5.2:** Create PortfolioPreview section
  - File: `apps/frontend/src/sections/PortfolioPreview.astro`
  - Display 3 items (limit query)
- [ ] **Subtask 1.5.5.3:** Add "View All" CTA button
- [ ] **Subtask 1.5.5.4:** Fetch from Portfolio collection with proper sorting
- [ ] **Subtask 1.5.5.5:** Handle empty portfolio state

### Task 1.5.6: Implement CTA Section (1h)
**AC Coverage:** AC4, AC6

- [ ] **Subtask 1.5.6.1:** Create CTASection component
  - File: `apps/frontend/src/sections/CTASection.astro`
  - Props: headline, description, ctaText, ctaLink
- [ ] **Subtask 1.5.6.2:** Style with gradient background matching Webflow
- [ ] **Subtask 1.5.6.3:** Add primary button styling
- [ ] **Subtask 1.5.6.4:** Connect to Contact page route
- [ ] **Subtask 1.5.6.5:** Make text configurable via CMS

### Task 1.5.7: Performance Optimization and Testing (1h)
**AC Coverage:** AC7

- [ ] **Subtask 1.5.7.1:** Run Lighthouse audit (desktop + mobile)
- [ ] **Subtask 1.5.7.2:** Optimize images (use WebP, responsive sizes)
- [ ] **Subtask 1.5.7.3:** Implement lazy loading for below-fold content
- [ ] **Subtask 1.5.7.4:** Minimize CLS (reserve space for dynamic content)
- [ ] **Subtask 1.5.7.5:** Test on actual devices (iOS, Android)

---

## Dev Notes

### Architecture Patterns

1. **Data Fetching Pattern:**
   - Use Astro's server-side fetching in the frontmatter
   - Cache aggressively (Payload CMS responses are stable)
   - Use `draft=false` for public content

2. **Component Structure:**
   ```
   index.astro (main page)
   ├── VideoHero (hero section)
   ├── ServiceFeatures (services grid)
   ├── PortfolioPreview (portfolio cards)
   ├── CTASection (call to action)
   └── uses Layout.astro (wraps with Header/Footer)
   ```

3. **Styling Approach:**
   - Use Tailwind CSS utility classes
   - Reference design tokens from `apps/frontend/src/styles/theme.css`
   - Maintain consistency with existing components

### Project Structure Notes

**Files to Create:**
```
apps/backend/src/
├── Home/
│   └── config.ts              # Home global configuration

apps/frontend/src/
├── lib/
│   └── api/
│       └── home.ts            # Data fetching utilities
├── components/
│   └── ServiceFeatureCard.astro
├── sections/
│   ├── ServiceFeatures.astro
│   ├── PortfolioPreview.astro
│   └── CTASection.astro
```

**Files to Modify:**
```
apps/frontend/src/
├── pages/
│   └── index.astro            # Main page, refactor to use CMS data
└── components/
    └── videoHero.astro        # Enhance for CMS integration
```

**Naming Conventions:**
- Components: `PascalCase.astro` (e.g., ServiceFeatureCard.astro)
- Sections: `PascalCase.astro` (e.g., ServiceFeatures.astro)
- Utilities: `camelCase.ts` (e.g., getHomeData.ts)

### Design Tokens (from theme.css)

```css
/* Primary Colors */
--color-enchunblue: #0E79B2;
--color-tropical-blue: #E6F4FC;
--color-amber: #F9A825;
--color-st-tropaz: #2C5282;

/* Text Colors */
--color-tarawera: #3D4C53;
--color-dove-gray: #666666;

/* Use these for consistency! */
```

### References

- [Source: docs/prd/05-epic-stories.md#Story-15](/Users/pukpuk/Dev/website-enchun-mgr/docs/prd/05-epic-stories.md)
- [Source: apps/frontend/src/pages/index.astro](/Users/pukpuk/Dev/website-enchun-mgr/apps/frontend/src/pages/index.astro) (existing implementation)
- [Source: apps/backend/src/Header/config.ts](/Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/Header/config.ts) (Global pattern reference)
- [Source: apps/backend/src/Footer/config.ts](/Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/Footer/config.ts) (Global pattern reference)
- [Source: research/www.enchun.tw/index.html](/Users/pukpuk/Dev/website-enchun-mgr/research/www.enchun.tw/index.html) (Original Webflow)

---

## Testing Requirements

### Visual Testing Checklist
- [ ] Hero section displays correctly on all screen sizes
- [ ] Video background plays smoothly on desktop
- [ ] Mobile video loads and plays on mobile devices
- [ ] Service cards align properly in grid
- [ ] Portfolio preview cards have consistent heights
- [ ] CTA section button is prominent and clickable

### Functional Testing
- [ ] All navigation links work correctly
- [ ] CTA buttons route to correct pages
- [ ] Portfolio preview cards link to detail pages
- [ ] Data loads from Payload CMS without errors
- [ ] Fallback content displays if CMS is unavailable

### Performance Testing
```bash
# Run Lighthouse audit
npx lighthouse http://localhost:4321 --view
```

**Targets:**
- Performance: >= 90
- Accessibility: >= 90
- Best Practices: >= 90
- SEO: >= 90

### Manual Testing Steps
1. Start dev server: `pnpm dev`
2. Navigate to `http://localhost:4321`
3. Verify hero video loads and plays
4. Scroll through all sections
5. Click all CTA buttons
6. Test on mobile (resize browser or use device)
7. Check console for errors

---

## Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| Video file too large | Medium | High | Compress video, use separate mobile version |
| CLS from dynamic content | Low | Medium | Reserve space with aspect-ratio |
| CMS fetch fails | Low | Medium | Add error boundaries and fallback UI |
| Portfolio empty state | Medium | Low | Show placeholder or hide section |

---

## Definition of Done

- [ ] All 7 tasks completed
- [ ] Home global created and seeded with content
- [ ] index.astro refactored to use Payload CMS data
- [ ] All sections (Hero, Services, Portfolio, CTA) implemented
- [ ] Visual fidelity matches Webflow (95%+)
- [ ] Lighthouse Performance score 90+
- [ ] No console errors on page load
- [ ] Code follows existing patterns
- [ ] No linting errors (`pnpm lint`)
- [ ] sprint-status.yaml updated to mark story as ready-for-dev

---

## Dev Agent Record

### Agent Model Used
*To be filled by Dev Agent*

### Debug Log References
*To be filled by Dev Agent*

### Completion Notes
*To be filled by Dev Agent*

### File List
*To be filled by Dev Agent*

---

## Change Log

| Date | Action | Author |
|------|--------|--------|
| 2026-01-31 | Story created (Draft) | SM Agent (Bob) |