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/_bmad-output/implementation-artifacts/1-7-solutions-page.story.md
+++ b/_bmad-output/implementation-artifacts/1-7-solutions-page.story.md
@@ -0,0 +1,469 @@
+# Story 1-7: Solutions Page Implementation (行銷方案頁面)
+
+**Status:** ready-for-dev
+**Epic:** Epic 1 - Webflow to Payload CMS + Astro Migration
+**Priority:** P1 (High)
+**Estimated Time:** 6 hours
+
+---
+
+## Story
+
+**As a** Visitor (訪客),
+**I want** to see the marketing services offered (查看恩群提供的行銷服務),
+**So that** I can understand how Enchun can help my business (了解恩群如何幫助我的事業).
+
+---
+
+## Context
+
+這是 Story 1.7 的實作文檔，屬於 Sprint 2 頁面實作階段。Solutions Page（行銷方案頁面）是恩群數位展示核心服務的重要頁面，包含 6 個主要行銷服務項目。
+
+**Story Source:**
+- PRD: `docs/prd/05-epic-stories.md` - Story 1.7
+- Tasks: `docs/prd/epic-1-stories-1.3-1.17-tasks.md` - Story 1.7
+- Depends on: Story 1.4 (Global Layout Components)
+
+**原始 HTML 參考：**
+- [Source: research/www.enchun.tw/marketing-solutions.html](../../research/www.enchun.tw/marketing-solutions.html) - Webflow 原始頁面
+
+**Key Services to Display:**
+| Service Name | Badge | Description Source |
+|--------------|-------|-------------------|
+| Google 商家關鍵字 | Hot | Google Business Profile optimization |
+| Google Ads | - | PPC advertising management |
+| 社群代操 | Hot | Social media operation |
+| 論壇行銷 | - | Forum marketing strategies |
+| 網紅行銷 | Hot | Influencer collaboration |
+| 形象影片 | - | Corporate video production |
+
+---
+
+## Acceptance Criteria
+
+### AC1: Hero Section Created
+- [ ] Hero section with title "行銷方案"
+- [ ] Background image matching Webflow design
+- [ ] Overlay for text readability
+- [ ] Responsive alignment
+
+### AC2: Services List Complete
+All 6 services must be displayed:
+- [ ] Google 商家關鍵字 (with Hot badge)
+- [ ] Google Ads
+- [ ] 社群代操 (with Hot badge)
+- [ ] 論壇行銷
+- [ ] 網紅行銷 (with Hot badge)
+- [ ] 形象影片
+
+### AC3: Service Cards Content
+Each service card must include:
+- [ ] Service icon (using Iconify or custom SVG)
+- [ ] Service title (Chinese)
+- [ ] Service description
+- [ ] Optional details section
+- [ ] Hot badge indicator (where applicable)
+
+### AC4: Badge System
+- [ ] "Hot" badge styled (red/orange accent)
+- [ ] Badge positioned correctly on service card
+- [ ] Badge visibility tested
+
+### AC5: Visual Fidelity
+- [ ] Visual similarity 95%+ compared to Webflow
+- [ ] Colors match brand design system
+- [ ] Typography matches original
+- [ ] Spacing and layout consistent
+
+### AC6: Performance
+- [ ] Lighthouse Performance score 90+
+- [ ] First Contentful Paint (FCP) < 1.5s
+- [ ] Largest Contentful Paint (LCP) < 2.5s
+- [ ] Images optimized (WebP format)
+
+### AC7: Content Management
+- [ ] Content editable via Payload CMS
+- [ ] Services stored in Pages collection or as globals
+- [ ] Admin can modify service descriptions
+- [ ] Admin can toggle Hot badges
+
+---
+
+## Tasks / Subtasks
+
+### Task 1.7.1: Create Solutions Page in Payload CMS (1h)
+
+**Description:**
+在 Payload CMS 建立行銷方案頁面的內容結構
+
+**Acceptance Criteria:**
+- [ ] 建立 `marketing-solutions` 頁面 (slug: marketing-solutions)
+- [ ] Hero section fields:
+  - Title: "行銷方案"
+  - Background image
+  - Optional subtitle
+- [ ] Services list block:
+  - Repeater/array for 6 services
+  - Each service: title, description, icon, hotBadge (boolean)
+- [ ] SEO meta fields configured
+- [ ] Access control: authenticated for edit, anyone for read
+
+**Definition of Done:**
+- [ ] Page created in Payload admin
+- [ ] All 6 services populated
+- [ ] Hot badges set (3 services marked as hot)
+- [ ] Page preview works
+
+---
+
+### Task 1.7.2: Create marketing-solutions.astro Route (1.5h)
+
+**Description:**
+建立前端路由頁面，從 Payload API 載入內容
+
+**File to Create:**
+`apps/frontend/src/pages/marketing-solutions.astro`
+
+**Acceptance Criteria:**
+- [ ] Route file created
+- [ ] Uses MainLayout component
+- [ ] Fetches page data from Payload API:
+  - `GET /api/pages?where[slug][equals]=marketing-solutions`
+- [ ] Error handling for 404
+- [ ] Loading state
+- [ ] SEO meta tags populated dynamically
+
+**Definition of Done:**
+- [ ] Route accessible at `/marketing-solutions`
+- [ ] Data loads successfully
+- [ ] Error handling tested
+
+---
+
+### Task 1.7.3: Implement Hero Section (1h)
+
+**Description:**
+實作頁面頂部 Hero 區塊
+
+**Component to Create:**
+`apps/frontend/src/components/solutions/SolutionsHero.astro`
+
+**Acceptance Criteria:**
+- [ ] Background image with overlay
+- [ ] Title "行銷方案" prominently displayed
+- [ ] Text centered and readable
+- [ ] Responsive sizing (desktop > mobile)
+- [ ] Matches Webflow visual design
+
+**Definition of Done:**
+- [ ] Component created and integrated
+- [ ] Visual fidelity 95%+
+- [ ] Responsive tested
+
+---
+
+### Task 1.7.4: Implement Services List Component (2h)
+
+**Description:**
+實作服務列表組件，包含 6 個服務卡片
+
+**Component to Create:**
+`apps/frontend/src/components/solutions/ServicesList.astro`
+
+**Acceptance Criteria:**
+- [ ] Grid layout (desktop: 3 columns, tablet: 2, mobile: 1)
+- [ ] 6 service cards rendered
+- [ ] Each card contains:
+  - Icon (Iconify or SVG)
+  - Service title
+  - Description text
+  - Hot badge (conditional)
+- [ ] Hover effects:
+  - Card elevation (shadow)
+  - Subtle transform
+  - Color accent
+- [ ] Hot badge styling:
+  - Red/orange background
+  - White text
+  - Corner positioning
+
+**Icon Suggestions:**
+| Service | Iconify Icon |
+|---------|--------------|
+| Google 商家關鍵字 | `mdi:google` or `logos:google-icon` |
+| Google Ads | `mdi:google-ads` |
+| 社群代操 | `mdi:social` or `mdi:account-group` |
+| 論壇行銷 | `mdi:forum` or `mdi:comment-multiple` |
+| 網紅行銷 | `mdi:star-face` or `mdi:account-star` |
+| 形象影片 | `mdi:video` or `mdi:play-circle` |
+
+**Definition of Done:**
+- [ ] Component created
+- [ ] All 6 services displayed
+- [ ] Hot badges visible on 3 services
+- [ ] Hover effects smooth
+- [ ] Responsive grid working
+
+---
+
+### Task 1.7.5: Performance and Visual Testing (1h)
+
+**Description:**
+效能測試和視覺驗證
+
+**Acceptance Criteria:**
+- [ ] Lighthouse Performance audit:
+  - Performance score >= 90
+  - Accessibility >= 90
+  - Best Practices >= 90
+  - SEO >= 95
+- [ ] Visual fidelity check:
+  - Compare with Webflow original
+  - 95%+ similarity
+- [ ] Responsive testing:
+  - Desktop (1920x1080)
+  - Tablet (768x1024)
+  - Mobile (375x667)
+- [ ] Cross-browser testing:
+  - Chrome, Firefox, Safari, Edge
+- [ ] Image optimization verified
+
+**Definition of Done:**
+- [ ] All performance metrics met
+- [ ] Visual fidelity confirmed
+- [ ] No critical bugs
+
+---
+
+## Dev Technical Guidance
+
+### File Structure
+
+```
+apps/frontend/src/
+├── pages/
+│   └── marketing-solutions.astro        <-- CREATE (Task 1.7.2)
+├── components/
+│   └── solutions/
+│       ├── SolutionsHero.astro          <-- CREATE (Task 1.7.3)
+│       └── ServicesList.astro           <-- CREATE (Task 1.7.4)
+└── layouts/
+    └── Layout.astro                     <-- EXISTS (use for integration)
+
+apps/backend/src/
+└── collections/
+    └── Pages/                           <-- EXISTS (add marketing-solutions page)
+```
+
+### Payload CMS Page Structure
+
+When creating the marketing-solutions page in Payload CMS:
+
+```typescript
+// Page content structure example
+{
+  title: "行銷方案",
+  slug: "marketing-solutions",
+  hero: {
+    title: "行銷方案",
+    subtitle: "全方位數位行銷解決方案",
+    backgroundImage: "..." // media upload
+  },
+  services: [
+    {
+      title: "Google 商家關鍵字",
+      description: "優化 Google 商家檔案，提升在地搜尋排名...",
+      icon: "mdi:google",
+      hotBadge: true
+    },
+    {
+      title: "Google Ads",
+      description: "精準投放 Google 廣告，最大化投資報酬率...",
+      icon: "mdi:google-ads",
+      hotBadge: false
+    },
+    // ... 4 more services
+  ],
+  meta: {
+    title: "行銷方案 | 恩群數位",
+    description: "提供全方位數位行銷服務，包含 Google Ads、社群代操、論壇行銷、網紅行銷等專業服務"
+  }
+}
+```
+
+### Tailwind CSS Styling Guide
+
+```css
+/* Hero Section */
+.hero-section {
+  @apply relative min-h-[400px] flex items-center justify-center;
+  @apply bg-cover bg-center bg-no-repeat;
+}
+.hero-overlay {
+  @apply absolute inset-0 bg-black/50;
+}
+.hero-title {
+  @apply relative z-10 text-4xl md:text-5xl font-bold text-white text-center;
+}
+
+/* Services Grid */
+.services-grid {
+  @apply grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8;
+  @apply max-w-7xl mx-auto px-4 py-16;
+}
+
+/* Service Card */
+.service-card {
+  @apply bg-white rounded-xl shadow-md p-6;
+  @apply transition-all duration-300;
+  @apply hover:shadow-xl hover:-translate-y-1;
+}
+.service-icon {
+  @apply w-16 h-16 mx-auto mb-4;
+  @apply text-primary-600;
+}
+.service-title {
+  @apply text-xl font-bold text-gray-900 mb-3 text-center;
+}
+.service-description {
+  @apply text-gray-600 text-center leading-relaxed;
+}
+
+/* Hot Badge */
+.hot-badge {
+  @apply absolute top-4 right-4;
+  @apply bg-red-500 text-white px-3 py-1;
+  @apply rounded-full text-sm font-semibold;
+}
+```
+
+### API Fetch Pattern
+
+```typescript
+// marketing-solutions.astro
+---
+import Layout from '../layouts/Layout.astro'
+import { payload } from '@payload-client'
+
+const page = await payload.find({
+  collection: 'pages',
+  where: {
+    slug: {
+      equals: 'marketing-solutions'
+    }
+  },
+  depth: 1
+})
+
+if (!page.docs[0]) {
+  return Astro.redirect('/404')
+}
+
+const { title, hero, services, meta } = page.docs[0]
+---
+
+<Layout title={meta?.title || title} meta={meta}>
+  <!-- Components here -->
+</Layout>
+```
+
+---
+
+## Testing Requirements
+
+### Manual Testing Checklist
+- [ ] Page loads at `/marketing-solutions`
+- [ ] Hero section displays correctly
+- [ ] All 6 services are visible
+- [ ] Hot badges appear on correct services (Google 商家關鍵字, 社群代操, 網紅行銷)
+- [ ] Icons load and display
+- [ ] Hover effects work on desktop
+- [ ] Responsive layout on tablet
+- [ ] Single column layout on mobile
+- [ ] No horizontal scroll on mobile
+- [ ] Images load from R2/CDN
+- [ ] SEO meta tags present in page source
+
+### Performance Targets
+| Metric | Target | How to Measure |
+|--------|--------|----------------|
+| Lighthouse Performance | >= 90 | Chrome DevTools Lighthouse |
+| First Contentful Paint | < 1.5s | Lighthouse |
+| Largest Contentful Paint | < 2.5s | Lighthouse |
+| Cumulative Layout Shift | < 0.1 | Lighthouse |
+| Visual Fidelity | >= 95% | Manual comparison with Webflow |
+
+### Cross-Browser Testing
+- [ ] Chrome (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest, if available)
+- [ ] Edge (latest)
+
+---
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| Visual deviation from Webflow | Medium | Medium | Use exact colors and spacing from design tokens |
+| Icon loading issues | Low | Low | Use Iconify CDN fallback or inline SVGs |
+| Content management complexity | Low | Medium | Keep CMS structure simple, reuse patterns |
+| Performance below target | Low | High | Optimize images, use lazy loading for below-fold |
+
+---
+
+## Definition of Done
+
+- [ ] All 6 services displayed on page
+- [ ] Hot badges visible on 3 services
+- [ ] Content editable via Payload CMS
+- [ ] Visual fidelity 95%+ compared to Webflow
+- [ ] Lighthouse Performance score >= 90
+- [ ] Responsive on all device sizes
+- [ ] Cross-browser compatible
+- [ ] SEO meta tags configured
+- [ ] No console errors
+- [ ] Code follows project conventions
+- [ ] sprint-status.yaml updated
+
+---
+
+## Architecture Compliance
+
+### Follows Project Patterns
+- **Component Structure**: Follows `pages/` + `components/` pattern
+- **Layout System**: Uses existing MainLayout from Story 1.4
+- **Styling**: Tailwind CSS with design tokens from `theme.css`
+- **Data Fetching**: Payload API client pattern
+- **TypeScript**: Strict typing for all props and data
+- **Performance**: SSR with Astro for optimal loading
+
+### Non-Functional Requirements Met
+- **NFR1**: Lighthouse scores 95+ (targeting 90+)
+- **NFR2**: FCP < 1.5s, LCP < 2.5s
+- **NFR3**: WCAG 2.1 AA compliance (semantic HTML)
+- **NFR12**: Responsive design across all devices
+
+---
+
+## Dev Agent Record
+
+### Agent Model Used
+*To be filled by Dev Agent*
+
+### Debug Log References
+*To be filled by Dev Agent*
+
+### Completion Notes
+*To be filled by Dev Agent*
+
+### File List
+*To be filled by Dev Agent*
+
+---
+
+## Change Log
+
+| Date | Action | Author |
+|------|--------|--------|
+| 2026-01-31 | Story created (ready-for-dev) | SM Agent (Bob) |