website-enchun-mgr/combined-prd-plan.md

Combined Document: PRD and Astro Migration Plan

Product Requirements Document: enchun.tw Website Migration to Astro (v2)

1. Introduction

This document outlines the requirements for migrating the existing enchun.tw website to a new, modern web application built with the Astro framework and managed by Payload CMS. The primary goal is to create a faster, more secure, and more maintainable website, complete with a secure authentication system and a user-friendly editing experience for copywriters. The project will preserve all existing content, functionality, and SEO value while implementing a more logical site structure.

2. Goals & Objectives

• Performance: Achieve Lighthouse scores of 95+ on public-facing pages.
• Maintainability: Provide a user-friendly, web-based interface for content editors via Payload CMS, protected by a robust authentication system.
• Developer Experience: Leverage Astro's modern features for a fast frontend build process and easier component management.
• Security: Implement role-based access control (RBAC) to secure the CMS and dashboard areas.
• Future-Proofing: Build on a modern, flexible stack that can easily integrate with other services and APIs.

3. Target Audience

• Public Users: Potential and existing clients, industry peers.
• Authenticated Users:
  • Content Editors/Copywriters: Internal team members who will manage website content.
  • Administrators: Technical staff responsible for managing users and site settings.

4. Functional Requirements

4.1. Redesigned Page Structure & Routing

The application will feature a clear separation between public and protected routes.

• Public Routes:

  • / (Homepage)
  • /about-enchun
  • /contact-us
  • /marketing-solutions
  • /news (Blog listing page)
  • /teams
  • /website-portfolio (Portfolio listing page)

• Dynamic Routes:

  • /xing-xiao-fang-da-jing/[slug] (Individual blog posts)
  • /wen-zhang-fen-lei/[slug] (Blog category pages)
  • /webdesign-profolio/[slug] (Individual portfolio projects)

• Protected Routes (Require Authentication):

  • /admin/login (Login page)
  • /admin/dashboard (A general dashboard for authenticated users)
  • /admin/cms (The embedded Payload CMS admin interface)

4.2. Authentication & Authorization

