🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,151 @@
+# Frontend Builder Agent
+
+> SF-03 — Automated Frontend Project Generation
+
+## Overview
+
+The Frontend Builder Agent consumes PRD (SF-01) + Architecture (SF-02) and generates a **complete, runnable Next.js project** with TypeScript and Tailwind CSS.
+
+Every page is a **real component** with meaningful JSX, state management, and API integration patterns — no stubs.
+
+## Quick Start
+
+```bash
+# From PRD + Architecture files
+node scripts/frontend-builder-agent.mjs --prd prd-example.json --arch architecture-example.json --verbose
+
+# Full pipeline from one sentence
+node scripts/frontend-builder-agent.mjs --input-text "做一个宠物管理 App" --output my-app
+```
+
+## Output Structure
+
+```
+frontend/
+├── app/                          # Next.js App Router pages
+│   ├── page.tsx                  # Home page
+│   ├── layout.tsx                # (in src/app/)
+│   ├── pet/[id]/page.tsx         # Dynamic route
+│   ├── schedule/page.tsx
+│   ├── daily-log/page.tsx
+│   ├── album/page.tsx
+│   ├── hospitals/page.tsx
+│   └── profile/page.tsx
+├── components/
+│   ├── ui/                       # Shared UI (Button, Card, Input, Modal, EmptyState)
+│   ├── layout/                   # Sidebar, BottomNav
+│   └── {domain}/                 # Domain components (PetCard, ProductCard, NoteCard)
+├── hooks/                        # Custom React hooks
+│   ├── usePets.ts               # Per-resource data hooks
+│   ├── useSchedules.ts
+│   ├── useForm.ts               # Generic hooks
+│   └── useDebounce.ts
+├── services/                     # API service layer
+│   ├── api.ts                   # Base API client (get/post/put/delete)
+│   ├── pets.ts                  # Per-resource API functions
+│   └── schedules.ts
+├── types/
+│   └── index.ts                 # TypeScript interfaces
+├── package.json
+├── tsconfig.json
+├── tailwind.config.ts
+├── next.config.ts
+└── postcss.config.js
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│              SF-03 Frontend Builder                 │
+│                                                     │
+│  PRD + Architecture ──▶                             │
+│                                                     │
+│  1. Type Generator                                  │
+│     Domain → TS interfaces (User, Pet, Order...)    │
+│     Always: ApiResponse, PaginatedResponse          │
+│                                                     │
+│  2. Config Generator                                │
+│     package.json, tsconfig, tailwind, next.config   │
+│                                                     │
+│  3. Layout Generator                                │
+│     Root layout + Sidebar (desktop) + BottomNav     │
+│     Auto-generates nav from PRD pages               │
+│                                                     │
+│  4. UI Component Generator                          │
+│     Button, Card, Input, Modal, EmptyState          │
+│     All with props, variants, accessibility         │
+│                                                     │
+│  5. Domain Component Generator                      │
+│     pet → PetCard, ScheduleCard                     │
+│     ecommerce → ProductCard                         │
+│     note → NoteCard                                 │
+│                                                     │
+│  6. Page Generator                                  │
+│     Per-route page with real JSX                    │
+│     Domain-specific layouts & interactions          │
+│     Loading, error, and empty states                │
+│                                                     │
+│  7. Hook Generator                                  │
+│     Per-resource: usePets, useSchedules...          │
+│     Generic: useForm, useDebounce                   │
+│                                                     │
+│  8. API Service Generator                           │
+│     Base client with fetch wrapper                  │
+│     Per-resource: get/post/put/delete functions     │
+│                                                     │
+│  ──────────────▶ frontend/ directory               │
+└─────────────────────────────────────────────────────┘
+```
+
+## Page Quality
+
+Every generated page contains:
+
+- **Layout**: Heading, description, grid/flex layout
+- **State**: `useState` for interactive elements
+- **Hooks**: `useEffect` for data loading simulation
+- **Loading state**: Spinner animation
+- **Error state**: Error message with retry button
+- **Empty state**: Illustrated empty state with CTA
+- **Data display**: Cards, lists, grids with real-looking mock data
+- **Interactivity**: Buttons, toggles, modals, forms
+
+No page is a simple `return <div>TODO</div>`.
+
+## Domain Coverage
+
+| Domain | Pages | Components | Types |
+|--------|-------|------------|-------|
+| 🐱 pet | 7 pages | PetCard, ScheduleCard | Pet, Schedule, DailyLog, Hospital |
+| 🛒 ecommerce | 6 pages | ProductCard | Product, Order, Logistics |
+| 📚 education | 6 pages | — | Course, Lesson, Exercise, Progress |
+| 🏢 enterprise | 6 pages | — | Department, Approval, Attendance |
+| 💪 fitness | 5 pages | — | CheckIn, TrainingPlan |
+| 📝 note | 4 pages | NoteCard | Note, Tag |
+| 🔧 generic | 4+ pages | — | Item |
+
+## Tech Stack
+
+- **Framework**: Next.js 15 (App Router)
+- **Language**: TypeScript 5 (strict mode)
+- **Styling**: Tailwind CSS 3.4
+- **State**: React 19 hooks (useState, useEffect, useCallback)
+- **Routing**: File-based dynamic routes (`[id]`)
+- **API**: fetch-based client with typed wrappers
+
+## Test Coverage
+
+32 tests across 11 suites.
+
+```bash
+node --test test/frontend-builder-agent.test.mjs
+```
+
+## Downstream Integration
+
+Generated frontend is designed for:
+
+- **SF-04 (Dev Agent)**: Reads generated project → sets up CI/CD, runs compilation
+- **SF-05 (QA Agent)**: Reads pages, types → generates test cases
+- **Direct use**: `cd frontend && npm install && npm run dev`