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

refactor: align plan and tasks with PRD, remove e-commerce scope

Browse Source
This commit is contained in:
Louis Chen
2025-09-22 16:53:47 +08:00
parent e7747c1c3e
commit 4efabd168c
2 changed files with 74 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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`*

110
specs/001-users-pukpuk-dev/tasks.md
View File

@@ -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 `<Header>` and `<Footer>` components.
- **T012**: **[P]** Create the secure admin layout (`AdminLayout.astro`).
- **T013**: **[P]** Create the static page `frontend/src/pages/about-enchun.astro`.
- **T014**: **[P]** Create the static page `frontend/src/pages/marketing-solutions.astro`.
- **T015**: **[P]** Create the static page `frontend/src/pages/teams.astro`.
- **T016**: **[P]** Create the static page `frontend/src/pages/marketingclass.astro`.
- **T017**: **[P]** Create the contact page at `frontend/src/pages/contact-us.astro` with a functional form.
- **T018**: Create the blog listing page at `frontend/src/pages/news.astro`, fetching data from Payload.
- **T019**: Create the dynamic blog post page at `frontend/src/pages/xing-xiao-fang-da-jing/[slug].astro`.
- **T020**: Create the portfolio listing page at `frontend/src/pages/website-portfolio.astro`.
- **T021**: Create the dynamic portfolio item page at `frontend/src/pages/webdesign-profolio/[slug].astro`.
- **T022**: Create the dynamic category page at `frontend/src/pages/wen-zhang-fen-lei/[slug].astro`.
- **T023**: Implement the login page at `frontend/src/pages/admin/login.astro`.
- **T024**: Implement the protected CMS view at `frontend/src/pages/admin/cms.astro`.
- **T025**: Implement the authentication check in `frontend/src/middleware.ts`.
- **T012**: Integrate Auth.js (`astro-auth`) with the Astro project.
- **T013**: Implement the authentication check for all `/admin/*` routes in `frontend/src/middleware.ts`.
- **T014**: **[P]** Create the main site layout (`Layout.astro`) with shared Header and Footer components.
- **T015**: **[P]** Create the secure admin layout (`AdminLayout.astro`).
- **T016**: **[P]** Create the static page `frontend/src/pages/about.astro`.
- **T017**: **[P]** Create the static page `frontend/src/pages/solutions.astro`.
- **T018**: **[P]** Create the static page `frontend/src/pages/teams.astro`.
- **T019**: **[P]** Create the static page `frontend/src/pages/marketing-class.astro`.
- **T020**: **[P]** Create the contact page at `frontend/src/pages/contact.astro`.
- **T021**: Create the blog listing page at `frontend/src/pages/blog/index.astro`.
- **T022**: Create the dynamic blog post page at `frontend/src/pages/blog/[slug].astro`.
- **T023**: Create the blog category page at `frontend/src/pages/blog/category/[category-slug].astro`.
- **T024**: Create the portfolio listing page at `frontend/src/pages/portfolio/index.astro`.
- **T025**: Create the dynamic portfolio item page at `frontend/src/pages/portfolio/[slug].astro`.
- **T026**: Implement the login page at `frontend/src/pages/admin/login.astro`.
- **T027**: Implement the protected dashboard at `frontend/src/pages/admin/dashboard.astro`.
- **T028**: Implement the embedded Payload CMS view at `frontend/src/pages/admin/cms.astro`.
## Phase 4: E-Commerce (NEW SCOPE)
## Phase 4: Functionality & Migration
- **T026**: **(NEW SCOPE)** Create the page `frontend/src/pages/checkout.astro`.
- **T027**: **(NEW SCOPE)** Create the page `frontend/src/pages/paypal-checkout.astro`.
- **T028**: **(NEW SCOPE)** Create the page `frontend/src/pages/order-confirmation.astro`.
- **T029**: Implement the contact form submission logic using a Cloudflare Worker.
- **T030**: Create and implement the 301 redirect map for all URLs from `enchun-sitemap.txt`.
- **T031**: Write a script to migrate existing content from CSVs into the new Payload CMS.
## Phase 5: Testing
## Phase 5: Testing & Deployment
- **T029**: **[P]** Write contract tests for the `/admin/login` endpoint.
- **T030**: **[P]** Write contract tests for the `/contact-us` endpoint.
- **T031**: **[P]** Write integration tests for the user login and admin area access.
- **T032**: **[P]** Write integration tests for the contact form submission.
- **T033**: **[P]** Write unit tests for major Astro components.
## Phase 6: Content Migration and Deployment
- **T034**: Write scripts to migrate content from the old site to the new Payload CMS.
- **T035**: Implement 301 redirects for all old URLs to their new equivalents.
- **T036**: Configure the deployment pipeline to Cloudflare Pages.
- **T037**: Perform a final performance and accessibility audit using Google Lighthouse.
---
## Parallel Execution Examples
The following tasks can be run in parallel:
```bash
# Backend collections
gemini execute --task T005 &
gemini execute --task T006 &
gemini execute --task T007 &
gemini execute --task T008 &
```
```bash
# Static frontend pages
gemini execute --task T013 &
gemini execute --task T014 &
gemini execute --task T015 &
gemini execute --task T016 &
gemini execute --task T017 &
```
- **T032**: **[P]** Write integration tests for the Auth.js login and protected route flow.
- **T033**: **[P]** Write integration tests for the contact form submission.
- **T034**: **[P]** Write unit tests for critical shared utilities or components.
- **T035**: Configure and test the deployment pipeline for the Astro frontend to Cloudflare Pages.
- **T036**: Configure and test the deployment pipeline for the Payload CMS backend to Cloudflare Workers.
- **T037**: Perform a final SEO and accessibility audit.