From 4efabd168c4376d4c7d919b4c091e708b83d89f4 Mon Sep 17 00:00:00 2001 From: Louis Date: Mon, 22 Sep 2025 16:53:47 +0800 Subject: [PATCH] refactor: align plan and tasks with PRD, remove e-commerce scope --- specs/001-users-pukpuk-dev/plan.md | 212 +++++----------------------- specs/001-users-pukpuk-dev/tasks.md | 110 ++++++--------- 2 files changed, 74 insertions(+), 248 deletions(-) diff --git a/specs/001-users-pukpuk-dev/plan.md b/specs/001-users-pukpuk-dev/plan.md index c552c3f..30c14fe 100644 --- a/specs/001-users-pukpuk-dev/plan.md +++ b/specs/001-users-pukpuk-dev/plan.md @@ -1,212 +1,64 @@ -# Implementation Plan: Website Migration to Astro with Payload CMS +# Implementation Plan: Website Migration to Astro (v2) **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) +**Input**: Feature specification from `/Users/pukpuk/Dev/website-enchuntw-migr/specs/001-users-pukpuk-dev/spec.md` and `PRD.md`. ## 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. +This plan outlines the migration of `enchun.tw` to a modern stack using Astro (SSR mode) for the frontend and Payload CMS for the backend, deployed on Cloudflare. The project will create a fast, static website with a secure, role-based admin area for content management using Auth.js, styled with Tailwind CSS. E-commerce functionality is explicitly out of scope. ## Technical Context **Language/Version**: Astro (JavaScript/TypeScript) -**Primary Dependencies**: Astro, Payload CMS, better-auth +**Primary Dependencies**: Astro, Payload CMS, Auth.js (`astro-auth`), Tailwind CSS **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. +**Target Platform**: Cloudflare Pages (SSR) & Cloudflare Workers +**Project Type**: Monorepo (pnpm workspaces) +**Performance Goals**: Google Lighthouse score of 95+ +**Constraints**: Adherence to WCAG 2.1 AA standards. +**Scale/Scope**: Migration of existing content (~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) -``` +**Structure Decision**: Monorepo with `frontend/`, `backend/`, and `packages/shared/` as per `PRD.md`. ### 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] +/ +├── backend/ # Payload CMS on Cloudflare Workers +├── frontend/ # Astro (SSR) on Cloudflare Pages +├── packages/ +│ └── shared/ # Shared TypeScript utilities, Tailwind config +└── pnpm-workspace.yaml ``` -**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 +Completed. Decisions are reflected in the Technical Context. ## 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 +Completed. Artifacts `data-model.md`, `contracts/`, and `quickstart.md` are still valid. ## 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] | +- **Workspace Setup**: Initialize pnpm monorepo. +- **Backend Setup**: Configure Payload CMS collections (`Users`, `BlogPosts`, etc.) for Cloudflare. +- **Frontend Setup**: Configure Astro (SSR) with Tailwind CSS. +- **Authentication**: Integrate Auth.js (`astro-auth`) for `/admin/*` routes. +- **Component & Page Creation**: Build all pages and components as per the `PRD.md` and corrected `route-structure.md`. +- **Content Migration**: Script the import of existing content into Payload. +- **SEO & Redirects**: Implement the 301 redirect map. +- **Testing**: Write contract, integration, and unit tests for the new structure. +- **Deployment**: Configure Cloudflare Pages & Workers deployment. +**Estimated Output**: 30-40 numbered, ordered tasks in `tasks.md`. ## 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) +- [X] Phase 0: Research complete +- [X] Phase 1: Design complete +- [X] Phase 2: Task planning complete (approach described) +- [ ] Phase 3: Tasks generated - [ ] 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`* diff --git a/specs/001-users-pukpuk-dev/tasks.md b/specs/001-users-pukpuk-dev/tasks.md index bcfef55..2a1c7b2 100644 --- a/specs/001-users-pukpuk-dev/tasks.md +++ b/specs/001-users-pukpuk-dev/tasks.md @@ -1,86 +1,60 @@ -# Tasks for Website Migration (Revised) +# Tasks for Website Migration (v2 - Corrected) **Feature**: Website Migration to Astro with Payload CMS **Branch**: `001-users-pukpuk-dev` -This document has been updated to reflect the corrected route structure from the sitemap. +This task list is aligned with the official `PRD.md` and excludes all e-commerce functionality. --- -## Phase 1: Project Setup +## Phase 1: Workspace & Project Setup -- **T001**: Initialize a new Astro project in the `frontend` directory. -- **T002**: Initialize a new Payload CMS project in the `backend` directory. -- **T003**: Install all necessary dependencies for both projects, including `better-auth`, `vitest`, and `playwright`. -- **T004**: Configure linting and formatting for both projects. +- **T001**: Initialize a pnpm monorepo with `pnpm-workspace.yaml`. +- **T002**: Create `frontend/`, `backend/`, and `packages/shared/` directories. +- **T003**: Initialize the Astro project in `frontend/` configured for SSR (Server-Side Rendering). +- **T004**: Initialize the Payload CMS project in `backend/` configured for Cloudflare Workers. +- **T005**: Configure Tailwind CSS in the `packages/shared/` directory to be used by the `frontend` app. +- **T006**: Install all necessary dependencies across the workspace. ## Phase 2: Backend Development (Payload CMS) -- **T005**: **[P]** Create the `Users` collection in Payload CMS, as defined in `data-model.md`. -- **T006**: **[P]** Create the `BlogPosts` collection in Payload CMS, corresponding to `/xing-xiao-fang-da-jing`. -- **T007**: **[P]** Create the `PortfolioItems` collection in Payload CMS, corresponding to `/webdesign-profolio`. -- **T008**: **[P]** Create the `Categories` collection in Payload CMS, corresponding to `/wen-zhang-fen-lei`. -- **T009**: Configure role-based access control for `admin` and `editor` roles in Payload. -- **T010**: Implement the authentication logic and API endpoint using `better-auth`. +- **T007**: **[P]** Create the `Users` collection in Payload CMS with `admin` and `editor` roles. +- **T008**: **[P]** Create the `BlogPosts` collection in Payload CMS. +- **T009**: **[P]** Create the `PortfolioItems` collection in Payload CMS. +- **T010**: **[P]** Create the `Categories` collection in Payload CMS. +- **T011**: Configure Payload to use Auth.js for authentication. ## Phase 3: Frontend Development (Astro) -- **T011**: **[P]** Create the main site layout (`Layout.astro`) with `
` and `