website-enchun-mgr/docs/prd/02-requirements.md

2. Requirements

Last Updated: 2025-01-29

Note: These requirements are based on the understanding of the existing Webflow to Payload CMS + Astro migration. Please review carefully to ensure alignment with project reality.

Functional Requirements

FR1: The system must fully migrate all 7 main pages (Home, About, Solutions, Marketing Magnifier/Blog, Teams, Portfolio, Contact) to the new Astro architecture while maintaining 95%+ visual similarity to the original Webflow design.

FR2: The system must implement Payload CMS as a Headless CMS supporting Users, Posts, Categories, Portfolio, and Media collections.

FR3: The system must implement authentication based on Payload CMS built-in authentication system, supporting Admin and Editor roles, with secure login/logout functionality.

FR4: The system must migrate all 35+ blog articles and 4 article categories (Google小學堂, Meta小學堂, 行銷時事最前線, 恩群數位最新公告) to Payload CMS.

FR5: The system must provide complete SEO support for all pages and articles, including dynamic sitemap.xml generation, meta tags, and Open Graph tags.

FR6: The system must implement complete 301 redirect mappings to redirect all old Webflow URLs to the new URL structure.

FR7: The contact form must function correctly, with submissions processed securely through a Cloudflare Worker.

FR8: The Payload CMS admin interface must be embedded at the /admin/cms route and accessible only to authenticated users.

FR9: The system must support Role-Based Access Control (RBAC), where Admins have access to all features, while Editors can only manage content but cannot modify system settings or users.

FR10: The system must provide a protected /admin/dashboard route as a general dashboard for authenticated users.

FR11: All media files (images, documents) must be migrated to Cloudflare R2 storage and correctly referenced in Payload CMS.

FR12: The system must support responsive design, maintaining consistent user experience across desktop, tablet, and mobile devices.

---

Non-Functional Requirements

NFR1: All public pages must achieve Lighthouse performance scores of 95+ (Performance, Accessibility, Best Practices, SEO).

NFR2: First Contentful Paint (FCP) should be under 1.5 seconds, and Largest Contentful Paint (LCP) should be under 2.5 seconds.

NFR3: Pages must comply with WCAG 2.1 AA accessibility standards.

NFR4: The system must support at least 100 concurrent users without performance degradation.

NFR5: All API response times must be under 500ms (95th percentile).

NFR6: The system must protect all sensitive data using HTTPS and security headers.

NFR7: Payload CMS and Astro frontend must be deployed to Cloudflare infrastructure to ensure global CDN acceleration.

NFR8: Pages must use Traditional Chinese (繁體中文).

NFR9: The system must log all critical operations (login, content changes, settings modifications) for audit purposes.

NFR10: Code must follow TypeScript and ESLint best practices and maintain 80%+ test coverage.

---

Compatibility Requirements

CR1: The new system must maintain compatibility with existing Google Analytics (G-DKBZWCGGZR) without disrupting data tracking.

CR2: The Payload CMS database schema must be able to map all existing Webflow CMS collections and fields without losing any content data.

CR3: UI/UX must maintain consistency with the original Webflow design, including:

• Fonts: Noto Sans TC and Quicksand
• Color schemes
• Responsive breakpoints
• Interaction patterns and animations

CR4: The system must maintain compatibility with existing social media integrations (Facebook, Google Analytics).

CR5: 301 redirects must ensure that all external links and bookmarks remain valid.

---

Technical Clarifications

Authentication System Clarification

❌ Incorrect (Legacy Documentation):

"The site will use Auth.js (astro-auth) to handle user authentication."

✅ Correct (Actual Implementation):

"The site will use Payload CMS built-in authentication system with cookie-based sessions."

Key Differences:

• Payload CMS Auth: Built-in, handles users collection directly, provides /api/users/login endpoint
• Session Management: Payload uses HTTP-only cookies for session storage
• Integration: Astro frontend communicates with Payload API for authentication verification
• RBAC: Implemented through Payload's access control functions (authenticated(), custom role checks)

API Integration Pattern

// Astro → Payload CMS Authentication Pattern
import { Payload } from '@payloadcms/payload'

// Verify session on protected routes
export async function GET({ request, locals }) {
  const user = locals.user // Set by Payload middleware

  if (!user) {
    return new Response(null, { status: 401 })
  }

  // Proceed with authenticated request
}

---

Next Section: User Interface Enhancement Goals