pukpuklouis/website-enchun-mgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: generate implementation plan and design artifacts

Browse Source
This commit is contained in:
Louis Chen
2025-09-19 18:09:18 +08:00
parent 01a8fa90e8
commit 25c01d1418
15 changed files with 834 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
specs/001-users-pukpuk-dev/contracts/contact.yaml Normal file
View File

@@ -0,0 +1,27 @@
openapi: 3.0.0
info:
title: Contact Form API
version: 1.0.0
paths:
/contact:
post:
summary: Submit a contact form
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
format: email
message:
type: string
responses:
'200':
description: Form submission successful
'400':
description: Invalid request

32
specs/001-users-pukpuk-dev/contracts/login.yaml Normal file
View File

@@ -0,0 +1,32 @@
openapi: 3.0.0
info:
title: Login API
version: 1.0.0
paths:
/admin/login:
post:
summary: Authenticate a user
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
password:
type: string
responses:
'200':
description: Authentication successful
content:
application/json:
schema:
type: object
properties:
token:
type: string
'401':
description: Authentication failed

39
specs/001-users-pukpuk-dev/data-model.md Normal file
View File

@@ -0,0 +1,39 @@
# Data Model
This document defines the data structures for the project, based on the entities identified in the feature specification.
## User
Represents an authenticated user of the admin panel.
- **email**: `string` (required, unique)
- **password**: `string` (required, hashed)
- **role**: `enum` (required, values: `admin`, `editor`)
## Blog Post
Represents a single article.
- **title**: `string` (required)
- **slug**: `string` (required, unique)
- **content**: `richText` (required)
- **author**: `relationship` to `User` (required)
- **category**: `relationship` to `Category` (required)
- **publication_date**: `date` (required)
- **meta_title**: `string` (required)
- **meta_description**: `string` (required)
## Portfolio Item
Represents a single project.
- **title**: `string` (required)
- **slug**: `string` (required, unique)
- **description**: `richText` (required)
- **project_images**: `array` of `media` (required)
- **completion_date**: `date` (required)
- **meta_title**: `string` (required)
- **meta_description**: `string` (required)
## Category
Represents a blog post category.
- **name**: `string` (required)
- **slug**: `string` (required, unique)

212
specs/001-users-pukpuk-dev/plan.md Normal file
View File

