website-enchun-mgr/specs/001-users-pukpuk-dev/spec.md

Feature Specification: Website Migration to Astro with Payload CMS

Feature Branch: 001-users-pukpuk-dev Created: 2025-09-18 Status: Draft Input: User description: "From PRD.md: Migrate enchun.tw to Astro, using Payload CMS for content. The site needs a secure admin area with role-based access for editors and admins. Deploy on Cloudflare."

---

Clarifications

Session 2025-10-06

• Q: What is the expected number of blog posts and portfolio items to be migrated? → A: 35
• Q: What are the possible states for blog posts? → A: published, draft, schedule publish
• Q: How will the system handle concurrent edits to the same content item? → A: Last write wins
• Q: What are the specific security measures for user authentication and data protection? → A: SSL/TLS certificates, input validation, regular security audits
• Q: What is the expected daily traffic volume for the website? → A: 500-2000 visitors per day

User Scenarios & Testing (mandatory)

Primary User Story

As a content editor, I want to log in to a secure admin area to create, edit, and manage blog posts and portfolio items through a user-friendly interface, so that I can keep the website content up-to-date without needing technical assistance.

As an administrator, I want to manage all site content and also control user access, so that I can ensure the site is secure and only authorized personnel can make changes.

As a public visitor, I want to browse a fast, well-structured, and informative website to learn about the company's services.

Acceptance Scenarios

1. Given an unauthenticated user, When they navigate to /admin/cms, Then they are redirected to the /admin/login page.
2. Given a user with an editor role is logged in, When they navigate to /admin/cms, Then they can access the content editing interface for blogs and portfolios but cannot see user management settings.
3. Given a user with an admin role is logged in, When they navigate to /admin/cms, Then they can access all content editing and user management features.
4. Given a public visitor, When they navigate to a URL from the old sitemap (e.g., /xing-xiao-fang-da-jing/storytelling), Then they are permanently redirected (301) to the new URL (/blog/storytelling).

Edge Cases

• What happens when a logged-in user's session expires? (System should redirect to the login page on the next action).
• How does the system handle a user trying to access an admin URL they don't have the role for? (System should show a "Permission Denied" or 403 error page).
• What happens if the Payload CMS API is unavailable during the static site build? (The build process should fail with a clear error message).
• Concurrent edits to the same content item are resolved by "last write wins" (latest save overwrites previous changes).

---

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST provide a secure login page at /admin/login.
• FR-002: The system MUST protect all routes under the /admin/ path, requiring user authentication.
• FR-003: The system MUST define at least two user roles: admin and editor.
• FR-004: admin users MUST have full access to all CMS collections and settings, including user management.
• FR-005: editor users MUST have access to content-related collections (e.g., Posts, Portfolios, Categories) but MUST NOT have access to system settings or user management.
• FR-006: The system MUST fetch all public content from a Payload CMS instance at build time to generate a static frontend.
• FR-007: The system MUST implement a 301 redirect map for all URLs listed in the original sitemap to their new, redesigned equivalents.
• FR-008: The system MUST provide a functional contact form on the /contact page.
• FR-009: The system MUST generate a sitemap.xml file based on the content stored in the CMS.
• FR-010: All content types in the CMS MUST include dedicated fields for SEO metadata (meta title, meta description).
• FR-011: The system MUST implement security measures including SSL/TLS certificates, input validation, and regular security audits for authentication and data protection.

Key Entities (include if feature involves data)

• User: Represents an authenticated user of the admin panel. Attributes: email, password hash, role (admin or editor).
• Blog Post: Represents a single article. Attributes: title, slug, content, author, category, publication date, state (draft, published, scheduled), SEO metadata. Lifecycle: Can transition from draft to scheduled to published.
• Portfolio Item: Represents a single project. Attributes: title, slug, description, project images, completion date, SEO metadata.
• Category: Represents a blog post category. Attributes: name, slug.

Expected data volume: Approximately 35 blog posts and portfolio items combined.

Non-Functional Requirements

• Scalability: Expected daily traffic of 500-2000 visitors.

---

Review & Acceptance Checklist

GATE: Automated checks run during main() execution

Content Quality

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
• Success criteria are measurable
• Scope is clearly bounded
• Dependencies and assumptions identified