docs: add research assets, screenshots and guides

Include supplementary documentation, research notes on Lexical/UX, and setup guides.
2026-02-11 11:51:35 +08:00
parent ad8e2e313e
commit f6b806617e
46 changed files with 11571 additions and 0 deletions
--- a/docs/prd/05-epic-stories.md
+++ b/docs/prd/05-epic-stories.md
@@ -0,0 +1,678 @@
+# 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**