pkupuk
f6b806617e
Include supplementary documentation, research notes on Lexical/UX, and setup guides.
114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
# 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)
|