# 5. Epic and Story Structure

**Last Updated:** 2025-01-29

For brownfield projects, we favor a single comprehensive epic unless the user is clearly requesting multiple unrelated enhancements.

---

## Epic Approach

**Epic Structure Decision:** Single comprehensive epic

**Rationale:**
- This is a cohesive migration project with interdependent components
- All stories contribute to the same goal: complete Webflow to Payload CMS + Astro migration
- Multiple epics would create artificial boundaries and coordination overhead
- Sequential execution minimizes risk to existing system during transition

---

## Epic 1: Webflow to Payload CMS + Astro Migration

**Epic Goal:** Complete migration of enchun.tw website from Webflow to modern Payload CMS + Astro architecture while maintaining content integrity, SEO value, and 95%+ visual fidelity.

**Integration Requirements:**
- Must maintain existing Google Analytics tracking (G-DKBZWCGGZR)
- Must preserve all content (35+ articles, 4 categories, portfolio items)
- Must implement complete 301 redirect mappings
- Must use Payload CMS built-in authentication system
- Must deploy to Cloudflare infrastructure

---

### Story 1.1: Project Infrastructure Setup

**As a** Developer,
**I want to** set up the monorepo structure with Payload CMS and Astro,
**So that** I have a solid foundation for the migration.

**Acceptance Criteria:**
1. ✅ pnpm workspace configured with apps/backend, apps/frontend, packages/shared
2. ✅ Payload CMS 3.x initialized in apps/backend with MongoDB adapter
3. ✅ Astro 6.0.x SSR project initialized in apps/frontend (with Cloudflare native runtime)
4. ✅ TypeScript strict mode enabled across all packages
5. ✅ Turborepo configured for build/dev/lint scripts
6. ✅ Shared utilities package properly linked
7. ✅ Local development runs with `pnpm dev` (both frontend and backend)

**Integration Verification:**
- IV1: Verify that frontend can fetch data from backend API
- IV2: Verify that shared utilities can be imported in both apps
- IV3: Verify that TypeScript compilation succeeds across workspace
- IV4: Verify that hot reload works in both frontend and backend

**Estimated Effort:** 4-6 hours

---

### Story 1.2: Payload CMS Collections Definition

**As a** Developer,
**I want to** define all Payload CMS collections matching Webflow structure,
**So that** I can store migrated content in the correct structure.

**Acceptance Criteria:**
1. ✅ Users collection configured with built-in authentication
2. ✅ Posts collection with fields: title, slug, excerpt, content (richText), category (relation), publishedDate, featuredImage, ogImage, showInFooter, status
3. ✅ Categories collection with fields: name, slug, nameEn, order, textColor, backgroundColor
4. ✅ Portfolio collection with fields: title, slug, url, image, description, websiteType, tags
5. ✅ Media collection configured with R2 storage adapter
6. ✅ Access control functions defined (admin, editor roles)
7. ✅ All collections have proper timestamps and draft/published status

**Integration Verification:**
- IV1: Verify that Payload CMS admin panel loads without errors
- IV2: Verify that all collections appear in admin sidebar
- IV3: Verify that Users collection authentication works (can create/login user)
- IV4: Verify that Media collection uploads to R2 successfully
- IV5: Verify that rich text editor (Lexical) works in Posts collection

**Estimated Effort:** 8-10 hours

---

### Story 1.3: Content Migration Script

**As a** Developer,
**I want to** create a migration script that imports Webflow content to Payload CMS,
**So that** I can automate content transfer and reduce manual errors.

**Acceptance Criteria:**
1. ✅ Script accepts Webflow JSON/CSV export as input
2. ✅ Script transforms Webflow data to Payload CMS API format
3. ✅ Script migrates all 35+ posts with proper field mapping
4. ✅ Script migrates all 4 categories
5. ✅ Script migrates all portfolio items
6. ✅ Script downloads and uploads media to R2
7. ✅ Script preserves original slugs for SEO
8. ✅ Script generates migration report (success/failure counts)
9. ✅ Script supports dry-run mode for testing

**Integration Verification:**
- IV1: Verify that migrated content matches Webflow source (manual spot check)
- IV2: Verify that all media files are accessible in R2
- IV3: Verify that rich text content is formatted correctly
- IV4: Verify that category relationships are preserved
- IV5: Verify that script can be re-run without creating duplicates

**Estimated Effort:** 12-16 hours

---

### Story 1.4: Global Layout Components

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