@@ -0,0 +1,212 @@
# Implementation Plan: Website Migration to Astro with Payload CMS
**Branch**: `001-users-pukpuk-dev` | **Date**: 2025-09-19 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/Users/pukpuk/Dev/website-enchuntw-migr/specs/001-users-pukpuk-dev/spec.md`
## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
→ If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
→ Detect Project Type from context (web=frontend+backend, mobile=app+api)
→ Set Structure Decision based on project type
3. Fill the Constitution Check section based on the content of the constitution document.
4. Evaluate Constitution Check section below
→ If violations exist: Document in Complexity Tracking
→ If no justification possible: ERROR "Simplify approach first"
→ Update Progress Tracking: Initial Constitution Check
5. Execute Phase 0 → research.md
→ If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
7. Re-evaluate Constitution Check section
→ If new violations: Refactor design, return to Phase 1
→ Update Progress Tracking: Post-Design Constitution Check
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
9. STOP - Ready for /tasks command
```
**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)
## Summary
This plan outlines the migration of the enchun.tw website to a modern stack using Astro for the frontend and Payload CMS for the backend. The primary goal is to create a fast, static website with a secure, role-based admin area for content management. The technical approach involves using Astro for static site generation, Payload CMS for headless content management, and better-auth for authentication. The project will be deployed on Cloudflare Pages.
## Technical Context
**Language/Version**: Astro (JavaScript/TypeScript)
**Primary Dependencies**: Astro, Payload CMS, better-auth
**Storage**: N/A (handled by Payload CMS)
**Testing**: Vitest (unit), Playwright (e2e)
**Target Platform**: Cloudflare Pages
**Project Type**: web
**Performance Goals**: Google Lighthouse score of 90+ for Performance, Accessibility, Best Practices, and SEO.
**Constraints**: 3-month timeline, $10,000 budget.
**Scale/Scope**: ~50 blog posts, ~20 portfolio items.
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
No specific constitutional requirements found as the constitution file is a template.
## Project Structure
### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md # This file (/plan command output)
├── research.md # Phase 0 output (/plan command)
├── data-model.md # Phase 1 output (/plan command)
├── quickstart.md # Phase 1 output (/plan command)
├── contracts/ # Phase 1 output (/plan command)
└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
```
### Source Code (repository root)
```
# Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/
tests/
├── contract/
├── integration/
└── unit/
# Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│ ├── models/
│ ├── services/
│ └── api/
└── tests/
frontend/
├── src/
│ ├── components/
│ ├── pages/
│ └── services/
└── tests/
# Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]
ios/ or android/
└── [platform-specific structure]
```
**Structure Decision**: Option 2: Web application
## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
2. **Generate and dispatch research agents**:
```
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
```
3. **Consolidate findings** in `research.md` using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
**Output**: research.md with all NEEDS CLARIFICATION resolved
## Phase 1: Design & Contracts
*Prerequisites: research.md complete*
1. **Extract entities from feature spec** → `data-model.md`:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
2. **Generate API contracts** from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to `/contracts/`
3. **Generate contract tests** from contracts:
- One test file per endpoint
- Assert request/response schemas
- Tests must fail (no implementation yet)
4. **Extract test scenarios** from user stories:
- Each story → integration test scenario
- Quickstart test = story validation steps
5. **Update agent file incrementally** (O(1) operation):
- Run `.specify/scripts/bash/update-agent-context.sh gemini` for your AI assistant
- If exists: Add only NEW tech from current plan
- Preserve manual additions between markers
- Update recent changes (keep last 3)
- Keep under 150 lines for token efficiency
- Output to repository root
**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*
**Task Generation Strategy**:
- Load `.specify/templates/tasks-template.md` as base
- **Astro Setup**: Create tasks for initializing the Astro project, installing dependencies, and configuring the project.
- **Payload CMS Collections**: Generate tasks for creating the `Users`, `Blog Posts`, `Portfolio Items`, and `Categories` collections in Payload CMS, based on `data-model.md`.
- **Authentication**: Create tasks for implementing the login functionality using `better-auth`, including creating the login page and protecting the admin routes.
- **Frontend Development**: Generate tasks for creating the Astro components for the header, footer, blog page, portfolio page, and contact form.
- **Content Migration**: Create tasks for migrating the content from the old site to the new Payload CMS.
- **Deployment**: Generate tasks for setting up the deployment pipeline to Cloudflare Pages.
**Ordering Strategy**:
- TDD order: Tests before implementation
- Dependency order: Payload CMS setup before frontend development.
- Mark [P] for parallel execution (independent files)
**Estimated Output**: 30-40 numbered, ordered tasks in tasks.md
**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*
**Phase 3**: Task execution (/tasks command creates tasks.md)
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
## Progress Tracking
*This checklist is updated during execution flow*
**Phase Status**:
- [X] Phase 0: Research complete (/plan command)
- [X] Phase 1: Design complete (/plan command)
- [X] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed
**Gate Status**:
- [X] Initial Constitution Check: PASS
- [X] Post-Design Constitution Check: PASS
- [X] All NEEDS CLARIFICATION resolved
- [ ] Complexity deviations documented
---
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*

50
specs/001-users-pukpuk-dev/quickstart.md Normal file
View File

@@ -0,0 +1,50 @@
# Quickstart Guide
This guide provides instructions for setting up the project and running the tests.
## Prerequisites
- Node.js (v18 or later)
- pnpm
## Setup
1. **Clone the repository**:
```bash
git clone <repository-url>
cd <repository-name>
```
2. **Install dependencies**:
```bash
pnpm install
```
3. **Set up environment variables**:
Create a `.env` file in the root of the project and add the following variables:
```
PAYLOAD_CMS_URL=...
PAYLOAD_CMS_API_KEY=...
```
## Running the development server
```bash
pnpm dev
```
The application will be available at `http://localhost:4321`.
## Running the tests
### Unit tests
```bash
pnpm test:unit
```
### End-to-end tests
```bash
pnpm test:e2e
```

37
specs/001-users-pukpuk-dev/research.md Normal file
View File

@@ -0,0 +1,37 @@
# Phase 0: Research
## Testing Strategy
**Decision**: Use Vitest for unit testing Astro components and Playwright for end-to-end testing.
**Rationale**:
- **Vitest**: It's a fast and modern test runner that's compatible with Vite, which Astro uses under the hood. It's easy to set up and has a similar API to Jest.
- **Playwright**: It's a powerful end-to-end testing framework that allows testing across different browsers. It's great for simulating user interactions and verifying the complete functionality of the site.
**Alternatives considered**:
- **Jest**: A popular testing framework, but Vitest is more modern and better integrated with the Vite ecosystem.
- **Cypress**: Another popular end-to-end testing framework, but Playwright has better cross-browser support.
## Performance Goals
**Decision**: Aim for a Google Lighthouse score of 90+ for Performance, Accessibility, Best Practices, and SEO.
**Rationale**: This is a widely accepted benchmark for web performance and user experience. Achieving these scores will ensure a fast and accessible website.
**Alternatives considered**: None, as this is a standard best practice.
## Constraints
**Decision**: The project should be completed within 3 months and stay within a budget of $10,000.
**Rationale**: These constraints are based on the client's requirements.
**Alternatives considered**: None.
## Scale/Scope
**Decision**: The initial scope is to migrate the existing content from the old site to the new Astro and Payload CMS setup. This includes ~50 blog posts and ~20 portfolio items.
**Rationale**: This is based on the analysis of the existing sitemap and CMS structure.
**Alternatives considered**: None.

68
specs/001-users-pukpuk-dev/spec.md Normal file
View File

@@ -0,0 +1,68 @@
# 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."
---
## 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).
---
## 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).
### 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, SEO metadata.
- **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.
---
## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*
### Content Quality
- [X] No implementation details (languages, frameworks, APIs)
- [X] Focused on user value and business needs
- [X] Written for non-technical stakeholders
- [X] All mandatory sections completed
### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [X] Requirements are testable and unambiguous
- [X] Success criteria are measurable
- [X] Scope is clearly bounded
- [X] Dependencies and assumptions identified