pukpuk
c2d4c8d0a0
Add comprehensive workflow commands for AI-assisted development: - Claude commands: analyze, clarify, plan - Kilocode workflows: full feature development lifecycle - Opencode commands: specification and implementation workflows - Roo MCP configuration for tool integration Update .gitignore to exclude .astro build cache directories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
142 lines
8.9 KiB
Markdown
142 lines
8.9 KiB
Markdown
# 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. |