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
parent 8c87d71aa2
commit e9897388dc
34 changed files with 11920 additions and 8777 deletions
--- a/_bmad-output/implementation-artifacts/1-5-homepage.story.md
+++ b/_bmad-output/implementation-artifacts/1-5-homepage.story.md
@@ -0,0 +1,346 @@
+# 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) |