**Acceptance Criteria:**
1. ✅ Header component with:
   - Enchun logo (links to home)
   - Desktop navigation (About, Solutions, Marketing Magnifier, Teams, Portfolio, Contact)
   - "Hot" badge on Solutions link
   - "New" badge on Marketing Magnifier link
   - Mobile hamburger menu
   - Sticky behavior on scroll
2. ✅ Footer component with:
   - Enchun logo and description
   - Contact info (phone, Email, Facebook link)
   - Marketing solution links (static)
   - Marketing magnifier category links (dynamic from Payload CMS)
   - Copyright notice (2018 - 2024)
3. ✅ Both components use Tailwind CSS with Webflow colors
4. ✅ Both components are responsive (desktop/tablet/mobile)
5. ✅ Header/Footer integrated into MainLayout.astro
6. ✅ Mobile menu fully functional with smooth animations

**Integration Verification:**
- IV1: Verify that Header appears on all pages
- IV2: Verify that navigation links work correctly
- IV3: Verify that Footer dynamic categories load from Payload CMS
- IV4: Verify responsive behavior matches Webflow breakpoints
- IV5: Verify that mobile menu toggle works smoothly

**Estimated Effort:** 8-10 hours

---

### Story 1.5: Homepage Implementation

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

**Acceptance Criteria:**
1. ✅ Hero section with:
   - Background image/overlay
   - Main headline and subheadline
   - CTA button
2. ✅ Service features grid (4 cards):
   - Icon + title + description for each feature
   - Responsive grid layout
3. ✅ Portfolio preview section
4. ✅ CTA section ("準備好開始新的旅程了嗎")
5. ✅ All content fetched from Payload CMS (globals or pages collection)
6. ✅ Visual fidelity 95%+ compared to Webflow
7. ✅ Lighthouse Performance score 90+

**Integration Verification:**
- IV1: Verify that page loads without errors
- IV2: Verify that all dynamic content displays correctly
- IV3: Verify that CTA button links to contact page
- IV4: Verify responsive design on all devices
- IV5: Verify performance meets targets (Lighthouse audit)

**Estimated Effort:** 6-8 hours

---

### Story 1.6: About Page Implementation

**As a** Visitor,
**I want to** learn about Enchun Digital's values and differences,
**So that** I can trust them as my digital marketing partner.

**Acceptance Criteria:**
1. ✅ Hero section with title "關於恩群數位"
2. ✅ Service features section (4 cards):
   - 在地化優先
   - 高投資轉換率
   - 數據優先
   - 關係優於銷售
3. ✅ Comparison table (恩群數位 vs 其他行銷公司)
4. ✅ CTA section ("跟行銷顧問聊聊")
5. ✅ Visual fidelity 95%+ compared to Webflow
6. ✅ Lighthouse Performance score 90+

**Integration Verification:**
- IV1: Verify that all sections display correctly
- IV2: Verify that comparison table formatting matches original
- IV3: Verify that CTA links to consultation form
- IV4: Verify responsive layout on mobile devices
- IV5: Verify performance and accessibility scores

**Estimated Effort:** 6-8 hours

---

### Story 1.7: Solutions Page Implementation

**As a** Visitor,
**I want to** see the marketing services offered,
**So that** I can understand how Enchun can help my business.

**Acceptance Criteria:**
1. ✅ Hero section with title "行銷方案"
2. ✅ Services list:
   - Google 商家關鍵字
   - Google Ads
   - 社群代操
   - 論壇行銷
   - 網紅行銷
   - 形象影片
3. ✅ Each service has description and details
4. ✅ "Hot" badge indicator
5. ✅ Visual fidelity 95%+ compared to Webflow
6. ✅ Lighthouse Performance score 90+

**Integration Verification:**
- IV1: Verify that all services display correctly
- IV2: Verify that "Hot" badge is visible
- IV3: Verify responsive layout
- IV4: Verify content can be managed via Payload CMS
- IV5: Verify performance targets met

**Estimated Effort:** 4-6 hours

---

### Story 1.8: Contact Page with Form

**As a** Potential Client,
**I want to** contact Enchun Digital through a form,
**So that** I can inquire about their services.

**Acceptance Criteria:**
1. ✅ Contact form with fields:
   - Name (required)
   - Email (required, validated)
   - Phone (optional)
   - Message (required)
   - Service interest (dropdown)
2. ✅ Form submission handled by Cloudflare Worker
3. ✅ Success/error message display
4. ✅ Contact information display:
   - Phone: 02-55700527
   - Email: enchuntaiwan@gmail.com
   - Facebook link
