docs: separate documentation and specs into initial commit

Establish baseline for project documentation including BMAD specs, PRD, and system architecture notes.
2026-02-11 11:49:49 +08:00
parent 8c87d71aa2
commit e9897388dc
34 changed files with 11920 additions and 8777 deletions
--- a/PRD.md
+++ b/PRD.md
@@ -1,107 +1,140 @@
-### **Product Requirements Document: `enchun.tw` Website Migration to Astro (v2)**
+# Enchun.tw Website Migration - Product Requirements Document

-**1. Introduction**
+**Status:** Active
+**Version:** v4 (Brownfield Migration)
+**Last Updated:** 2025-01-29
+**Project:** Enchun CMS System Migration

-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**
+## 📋 Quick Navigation

-*   **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.
+**📘 Complete PRD:** See [`docs/prd.md`](./docs/prd.md) for the full documentation structure

-**3. Target Audience**
+**Key Sections:**
+- [Project Analysis](./docs/prd/01-project-analysis.md) - Background and scope
+- [Requirements](./docs/prd/02-requirements.md) - Functional and non-functional requirements
+- [UI Enhancement Goals](./docs/prd/03-ui-enhancement-goals.md) - Design system and pages
+- [Technical Constraints](./docs/prd/04-technical-constraints.md) - Architecture and integration
+- [Epic and Stories](./docs/prd/05-epic-stories.md) - Detailed user stories

-*   **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.
+**Archived Documentation:**
+- [Legacy PRD v1](./docs/archive/PRD-v1-legacy.md) - Original PRD with Auth.js references (archived 2025-01-29)

-**4. Functional Requirements**
+---

-**4.1. Redesigned Page Structure & Routing**
+## 🎯 Executive Summary

-The application will feature a clear separation between public and protected routes.
+This document defines the requirements for migrating the existing `enchun.tw` website from Webflow CMS to a modern architecture using **Payload CMS** and **Astro (SSR)**.

-*   **Public Routes:**
-    *   `/` (Homepage)
-    *   `/about`
-    *   `/contact`
-    *   `/solutions`
-    *   `/blog` (Blog listing page)
-    *   `/blog/[slug]` (Individual blog posts)
-    *   `/blog/category/[category-slug]` (Blog category pages)
-    *   `/portfolio` (Portfolio listing page)
-    *   `/portfolio/[slug]` (Individual portfolio projects)
-    *   `/teams`
-    *   `/marketing-class`
+### Migration Objectives

-*   **Protected Routes (Require Authentication):**
-    *   `/admin/login` (Login page)
-    *   `/admin/dashboard` (A general dashboard for authenticated users)
-    *   `/admin/cms` (The embedded Payload CMS admin interface)
+- ✅ Migrate 7 main pages + 35+ blog articles + 4 categories
+- ✅ Implement **Payload CMS built-in authentication** (Admin/Editor roles)
+- ✅ Achieve Lighthouse 95+ performance scores
+- ✅ Deploy to Cloudflare infrastructure
+- ✅ Maintain 95%+ visual fidelity to original Webflow design
+- ✅ Preserve SEO value with 301 redirects

-**4.2. Authentication & Authorization**
+### Technology Stack

-*   **Authentication Provider:** The site will use **Auth.js (`astro-auth`)** to handle user authentication.
-*   **Login:** A dedicated login page will be available at `/admin/login`.
-*   **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.
+| Component | Technology |
+|-----------|------------|
+| **Frontend** | Astro 4.x (SSR mode) + Tailwind CSS |
+| **Backend/CMS** | Payload CMS 3.x + MongoDB |
+| **Authentication** | ✅ Payload CMS built-in (NOT Auth.js) |
+| **Storage** | Cloudflare R2 |
+| **Deployment** | Cloudflare Pages (frontend) + Workers (backend) |

-**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.
+## 🚀 Migration Priority

-**5. Non-Functional Requirements**
+| Priority | Scope | Estimated Time |
+|----------|-------|----------------|
+| **P0** | Header, Footer, Home, Contact | 19-28h |
+| **P1** | About, Solutions, Teams, Portfolio | 24-32h |
+| **P2** | Blog system (list, categories, articles) | 30-44h |

-*   **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 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.
+**Total Estimate:** 120-160 hours (7 weeks for 1-2 developers)

-**6. Technology Stack**
+---

-*   **Framework:** Astro (in SSR mode)
-*   **Authentication:** Auth.js (`astro-auth`)
-*   **UI Components:** Astro components
-*   **Styling:** Tailwind CSS
-*   **CMS:** Payload CMS
-*   **Deployment:** Cloudflare Pages & Cloudflare Workers
+## 📊 Key Requirements Summary

-**7. Migration Plan (High-Level)**
+### Functional Requirements (Highlights)
+- **FR3:** Payload CMS built-in authentication system ✅
+- **FR4:** Migrate 35+ articles and 4 categories
+- **FR6:** Complete 301 redirect mappings
+- **FR12:** Responsive design across all devices

-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 Cloudflare Workers inside `backend/`.
-    *   Configure Tailwind CSS and shared TypeScript utilities in `packages/shared/`.
-2.  **Phase 2: Authentication & CMS Setup**
-    *   Integrate `astro-auth` 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 full stack to Cloudflare.
-    *   Configure DNS and go live.
+### Non-Functional Requirements (Highlights)
+- **NFR1:** Lighthouse scores 95+ (all public pages)
+- **NFR2:** FCP < 1.5s, LCP < 2.5s
+- **NFR3:** WCAG 2.1 AA compliance
+- **NFR10:** 80%+ test coverage

-**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.
+## 🔑 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 handles Users collection directly
+- Cookie-based sessions via HTTP-only cookies
+- `/api/users/login` endpoint provided by Payload
+- RBAC through Payload's access control functions
+
+---
+
+## 📂 Document Structure
+
+```
+website-enchun-mgr/
+├── PRD.md                          # This file (overview)
+├── docs/
+│   ├── prd.md                      # Main PRD index
+│   ├── prd/
+│   │   ├── 01-project-analysis.md
+│   │   ├── 02-requirements.md
+│   │   ├── 03-ui-enhancement-goals.md
+│   │   ├── 04-technical-constraints.md
+│   │   └── 05-epic-stories.md
+│   └── archive/
+│       └── PRD-v1-legacy.md        # Old PRD with Auth.js references
+├── cms_structure.md                # CMS collection reference
+└── research/
+    └── www.enchun.tw/              # Original Webflow HTML files
+```
+
+---
+
+## 🎯 Success Criteria
+
+The migration will be considered successful when:
+
+1. ✅ All 7 main pages are migrated with 95%+ visual fidelity
+2. ✅ All content (35+ articles, portfolio items) is accessible
+3. ✅ Authentication system works (Admin/Editor roles)
+4. ✅ Lighthouse scores 95+ on all public pages
+5. ✅ 301 redirects preserve SEO traffic
+6. ✅ Contact form submissions work correctly
+7. ✅ Website is deployed and accessible at www.enchun.tw
+
+---
+
+## 📞 Quick Links
+
+- **CMS Structure:** [`cms_structure.md`](./cms_structure.md)
+- **Original Website:** [`research/www.enchun.tw/`](./research/www.enchun.tw/)
+- **Full PRD:** [`docs/prd.md`](./docs/prd.md)
+
+---
+
+**Document maintained by:** Product Manager (PM Agent)
+**Last Updated:** 2025-01-29