• Authentication Provider: The site will use Payload CMS default authentication method.
• Login: The frontend Astro does not have a login button; use a subdomain to connect to Payload CMS.
• Access Control: All routes under /admin/* will be protected. Unauthenticated users attempting to access these routes will be redirected to the login page.
• Role-Based Access Control (RBAC):
  • Administrator (admin): Full access to the Payload CMS, including content creation/editing, user management, and system settings.
  • Editor (editor): Can create, edit, and manage content (blog posts, portfolio items) but cannot access system settings or manage users.
  • The CMS and dashboard will restrict visibility and actions based on the logged-in user's role.

4.3. Key Features

• Content Management: All public content will be managed via a self-hosted Payload CMS instance. The CMS admin panel will be accessible only to authenticated users at /admin/cms.
• Contact Form: The public /contact page will feature a functional contact form. Submissions will be handled securely by a Cloudflare Worker.
• SEO:
  • A dynamic sitemap.xml will be automatically generated.
  • Payload CMS will include dedicated SEO fields (meta title, description, Open Graph tags) for all pages and collections.
  • Redirects: A 301 redirect map will be implemented to permanently redirect all old URLs from enchun-sitemap.md to their new, redesigned equivalents to preserve SEO equity.

5. Non-Functional Requirements

• Styling: The project will use Tailwind CSS.
• Accessibility: The site must adhere to WCAG 2.1 AA standards.
• Deployment: The Astro frontend will be deployed on Cloudflare Pages in SSR (Server-Side Rendering) mode to support the authentication layer. The Payload CMS backend will run on self-hosted Coolify platform, and serverless functions will run on Cloudflare Workers.
• Workspace Layout: Monorepo managed with pnpm workspaces. Packages include frontend/ (Astro), backend/ (Payload CMS), and packages/shared/ for cross-cutting TypeScript utilities.

6. Technology Stack

• Framework: Astro (in SSR mode)
• Authentication: Payload CMS default authentication
• UI Components: Astro components
• Styling: Tailwind CSS
• CMS: Payload CMS is deploy on self-hosted coolify platform
• Deployment: Cloudflare Pages & Cloudflare Workers

7. Migration Plan (High-Level)

1. Phase 1: Project Setup
   • Initialize a pnpm workspace monorepo with frontend/, backend/, and packages/shared/.
   • Initialize a new Astro project configured for SSR inside frontend/.
   • Set up Payload CMS for self-hosted Coolify platform inside backend/.
   • Configure Tailwind CSS and shared TypeScript utilities in packages/shared/.
2. Phase 2: Authentication & CMS Setup
   • Integrate Payload CMS authentication and configure the login flow.
   • Define the collections and user roles (admin, editor) within Payload.
3. Phase 3: Content Migration
   • Write a script to import content from the CSV files into the Payload CMS via its API.
4. Phase 4: Page & Template Implementation
   • Build all public pages and templates, fetching data from the Payload API.
   • Build the protected /admin area, including the dashboard and the embedded CMS panel.
5. Phase 5: Functionality & SEO
   • Implement the contact form with its Cloudflare Worker backend.
   • Implement the 301 redirect map and all other SEO requirements.
6. Phase 6: Testing & Deployment
   • Thoroughly test all public pages, protected routes, user roles, and functionality.
   • Deploy the Astro frontend to Cloudflare Pages, and the Payload CMS backend to Coolify.
   • Configure DNS and go live.

8. Out of Scope

• Frontend user accounts or public-facing login capabilities.
• A complete visual redesign. The project aims to migrate the existing design to the new framework.

Astro Migration Plan

Phase 1 – Discovery & Gap Analysis

• Inventory research/www.enchun.tw/ HTML assets and map them against route-structure.md to verify required routes.
• Capture shared partials (headers, footers, CTA blocks) and cross-page assets (images, fonts, scripts).
• Note gaps between scraped content and Payload CMS scope to prevent out-of-scope feature work.

Phase 2 – Astro Foundation

• Confirm Astro project root (frontend/ vs apps/frontend/) and align pnpm workspace filters.
• Configure TypeScript support, Tailwind/global styles, and a base src/layouts/Layout.astro that centralizes <head>, navigation, and footer markup.
• Migrate critical global CSS from enchun.webflow.shared*.css, pruning unused rules to keep the baseline lean.

Phase 3 – Component Extraction

• Break repeated HTML fragments (hero modules, feature grids, testimonial sliders, footer columns) into focused components under src/components/.
• Expose component props for dynamic content (titles, copy, imagery) to support later CMS integration.
• Scope styles with component-level CSS modules or Tailwind utilities to avoid collisions and honor DRY.

Phase 4 – Route Implementation

• Translate each static page (index, about-enchun, marketing-solutions, teams, contact-us, news, website-portfolio) into .astro files inside src/pages/, preserving current URL structure.
• Stand up dynamic routes (xing-xiao-fang-da-jing/[slug].astro, wen-zhang-fen-lei/[slug].astro, webdesign-profolio/[slug].astro) with loaders that read corresponding HTML files until Payload integration lands.
• Add fallbacks for missing slugs (404 handling) to preserve production stability.

Phase 5 – Data & CMS Integration

• Implement src/services/payload.ts helpers that wrap Payload REST/GraphQL endpoints, returning typed data models.
• Wire page frontmatter or Astro getStaticPaths/getStaticProps to these helpers for dynamic collections.
• Keep CMS-specific logic isolated so components remain presentational and adhere to SOLID.

Phase 6 – QA & Deployment

• Add smoke coverage with Vitest for critical components and Playwright flows for forms/navigation if time permits.
• Configure Cloudflare Pages build: command pnpm --filter frontend build, output directory frontend/dist (adjust if project root differs).
• Validate sitemap, robots, and redirects before launch; document required environment variables (PAYLOAD_CMS_URL, PAYLOAD_CMS_API_KEY) for Cloudflare.