5. ✅ CTA section
6. ✅ Form validation on client and server
7. ✅ Visual fidelity 95%+ compared to Webflow

**Integration Verification:**
- IV1: Verify that form submission reaches Cloudflare Worker
- IV2: Verify that success message displays after submission
- IV3: Verify that validation errors display correctly
- IV4: Verify that spam protection works (honeypot or rate limiting)
- IV5: Verify that form data is properly stored/transmitted

**Estimated Effort:** 6-8 hours

---

### Story 1.9: Blog System Implementation

**As a** Visitor,
**I want to** browse marketing articles and insights,
**So that** I can learn from Enchun's expertise.

**Acceptance Criteria:**

**Blog Listing Page (`/blog`):**
1. ✅ Display all published posts
2. ✅ Category filter (4 categories)
3. ✅ Article cards with:
   - Featured image
   - Title
   - Excerpt
   - Category badge
   - Published date
4. ✅ Pagination or infinite scroll
5. ✅ Visual fidelity 95%+ compared to Webflow

**Article Detail Page (`/blog/[slug]`):**
1. ✅ Display full article content
2. ✅ Show category badge
3. ✅ Show published date
4. ✅ Related articles section (same category)
5. ✅ Social sharing buttons (OG tags configured)
6. ✅ Rich text rendering matches Webflow

**Category Page (`/blog/category/[slug]`):**
1. ✅ Filter articles by category
2. ✅ Show category description
3. ✅ Category color theming

**Integration Verification:**
- IV1: Verify that all 35+ articles are accessible
- IV2: Verify that category filtering works correctly
- IV3: Verify that article content formatting matches original
- IV4: Verify that related articles are actually related
- IV5: Verify that Open Graph tags work for social sharing
- IV6: Verify Lighthouse scores 90+ for all blog pages

**Estimated Effort:** 12-16 hours

---

### Story 1.10: Portfolio Implementation

**As a** Potential Client,
**I want to** see Enchun's past website projects,
**So that** I can evaluate their design capabilities.

**Acceptance Criteria:**

**Portfolio Listing (`/portfolio`):**
1. ✅ Display all portfolio items in 2-column grid
2. ✅ Each card shows:
   - Project image
   - Project title
   - Description
   - Tags (e.g., "一頁式銷售", "客戶預約")
3. ✅ Visual fidelity 95%+ compared to Webflow

**Project Detail (`/portfolio/[slug]`):**
1. ✅ Display project details
2. ✅ Link to live website
3. ✅ Additional images/slideshow (if available)
4. ✅ Case study content

**Integration Verification:**
- IV1: Verify that all portfolio items display correctly
- IV2: Verify that external links work
- IV3: Verify responsive grid layout
- IV4: Verify that images are optimized (WebP, responsive)
- IV5: Verify performance targets met

**Estimated Effort:** 6-8 hours

---

### Story 1.11: Teams Page Implementation

**As a** Visitor,
**I want to** see the Enchun team members,
**So that** I can know who will be working on my project.

**Acceptance Criteria:**
1. ✅ Display team member profiles
2. ✅ Each profile shows:
   - Photo
   - Name
   - Role/title
   - Bio (if available)
3. ✅ Responsive grid layout
4. ✅ Visual fidelity 95%+ compared to Webflow

**Integration Verification:**
- IV1: Verify that all team members display correctly
- IV2: Verify responsive layout
- IV3: Verify that images load from R2
- IV4: Verify content can be managed via Payload CMS

**Estimated Effort:** 4-6 hours

---

### Story 1.12: Authentication System Implementation

**As a** Content Editor or Admin,
**I want to** securely log in to the admin area,
**So that** I can manage website content.

**Acceptance Criteria:**

**Login Page (`/admin/login`):**
1. ✅ Login form with email/password
2. ✅ Error handling for invalid credentials
3. ✅ Redirect to /admin/dashboard after successful login
4. ✅ "Remember me" option (optional)
5. ✅ Password reset flow (email via Resend)

**Authentication Middleware:**
1. ✅ Protect all `/admin/*` routes
2. ✅ Redirect unauthenticated users to login
3. ✅ Use Payload CMS built-in authentication
4. ✅ Session management via HTTP-only cookies

**Role-Based Access Control:**
1. ✅ Admin role: Full access to CMS, settings, user management
2. ✅ Editor role: Content management only (no settings/users)
3. ✅ Access control functions enforced in Payload CMS

