# 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.