# 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

```typescript
// 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](./03-ui-enhancement-goals.md)