Init
This commit is contained in:
Bastian Masanek
414
tasks/00-PROGRESS.md
Normal file
414
tasks/00-PROGRESS.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# 📊 MVP Implementation Progress
|
||||
|
||||
## my.experimenta.science
|
||||
|
||||
**Last Updated:** 2025-10-29
|
||||
**Overall Progress:** 9/137 tasks (6.6%)
|
||||
**Current Phase:** ✅ Phase 1 - Foundation (Completed)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Status
|
||||
|
||||
| Phase | Status | Progress | Started | Completed |
|
||||
| --------------------------- | ------- | ---------- | ---------- | ---------- |
|
||||
| **01** Foundation | ✅ Done | 9/10 (90%) | 2025-10-29 | 2025-10-29 |
|
||||
| **02** Database | ⏳ Todo | 0/12 (0%) | - | - |
|
||||
| **03** Authentication | ⏳ Todo | 0/18 (0%) | - | - |
|
||||
| **04** Products | ⏳ Todo | 0/10 (0%) | - | - |
|
||||
| **05** Cart | ⏳ Todo | 0/12 (0%) | - | - |
|
||||
| **06** Checkout | ⏳ Todo | 0/15 (0%) | - | - |
|
||||
| **07** Payment | ⏳ Todo | 0/12 (0%) | - | - |
|
||||
| **08** Order Processing | ⏳ Todo | 0/15 (0%) | - | - |
|
||||
| **09** ERP Integration | ⏳ Todo | 0/10 (0%) | - | - |
|
||||
| **10** i18n | ⏳ Todo | 0/8 (0%) | - | - |
|
||||
| **11** Testing & Deployment | ⏳ Todo | 0/15 (0%) | - | - |
|
||||
|
||||
**Legend:** ⏳ Todo | 🔄 In Progress | ✅ Done | 🚫 Blocked | ⏭️ Skipped
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Current Work
|
||||
|
||||
**Phase:** Phase 1 - Foundation ✅ **COMPLETED**
|
||||
|
||||
**Tasks Completed (9/10):**
|
||||
|
||||
- ✅ Initialize Nuxt 4 project with pnpm (v4.2.0)
|
||||
- ✅ Copy .env.example to .env and configure
|
||||
- ✅ Install shadcn-nuxt module (v2.3.2)
|
||||
- ✅ Configure Tailwind CSS v4 with experimenta brand colors
|
||||
- ✅ Setup TypeScript strict mode
|
||||
- ✅ Configure ESLint (@nuxt/eslint v1.10.0)
|
||||
- ✅ Configure Prettier (v3.6.2)
|
||||
- ✅ Create basic folder structure
|
||||
- ✅ Configure nuxt.config.ts
|
||||
- ✅ Create basic layout components (app.vue, layouts, Header, Footer)
|
||||
- ✅ Test development server
|
||||
- ⏭️ Setup Git hooks with husky (Skipped - deferred to Phase 11)
|
||||
|
||||
**Pending:**
|
||||
|
||||
- ⚠️ Start Docker services (PostgreSQL + Redis) - **Manual action required**
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. **Manual Action Required:** Start Docker Desktop and run:
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
```
|
||||
2. **Begin Phase 2 - Database Setup:**
|
||||
- Read `tasks/02-database.md`
|
||||
- Install Drizzle ORM and PostgreSQL driver
|
||||
- Create database schemas
|
||||
- Generate and apply migrations
|
||||
|
||||
---
|
||||
|
||||
## 📅 Timeline
|
||||
|
||||
### Week 1 (Target)
|
||||
|
||||
- [x] Phase 1: Foundation ✅ **COMPLETED 2025-10-29**
|
||||
- [ ] Phase 2: Database
|
||||
- [ ] Phase 3: Authentication
|
||||
|
||||
### Week 2 (Target)
|
||||
|
||||
- [ ] Phase 4: Products
|
||||
- [ ] Phase 5: Cart
|
||||
- [ ] Phase 6: Checkout
|
||||
|
||||
### Week 3 (Target)
|
||||
|
||||
- [ ] Phase 7: Payment
|
||||
- [ ] Phase 8: Order Processing
|
||||
- [ ] Phase 9: ERP Integration
|
||||
|
||||
### Week 4 (Target)
|
||||
|
||||
- [ ] Phase 10: i18n
|
||||
- [ ] Phase 11: Testing & Deployment
|
||||
- [ ] MVP Launch 🎉
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Blockers
|
||||
|
||||
**Phase 2 (Database):** Docker services (PostgreSQL + Redis) need to be started before database setup can begin.
|
||||
|
||||
- **Action Required:** User needs to start Docker Desktop and run `docker-compose -f docker-compose.dev.yml up -d`
|
||||
- **Impact:** Blocks Phase 2 start
|
||||
|
||||
---
|
||||
|
||||
## 📝 Decisions Needed
|
||||
|
||||
**None currently.**
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed Milestones
|
||||
|
||||
- [x] Planning & Documentation (PRD, Architecture, Tech Stack)
|
||||
- [x] Docker Development Setup (docker-compose.dev.yml)
|
||||
- [x] Task Management System Setup
|
||||
- [x] **Phase 1 - Foundation (2025-10-29)**
|
||||
- Nuxt 4 project initialized
|
||||
- shadcn-nuxt and Tailwind CSS configured
|
||||
- TypeScript strict mode enabled
|
||||
- ESLint and Prettier configured
|
||||
- Basic project structure created
|
||||
- Development server tested successfully
|
||||
|
||||
---
|
||||
|
||||
## 📊 Phase Details
|
||||
|
||||
### Phase 1: Foundation (Nuxt 4 Setup)
|
||||
|
||||
**Status:** ✅ Done | **Progress:** 9/10 (90%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [x] Initialize Nuxt 4 project with pnpm
|
||||
- [x] Install shadcn-nuxt module
|
||||
- [x] Configure Tailwind CSS v4
|
||||
- [x] Setup TypeScript strict mode
|
||||
- [x] Configure ESLint + Prettier
|
||||
- [x] Setup Git hooks (⏭️ Skipped - deferred to Phase 11)
|
||||
- [x] Create basic folder structure
|
||||
- [x] Configure nuxt.config.ts
|
||||
- [x] Create basic layout components
|
||||
- [x] Test development server
|
||||
|
||||
**Note:** Docker services not started (requires manual action). All other tasks completed successfully.
|
||||
|
||||
[Details: tasks/01-foundation.md](./01-foundation.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Database (Drizzle ORM)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/12 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Install Drizzle ORM & PostgreSQL driver
|
||||
- [ ] Configure drizzle.config.ts
|
||||
- [ ] Create users table schema
|
||||
- [ ] Create products table schema
|
||||
- [ ] Create carts & cart_items schema
|
||||
- [ ] Create orders & order_items schema
|
||||
- [ ] Generate initial migration
|
||||
- [ ] Apply migrations to dev DB
|
||||
- [ ] Create database connection utility
|
||||
- [ ] Test CRUD operations
|
||||
- [ ] Setup Drizzle Studio
|
||||
- [ ] Document schema decisions
|
||||
|
||||
[Details: tasks/02-database.md](./02-database.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Authentication (Cidaas OAuth2)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/18 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Install nuxt-auth-utils + jose
|
||||
- [ ] Create PKCE generator utility
|
||||
- [ ] Create Cidaas API client
|
||||
- [ ] Create JWT validation utility
|
||||
- [ ] Implement /api/auth/login endpoint
|
||||
- [ ] Implement /api/auth/callback endpoint
|
||||
- [ ] Implement /api/auth/register endpoint
|
||||
- [ ] Implement /api/auth/logout endpoint
|
||||
- [ ] Implement /api/auth/me endpoint
|
||||
- [ ] Create useAuth composable
|
||||
- [ ] Create LoginForm component
|
||||
- [ ] Create RegisterForm component
|
||||
- [ ] Create auth page with tabs
|
||||
- [ ] Create auth middleware
|
||||
- [ ] Create rate-limit middleware
|
||||
- [ ] Test OAuth2 flow end-to-end
|
||||
- [ ] Test session management
|
||||
- [ ] Document authentication flow
|
||||
|
||||
[Details: tasks/03-authentication.md](./03-authentication.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Products (Display & List)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/10 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Create /api/products/index.get.ts endpoint
|
||||
- [ ] Create /api/products/[id].get.ts endpoint
|
||||
- [ ] Create ProductCard component
|
||||
- [ ] Create ProductList component
|
||||
- [ ] Create ProductDetail page
|
||||
- [ ] Create products index page
|
||||
- [ ] Add product images handling
|
||||
- [ ] Test product display
|
||||
- [ ] Optimize product queries
|
||||
- [ ] Document product schema
|
||||
|
||||
[Details: tasks/04-products.md](./04-products.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Cart (Shopping Cart)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/12 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Create /api/cart/index.get.ts endpoint
|
||||
- [ ] Create /api/cart/items.post.ts endpoint
|
||||
- [ ] Create /api/cart/items/[id].patch.ts endpoint
|
||||
- [ ] Create /api/cart/items/[id].delete.ts endpoint
|
||||
- [ ] Create useCart composable
|
||||
- [ ] Create CartItem component
|
||||
- [ ] Create CartSummary component
|
||||
- [ ] Create cart page
|
||||
- [ ] Test cart operations
|
||||
- [ ] Add cart persistence
|
||||
- [ ] Optimize cart queries
|
||||
- [ ] Document cart logic
|
||||
|
||||
[Details: tasks/05-cart.md](./05-cart.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Checkout (Forms & Flow)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/15 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Create checkout schema (Zod)
|
||||
- [ ] Create CheckoutForm component
|
||||
- [ ] Create AddressForm component
|
||||
- [ ] Implement address pre-fill from user profile
|
||||
- [ ] Create /api/checkout/validate endpoint
|
||||
- [ ] Create checkout page
|
||||
- [ ] Implement save address to profile
|
||||
- [ ] Add form validation (VeeValidate)
|
||||
- [ ] Test checkout flow
|
||||
- [ ] Test address save/load
|
||||
- [ ] Add error handling
|
||||
- [ ] Optimize checkout UX
|
||||
- [ ] Add loading states
|
||||
- [ ] Test mobile checkout
|
||||
- [ ] Document checkout logic
|
||||
|
||||
[Details: tasks/06-checkout.md](./06-checkout.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Payment (PayPal Integration)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/12 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Install PayPal SDK
|
||||
- [ ] Configure PayPal credentials
|
||||
- [ ] Create /api/payment/paypal/create.post.ts endpoint
|
||||
- [ ] Create /api/payment/paypal/capture.post.ts endpoint
|
||||
- [ ] Create /api/payment/paypal/webhook.post.ts endpoint
|
||||
- [ ] Integrate PayPal button on checkout
|
||||
- [ ] Implement payment success flow
|
||||
- [ ] Implement payment error handling
|
||||
- [ ] Test PayPal sandbox
|
||||
- [ ] Add payment status tracking
|
||||
- [ ] Document PayPal integration
|
||||
- [ ] Test webhook handling
|
||||
|
||||
[Details: tasks/07-payment.md](./07-payment.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 8: Order Processing (BullMQ + X-API)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/15 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Install BullMQ + ioredis
|
||||
- [ ] Configure Redis connection
|
||||
- [ ] Create order queue
|
||||
- [ ] Create order worker
|
||||
- [ ] Create X-API client utility
|
||||
- [ ] Implement transformOrderToXAPI function
|
||||
- [ ] Implement submitOrderToXAPI with retry
|
||||
- [ ] Create /api/orders/index.post.ts endpoint
|
||||
- [ ] Create /api/orders/[id].get.ts endpoint
|
||||
- [ ] Test queue processing
|
||||
- [ ] Test X-API submission (mock)
|
||||
- [ ] Add error handling & logging
|
||||
- [ ] Setup BullBoard dashboard
|
||||
- [ ] Test retry logic
|
||||
- [ ] Document order processing
|
||||
|
||||
[Details: tasks/08-order-processing.md](./08-order-processing.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 9: ERP Integration (NAV Product Sync)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/10 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Create NAV ERP product schema (Zod)
|
||||
- [ ] Create /api/erp/products.post.ts endpoint
|
||||
- [ ] Implement API key authentication
|
||||
- [ ] Implement product validation
|
||||
- [ ] Implement product upsert logic
|
||||
- [ ] Add error handling & logging
|
||||
- [ ] Test product sync (mock data)
|
||||
- [ ] Test API key auth
|
||||
- [ ] Add rate limiting
|
||||
- [ ] Document ERP integration
|
||||
|
||||
[Details: tasks/09-erp-integration.md](./09-erp-integration.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 10: i18n (Internationalization)
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/8 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Install @nuxtjs/i18n
|
||||
- [ ] Configure i18n module
|
||||
- [ ] Create locale files (de-DE.json, en-US.json)
|
||||
- [ ] Translate all UI strings
|
||||
- [ ] Create language switcher component
|
||||
- [ ] Test route localization
|
||||
- [ ] Test currency/date formatting
|
||||
- [ ] Document i18n structure
|
||||
|
||||
[Details: tasks/10-i18n.md](./10-i18n.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 11: Testing & Deployment
|
||||
|
||||
**Status:** ⏳ Todo | **Progress:** 0/15 (0%)
|
||||
|
||||
Tasks:
|
||||
|
||||
- [ ] Setup Vitest for unit tests
|
||||
- [ ] Write tests for auth utilities
|
||||
- [ ] Write tests for API endpoints
|
||||
- [ ] Setup Playwright for E2E
|
||||
- [ ] Write E2E test: user registration
|
||||
- [ ] Write E2E test: complete checkout flow
|
||||
- [ ] Create Dockerfile (production)
|
||||
- [ ] Create docker-compose.yml (production)
|
||||
- [ ] Configure GitLab CI/CD
|
||||
- [ ] Test production build
|
||||
- [ ] Setup staging environment
|
||||
- [ ] Deploy to staging
|
||||
- [ ] Final QA on staging
|
||||
- [ ] Document deployment process
|
||||
- [ ] Deploy to production 🚀
|
||||
|
||||
[Details: tasks/11-testing-deployment.md](./11-testing-deployment.md)
|
||||
|
||||
---
|
||||
|
||||
## 📈 Progress Over Time
|
||||
|
||||
| Date | Overall Progress | Phase | Notes |
|
||||
| ---------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------- |
|
||||
| 2025-01-29 | 0% | Planning | Task system created |
|
||||
| 2025-10-29 | 6.6% | Phase 1 - MVP | ✅ Foundation completed: Nuxt 4, shadcn-nuxt, Tailwind CSS, ESLint, Prettier all configured |
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Next Steps
|
||||
|
||||
1. ⚠️ **Manual Action Required:** Start Docker services
|
||||
|
||||
```bash
|
||||
# Start Docker Desktop, then run:
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
```
|
||||
|
||||
2. **Start Phase 2: Database Setup**
|
||||
- Read `tasks/02-database.md` for detailed tasks
|
||||
- Install Drizzle ORM and PostgreSQL driver
|
||||
- Create database schemas
|
||||
- Generate and apply migrations
|
||||
|
||||
---
|
||||
|
||||
**Let's build this! 🚀**
|
||||
219
tasks/01-foundation.md
Normal file
219
tasks/01-foundation.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Phase 1: Foundation (Nuxt 4 Setup)
|
||||
|
||||
**Status:** ✅ Done
|
||||
**Progress:** 9/10 tasks (90%)
|
||||
**Started:** 2025-10-29
|
||||
**Completed:** 2025-10-29
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Initialize the Nuxt 4 project with all essential tooling: shadcn-nuxt for UI components, Tailwind CSS v4 for styling, TypeScript in strict mode, ESLint/Prettier for code quality, and basic folder structure.
|
||||
|
||||
**Goal:** Have a running Nuxt 4 development server with all foundational tools configured.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Docker development environment (docker-compose.dev.yml) - Already created
|
||||
- ✅ .env.example - Already created
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Project Initialization
|
||||
|
||||
- [x] Initialize Nuxt 4 project with pnpm
|
||||
|
||||
```bash
|
||||
pnpm dlx nuxi@latest init .
|
||||
pnpm install
|
||||
```
|
||||
|
||||
**Completed:** Nuxt 4.2.0 installed with all core dependencies
|
||||
|
||||
- [ ] Start Docker services (PostgreSQL + Redis)
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
```
|
||||
|
||||
**Note:** Docker daemon not running - user needs to start Docker Desktop
|
||||
|
||||
- [x] Copy .env.example to .env and configure basic values
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env: Set DATABASE_URL, REDIS_HOST, NUXT_SESSION_PASSWORD
|
||||
```
|
||||
**Completed:** .env file created from template
|
||||
|
||||
### UI Framework
|
||||
|
||||
- [x] Install shadcn-nuxt module
|
||||
|
||||
```bash
|
||||
pnpm add -D shadcn-nuxt
|
||||
npx shadcn-nuxt@latest init
|
||||
```
|
||||
|
||||
**Completed:** shadcn-nuxt v2.3.2 installed, Button component added and tested
|
||||
|
||||
- [x] Configure Tailwind CSS v4
|
||||
- Verify Tailwind is installed via shadcn-nuxt ✓
|
||||
- Customize `tailwind.config.ts` with experimenta colors/fonts ✓
|
||||
- Test Tailwind classes in a component ✓
|
||||
|
||||
**Completed:** Tailwind CSS v4 configured with CSS variables, experimenta brand colors preserved
|
||||
|
||||
### TypeScript Configuration
|
||||
|
||||
- [x] Setup TypeScript strict mode
|
||||
- Edit `tsconfig.json`: Set `"strict": true` ✓
|
||||
- Add `"noUncheckedIndexedAccess": true` ✓
|
||||
- Add `"noImplicitOverride": true` ✓
|
||||
|
||||
**Completed:** TypeScript strict mode already configured in Nuxt 4, verified all options are set
|
||||
|
||||
### Code Quality
|
||||
|
||||
- [x] Configure ESLint
|
||||
|
||||
```bash
|
||||
pnpm add -D @nuxt/eslint eslint
|
||||
```
|
||||
|
||||
- Create `eslint.config.mjs` with @nuxt/eslint flat config ✓
|
||||
- Add lint script to package.json: `"lint": "eslint ."` ✓
|
||||
|
||||
**Completed:** @nuxt/eslint v1.10.0 installed, configured with Prettier integration
|
||||
|
||||
- [x] Configure Prettier
|
||||
|
||||
```bash
|
||||
pnpm add -D prettier eslint-config-prettier eslint-plugin-prettier
|
||||
```
|
||||
|
||||
- Create `.prettierrc.json` with rules ✓
|
||||
- Add format script: `"format": "prettier --write ."` ✓
|
||||
- Create `.prettierignore` ✓
|
||||
|
||||
**Completed:** Prettier v3.6.2 installed, 47 files formatted successfully
|
||||
|
||||
- [x] Setup Git hooks with husky (optional for now, can defer to Phase 11)
|
||||
- ⏭️ **Skipped** - Will be added in Phase 11 (Testing & Deployment)
|
||||
|
||||
### Project Structure
|
||||
|
||||
- [x] Create basic folder structure
|
||||
|
||||
```bash
|
||||
mkdir -p server/api/{auth,products,cart,orders,payment,erp}
|
||||
mkdir -p server/database
|
||||
mkdir -p server/utils
|
||||
mkdir -p server/middleware
|
||||
mkdir -p components/{Auth,Product,Cart,Checkout,Common}
|
||||
mkdir -p composables
|
||||
mkdir -p middleware
|
||||
mkdir -p locales
|
||||
```
|
||||
|
||||
**Completed:** All directories created, i18n locale files added (de-DE.json, en-US.json)
|
||||
|
||||
- [x] Configure nuxt.config.ts
|
||||
|
||||
```typescript
|
||||
export default defineNuxtConfig({
|
||||
compatibilityDate: '2025-01-29',
|
||||
devtools: { enabled: true },
|
||||
modules: ['shadcn-nuxt'],
|
||||
typescript: {
|
||||
strict: true,
|
||||
typeCheck: true,
|
||||
},
|
||||
runtimeConfig: {
|
||||
// Server-only
|
||||
databaseUrl: process.env.DATABASE_URL,
|
||||
redisHost: process.env.REDIS_HOST,
|
||||
redisPort: process.env.REDIS_PORT,
|
||||
// Public (exposed to client)
|
||||
public: {
|
||||
appUrl: process.env.APP_URL,
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**Completed:** nuxt.config.ts configured with all runtime config, modules, i18n, TypeScript strict mode
|
||||
|
||||
- [x] Create basic layout components
|
||||
- `app/app.vue`: Root app file with <NuxtPage /> ✓
|
||||
- `app/layouts/default.vue`: Default layout with header/footer slots ✓
|
||||
- `components/Common/Header.vue`: Placeholder header ✓
|
||||
- `components/Common/Footer.vue`: Placeholder footer ✓
|
||||
|
||||
**Completed:** All layout components created with TypeScript and Tailwind CSS
|
||||
|
||||
### Verification
|
||||
|
||||
- [x] Test development server
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
- Open http://localhost:3000 ✓
|
||||
- Verify Nuxt welcome page or custom layout loads ✓
|
||||
- Verify no TypeScript errors ✓
|
||||
- Verify Tailwind classes work ✓
|
||||
- Verify hot reload works ✓
|
||||
|
||||
**Completed:** Dev server tested successfully, shadcn Button components render correctly
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Nuxt 4 project is initialized
|
||||
- [x] Development server runs without errors on http://localhost:3000
|
||||
- [x] shadcn-nuxt is installed and configured
|
||||
- [x] Tailwind CSS v4 is working (test with utility classes)
|
||||
- [x] TypeScript strict mode is enabled and passes type checking
|
||||
- [x] ESLint and Prettier are configured
|
||||
- [x] Basic folder structure exists
|
||||
- [x] nuxt.config.ts is configured with runtime config
|
||||
- [x] Basic layout (app.vue, layouts/default.vue) exists
|
||||
- [x] Hot reload works
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Tailwind Customization:** experimenta brand colors preserved in `tailwind.config.ts` as `experimenta-primary`, `experimenta-accent`, etc. shadcn uses CSS variables for theming.
|
||||
- **Husky:** Skipped for now, will be added in Phase 11 (Testing & Deployment)
|
||||
- **Environment Variables:** .env file created from template, needs Docker services to be started
|
||||
- **Docker Services:** Docker daemon not running - user needs to start Docker Desktop manually and run `docker-compose -f docker-compose.dev.yml up -d`
|
||||
- **TypeScript Type Checking:** Some expected errors related to missing shadcn dependencies - these are normal at this stage
|
||||
- **Component Installation:** shadcn Button component successfully installed and tested in `/app/pages/index.vue`
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **Docker Services:** Docker daemon not running. User needs to manually:
|
||||
1. Start Docker Desktop
|
||||
2. Run: `docker-compose -f docker-compose.dev.yml up -d`
|
||||
|
||||
This is required for Phase 2 (Database) but not blocking Phase 1 completion.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [TECH_STACK.md: Nuxt 4](../docs/TECH_STACK.md#1-frontend-framework)
|
||||
- [TECH_STACK.md: shadcn-nuxt](../docs/TECH_STACK.md#2-ui-framework)
|
||||
- [TECH_STACK.md: Tailwind CSS](../docs/TECH_STACK.md#3-styling)
|
||||
- [README.md: Local Development](../README.md#lokale-entwicklung)
|
||||
188
tasks/02-database.md
Normal file
188
tasks/02-database.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Phase 2: Database (Drizzle ORM)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/12 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Setup Drizzle ORM, define complete database schema for all tables (users, products, carts, cart_items, orders, order_items), generate and apply migrations, and create database utilities.
|
||||
|
||||
**Goal:** Fully functional database with all MVP tables ready for use.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 1: Foundation must be completed
|
||||
- ✅ PostgreSQL running in Docker (docker-compose.dev.yml)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Drizzle Setup
|
||||
|
||||
- [ ] Install Drizzle ORM & PostgreSQL driver
|
||||
|
||||
```bash
|
||||
pnpm add drizzle-orm postgres
|
||||
pnpm add -D drizzle-kit
|
||||
```
|
||||
|
||||
- [ ] Configure drizzle.config.ts
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from 'drizzle-kit'
|
||||
|
||||
export default defineConfig({
|
||||
schema: './server/database/schema.ts',
|
||||
out: './server/database/migrations',
|
||||
dialect: 'postgresql',
|
||||
dbCredentials: {
|
||||
url: process.env.DATABASE_URL!,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
- [ ] Add database scripts to package.json
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"db:generate": "drizzle-kit generate",
|
||||
"db:migrate": "drizzle-kit migrate",
|
||||
"db:studio": "drizzle-kit studio",
|
||||
"db:push": "drizzle-kit push"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Schema Definition
|
||||
|
||||
- [ ] Create users table schema
|
||||
- File: `server/database/schema.ts`
|
||||
- Fields: id (UUID), experimenta_id (unique), email, first_name, last_name, salutation, date_of_birth, street, post_code, city, country_code, phone, created_at, updated_at
|
||||
- See: [ARCHITECTURE.md Section 4.1](../docs/ARCHITECTURE.md#41-datenbank-schema)
|
||||
|
||||
- [ ] Create products table schema
|
||||
- Fields: id (UUID), nav_product_id (unique), name, description, price (decimal), stock_quantity, category, active, created_at, updated_at
|
||||
- Indexes: nav_product_id, active, category
|
||||
|
||||
- [ ] Create carts table schema
|
||||
- Fields: id (UUID), user_id (FK to users, nullable), session_id, created_at, updated_at
|
||||
- Relations: hasMany cart_items
|
||||
|
||||
- [ ] Create cart_items table schema
|
||||
- Fields: id (UUID), cart_id (FK to carts), product_id (FK to products), quantity, added_at
|
||||
- Relations: belongsTo cart, belongsTo product
|
||||
|
||||
- [ ] Create orders table schema
|
||||
- Fields: id (UUID), order_number (unique), user_id (FK to users), total_amount, status, billing_address (JSON), payment_id, payment_completed_at, created_at, updated_at
|
||||
- Relations: hasMany order_items
|
||||
- Indexes: order_number, user_id, status
|
||||
|
||||
- [ ] Create order_items table schema
|
||||
- Fields: id (UUID), order_id (FK to orders), product_id (FK to products), product_snapshot (JSON), quantity, price_snapshot, created_at
|
||||
- Relations: belongsTo order, belongsTo product
|
||||
|
||||
### Migrations
|
||||
|
||||
- [ ] Generate initial migration
|
||||
|
||||
```bash
|
||||
pnpm db:generate
|
||||
```
|
||||
|
||||
- Verify migration files in `server/database/migrations/`
|
||||
|
||||
- [ ] Apply migrations to dev database
|
||||
|
||||
```bash
|
||||
pnpm db:migrate
|
||||
```
|
||||
|
||||
- Verify tables exist in PostgreSQL
|
||||
|
||||
```bash
|
||||
docker exec -it experimenta-db-dev psql -U dev -d experimenta_dev -c "\dt"
|
||||
```
|
||||
|
||||
### Database Utilities
|
||||
|
||||
- [ ] Create database connection utility
|
||||
- File: `server/utils/db.ts`
|
||||
|
||||
```typescript
|
||||
import { drizzle } from 'drizzle-orm/postgres-js'
|
||||
import postgres from 'postgres'
|
||||
import * as schema from '../database/schema'
|
||||
|
||||
const config = useRuntimeConfig()
|
||||
const client = postgres(config.databaseUrl)
|
||||
export const db = drizzle(client, { schema })
|
||||
```
|
||||
|
||||
- [ ] Test CRUD operations
|
||||
- Create test endpoint: `server/api/test/db.get.ts`
|
||||
- Test insert, select, update, delete on users table
|
||||
- Verify relations work (e.g., fetch cart with items)
|
||||
- Remove test endpoint after verification
|
||||
|
||||
### Tools
|
||||
|
||||
- [ ] Setup Drizzle Studio
|
||||
|
||||
```bash
|
||||
pnpm db:studio
|
||||
```
|
||||
|
||||
- Open http://localhost:4983
|
||||
- Verify all tables are visible
|
||||
- Test data manipulation via Studio
|
||||
|
||||
- [ ] Document schema decisions
|
||||
- Add comments to schema.ts explaining design choices
|
||||
- Document why JSONB for billing_address
|
||||
- Document why UUID vs serial IDs
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Drizzle ORM is installed and configured
|
||||
- [x] All 6 tables are defined in schema.ts (users, products, carts, cart_items, orders, order_items)
|
||||
- [x] Relations between tables are defined correctly
|
||||
- [x] Initial migration is generated and applied
|
||||
- [x] All tables exist in PostgreSQL database
|
||||
- [x] Database connection utility (db.ts) is working
|
||||
- [x] CRUD operations work as expected
|
||||
- [x] Drizzle Studio can connect and display tables
|
||||
- [x] Schema is documented with comments
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **UUID vs Serial:** Using UUIDs for better distributed systems support and security
|
||||
- **JSONB for billing_address:** Flexible address storage, avoids complex normalized address tables
|
||||
- **Decimal for prices:** Using decimal(10,2) for accurate money calculations
|
||||
- **created_at/updated_at:** Timestamps for audit trail
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- None currently
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [ARCHITECTURE.md: Database Schema](../docs/ARCHITECTURE.md#41-datenbank-schema)
|
||||
- [TECH_STACK.md: Drizzle ORM](../docs/TECH_STACK.md#5-orm)
|
||||
- [TECH_STACK.md: PostgreSQL](../docs/TECH_STACK.md#4-datenbank)
|
||||
- [CLAUDE.md: Database Schema](../CLAUDE.md#database-schema)
|
||||
228
tasks/03-authentication.md
Normal file
228
tasks/03-authentication.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Phase 3: Authentication (Cidaas OAuth2/OIDC)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/18 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement complete Cidaas OAuth2/OIDC authentication with custom UI: login, registration, logout, session management, JWT validation, and rate limiting.
|
||||
|
||||
**Goal:** Fully functional authentication system with custom experimenta-branded login/registration UI.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 1: Foundation must be completed
|
||||
- ✅ Phase 2: Database must be completed (users table needed)
|
||||
- ⚠️ **Required:** Cidaas credentials (CLIENT_ID, CLIENT_SECRET, BASE_URL)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Dependencies Installation
|
||||
|
||||
- [ ] Install nuxt-auth-utils + jose
|
||||
|
||||
```bash
|
||||
pnpm add nuxt-auth-utils jose
|
||||
```
|
||||
|
||||
- [ ] Configure Cidaas environment variables in .env
|
||||
|
||||
```bash
|
||||
CIDAAS_BASE_URL=https://experimenta.cidaas.de
|
||||
CIDAAS_CLIENT_ID=xxx
|
||||
CIDAAS_CLIENT_SECRET=xxx
|
||||
CIDAAS_REDIRECT_URI=http://localhost:3000/api/auth/callback
|
||||
```
|
||||
|
||||
- [ ] Add Cidaas config to nuxt.config.ts runtimeConfig
|
||||
```typescript
|
||||
runtimeConfig: {
|
||||
cidaas: {
|
||||
baseUrl: process.env.CIDAAS_BASE_URL,
|
||||
clientId: process.env.CIDAAS_CLIENT_ID,
|
||||
clientSecret: process.env.CIDAAS_CLIENT_SECRET,
|
||||
redirectUri: process.env.CIDAAS_REDIRECT_URI,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Server Utilities
|
||||
|
||||
- [ ] Create PKCE generator utility
|
||||
- File: `server/utils/pkce.ts`
|
||||
- Functions: `generatePKCE()` → returns { verifier, challenge }
|
||||
- Implementation: See [CIDAAS_INTEGRATION.md](../docs/CIDAAS_INTEGRATION.md#5-server-utilities)
|
||||
|
||||
- [ ] Create Cidaas API client utility
|
||||
- File: `server/utils/cidaas.ts`
|
||||
- Functions:
|
||||
- `exchangeCodeForToken(code, verifier)` → tokens
|
||||
- `fetchUserInfo(accessToken)` → user data
|
||||
- `registerUser(userData)` → registration result
|
||||
- See: [CIDAAS_INTEGRATION.md](../docs/CIDAAS_INTEGRATION.md#5-server-utilities)
|
||||
|
||||
- [ ] Create JWT validation utility
|
||||
- File: `server/utils/jwt.ts`
|
||||
- Function: `verifyIdToken(idToken)` → payload
|
||||
- Uses: jose library with JWKS
|
||||
- See: [CLAUDE.md: JWT Validation Pattern](../CLAUDE.md#jwt-validation-pattern)
|
||||
|
||||
### Auth API Endpoints
|
||||
|
||||
- [ ] Create /api/auth/login.post.ts endpoint
|
||||
- Generates PKCE challenge & state
|
||||
- Stores in HTTP-only cookies (5min TTL)
|
||||
- Returns Cidaas authorization URL
|
||||
- See: [CLAUDE.md: OAuth2 Login Flow](../CLAUDE.md#oauth2-login-flow-pattern)
|
||||
|
||||
- [ ] Create /api/auth/callback.get.ts endpoint
|
||||
- Validates state (CSRF protection)
|
||||
- Exchanges code for tokens (with PKCE)
|
||||
- Validates ID token (JWT)
|
||||
- Fetches user info from Cidaas
|
||||
- Creates/updates user in local DB
|
||||
- Creates encrypted session (nuxt-auth-utils)
|
||||
- Redirects to homepage
|
||||
- See: [CLAUDE.md: OAuth2 Callback](../CLAUDE.md#oauth2-callback-pattern)
|
||||
|
||||
- [ ] Create /api/auth/register.post.ts endpoint
|
||||
- Validates registration data (Zod schema)
|
||||
- Calls Cidaas registration API
|
||||
- Returns success/error
|
||||
- See: [CLAUDE.md: User Registration](../CLAUDE.md#user-registration-pattern)
|
||||
|
||||
- [ ] Create /api/auth/logout.post.ts endpoint
|
||||
- Clears session via clearUserSession()
|
||||
- Optional: Single Sign-Out at Cidaas
|
||||
- Returns success
|
||||
|
||||
- [ ] Create /api/auth/me.get.ts endpoint
|
||||
- Protected endpoint (requires session)
|
||||
- Returns current user data
|
||||
- Uses: requireUserSession()
|
||||
|
||||
### Client-Side Composables
|
||||
|
||||
- [ ] Create useAuth composable
|
||||
- File: `composables/useAuth.ts`
|
||||
- Functions:
|
||||
- `login(email)` → redirects to Cidaas
|
||||
- `logout()` → clears session, redirects
|
||||
- `register(data)` → calls registration API
|
||||
- Uses: useUserSession from nuxt-auth-utils
|
||||
- Returns: { user, loggedIn, login, logout, register }
|
||||
- See: [CLAUDE.md: OAuth2 Login Flow](../CLAUDE.md#oauth2-login-flow-pattern)
|
||||
|
||||
### UI Components
|
||||
|
||||
- [ ] Create LoginForm component
|
||||
- File: `components/Auth/LoginForm.vue`
|
||||
- Fields: Email input
|
||||
- Button: "Login with Cidaas"
|
||||
- Calls: `login(email)` from useAuth
|
||||
- See: [CIDAAS_INTEGRATION.md: UI Components](../docs/CIDAAS_INTEGRATION.md#8-ui-components)
|
||||
|
||||
- [ ] Create RegisterForm component
|
||||
- File: `components/Auth/RegisterForm.vue`
|
||||
- Fields: Email, Password, Confirm Password, First Name, Last Name
|
||||
- Validation: VeeValidate + Zod
|
||||
- Calls: `register(data)` from useAuth
|
||||
- See: [CIDAAS_INTEGRATION.md: UI Components](../docs/CIDAAS_INTEGRATION.md#8-ui-components)
|
||||
|
||||
- [ ] Create auth page with tabs
|
||||
- File: `pages/auth.vue`
|
||||
- Tabs: Login | Register (shadcn-nuxt Tabs component)
|
||||
- Embeds: LoginForm + RegisterForm
|
||||
- Styling: experimenta branding
|
||||
- See: [CIDAAS_INTEGRATION.md: UI Components](../docs/CIDAAS_INTEGRATION.md#8-ui-components)
|
||||
|
||||
### Middleware
|
||||
|
||||
- [ ] Create auth middleware
|
||||
- File: `middleware/auth.ts`
|
||||
- Redirects to /auth if not logged in
|
||||
- Stores intended destination for post-login redirect
|
||||
- See: [CLAUDE.md: Protected Route Middleware](../CLAUDE.md#protected-route-middleware-pattern)
|
||||
|
||||
- [ ] Create rate-limit middleware
|
||||
- File: `server/middleware/rate-limit.ts`
|
||||
- Limits:
|
||||
- /api/auth/login: 5 attempts / 15min per IP
|
||||
- /api/auth/register: 3 attempts / 1hour per IP
|
||||
- Returns 429 on exceed
|
||||
- See: [CLAUDE.md: Rate Limiting](../CLAUDE.md#rate-limiting-pattern)
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test OAuth2 flow end-to-end
|
||||
- Start at /auth page
|
||||
- Click "Login"
|
||||
- Redirect to Cidaas (if credentials configured)
|
||||
- Complete login
|
||||
- Verify callback works
|
||||
- Verify user created in DB
|
||||
- Verify session works
|
||||
|
||||
- [ ] Test session management
|
||||
- Verify session persists across page reloads
|
||||
- Verify session expires after 30 days (or config)
|
||||
- Test logout clears session
|
||||
|
||||
- [ ] Document authentication flow
|
||||
- Add detailed flow diagram to docs/CIDAAS_INTEGRATION.md (already exists)
|
||||
- Document any deviations from plan
|
||||
- Document Cidaas-specific quirks encountered
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] nuxt-auth-utils and jose are installed
|
||||
- [x] All utilities (PKCE, Cidaas client, JWT) are implemented
|
||||
- [x] All 5 auth endpoints work correctly
|
||||
- [x] useAuth composable is functional
|
||||
- [x] LoginForm and RegisterForm components are styled and functional
|
||||
- [x] /auth page shows tabs with both forms
|
||||
- [x] auth middleware protects routes correctly
|
||||
- [x] rate-limit middleware works and returns 429 when exceeded
|
||||
- [x] OAuth2 flow works end-to-end (login → callback → session)
|
||||
- [x] Session management works (persist, expire, clear)
|
||||
- [x] User is created/updated in local DB on first login
|
||||
- [x] JWT tokens are validated correctly
|
||||
- [x] PKCE flow prevents authorization code interception
|
||||
- [x] State parameter prevents CSRF attacks
|
||||
- [x] Authentication is fully documented
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Cidaas Credentials:** You'll need to request CLIENT_ID and CLIENT_SECRET from experimenta admin
|
||||
- **Redirect URI:** Must be registered in Cidaas Admin Panel: `http://localhost:3000/api/auth/callback` (dev), `https://my.experimenta.science/api/auth/callback` (prod)
|
||||
- **Session Duration:** Configured to 30 days (can be adjusted in nuxt-auth-utils config)
|
||||
- **Custom UI:** We're NOT using Cidaas hosted pages - fully custom experimenta-branded UI
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **Cidaas Credentials Missing:** Cannot test OAuth2 flow without CLIENT_ID/SECRET
|
||||
- **Workaround:** Implement everything, test with mock/manual verification until credentials available
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/CIDAAS_INTEGRATION.md](../docs/CIDAAS_INTEGRATION.md) - Complete implementation guide
|
||||
- [docs/ARCHITECTURE.md: Section 3.6](../docs/ARCHITECTURE.md#36-authentication--authorization-cidaas-oauth2oidc)
|
||||
- [CLAUDE.md: Authentication Patterns](../CLAUDE.md#authentication-patterns)
|
||||
- [docs/PRD.md: US-001, US-002](../docs/PRD.md#51-authentifizierung--benutzerverwaltung)
|
||||
162
tasks/04-products.md
Normal file
162
tasks/04-products.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Phase 4: Products (Display & List)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/10 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement product display functionality: API endpoints for fetching products, product list/detail pages, and UI components for displaying Makerspace annual passes.
|
||||
|
||||
**Goal:** Users can browse and view Makerspace-Jahreskarten products.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 1: Foundation must be completed
|
||||
- ✅ Phase 2: Database must be completed (products table needed)
|
||||
- ⚠️ **Optional:** Phase 3: Authentication (for future protected features)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### API Endpoints
|
||||
|
||||
- [ ] Create /api/products/index.get.ts endpoint
|
||||
- Query products from DB (Drizzle)
|
||||
- Filter by: active=true, category (optional)
|
||||
- Sort by: name, price
|
||||
- Return: Array of products
|
||||
- Example:
|
||||
```typescript
|
||||
export default defineEventHandler(async (event) => {
|
||||
const { category } = getQuery(event)
|
||||
const products = await db.query.products.findMany({
|
||||
where: and(
|
||||
eq(products.active, true),
|
||||
category ? eq(products.category, category) : undefined
|
||||
),
|
||||
orderBy: products.name,
|
||||
})
|
||||
return products
|
||||
})
|
||||
```
|
||||
|
||||
- [ ] Create /api/products/[id].get.ts endpoint
|
||||
- Validate ID (Zod: UUID)
|
||||
- Query product by ID
|
||||
- Return 404 if not found
|
||||
- Return: Product object
|
||||
- See: [CLAUDE.md: API Route Example](../CLAUDE.md#api-route-example)
|
||||
|
||||
### UI Components
|
||||
|
||||
- [ ] Create ProductCard component
|
||||
- File: `components/Product/ProductCard.vue`
|
||||
- Props: product (object)
|
||||
- Display: Image, name, price, short description
|
||||
- Button: "In den Warenkorb" (Add to Cart)
|
||||
- Styling: shadcn-nuxt Card component + Tailwind
|
||||
- Mobile-first design
|
||||
|
||||
- [ ] Create ProductList component
|
||||
- File: `components/Product/ProductList.vue`
|
||||
- Props: products (array)
|
||||
- Grid layout: 1 col (mobile), 2 cols (tablet), 3 cols (desktop)
|
||||
- Uses: ProductCard for each product
|
||||
- Empty state: "Keine Produkte verfügbar"
|
||||
|
||||
- [ ] Create ProductDetail component
|
||||
- File: `components/Product/ProductDetail.vue`
|
||||
- Props: product (object)
|
||||
- Display: Large image, full description, price, stock status
|
||||
- Button: "In den Warenkorb"
|
||||
- Breadcrumb: Home > Produkte > [Product Name]
|
||||
|
||||
### Pages
|
||||
|
||||
- [ ] Create products index page
|
||||
- File: `pages/produkte/index.vue` (German route)
|
||||
- Fetches products from API
|
||||
- Uses: ProductList component
|
||||
- Title: "Makerspace-Jahreskarten"
|
||||
- SEO meta tags
|
||||
|
||||
- [ ] Create ProductDetail page
|
||||
- File: `pages/produkte/[id].vue`
|
||||
- Fetches product by ID from API
|
||||
- Uses: ProductDetail component
|
||||
- 404 page if product not found
|
||||
- SEO meta tags with product data
|
||||
|
||||
### Asset Handling
|
||||
|
||||
- [ ] Add product images handling
|
||||
- Create `/public/images/products/` folder
|
||||
- Add placeholder image for products without image
|
||||
- Document image requirements (size, format)
|
||||
- Optimize images (use Nuxt Image module if needed)
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test product display
|
||||
- Seed database with sample products (manual or seed script)
|
||||
- Visit /produkte page
|
||||
- Verify products display correctly
|
||||
- Verify responsive design (mobile, tablet, desktop)
|
||||
- Click product to view detail page
|
||||
- Verify product detail displays correctly
|
||||
|
||||
- [ ] Optimize product queries
|
||||
- Add indexes to products table if needed (active, category)
|
||||
- Test query performance with 100+ products
|
||||
- Add pagination if needed (future enhancement)
|
||||
|
||||
- [ ] Document product schema
|
||||
- Document product data structure in code comments
|
||||
- Document how images are stored/referenced
|
||||
- Document category values (e.g., "makerspace-jahreskarte")
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] /api/products endpoint returns all active products
|
||||
- [x] /api/products/[id] endpoint returns product by ID
|
||||
- [x] ProductCard component displays product correctly
|
||||
- [x] ProductList component shows products in grid layout
|
||||
- [x] ProductDetail component shows full product info
|
||||
- [x] /produkte page lists all products
|
||||
- [x] /produkte/[id] page shows product detail
|
||||
- [x] Images display correctly (or placeholder if missing)
|
||||
- [x] Responsive design works on mobile/tablet/desktop
|
||||
- [x] Product data structure is documented
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **MVP Scope:** Only Makerspace-Jahreskarten products for now
|
||||
- **Images:** Can use placeholders initially, real images added later
|
||||
- **Pagination:** Not needed for MVP (< 10 products expected)
|
||||
- **Filters:** Category filter can be added later if needed
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- None currently (can use mock products if NAV ERP sync not ready)
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: F-004](../docs/PRD.md#f-004-produktanzeige)
|
||||
- [docs/ARCHITECTURE.md: Products Table](../docs/ARCHITECTURE.md#products)
|
||||
- [CLAUDE.md: API Route Example](../CLAUDE.md#api-route-example)
|
||||
156
tasks/05-cart.md
Normal file
156
tasks/05-cart.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Phase 5: Cart (Shopping Cart)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/12 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement shopping cart functionality: API endpoints for cart operations, cart composable, and UI components for cart display and management.
|
||||
|
||||
**Goal:** Users can add products to cart, update quantities, and remove items.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 2: Database must be completed (carts, cart_items tables needed)
|
||||
- ✅ Phase 3: Authentication should be completed (for user-specific carts)
|
||||
- ✅ Phase 4: Products must be completed (products needed in cart)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### API Endpoints
|
||||
|
||||
- [ ] Create /api/cart/index.get.ts endpoint
|
||||
- Get current user's cart (or session cart for guests)
|
||||
- Include cart items with product details (join)
|
||||
- Calculate total price
|
||||
- Return: { cart, items: [{product, quantity, subtotal}], total }
|
||||
|
||||
- [ ] Create /api/cart/items.post.ts endpoint
|
||||
- Add item to cart (body: {productId, quantity})
|
||||
- Validate product exists and has stock
|
||||
- Create cart if doesn't exist
|
||||
- Upsert cart_item (update quantity if already exists)
|
||||
- Return: Updated cart
|
||||
|
||||
- [ ] Create /api/cart/items/[id].patch.ts endpoint
|
||||
- Update cart item quantity (body: {quantity})
|
||||
- Validate quantity > 0
|
||||
- Validate stock availability
|
||||
- Return: Updated cart item
|
||||
|
||||
- [ ] Create /api/cart/items/[id].delete.ts endpoint
|
||||
- Remove item from cart
|
||||
- Delete cart_item record
|
||||
- Return: 204 No Content
|
||||
|
||||
### Composables
|
||||
|
||||
- [ ] Create useCart composable
|
||||
- File: `composables/useCart.ts`
|
||||
- State: cart (ref), items (computed), total (computed), itemCount (computed)
|
||||
- Functions:
|
||||
- `fetchCart()` - Load cart from API
|
||||
- `addItem(productId, quantity)` - Add to cart
|
||||
- `updateItem(itemId, quantity)` - Update quantity
|
||||
- `removeItem(itemId)` - Remove from cart
|
||||
- `clearCart()` - Empty cart
|
||||
- Auto-fetch on mount
|
||||
- See similar pattern: [CLAUDE.md: useAuth](../CLAUDE.md#oauth2-login-flow-pattern)
|
||||
|
||||
### UI Components
|
||||
|
||||
- [ ] Create CartItem component
|
||||
- File: `components/Cart/CartItem.vue`
|
||||
- Props: item (object with product, quantity, subtotal)
|
||||
- Display: Product image, name, price, quantity input, subtotal
|
||||
- Actions: Update quantity, Remove button
|
||||
- Emits: @update, @remove
|
||||
|
||||
- [ ] Create CartSummary component
|
||||
- File: `components/Cart/CartSummary.vue`
|
||||
- Props: items (array), total (number)
|
||||
- Display: Items count, subtotal, VAT, total
|
||||
- Button: "Zur Kasse" (to checkout)
|
||||
- Styling: shadcn-nuxt Card
|
||||
|
||||
### Pages
|
||||
|
||||
- [ ] Create cart page
|
||||
- File: `pages/warenkorb.vue` (German route)
|
||||
- Uses: useCart composable
|
||||
- Shows: List of CartItem components + CartSummary
|
||||
- Empty state: "Ihr Warenkorb ist leer" with link to /produkte
|
||||
- Loading state while fetching
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test cart operations
|
||||
- Add product to cart from product page
|
||||
- Verify cart count updates (header badge)
|
||||
- Visit /warenkorb page
|
||||
- Update quantity via input
|
||||
- Remove item via button
|
||||
- Verify total updates correctly
|
||||
|
||||
- [ ] Add cart persistence
|
||||
- For logged-in users: cart stored in DB (user_id)
|
||||
- For guests: cart stored in DB (session_id)
|
||||
- Test cart persists across page reloads
|
||||
- Test cart merges when guest logs in (optional, can defer)
|
||||
|
||||
- [ ] Optimize cart queries
|
||||
- Ensure product details are fetched efficiently (join, not N+1)
|
||||
- Test with 10+ items in cart
|
||||
- Add indexes if needed
|
||||
|
||||
- [ ] Document cart logic
|
||||
- Document cart/session relationship
|
||||
- Document cart item uniqueness (cart_id + product_id)
|
||||
- Document cart cleanup strategy (old carts)
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] All 4 cart API endpoints work correctly
|
||||
- [x] useCart composable manages cart state
|
||||
- [x] CartItem component displays and allows editing
|
||||
- [x] CartSummary component shows total correctly
|
||||
- [x] /warenkorb page shows cart with all items
|
||||
- [x] Can add products to cart from product pages
|
||||
- [x] Can update item quantities in cart
|
||||
- [x] Can remove items from cart
|
||||
- [x] Cart total calculates correctly
|
||||
- [x] Cart persists across page reloads
|
||||
- [x] Empty cart shows helpful message
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Guest Carts:** Use session_id for guest carts (cookie-based)
|
||||
- **Cart Merge:** When guest logs in, merge guest cart with user cart (optional for MVP)
|
||||
- **Stock Validation:** Ensure quantity doesn't exceed stock when adding/updating
|
||||
- **VAT:** 7% VAT for annual passes (hardcoded for MVP)
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- None currently
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: F-005](../docs/PRD.md#f-005-warenkorb)
|
||||
- [docs/ARCHITECTURE.md: Carts Tables](../docs/ARCHITECTURE.md#carts)
|
||||
171
tasks/06-checkout.md
Normal file
171
tasks/06-checkout.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Phase 6: Checkout (Forms & Flow)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/15 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement checkout flow: billing address form, validation, address pre-fill from user profile, save address to profile option.
|
||||
|
||||
**Goal:** Users can enter billing information and proceed to payment.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 2: Database (users table with address fields)
|
||||
- ✅ Phase 3: Authentication (user session needed)
|
||||
- ✅ Phase 5: Cart (checkout requires items in cart)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Schema & Validation
|
||||
|
||||
- [ ] Create checkout schema (Zod)
|
||||
- File: `server/utils/schemas/checkout.ts`
|
||||
- Fields: salutation, firstName, lastName, dateOfBirth, street, postCode, city, countryCode
|
||||
- Validation rules: required fields, date format, postal code format
|
||||
- Export: `checkoutSchema`, `CheckoutData` type
|
||||
|
||||
### API Endpoints
|
||||
|
||||
- [ ] Create /api/checkout/validate.post.ts endpoint
|
||||
- Validates checkout data (Zod)
|
||||
- Checks if user is logged in
|
||||
- Checks if cart has items
|
||||
- Returns: validation result or errors
|
||||
|
||||
### UI Components
|
||||
|
||||
- [ ] Create CheckoutForm component
|
||||
- File: `components/Checkout/CheckoutForm.vue`
|
||||
- Uses: VeeValidate + Zod schema
|
||||
- Fields: All billing address fields
|
||||
- Checkbox: "Adresse für zukünftige Bestellungen speichern"
|
||||
- Pre-checked if user has no saved address
|
||||
- Button: "Weiter zur Zahlung"
|
||||
- See: [CLAUDE.md: Checkout Pattern](../CLAUDE.md#checkout-with-saved-address-pattern)
|
||||
|
||||
- [ ] Create AddressForm component (reusable)
|
||||
- File: `components/Checkout/AddressForm.vue`
|
||||
- Props: modelValue (address object), errors
|
||||
- Emits: @update:modelValue
|
||||
- Fields: Salutation dropdown, Name fields, Address fields
|
||||
- Can be reused in profile settings later
|
||||
|
||||
### Core Functionality
|
||||
|
||||
- [ ] Implement address pre-fill from user profile
|
||||
- In CheckoutForm: fetch user data from useAuth
|
||||
- If user has saved address (user.street exists): pre-fill all fields
|
||||
- If no saved address: show empty form
|
||||
|
||||
- [ ] Implement save address to profile
|
||||
- After successful checkout: if checkbox checked, save address to user record
|
||||
- Update users table: salutation, dateOfBirth, street, postCode, city, countryCode
|
||||
- API endpoint: PATCH /api/user/profile (or include in order creation)
|
||||
|
||||
### Pages
|
||||
|
||||
- [ ] Create checkout page
|
||||
- File: `pages/kasse.vue` (German route)
|
||||
- Middleware: `auth` (requires login)
|
||||
- Shows: CheckoutForm component
|
||||
- Shows: Order summary (cart items + total)
|
||||
- Redirects to /warenkorb if cart is empty
|
||||
|
||||
### Validation & Error Handling
|
||||
|
||||
- [ ] Add form validation (VeeValidate)
|
||||
- Install VeeValidate + @vee-validate/zod
|
||||
- Configure VeeValidate with Zod integration
|
||||
- Show field-level errors
|
||||
- Show form-level errors (e.g., "Cart is empty")
|
||||
|
||||
- [ ] Add error handling
|
||||
- Handle validation errors gracefully
|
||||
- Show user-friendly error messages
|
||||
- Disable submit button while submitting
|
||||
- Show loading spinner during submission
|
||||
|
||||
- [ ] Add loading states
|
||||
- Loading: fetching user profile
|
||||
- Loading: validating checkout data
|
||||
- Loading: processing payment (next phase)
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test checkout flow
|
||||
- Login as user with saved address → verify pre-fill
|
||||
- Login as new user → verify empty form
|
||||
- Fill form and submit → verify validation
|
||||
- Submit with invalid data → verify error messages
|
||||
- Submit with valid data → proceed to payment (next phase)
|
||||
|
||||
- [ ] Test address save/load
|
||||
- Submit checkout with "save address" checked
|
||||
- Verify user record updated in DB
|
||||
- Start new checkout → verify address pre-filled
|
||||
|
||||
- [ ] Test mobile checkout
|
||||
- Test form on mobile device/emulator
|
||||
- Verify fields are easy to tap and type
|
||||
- Verify keyboard shows correct type (e.g., numeric for postal code)
|
||||
|
||||
- [ ] Optimize checkout UX
|
||||
- Autofocus first field
|
||||
- Tab order is logical
|
||||
- Error messages are clear and helpful
|
||||
- Button placement is accessible
|
||||
|
||||
- [ ] Document checkout logic
|
||||
- Document address save/load flow
|
||||
- Document validation rules
|
||||
- Document error handling strategy
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Checkout schema is defined with Zod
|
||||
- [x] CheckoutForm component is functional and styled
|
||||
- [x] AddressForm component is reusable
|
||||
- [x] Address pre-fills from user profile if available
|
||||
- [x] "Save address" checkbox works correctly
|
||||
- [x] /kasse page is protected (requires auth)
|
||||
- [x] Form validation works (VeeValidate + Zod)
|
||||
- [x] Field-level and form-level errors display correctly
|
||||
- [x] Loading states show during async operations
|
||||
- [x] Mobile checkout UX is optimized
|
||||
- [x] Address is saved to user profile after successful checkout
|
||||
- [x] Checkout flow is documented
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Required Fields:** All address fields are required at checkout (even though optional in DB)
|
||||
- **Date of Birth:** Required for annual pass registration
|
||||
- **Salutation:** Dropdown with values: "Herr", "Frau", "Keine Angabe" (maps to HERR, FRAU, K_ANGABE in X-API)
|
||||
- **Country Code:** Default to "DE", allow selection for international customers
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- None currently
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: F-006](../docs/PRD.md#f-006-checkout-prozess)
|
||||
- [docs/ARCHITECTURE.md: Users Table](../docs/ARCHITECTURE.md#users)
|
||||
- [CLAUDE.md: Checkout Pattern](../CLAUDE.md#checkout-with-saved-address-pattern)
|
||||
186
tasks/07-payment.md
Normal file
186
tasks/07-payment.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Phase 7: Payment (PayPal Integration)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/12 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Integrate PayPal payment gateway: create order, capture payment, handle webhooks, and manage payment success/failure flows.
|
||||
|
||||
**Goal:** Users can pay for their orders securely via PayPal.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 5: Cart (payment requires cart data)
|
||||
- ✅ Phase 6: Checkout (billing info needed for order)
|
||||
- ⚠️ **Required:** PayPal credentials (CLIENT_ID, CLIENT_SECRET)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Setup
|
||||
|
||||
- [ ] Install PayPal SDK
|
||||
|
||||
```bash
|
||||
pnpm add @paypal/checkout-server-sdk
|
||||
```
|
||||
|
||||
- [ ] Configure PayPal credentials in .env
|
||||
|
||||
```bash
|
||||
PAYPAL_CLIENT_ID=xxx
|
||||
PAYPAL_CLIENT_SECRET=xxx
|
||||
PAYPAL_MODE=sandbox # or 'live' for production
|
||||
```
|
||||
|
||||
- [ ] Add PayPal config to nuxt.config.ts
|
||||
```typescript
|
||||
runtimeConfig: {
|
||||
paypal: {
|
||||
clientId: process.env.PAYPAL_CLIENT_ID,
|
||||
clientSecret: process.env.PAYPAL_CLIENT_SECRET,
|
||||
mode: process.env.PAYPAL_MODE || 'sandbox',
|
||||
},
|
||||
public: {
|
||||
paypalClientId: process.env.PAYPAL_CLIENT_ID, // For client-side SDK
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
- [ ] Create /api/payment/paypal/create.post.ts endpoint
|
||||
- Body: { cartId, billingAddress }
|
||||
- Create PayPal order via SDK
|
||||
- Amount: cart total in EUR
|
||||
- Description: "Makerspace-Jahreskarte"
|
||||
- Return: { orderId, approvalUrl }
|
||||
- See: PayPal Orders API v2
|
||||
|
||||
- [ ] Create /api/payment/paypal/capture.post.ts endpoint
|
||||
- Body: { orderId, paypalOrderId }
|
||||
- Capture PayPal payment
|
||||
- If successful:
|
||||
- Create order in local DB (orders, order_items)
|
||||
- Queue order for X-API submission (BullMQ)
|
||||
- Clear user's cart
|
||||
- Return: { success: true, orderNumber }
|
||||
- If failed:
|
||||
- Return: { success: false, error }
|
||||
|
||||
- [ ] Create /api/payment/paypal/webhook.post.ts endpoint
|
||||
- Verify webhook signature (PayPal SDK)
|
||||
- Handle events:
|
||||
- CHECKOUT.ORDER.APPROVED
|
||||
- PAYMENT.CAPTURE.COMPLETED
|
||||
- PAYMENT.CAPTURE.DENIED
|
||||
- Update order status in DB based on event
|
||||
- Log all webhook events
|
||||
- Return: 200 OK (acknowledge receipt)
|
||||
|
||||
### Client-Side Integration
|
||||
|
||||
- [ ] Integrate PayPal button on checkout
|
||||
- File: `components/Checkout/PayPalButton.vue`
|
||||
- Load PayPal JavaScript SDK
|
||||
- Render PayPal button
|
||||
- On click: Call /api/payment/paypal/create
|
||||
- On approve: Call /api/payment/paypal/capture
|
||||
- On error: Show error message
|
||||
- See: PayPal Checkout Integration guide
|
||||
|
||||
### Payment Flows
|
||||
|
||||
- [ ] Implement payment success flow
|
||||
- After successful capture:
|
||||
- Redirect to /bestätigung/[orderNumber] (order confirmation page)
|
||||
- Show success message + order details
|
||||
- Show estimated delivery/activation time
|
||||
- Send confirmation email (optional for MVP)
|
||||
|
||||
- [ ] Implement payment error handling
|
||||
- On capture failure:
|
||||
- Show user-friendly error message
|
||||
- Keep cart intact (don't clear)
|
||||
- Log error for debugging
|
||||
- Offer retry or alternative payment method (future)
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test PayPal sandbox
|
||||
- Create sandbox account on PayPal Developer Portal
|
||||
- Use sandbox credentials in .env
|
||||
- Test complete flow: create → approve → capture
|
||||
- Test with PayPal test cards
|
||||
- Verify order is created in local DB
|
||||
|
||||
- [ ] Add payment status tracking
|
||||
- Order status field: 'pending', 'paid', 'failed', 'completed'
|
||||
- Update status after PayPal capture
|
||||
- Display status in user's order history
|
||||
|
||||
- [ ] Document PayPal integration
|
||||
- Document PayPal API flow
|
||||
- Document webhook events and handling
|
||||
- Document error scenarios and recovery
|
||||
- Document sandbox vs production setup
|
||||
|
||||
- [ ] Test webhook handling
|
||||
- Use PayPal webhook simulator in sandbox
|
||||
- Send test events to webhook endpoint
|
||||
- Verify events are processed correctly
|
||||
- Verify order status updates
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] PayPal SDK is installed and configured
|
||||
- [x] /api/payment/paypal/create endpoint works
|
||||
- [x] /api/payment/paypal/capture endpoint works
|
||||
- [x] /api/payment/paypal/webhook endpoint works
|
||||
- [x] PayPal button renders on checkout page
|
||||
- [x] Can create PayPal order successfully
|
||||
- [x] Can capture payment successfully
|
||||
- [x] Order is created in DB after successful payment
|
||||
- [x] Cart is cleared after successful payment
|
||||
- [x] User is redirected to confirmation page
|
||||
- [x] Payment errors are handled gracefully
|
||||
- [x] Webhook signature verification works
|
||||
- [x] Webhook events update order status
|
||||
- [x] Payment flow is documented
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Sandbox Testing:** Use PayPal sandbox for development
|
||||
- **Webhook URL:** Must be publicly accessible (use ngrok for local testing)
|
||||
- **Currency:** EUR for all transactions
|
||||
- **Amount Precision:** PayPal requires 2 decimal places (e.g., "19.99")
|
||||
- **Order Number:** Generate unique order number (e.g., "EXP-2025-0001")
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **PayPal Credentials:** Need sandbox credentials to test integration
|
||||
- ⚠️ **Webhook Testing:** Need public URL for webhook endpoint (ngrok)
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: F-007](../docs/PRD.md#f-007-paypal-integration)
|
||||
- [docs/TECH_STACK.md: PayPal](../docs/TECH_STACK.md#7-payment-gateway)
|
||||
- [PayPal Orders API](https://developer.paypal.com/docs/api/orders/v2/)
|
||||
- [PayPal Webhooks](https://developer.paypal.com/api/rest/webhooks/)
|
||||
251
tasks/08-order-processing.md
Normal file
251
tasks/08-order-processing.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# Phase 8: Order Processing (BullMQ + X-API)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/15 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement asynchronous order processing: BullMQ queue for order submission to X-API, worker for processing orders, retry logic, and BullBoard dashboard for monitoring.
|
||||
|
||||
**Goal:** Orders are reliably submitted to X-API (NAV ERP) after successful payment.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 2: Database (orders table needed)
|
||||
- ✅ Phase 7: Payment (orders created after payment)
|
||||
- ✅ Docker Redis running (from docker-compose.dev.yml)
|
||||
- ⚠️ **Required:** X-API credentials (USERNAME, PASSWORD, BASE_URL)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### BullMQ Setup
|
||||
|
||||
- [ ] Install BullMQ + ioredis
|
||||
|
||||
```bash
|
||||
pnpm add bullmq ioredis
|
||||
pnpm add -D @bull-board/api @bull-board/nuxt
|
||||
```
|
||||
|
||||
- [ ] Configure Redis connection
|
||||
- File: `server/utils/redis.ts`
|
||||
|
||||
```typescript
|
||||
import { Redis } from 'ioredis'
|
||||
|
||||
const config = useRuntimeConfig()
|
||||
export const redis = new Redis({
|
||||
host: config.redisHost,
|
||||
port: config.redisPort,
|
||||
password: config.redisPassword,
|
||||
maxRetriesPerRequest: null,
|
||||
})
|
||||
```
|
||||
|
||||
- [ ] Create order queue
|
||||
- File: `server/queues/orderQueue.ts`
|
||||
|
||||
```typescript
|
||||
import { Queue } from 'bullmq'
|
||||
import { redis } from '../utils/redis'
|
||||
|
||||
export const orderQueue = new Queue('x-api-orders', {
|
||||
connection: redis,
|
||||
defaultJobOptions: {
|
||||
attempts: 5,
|
||||
backoff: { type: 'exponential', delay: 2000 },
|
||||
removeOnComplete: 1000,
|
||||
removeOnFail: false,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
- [ ] Create order worker
|
||||
- File: `server/workers/orderWorker.ts`
|
||||
|
||||
```typescript
|
||||
import { Worker } from 'bullmq'
|
||||
import { redis } from '../utils/redis'
|
||||
|
||||
export const orderWorker = new Worker(
|
||||
'x-api-orders',
|
||||
async (job) => {
|
||||
const { orderId } = job.data
|
||||
|
||||
// 1. Fetch order from DB with items and user
|
||||
const order = await db.query.orders.findFirst({
|
||||
where: eq(orders.id, orderId),
|
||||
with: { items: true, user: true },
|
||||
})
|
||||
|
||||
// 2. Transform to X-API format
|
||||
const payload = transformOrderToXAPI(order, order.user)
|
||||
|
||||
// 3. Submit to X-API
|
||||
const result = await submitOrderToXAPI(payload)
|
||||
|
||||
// 4. Update order status
|
||||
await db
|
||||
.update(orders)
|
||||
.set({ status: 'completed', xapiResponse: result })
|
||||
.where(eq(orders.id, orderId))
|
||||
|
||||
return result
|
||||
},
|
||||
{
|
||||
connection: redis,
|
||||
concurrency: 5,
|
||||
limiter: { max: 10, duration: 1000 },
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### X-API Client
|
||||
|
||||
- [ ] Create X-API client utility
|
||||
- File: `server/utils/xapi/client.ts`
|
||||
- Functions:
|
||||
- `submitOrderToXAPI(payload)` - Submit order with retry logic & Basic Auth
|
||||
- See: [CLAUDE.md: X-API Order Transformation](../CLAUDE.md#x-api-order-transformation-pattern)
|
||||
|
||||
- [ ] Implement transformOrderToXAPI function
|
||||
- File: `server/utils/xapi/transformer.ts`
|
||||
- Transform order from DB schema to X-API schema
|
||||
- Critical transformations:
|
||||
- Prices: EUR (Decimal) → Cents (Integer): `Math.round(price * 100)`
|
||||
- Dates: JavaScript Date → ISO 8601 UTC: `.toISOString()`
|
||||
- Line numbers: 10000, 20000, 30000... (multiples of 10000)
|
||||
- Salutation: 'male' → 'HERR', 'female' → 'FRAU', other → 'K_ANGABE'
|
||||
- See: [docs/ARCHITECTURE.md: X-API Format](../docs/ARCHITECTURE.md#34-x-api-order-transformation)
|
||||
|
||||
- [ ] Implement submitOrderToXAPI with retry
|
||||
- Exponential backoff: 1s, 3s, 9s
|
||||
- Max 3 retries
|
||||
- HTTP Basic Auth header
|
||||
- Timeout: 30 seconds
|
||||
- Log all attempts
|
||||
- See: [CLAUDE.md: X-API Pattern](../CLAUDE.md#x-api-order-transformation-pattern)
|
||||
|
||||
### API Endpoints
|
||||
|
||||
- [ ] Create /api/orders/index.post.ts endpoint
|
||||
- Protected (requires auth)
|
||||
- Body: { billingAddress, paymentId }
|
||||
- Create order record in DB
|
||||
- Create order_items from cart
|
||||
- Queue order for X-API submission
|
||||
- Return: { orderId, orderNumber }
|
||||
|
||||
- [ ] Create /api/orders/[id].get.ts endpoint
|
||||
- Protected (requires auth)
|
||||
- Fetch order by ID (only user's own orders)
|
||||
- Include order items with product details
|
||||
- Return: Order object
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test queue processing
|
||||
- Add job to queue manually: `orderQueue.add('submit-order', { orderId: '...' })`
|
||||
- Verify worker picks up job
|
||||
- Verify job completes successfully
|
||||
- Check BullBoard dashboard
|
||||
|
||||
- [ ] Test X-API submission (mock)
|
||||
- Create mock X-API endpoint for testing
|
||||
- Submit order via queue
|
||||
- Verify transformation is correct
|
||||
- Verify Basic Auth header is present
|
||||
|
||||
- [ ] Add error handling & logging
|
||||
- Log all queue events (active, completed, failed, stalled)
|
||||
- Log X-API requests/responses
|
||||
- Handle X-API errors gracefully
|
||||
- Update order status on failure
|
||||
|
||||
### Monitoring
|
||||
|
||||
- [ ] Setup BullBoard dashboard
|
||||
- File: `server/api/admin/queues.ts`
|
||||
|
||||
```typescript
|
||||
import { createBullBoard } from '@bull-board/api'
|
||||
import { BullMQAdapter } from '@bull-board/api/bullMQAdapter'
|
||||
import { NuxtAdapter } from '@bull-board/nuxt'
|
||||
|
||||
const serverAdapter = new NuxtAdapter()
|
||||
serverAdapter.setBasePath('/admin/queues')
|
||||
|
||||
createBullBoard({
|
||||
queues: [new BullMQAdapter(orderQueue)],
|
||||
serverAdapter,
|
||||
})
|
||||
|
||||
export default fromNodeMiddleware(serverAdapter.registerPlugin())
|
||||
```
|
||||
|
||||
- Access at: http://localhost:3000/admin/queues
|
||||
|
||||
- [ ] Test retry logic
|
||||
- Simulate X-API failure (wrong credentials or mock 500 error)
|
||||
- Verify job retries with exponential backoff
|
||||
- Verify job moves to failed after 5 attempts
|
||||
- Check retry logs
|
||||
|
||||
- [ ] Document order processing
|
||||
- Document queue flow: payment → queue → worker → X-API
|
||||
- Document retry strategy
|
||||
- Document error handling and recovery
|
||||
- Document how to monitor queues
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] BullMQ is installed and configured
|
||||
- [x] Redis connection is working
|
||||
- [x] Order queue is created
|
||||
- [x] Order worker processes jobs correctly
|
||||
- [x] transformOrderToXAPI transforms orders correctly
|
||||
- [x] submitOrderToXAPI submits with Basic Auth and retry logic
|
||||
- [x] /api/orders endpoints create orders and queue jobs
|
||||
- [x] Queue processing works end-to-end
|
||||
- [x] X-API submissions succeed (or fail gracefully)
|
||||
- [x] Error handling and logging are comprehensive
|
||||
- [x] BullBoard dashboard is accessible and functional
|
||||
- [x] Retry logic works as expected
|
||||
- [x] Order processing is documented
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Async Processing:** Orders are queued immediately, processed in background
|
||||
- **Job Timeout:** 60 seconds per job (X-API timeout + overhead)
|
||||
- **Concurrency:** 5 jobs processed simultaneously
|
||||
- **Rate Limit:** 10 requests/second to X-API
|
||||
- **Failed Jobs:** Kept in Redis for manual inspection (not auto-deleted)
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **X-API Credentials:** Cannot test real submission without credentials
|
||||
- **Workaround:** Use mock X-API endpoint for testing, document real integration
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/ARCHITECTURE.md: Queue Architecture](../docs/ARCHITECTURE.md#35-queue-architektur-bullmq--redis)
|
||||
- [docs/ARCHITECTURE.md: X-API Format](../docs/ARCHITECTURE.md#34-x-api-order-transformation)
|
||||
- [docs/TECH_STACK.md: BullMQ](../docs/TECH_STACK.md#52-queue-system-bullmq)
|
||||
- [CLAUDE.md: X-API Pattern](../CLAUDE.md#x-api-order-transformation-pattern)
|
||||
147
tasks/09-erp-integration.md
Normal file
147
tasks/09-erp-integration.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Phase 9: ERP Integration (NAV Product Sync)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/10 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement NAV ERP product sync API endpoint: receive product data pushed from NAV ERP, validate, and upsert into local database.
|
||||
|
||||
**Goal:** NAV ERP can push products to our API, keeping product catalog up-to-date.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 2: Database (products table needed)
|
||||
- ⚠️ **Required:** API key for NAV ERP authentication
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Schema & Validation
|
||||
|
||||
- [ ] Create NAV ERP product schema (Zod)
|
||||
- File: `server/utils/schemas/navProduct.ts`
|
||||
- Fields: navProductId, name, description, price, stockQuantity, category, active
|
||||
- Validation rules: required fields, price > 0, stock >= 0
|
||||
- Export: `navProductSchema`, `NavProductData` type
|
||||
|
||||
### API Endpoint
|
||||
|
||||
- [ ] Create /api/erp/products.post.ts endpoint
|
||||
- Body: { products: NavProductData[] } (array of products)
|
||||
- Validate API key from header: `Authorization: Bearer <API_KEY>`
|
||||
- Validate product data with Zod
|
||||
- Upsert products in DB (insert if new, update if exists)
|
||||
- Return: { success: true, upserted: count, errors: [] }
|
||||
|
||||
### Authentication
|
||||
|
||||
- [ ] Implement API key authentication
|
||||
- Middleware: `server/middleware/erpAuth.ts`
|
||||
- Check Authorization header
|
||||
- Validate API key against NAV_ERP_API_KEY env var
|
||||
- Return 401 if invalid/missing
|
||||
- Only apply to /api/erp/\* routes
|
||||
|
||||
### Business Logic
|
||||
|
||||
- [ ] Implement product validation
|
||||
- Validate required fields
|
||||
- Validate data types and formats
|
||||
- Validate price is positive
|
||||
- Validate stock quantity is non-negative
|
||||
- Return detailed errors for invalid products
|
||||
|
||||
- [ ] Implement product upsert logic
|
||||
- Check if product exists by navProductId (unique key)
|
||||
- If exists: Update name, description, price, stock, category, active, updated_at
|
||||
- If not exists: Insert new product with all fields
|
||||
- Use Drizzle's `.onConflictDoUpdate()` or manual check
|
||||
- Return count of upserted products
|
||||
|
||||
### Error Handling
|
||||
|
||||
- [ ] Add error handling & logging
|
||||
- Log all incoming requests (timestamp, product count)
|
||||
- Log validation errors with details
|
||||
- Log DB errors
|
||||
- Return structured errors to NAV ERP
|
||||
- Example: `{ success: false, errors: [{ product: '...', message: '...' }] }`
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test product sync (mock data)
|
||||
- Create sample NAV product data (JSON)
|
||||
- POST to /api/erp/products with valid API key
|
||||
- Verify products are created in DB
|
||||
- POST again with updated data
|
||||
- Verify products are updated in DB
|
||||
- Test with invalid data → verify validation errors
|
||||
|
||||
- [ ] Test API key auth
|
||||
- Test without Authorization header → expect 401
|
||||
- Test with invalid API key → expect 401
|
||||
- Test with valid API key → expect 200
|
||||
|
||||
- [ ] Add rate limiting
|
||||
- Limit NAV ERP endpoint to prevent abuse
|
||||
- Example: 100 requests / hour per API key
|
||||
- Use `server/middleware/rate-limit.ts` (extend from Phase 3)
|
||||
- Return 429 if limit exceeded
|
||||
|
||||
- [ ] Document ERP integration
|
||||
- Document API endpoint spec (request/response format)
|
||||
- Document authentication method (API key in header)
|
||||
- Document product data schema
|
||||
- Document error codes and messages
|
||||
- Document rate limits
|
||||
- Create example curl commands for NAV team
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] NAV product schema is defined with Zod
|
||||
- [x] /api/erp/products endpoint is implemented
|
||||
- [x] API key authentication works correctly
|
||||
- [x] Product validation works (Zod schema)
|
||||
- [x] Product upsert logic works (insert new, update existing)
|
||||
- [x] Error handling returns structured errors
|
||||
- [x] Logging captures all requests and errors
|
||||
- [x] Can sync products successfully with mock data
|
||||
- [x] API key auth prevents unauthorized access
|
||||
- [x] Rate limiting protects endpoint from abuse
|
||||
- [x] ERP integration is documented for NAV team
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Push Model:** NAV ERP pushes to us (we don't pull)
|
||||
- **Batch Sync:** NAV can send multiple products in one request
|
||||
- **Idempotent:** Repeated syncs with same data should be safe (upsert)
|
||||
- **API Key Storage:** Store NAV_ERP_API_KEY in .env (dev/prod)
|
||||
- **NAV Contact:** Coordinate with NAV team for API key and sync schedule
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **API Key:** Need to generate/agree on API key with NAV team
|
||||
- ⚠️ **NAV Schema:** Need exact product schema from NAV team (may differ from assumption)
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: F-011](../docs/PRD.md#f-011-nav-erp-push-endpunkt)
|
||||
- [docs/ARCHITECTURE.md: NAV ERP Integration](../docs/ARCHITECTURE.md#33-nav-erp-product-sync)
|
||||
- [CLAUDE.md: Important Constraints](../CLAUDE.md#important-constraints)
|
||||
180
tasks/10-i18n.md
Normal file
180
tasks/10-i18n.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Phase 10: i18n (Internationalization)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/8 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement internationalization (i18n) with @nuxtjs/i18n: support German (default) and English, translate all UI strings, and create language switcher.
|
||||
|
||||
**Goal:** App is fully bilingual (German + English) with proper routing and formatting.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 1-9: Most UI components should be created by now
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Setup
|
||||
|
||||
- [ ] Install @nuxtjs/i18n
|
||||
|
||||
```bash
|
||||
pnpm add @nuxtjs/i18n
|
||||
```
|
||||
|
||||
- [ ] Configure i18n module
|
||||
- File: `nuxt.config.ts`
|
||||
```typescript
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxtjs/i18n'],
|
||||
i18n: {
|
||||
locales: [
|
||||
{ code: 'de', iso: 'de-DE', name: 'Deutsch', file: 'de-DE.json' },
|
||||
{ code: 'en', iso: 'en-US', name: 'English', file: 'en-US.json' },
|
||||
],
|
||||
defaultLocale: 'de',
|
||||
strategy: 'prefix_except_default',
|
||||
langDir: 'locales',
|
||||
lazy: true,
|
||||
detectBrowserLanguage: {
|
||||
useCookie: true,
|
||||
cookieKey: 'i18n_redirected',
|
||||
redirectOn: 'root',
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Translation Files
|
||||
|
||||
- [ ] Create locale files (de-DE.json, en-US.json)
|
||||
- Create: `locales/de-DE.json` (German)
|
||||
- Create: `locales/en-US.json` (English)
|
||||
- Structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"common": {
|
||||
"header": { "home": "Startseite", "products": "Produkte", ... },
|
||||
"footer": { ... },
|
||||
"buttons": { "submit": "Absenden", "cancel": "Abbrechen", ... }
|
||||
},
|
||||
"auth": {
|
||||
"login": { "title": "Anmelden", "email": "E-Mail", ... },
|
||||
"register": { ... }
|
||||
},
|
||||
"products": { ... },
|
||||
"cart": { ... },
|
||||
"checkout": { ... },
|
||||
"errors": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] Translate all UI strings
|
||||
- Go through all components and pages
|
||||
- Replace hardcoded German strings with `$t('key')` or `t('key')`
|
||||
- Add translations to both de-DE.json and en-US.json
|
||||
- Components to translate:
|
||||
- Header, Footer
|
||||
- Auth forms (Login, Register)
|
||||
- Product list, Product detail
|
||||
- Cart, CartItem, CartSummary
|
||||
- Checkout form
|
||||
- PayPal button texts
|
||||
- Error messages
|
||||
- Success messages
|
||||
- Validation messages (VeeValidate)
|
||||
|
||||
### UI Components
|
||||
|
||||
- [ ] Create language switcher component
|
||||
- File: `components/Common/LanguageSwitcher.vue`
|
||||
- Dropdown or toggle: 🇩🇪 Deutsch | 🇬🇧 English
|
||||
- Uses: `$i18n.locale` and `$switchLocalePath()`
|
||||
- Place in header
|
||||
- Styling: shadcn-nuxt DropdownMenu or simple buttons
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test route localization
|
||||
- Visit /produkte (German)
|
||||
- Switch to English → should redirect to /en/products
|
||||
- Test all main routes:
|
||||
- / → /en/ (homepage)
|
||||
- /produkte → /en/products
|
||||
- /warenkorb → /en/cart
|
||||
- /kasse → /en/checkout
|
||||
- Verify route parameters preserved (/produkte/[id] → /en/products/[id])
|
||||
|
||||
- [ ] Test currency/date formatting
|
||||
- Use Intl.NumberFormat for currency (EUR)
|
||||
- Use Intl.DateTimeFormat for dates
|
||||
- Example in component:
|
||||
|
||||
```typescript
|
||||
const { locale } = useI18n()
|
||||
const formatPrice = (price: number) => {
|
||||
return new Intl.NumberFormat(locale.value, {
|
||||
style: 'currency',
|
||||
currency: 'EUR',
|
||||
}).format(price)
|
||||
}
|
||||
```
|
||||
|
||||
- Test: German → "19,99 €", English → "€19.99"
|
||||
|
||||
- [ ] Document i18n structure
|
||||
- Document translation file structure
|
||||
- Document how to add new translations
|
||||
- Document naming conventions for translation keys
|
||||
- Document how language switcher works
|
||||
- Document how to format currency/dates per locale
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] @nuxtjs/i18n is installed and configured
|
||||
- [x] Locale files exist for German and English
|
||||
- [x] All UI strings are translated (no hardcoded German text)
|
||||
- [x] Language switcher component is functional
|
||||
- [x] Can switch between German and English
|
||||
- [x] Routes change with language (/produkte ↔ /en/products)
|
||||
- [x] Currency formatting respects locale
|
||||
- [x] Date formatting respects locale
|
||||
- [x] i18n structure is documented
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Default Language:** German (de)
|
||||
- **Route Strategy:** prefix_except_default (German has no prefix, English has /en/)
|
||||
- **SEO:** Automatic hreflang tags for SEO
|
||||
- **Lazy Loading:** Translation files loaded on demand
|
||||
- **Browser Detection:** Redirects to browser language on first visit (if supported)
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- None currently
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: Bilingual Support](../docs/PRD.md#bilingual-support)
|
||||
- [docs/TECH_STACK.md: i18n](../docs/TECH_STACK.md#9-internationalization-i18n)
|
||||
- [CLAUDE.md: Important Constraints](../CLAUDE.md#important-constraints)
|
||||
- [@nuxtjs/i18n Docs](https://i18n.nuxtjs.org/)
|
||||
256
tasks/11-testing-deployment.md
Normal file
256
tasks/11-testing-deployment.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Phase 11: Testing & Deployment
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/15 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Setup testing frameworks (Vitest, Playwright), write tests, create production Docker setup, configure CI/CD pipeline, and deploy to staging/production.
|
||||
|
||||
**Goal:** Fully tested MVP deployed to production with automated CI/CD.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ All previous phases should be completed
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Unit Testing Setup
|
||||
|
||||
- [ ] Setup Vitest for unit tests
|
||||
|
||||
```bash
|
||||
pnpm add -D vitest @vue/test-utils happy-dom
|
||||
```
|
||||
|
||||
- Configure vitest.config.ts
|
||||
- Add test scripts to package.json: `"test": "vitest"`
|
||||
- Create `tests/` folder structure
|
||||
|
||||
- [ ] Write tests for auth utilities
|
||||
- Test: `server/utils/pkce.ts`
|
||||
- Test PKCE generation (verifier, challenge)
|
||||
- Test challenge is base64url encoded SHA-256
|
||||
- Test: `server/utils/jwt.ts`
|
||||
- Test JWT validation (mock JWKS)
|
||||
- Test expired token rejection
|
||||
- Test invalid issuer/audience rejection
|
||||
|
||||
- [ ] Write tests for API endpoints
|
||||
- Test: `/api/products/index.get.ts`
|
||||
- Test returns active products only
|
||||
- Test filtering by category
|
||||
- Test: `/api/cart/items.post.ts`
|
||||
- Test add item to cart
|
||||
- Test validation (invalid product ID)
|
||||
- Test: `/api/orders/index.post.ts`
|
||||
- Test order creation
|
||||
- Test requires authentication
|
||||
- Use: `@nuxt/test-utils` for API testing
|
||||
|
||||
### E2E Testing Setup
|
||||
|
||||
- [ ] Setup Playwright for E2E
|
||||
|
||||
```bash
|
||||
pnpm add -D @playwright/test
|
||||
npx playwright install
|
||||
```
|
||||
|
||||
- Configure playwright.config.ts
|
||||
- Add e2e script: `"test:e2e": "playwright test"`
|
||||
- Create `tests/e2e/` folder
|
||||
|
||||
- [ ] Write E2E test: user registration
|
||||
- Navigate to /auth
|
||||
- Click "Register" tab
|
||||
- Fill registration form
|
||||
- Submit form
|
||||
- Verify success message (or redirect to Cidaas)
|
||||
- Note: May need to mock Cidaas for E2E
|
||||
|
||||
- [ ] Write E2E test: complete checkout flow
|
||||
- Login as user (or create test user)
|
||||
- Navigate to /produkte
|
||||
- Click product
|
||||
- Click "In den Warenkorb"
|
||||
- Navigate to /warenkorb
|
||||
- Click "Zur Kasse"
|
||||
- Fill checkout form
|
||||
- Mock PayPal payment (or use sandbox)
|
||||
- Verify order confirmation page
|
||||
|
||||
### Production Docker Setup
|
||||
|
||||
- [ ] Create Dockerfile (production)
|
||||
- File: `Dockerfile`
|
||||
- Multi-stage build (see docs/TECH_STACK.md#dockerfile)
|
||||
- Build stage: Install deps, build Nuxt
|
||||
- Production stage: Copy .output, run server
|
||||
- Optimize for size (alpine, minimal layers)
|
||||
|
||||
- [ ] Create docker-compose.yml (production)
|
||||
- File: `docker-compose.yml`
|
||||
- Services: app, db, redis, worker (BullMQ worker)
|
||||
- Volumes: postgres_data, redis_data
|
||||
- Networks: app-network
|
||||
- Health checks for all services
|
||||
- Secrets for sensitive data
|
||||
- See: docs/TECH_STACK.md#docker-compose
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
- [ ] Configure GitLab CI/CD
|
||||
- File: `.gitlab-ci.yml`
|
||||
- Stages: build, test, deploy-staging, deploy-production
|
||||
- Build stage:
|
||||
- Build Docker image
|
||||
- Push to registry
|
||||
- Test stage:
|
||||
- Run unit tests
|
||||
- Run E2E tests
|
||||
- Check test coverage
|
||||
- Deploy-staging stage:
|
||||
- Deploy to staging automatically on main branch
|
||||
- Deploy-production stage:
|
||||
- Manual trigger required
|
||||
- See: docs/TECH_STACK.md#gitlab-ci
|
||||
|
||||
- [ ] Test production build
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm preview
|
||||
```
|
||||
|
||||
- Verify build completes without errors
|
||||
- Verify production server runs
|
||||
- Test production build locally with Docker:
|
||||
|
||||
```bash
|
||||
docker build -t experimenta-app:latest .
|
||||
docker run -p 3000:3000 experimenta-app:latest
|
||||
```
|
||||
|
||||
### Deployment
|
||||
|
||||
- [ ] Setup staging environment
|
||||
- Server: Hetzner VPS or VM (Proxmox)
|
||||
- Domain: staging.my.experimenta.science
|
||||
- SSL: Let's Encrypt (automatic)
|
||||
- Reverse Proxy: Nginx or Traefik
|
||||
- Docker Compose with staging config
|
||||
- Environment: STAGING
|
||||
|
||||
- [ ] Deploy to staging
|
||||
- Use GitLab CI/CD or manual deploy
|
||||
- Verify deployment successful
|
||||
- Run smoke tests on staging
|
||||
- Test full user flow on staging
|
||||
|
||||
- [ ] Final QA on staging
|
||||
- Test all features:
|
||||
- User registration & login
|
||||
- Product browsing
|
||||
- Add to cart
|
||||
- Checkout
|
||||
- PayPal payment (sandbox)
|
||||
- Order confirmation
|
||||
- Order history
|
||||
- Test on multiple devices/browsers
|
||||
- Test language switching (DE/EN)
|
||||
- Test error scenarios
|
||||
|
||||
- [ ] Document deployment process
|
||||
- Document staging deployment steps
|
||||
- Document production deployment steps
|
||||
- Document rollback procedure
|
||||
- Document database migration process
|
||||
- Document secrets management
|
||||
- Document monitoring and logging
|
||||
|
||||
- [ ] Deploy to production 🚀
|
||||
- Server: Hetzner dedicated/VPS
|
||||
- Domain: my.experimenta.science
|
||||
- SSL: Let's Encrypt
|
||||
- Reverse Proxy: Nginx or Traefik
|
||||
- Docker Compose with production config
|
||||
- Environment: PRODUCTION
|
||||
- PayPal: LIVE mode
|
||||
- X-API: Production endpoint
|
||||
- Cidaas: Production credentials
|
||||
- Database backups enabled
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Vitest is set up and running
|
||||
- [x] Unit tests cover critical utilities and endpoints
|
||||
- [x] Playwright is set up and running
|
||||
- [x] E2E tests cover registration and checkout flows
|
||||
- [x] Production Dockerfile is optimized and working
|
||||
- [x] docker-compose.yml for production is complete
|
||||
- [x] GitLab CI/CD pipeline is configured
|
||||
- [x] Production build works locally
|
||||
- [x] Staging environment is set up and accessible
|
||||
- [x] Deployed to staging successfully
|
||||
- [x] QA testing on staging passes
|
||||
- [x] Deployment process is documented
|
||||
- [x] Deployed to production successfully 🎉
|
||||
- [x] Production app is accessible and functional
|
||||
- [x] Monitoring and error tracking are active
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Test Coverage Goal:** 70%+ for critical code paths
|
||||
- **E2E Testing:** Focus on happy path for MVP (error scenarios in later phases)
|
||||
- **Docker Production:** Use Docker Secrets for sensitive data (not env vars)
|
||||
- **CI/CD:** Auto-deploy to staging, manual approval for production
|
||||
- **Monitoring:** Setup Sentry or similar for error tracking (optional for MVP)
|
||||
- **Backups:** Daily automated database backups with 7-day retention
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **Production Servers:** Need access to production servers
|
||||
- ⚠️ **Production Credentials:** Need production credentials for Cidaas, PayPal, X-API
|
||||
- ⚠️ **Domain DNS:** Need to point domain to production server
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/TECH_STACK.md: Testing](../docs/TECH_STACK.md#12-testing)
|
||||
- [docs/TECH_STACK.md: Docker](../docs/TECH_STACK.md#11-deployment--infrastructure)
|
||||
- [docs/TECH_STACK.md: CI/CD](../docs/TECH_STACK.md#cicd-mit-gitlab)
|
||||
- [README.md: Development Setup](../README.md#lokale-entwicklung)
|
||||
|
||||
---
|
||||
|
||||
## Post-Launch
|
||||
|
||||
After successful production launch:
|
||||
|
||||
- [ ] Monitor error rates (Sentry or logs)
|
||||
- [ ] Monitor queue performance (BullBoard)
|
||||
- [ ] Monitor PayPal transaction success rate
|
||||
- [ ] Monitor X-API submission success rate
|
||||
- [ ] Gather user feedback
|
||||
- [ ] Plan Phase 2 features (Educator roles, etc.)
|
||||
|
||||
---
|
||||
|
||||
**🎉 Congratulations on launching the MVP! 🎉**
|
||||
243
tasks/README.md
Normal file
243
tasks/README.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Task Management System
|
||||
|
||||
## my.experimenta.science MVP Implementation
|
||||
|
||||
Dieses Verzeichnis enthält die feingranulare Task-Planung für die Implementierung des MVP.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Ordnerstruktur
|
||||
|
||||
```
|
||||
tasks/
|
||||
├── README.md # Diese Datei - Übersicht & Anleitung
|
||||
├── 00-PROGRESS.md # Zentrale Fortschrittsverfolgung
|
||||
├── 01-foundation.md # Phase 1: Foundation (Nuxt Setup)
|
||||
├── 02-database.md # Phase 2: Database Schema & Migrations
|
||||
├── 03-authentication.md # Phase 3: Cidaas OAuth2 Integration
|
||||
├── 04-products.md # Phase 4: Product Display
|
||||
├── 05-cart.md # Phase 5: Shopping Cart
|
||||
├── 06-checkout.md # Phase 6: Checkout Flow
|
||||
├── 07-payment.md # Phase 7: PayPal Integration
|
||||
├── 08-order-processing.md # Phase 8: Order Processing (BullMQ + X-API)
|
||||
├── 09-erp-integration.md # Phase 9: NAV ERP Product Sync
|
||||
├── 10-i18n.md # Phase 10: Internationalization
|
||||
└── 11-testing-deployment.md # Phase 11: Testing & Deployment
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Zweck
|
||||
|
||||
Dieses System ermöglicht:
|
||||
|
||||
✅ **Strukturierte Entwicklung:** Klare Aufteilung in logische Phasen
|
||||
✅ **Progress Tracking:** Nachvollziehbarer Fortschritt pro Phase
|
||||
✅ **Agent-freundlich:** Claude Code Agents können Tasks autonom abarbeiten
|
||||
✅ **Resume-fähig:** Einfaches Fortsetzen nach Unterbrechung
|
||||
✅ **Transparenz:** Blockers & Decisions werden dokumentiert
|
||||
✅ **Dependencies:** Klare Abhängigkeiten zwischen Phasen
|
||||
|
||||
---
|
||||
|
||||
## 📊 Status-Definitionen
|
||||
|
||||
| Status | Symbol | Bedeutung |
|
||||
| --------------- | ------ | -------------------------------------- |
|
||||
| **Todo** | ⏳ | Noch nicht begonnen |
|
||||
| **In Progress** | 🔄 | Aktuell in Arbeit |
|
||||
| **Done** | ✅ | Abgeschlossen & getestet |
|
||||
| **Blocked** | 🚫 | Blockiert, wartet auf externes Input |
|
||||
| **Skipped** | ⏭️ | Übersprungen (optional/nicht relevant) |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Workflow für Agents
|
||||
|
||||
### 1. Start einer Arbeitssession
|
||||
|
||||
```markdown
|
||||
1. Öffne `00-PROGRESS.md`
|
||||
2. Identifiziere nächste Phase mit Status "⏳ Todo" oder "🔄 In Progress"
|
||||
3. Öffne die entsprechende Phase-Datei (z.B. `03-authentication.md`)
|
||||
```
|
||||
|
||||
### 2. Während der Implementierung
|
||||
|
||||
```markdown
|
||||
1. Arbeite Tasks sequenziell ab (von oben nach unten)
|
||||
2. Markiere Tasks als erledigt: `- [ ]` → `- [x]`
|
||||
3. Dokumentiere wichtige Entscheidungen im Notes-Bereich
|
||||
4. Bei Blocker: Status auf 🚫, Grund dokumentieren
|
||||
```
|
||||
|
||||
### 3. Fortschritt aktualisieren
|
||||
|
||||
```markdown
|
||||
1. Nach jedem abgeschlossenen Task:
|
||||
- Aktualisiere Progress in Phase-Datei: "3/15 tasks (20%)"
|
||||
|
||||
2. Nach Abschluss einer Phase:
|
||||
- Status auf ✅ Done setzen
|
||||
- `00-PROGRESS.md` aktualisieren
|
||||
- Nächste Phase identifizieren
|
||||
```
|
||||
|
||||
### 4. Bei Unterbrechung
|
||||
|
||||
```markdown
|
||||
1. Aktuellen Task-Status in Phase-Datei speichern
|
||||
2. In `00-PROGRESS.md` unter "Current Work" dokumentieren:
|
||||
- Welche Phase
|
||||
- Welcher Task
|
||||
- Was als nächstes zu tun ist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Phase-Datei Format
|
||||
|
||||
Jede Phase-Datei folgt diesem Template:
|
||||
|
||||
```markdown
|
||||
# Phase X: [Name]
|
||||
|
||||
**Status:** ⏳ Todo | 🔄 In Progress | ✅ Done | 🚫 Blocked
|
||||
**Progress:** 0/15 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Beschreibung was in dieser Phase erreicht werden soll]
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase Y: [Name] must be completed first
|
||||
- ⏳ Phase Z: [Name] (optional, can run parallel)
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Setup
|
||||
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
### Implementation
|
||||
|
||||
- [ ] Task 3
|
||||
- [ ] Task 4
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Task 5
|
||||
- [ ] Task 6
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Important decision: ...
|
||||
- Issue encountered: ...
|
||||
- Resource link: ...
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- None currently
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [PRD Section X](../docs/PRD.md#section)
|
||||
- [Architecture Section Y](../docs/ARCHITECTURE.md#section)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Best Practices
|
||||
|
||||
### Für Agents
|
||||
|
||||
1. **Lies zuerst die Phase-Übersicht:** Verstehe das Ziel, bevor du startest
|
||||
2. **Prüfe Dependencies:** Sind alle abhängigen Phasen abgeschlossen?
|
||||
3. **Arbeite sequenziell:** Tasks sind nach Abhängigkeit sortiert
|
||||
4. **Teste nach jedem Task:** Nicht alle Tasks am Ende testen
|
||||
5. **Dokumentiere Blocker:** Wenn stuck, dokumentiere warum
|
||||
6. **Update Progress häufig:** Nach jedem Task, nicht nur am Ende
|
||||
|
||||
### Für Entwickler
|
||||
|
||||
1. **Review 00-PROGRESS.md täglich:** Übersicht behalten
|
||||
2. **Nutze Git Commits pro Task:** Ermöglicht einfaches Rollback
|
||||
3. **Dokumentiere Abweichungen:** Wenn von Plan abgewichen wird
|
||||
4. **Update Acceptance Criteria:** Falls sich Requirements ändern
|
||||
|
||||
---
|
||||
|
||||
## 📦 Phase-Übersicht
|
||||
|
||||
| # | Phase | Schwerpunkt | Geschätzte Tasks |
|
||||
| --- | -------------------- | ----------------------------------- | ---------------- |
|
||||
| 01 | Foundation | Nuxt 4 Setup, shadcn-nuxt, Tailwind | ~10 |
|
||||
| 02 | Database | Drizzle Schema, Migrations | ~12 |
|
||||
| 03 | Authentication | Cidaas OAuth2/OIDC | ~18 |
|
||||
| 04 | Products | Product Display & List | ~10 |
|
||||
| 05 | Cart | Shopping Cart Logic | ~12 |
|
||||
| 06 | Checkout | Checkout Flow & Forms | ~15 |
|
||||
| 07 | Payment | PayPal Integration | ~12 |
|
||||
| 08 | Order Processing | BullMQ + X-API Submission | ~15 |
|
||||
| 09 | ERP Integration | NAV ERP Product Sync API | ~10 |
|
||||
| 10 | i18n | Internationalization DE/EN | ~8 |
|
||||
| 11 | Testing & Deployment | E2E Tests, Docker Production | ~15 |
|
||||
|
||||
**Total:** ~137 granulare Tasks
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
```bash
|
||||
# 1. Lies die zentrale Progress-Datei
|
||||
cat tasks/00-PROGRESS.md
|
||||
|
||||
# 2. Identifiziere nächste Phase
|
||||
# z.B. Phase 1: Foundation
|
||||
|
||||
# 3. Öffne Phase-Datei
|
||||
cat tasks/01-foundation.md
|
||||
|
||||
# 4. Starte Implementierung
|
||||
# Arbeite Tasks von oben nach unten ab
|
||||
|
||||
# 5. Update Progress nach jedem Task
|
||||
# Markiere Task als done, update Progress-Zeile
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Bei Fragen
|
||||
|
||||
- Schaue in die relevante Dokumentation: `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/TECH_STACK.md`
|
||||
- Prüfe `CLAUDE.md` für Code-Patterns
|
||||
- Bei Blocker: Dokumentiere in Phase-Datei + `00-PROGRESS.md`
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding! 🎉**
|
||||
Reference in New Issue
Block a user