**Integration Verification:**
- IV1: Verify that login works with valid credentials
- IV2: Verify that invalid credentials show error message
- IV3: Verify that /admin/* redirects to /admin/login when not authenticated
- IV4: Verify that authenticated users can access /admin/dashboard
- IV5: Verify that role-based restrictions work (editor can't access settings)
- IV6: Verify that logout works correctly
- IV7: Verify that sessions persist across page refreshes

**Estimated Effort:** 8-10 hours

---

### Story 1.13: Admin Dashboard

**As an** Authenticated User,
**I want to** see a dashboard after logging in,
**So that** I can access key features quickly.

**Acceptance Criteria:**
1. ✅ Welcome message with user's name
2. ✅ Quick stats:
   - Total posts
   - Published posts
   - Draft posts
   - Total portfolio items
3. ✅ Quick actions:
   - Create new post
   - Create new portfolio item
   - Go to CMS admin
4. ✅ Recent activity list (last 5 content changes)
5. ✅ Logout button
6. ✅ Navigation to /admin/cms

**Integration Verification:**
- IV1: Verify that dashboard displays correct stats from Payload CMS
- IV2: Verify that quick actions navigate to correct pages
- IV3: Verify that recent activity is accurate
- IV4: Verify that only authenticated users can access dashboard

**Estimated Effort:** 4-6 hours

---

### Story 1.14: SEO Implementation

**As a** Marketing Manager,
**I want to** maintain SEO rankings after migration,
**So that** organic traffic is not lost.

**Acceptance Criteria:**

**Dynamic Sitemap:**
1. ✅ Generate `/sitemap.xml` automatically
2. ✅ Include all public pages
3. ✅ Include all blog posts
4. ✅ Include all portfolio items
5. ✅ Update when content changes

**Meta Tags:**
1. ✅ All pages have:
   - Meta title
   - Meta description
   - Open Graph title
   - Open Graph description
   - Open Graph image
   - Canonical URL
2. ✅ Payload CMS collections include SEO fields
3. ✅ Admin can edit SEO metadata per page/post

**301 Redirects:**
1. ✅ Create redirect map from Webflow URLs
2. ✅ Implement redirects in Astro
3. ✅ Test all critical redirects
4. ✅ Monitor 404 errors

**Google Analytics:**
1. ✅ Maintain existing GA tracking (G-DKBZWCGGZR)
2. ✅ GA script loads on all pages
3. ✅ Events tracked (form submissions, link clicks)

**Integration Verification:**
- IV1: Verify that sitemap.xml is accessible and valid
- IV2: Verify that all URLs in sitemap return 200 status
- IV3: Verify that meta tags appear in page source
- IV4: Verify that Open Graph tags work in social media previews
- IV5: Verify that 301 redirects preserve SEO equity
- IV6: Verify that Google Analytics receives data
- IV7: Verify Lighthouse SEO scores 95+

**Estimated Effort:** 8-10 hours

---

### Story 1.15: Performance Optimization

**As a** Visitor,
**I want to** pages load quickly,
**So that** I have a smooth browsing experience.

**Acceptance Criteria:**
1. ✅ Lighthouse Performance score 95+ on all public pages
2. ✅ First Contentful Paint (FCP) < 1.5s
3. ✅ Largest Contentful Paint (LCP) < 2.5s
4. ✅ All images optimized (WebP, responsive sizes)
5. ✅ Lazy loading for below-fold images
6. ✅ CSS/JS minified and split
7. ✅ Font loading optimized (preload critical fonts, font-display: swap)
8. ✅ CLS (Cumulative Layout Shift) < 0.1

**Integration Verification:**
- IV1: Run Lighthouse audit on all pages (desktop + mobile)
- IV2: Verify Core Web Vitals are in "Good" range
- III: Verify that images are served in modern formats
- IV4: Verify that lazy loading works correctly
- IV5: Verify that fonts don't cause FOUT/FOIT issues
- IV6: Verify that CLS score is acceptable

**Estimated Effort:** 8-12 hours

---

### Story 1.16: Deployment to Cloudflare

**As a** DevOps Engineer,
**I want to** deploy the application to Cloudflare,
**So that** the website is live and accessible.

**Acceptance Criteria:**

**Frontend Deployment (Cloudflare Pages):**
1. ✅ Build process generates optimized production bundle
2. ✅ Environment variables configured
3. ✅ Custom domain configured (www.enchun.tw)
4. ✅ SSL certificate active
5. ✅ CI/CD pipeline set up (auto-deploy on push to main)

**Backend Deployment (Cloudflare Workers):**
1. ✅ Payload CMS API deployed
2. ✅ Admin panel accessible at enchuntw-admin.anlstudio.cc
3. ✅ Cron jobs configured (if needed)
4. ✅ R2 storage configured and accessible

**DNS Configuration:**
1. ✅ DNS records point to Cloudflare
2. ✅ Propagation complete
3. ✅ DNSSEC configured (optional)

**Monitoring:**
1. ✅ Cloudflare Analytics enabled
2. ✅ Error tracking configured
3. ✅ Uptime monitoring configured

**Integration Verification:**
- IV1: Verify that www.enchun.tw loads correctly
- IV2: Verify that all pages are accessible (no 404s)
- IV3: Verify that /admin/cms loads and functions
- IV4: Verify that contact form submissions work
- IV5: Verify that Google Analytics tracks visits
- IV6: Verify that deployment process is automated

**Estimated Effort:** 6-8 hours

---

### Story 1.17: Testing and Quality Assurance

**As a** QA Engineer,
**I want to** thoroughly test the application,
**So that** there are no critical bugs at launch.

**Acceptance Criteria:**

**Cross-Browser Testing:**
1. ✅ Test on Chrome, Firefox, Safari, Edge
2. ✅ Test on latest 2 versions
3. ✅ Document any browser-specific issues

**Responsive Testing:**
1. ✅ Test on desktop (1920x1080, 1440x900)
2. ✅ Test on tablet (iPad 768x1024)
3. ✅ Test on mobile (iPhone 375x667, 414x896)
4. ✅ Verify no horizontal scroll at any size

**Functional Testing:**
1. ✅ Test all user flows:
   - Browse pages
   - Read blog articles
   - Submit contact form
   - Login/logout
   - Create/edit content (CMS)
2. ✅ Test all forms with valid and invalid data
3. ✅ Test all external links
4. ✅ Test all 301 redirects

**Performance Testing:**
1. ✅ Lighthouse audit all pages (desktop + mobile)
2. ✅ WebPageTest analysis
3. ✅ Verify Core Web Vitals

**Accessibility Testing:**
1. ✅ WCAG 2.1 AA compliance check
2. ✅ Keyboard navigation test
3. ✅ Screen reader test (basic)
4. ✅ Color contrast verification

**Integration Verification:**
- IV1: All critical bugs must be fixed before launch
- IV2: All known issues documented with severity
- IV3: Test coverage report generated
- IV4: Launch checklist completed

**Estimated Effort:** 12-16 hours

---

## Story Dependencies and Sequencing

### Critical Path
```
1.1 (Infrastructure)
  ↓
1.2 (Collections)
  ↓
1.3 (Migration) ← Can parallel with 1.4
  ↓
1.4 (Header/Footer)
  ↓
1.5 (Homepage) ← Must complete before other pages
  ↓
1.6, 1.7, 1.8, 1.9, 1.10, 1.11 (All pages) ← Can parallel
  ↓
1.12 (Authentication) ← Can start in parallel with pages
  ↓
1.13 (Dashboard)
  ↓
1.14 (SEO)
  ↓
1.15 (Performance)
  ↓
1.16 (Deployment)
  ↓
1.17 (Testing)
```

### Parallel Development Opportunities
- **Sprint 1:** Stories 1.1, 1.2 (infrastructure)
- **Sprint 2:** Stories 1.3, 1.4 (migration + layout)
- **Sprint 3:** Stories 1.5, 1.6, 1.7 (core pages)
- **Sprint 4:** Stories 1.8, 1.9, 1.10 (forms + blog + portfolio)
- **Sprint 5:** Stories 1.11, 1.12, 1.13 (teams + auth + dashboard)
- **Sprint 6:** Stories 1.14, 1.15 (SEO + performance)
- **Sprint 7:** Stories 1.16, 1.17 (deployment + testing)

---

## Estimated Timeline

**Total Estimated Effort:** 120-160 hours

**Team Size Assumption:** 1-2 developers

**Timeline:**
- **Week 1-2:** Infrastructure, Collections, Migration, Layout (Stories 1.1-1.4)
- **Week 3-4:** Core Pages Implementation (Stories 1.5-1.11)
- **Week 5:** Authentication and Dashboard (Stories 1.12-1.13)
- **Week 6:** SEO and Performance (Stories 1.14-1.15)
- **Week 7:** Deployment and Testing (Stories 1.16-1.17)

**Launch Readiness:** End of Week 7

---

**End of PRD**