@adlas/create-app 1.0.0

package/templates/docs/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,892 @@
+# Implementation Guide
+
+Step-by-step guide for implementing features in the Berndorf e-commerce project. Follow this guide to ensure consistency and quality.
+
+## Table of Contents
+
+1. [Pre-Implementation Checklist](#pre-implementation-checklist)
+2. [Implementation Steps](#implementation-steps)
+3. [Quality Checklist](#quality-checklist)
+4. [Troubleshooting](#troubleshooting)
+5. [Complete Example](#complete-example)
+
+---
+
+## Pre-Implementation Checklist
+
+Before starting any implementation, verify:
+
+### 1. Requirements Clarity
+
+- [ ] Figma design is complete and reviewed
+- [ ] Feature requirements are documented
+- [ ] API endpoints are defined
+- [ ] Data models are specified
+- [ ] User flows are clear
+
+### 2. Technical Review
+
+- [ ] Checked existing components in `/src/components/ui/`
+- [ ] Checked existing elements in `/src/components/elements/`
+- [ ] Reviewed similar features in `/src/services/`
+- [ ] Identified reusable patterns
+- [ ] No new UI libraries needed
+
+### 3. Planning
+
+- [ ] Service module structure planned
+- [ ] Component hierarchy defined
+- [ ] State management approach decided
+- [ ] Translation keys prepared
+- [ ] Validation rules defined
+
+---
+
+## Implementation Steps
+
+Follow these steps in order for any new feature.
+
+### Step 1: Create Service Module Structure
+
+Create the directory structure for your feature.
+
+```bash
+# Create directory structure
+mkdir -p src/services/[feature]/{api,queries,hooks,types,actions,store,constants,helpers}
+```
+
+Create `index.ts` to export all modules:
+
+```typescript
+// src/services/[feature]/index.ts
+export * from './api/[feature].api';
+export * from './queries/[feature].queries';
+export * from './hooks/use[Feature]';
+export * from './types/[feature].types';
+export * from './actions/[feature].actions';
+export * from './store/[feature].store';
+export * from './constants/[feature].constants';
+export * from './helpers/[feature].helpers';
+```
+
+### Step 2: Define TypeScript Types
+
+Define all types for your feature.
+
+**File:** `src/services/[feature]/types/[feature].types.ts`
+
+```typescript
+// API Response types (match backend structure)
+export interface FeatureApiResponse {
+  id: string;
+  name: string;
+  created_at: string; // snake_case from API
+}
+
+// Frontend Model types (camelCase for frontend)
+export interface Feature {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+
+// Request types
+export interface CreateFeatureRequest {
+  name: string;
+}
+
+export interface UpdateFeatureRequest {
+  name?: string;
+}
+
+// Filter types
+export interface FeatureFilters {
+  search?: string;
+  status?: 'active' | 'inactive';
+}
+```
+
+### Step 3: Create Helper Functions
+
+Create transformation and utility functions.
+
+**File:** `src/services/[feature]/helpers/[feature].helpers.ts`
+
+```typescript
+import type { Feature, FeatureApiResponse } from '../types/[feature].types';
+
+/**
+ * Transform API response to frontend model
+ */
+export function transformFeatureResponse(data: FeatureApiResponse): Feature {
+  return {
+    id: data.id,
+    name: data.name,
+    createdAt: new Date(data.created_at),
+  };
+}
+
+/**
+ * Format date for display
+ */
+export function formatFeatureDate(date: Date): string {
+  return new Intl.DateTimeFormat('de-AT', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  }).format(date);
+}
+```
+
+### Step 4: Create API Client
+
+Create API client functions.
+
+**File:** `src/services/[feature]/api/[feature].api.ts`
+
+```typescript
+import { apiRequest } from '@/lib/apiRequest';
+import type {
+  Feature,
+  FeatureApiResponse,
+  CreateFeatureRequest,
+  UpdateFeatureRequest,
+  FeatureFilters,
+} from '../types/[feature].types';
+import { transformFeatureResponse } from '../helpers/[feature].helpers';
+
+/**
+ * Fetch all features
+ */
+export async function getFeatures(filters?: FeatureFilters): Promise<Feature[]> {
+  const queryParams = new URLSearchParams();
+
+  if (filters?.search) queryParams.append('search', filters.search);
+  if (filters?.status) queryParams.append('status', filters.status);
+
+  const url = `/api/features${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+
+  const response = await apiRequest<FeatureApiResponse[]>({
+    url,
+    method: 'GET',
+  });
+
+  return response.map(transformFeatureResponse);
+}
+
+/**
+ * Fetch single feature
+ */
+export async function getFeature(id: string): Promise<Feature> {
+  const response = await apiRequest<FeatureApiResponse>({
+    url: `/api/features/${id}`,
+    method: 'GET',
+  });
+
+  return transformFeatureResponse(response);
+}
+
+/**
+ * Create new feature
+ */
+export async function createFeature(data: CreateFeatureRequest): Promise<Feature> {
+  const response = await apiRequest<FeatureApiResponse>({
+    url: '/api/features',
+    method: 'POST',
+    data,
+  });
+
+  return transformFeatureResponse(response);
+}
+
+/**
+ * Update feature
+ */
+export async function updateFeature(id: string, data: UpdateFeatureRequest): Promise<Feature> {
+  const response = await apiRequest<FeatureApiResponse>({
+    url: `/api/features/${id}`,
+    method: 'PATCH',
+    data,
+  });
+
+  return transformFeatureResponse(response);
+}
+
+/**
+ * Delete feature
+ */
+export async function deleteFeature(id: string): Promise<void> {
+  await apiRequest<void>({
+    url: `/api/features/${id}`,
+    method: 'DELETE',
+  });
+}
+```
+
+### Step 5: Create React Query Hooks
+
+Create React Query hooks for data fetching.
+
+**File:** `src/services/[feature]/queries/[feature].queries.ts`
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { useTranslations } from 'next-intl';
+import type { FeatureFilters, CreateFeatureRequest, UpdateFeatureRequest } from '../types/[feature].types';
+import {
+  getFeatures,
+  getFeature,
+  createFeature,
+  updateFeature,
+  deleteFeature,
+} from '../api/[feature].api';
+
+// Query Keys
+export const featureKeys = {
+  all: ['features'] as const,
+  lists: () => [...featureKeys.all, 'list'] as const,
+  list: (filters?: FeatureFilters) => [...featureKeys.lists(), filters] as const,
+  details: () => [...featureKeys.all, 'detail'] as const,
+  detail: (id: string) => [...featureKeys.details(), id] as const,
+};
+
+/**
+ * Fetch all features
+ */
+export function useFeaturesQuery(filters?: FeatureFilters) {
+  return useQuery({
+    queryKey: featureKeys.list(filters),
+    queryFn: () => getFeatures(filters),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+}
+
+/**
+ * Fetch single feature
+ */
+export function useFeatureQuery(id: string) {
+  return useQuery({
+    queryKey: featureKeys.detail(id),
+    queryFn: () => getFeature(id),
+    enabled: !!id,
+  });
+}
+
+/**
+ * Create feature mutation
+ */
+export function useCreateFeatureMutation() {
+  const queryClient = useQueryClient();
+  const t = useTranslations('Feature');
+
+  return useMutation({
+    mutationFn: createFeature,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: featureKeys.lists() });
+      toast.success(t('createSuccess'));
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || t('createError'));
+    },
+  });
+}
+
+/**
+ * Update feature mutation
+ */
+export function useUpdateFeatureMutation() {
+  const queryClient = useQueryClient();
+  const t = useTranslations('Feature');
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateFeatureRequest }) =>
+      updateFeature(id, data),
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({ queryKey: featureKeys.lists() });
+      queryClient.invalidateQueries({ queryKey: featureKeys.detail(variables.id) });
+      toast.success(t('updateSuccess'));
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || t('updateError'));
+    },
+  });
+}
+
+/**
+ * Delete feature mutation
+ */
+export function useDeleteFeatureMutation() {
+  const queryClient = useQueryClient();
+  const t = useTranslations('Feature');
+
+  return useMutation({
+    mutationFn: deleteFeature,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: featureKeys.lists() });
+      toast.success(t('deleteSuccess'));
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || t('deleteError'));
+    },
+  });
+}
+```
+
+### Step 6: Create Custom Hooks (Optional)
+
+Create custom hooks for complex logic.
+
+**File:** `src/services/[feature]/hooks/useFeature.ts`
+
+```typescript
+import { useMemo } from 'react';
+import { useFeaturesQuery } from '../queries/[feature].queries';
+import type { FeatureFilters } from '../types/[feature].types';
+
+export function useFeatures(filters?: FeatureFilters) {
+  const { data, isLoading, error } = useFeaturesQuery(filters);
+
+  const features = useMemo(() => data || [], [data]);
+
+  const activeFeatures = useMemo(
+    () => features.filter(f => f.status === 'active'),
+    [features],
+  );
+
+  return {
+    features,
+    activeFeatures,
+    isLoading,
+    error,
+    isEmpty: features.length === 0,
+  };
+}
+```
+
+### Step 7: Create Zustand Store (If Needed)
+
+Create Zustand store for global state.
+
+**File:** `src/services/[feature]/store/[feature].store.ts`
+
+```typescript
+import { create } from 'zustand';
+import type { FeatureFilters } from '../types/[feature].types';
+
+interface FeatureStore {
+  filters: FeatureFilters;
+  selectedId: string | null;
+  setFilters: (filters: FeatureFilters) => void;
+  setSelectedId: (id: string | null) => void;
+  resetFilters: () => void;
+  reset: () => void;
+}
+
+const initialState = {
+  filters: {},
+  selectedId: null,
+};
+
+export const useFeatureStore = create<FeatureStore>((set) => ({
+  ...initialState,
+
+  setFilters: (filters) => set({ filters }),
+
+  setSelectedId: (id) => set({ selectedId: id }),
+
+  resetFilters: () => set({ filters: {} }),
+
+  reset: () => set(initialState),
+}));
+```
+
+### Step 8: Create Server Actions (If Needed)
+
+Create server actions for server-side operations.
+
+**File:** `src/services/[feature]/actions/[feature].actions.ts`
+
+```typescript
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import type { CreateFeatureRequest } from '../types/[feature].types';
+
+export async function createFeatureAction(data: CreateFeatureRequest) {
+  try {
+    const response = await fetch(`${process.env.API_URL}/features`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      return { success: false, error: error.message };
+    }
+
+    const feature = await response.json();
+
+    // Revalidate relevant paths
+    revalidatePath('/features');
+    revalidatePath(`/features/${feature.id}`);
+
+    return { success: true, data: feature };
+  } catch (error) {
+    console.error('Create feature action error:', error);
+    return { success: false, error: 'Failed to create feature' };
+  }
+}
+```
+
+### Step 9: Add Translations
+
+Add translation keys to both English and German files.
+
+**English:** `/src/locales/en.json`
+
+```json
+{
+  "Feature": {
+    "title": "Features",
+    "create": "Create Feature",
+    "edit": "Edit Feature",
+    "delete": "Delete Feature",
+    "name": "Name",
+    "description": "Description",
+    "createSuccess": "Feature created successfully",
+    "createError": "Failed to create feature",
+    "updateSuccess": "Feature updated successfully",
+    "updateError": "Failed to update feature",
+    "deleteSuccess": "Feature deleted successfully",
+    "deleteError": "Failed to delete feature"
+  }
+}
+```
+
+**German:** `/src/locales/de.json`
+
+```json
+{
+  "Feature": {
+    "title": "Funktionen",
+    "create": "Funktion erstellen",
+    "edit": "Funktion bearbeiten",
+    "delete": "Funktion löschen",
+    "name": "Name",
+    "description": "Beschreibung",
+    "createSuccess": "Funktion erfolgreich erstellt",
+    "createError": "Funktion konnte nicht erstellt werden",
+    "updateSuccess": "Funktion erfolgreich aktualisiert",
+    "updateError": "Funktion konnte nicht aktualisiert werden",
+    "deleteSuccess": "Funktion erfolgreich gelöscht",
+    "deleteError": "Funktion konnte nicht gelöscht werden"
+  }
+}
+```
+
+### Step 10: Create Page Components
+
+Create page components using the service module.
+
+**File:** `src/app/[locale]/features/page.tsx`
+
+```tsx
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { Button } from '@/components/ui/Button';
+import { useFeaturesQuery } from '@/services/feature';
+import { FeatureList } from './_components/FeatureList';
+
+export default function FeaturesPage() {
+  const t = useTranslations('Feature');
+  const { data: features, isLoading } = useFeaturesQuery();
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <div className="flex items-center justify-between mb-6">
+        <h1 className="text-2xl font-bold">{t('title')}</h1>
+        <Button href="/features/new">{t('create')}</Button>
+      </div>
+
+      {isLoading ? (
+        <div>Loading...</div>
+      ) : (
+        <FeatureList features={features || []} />
+      )}
+    </div>
+  );
+}
+```
+
+### Step 11: Create Form Components
+
+Create form components with validation.
+
+**File:** `src/app/[locale]/features/_components/FeatureForm.tsx`
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { useTranslations } from 'next-intl';
+import { Form } from '@/components/ui/form/Form';
+import { Input } from '@/components/ui/Input';
+import { Textarea } from '@/components/ui/Textarea';
+import { Button } from '@/components/ui/Button';
+import { useCreateFeatureMutation } from '@/services/feature';
+
+const schema = z.object({
+  name: z.string().min(1, 'Errors.validation.required'),
+  description: z.string().min(1, 'Errors.validation.required'),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function FeatureForm() {
+  const t = useTranslations('Feature');
+  const createMutation = useCreateFeatureMutation();
+
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      name: '',
+      description: '',
+    },
+  });
+
+  const onSubmit = (data: FormData) => {
+    createMutation.mutate(data);
+  };
+
+  return (
+    <Form form={form} validationSchema={schema}>
+      <Form.Item name="name">
+        {(props) => <Input {...props} label={t('name')} />}
+      </Form.Item>
+
+      <Form.Item name="description">
+        {(props) => <Textarea {...props} label={t('description')} />}
+      </Form.Item>
+
+      <div className="col-span-10 flex justify-end gap-4">
+        <Button variant="bordered" href="/features">
+          {t('cancel')}
+        </Button>
+        <Button
+          onPress={form.handleSubmit(onSubmit)}
+          isLoading={createMutation.isPending}
+        >
+          {t('create')}
+        </Button>
+      </div>
+    </Form>
+  );
+}
+```
+
+### Step 12: Create Element Components (If Needed)
+
+Create reusable element components.
+
+**File:** `src/components/elements/FeatureCard.tsx`
+
+```tsx
+import { Card, CardBody, CardHeader } from '@heroui/react';
+import { Button } from '@/components/ui/Button';
+import type { Feature } from '@/services/feature';
+
+interface FeatureCardProps {
+  feature: Feature;
+  onEdit?: (id: string) => void;
+  onDelete?: (id: string) => void;
+}
+
+export function FeatureCard({ feature, onEdit, onDelete }: FeatureCardProps) {
+  return (
+    <Card>
+      <CardHeader>
+        <h3 className="text-lg font-semibold">{feature.name}</h3>
+      </CardHeader>
+      <CardBody>
+        <p className="text-default-600">{feature.description}</p>
+        <div className="flex gap-2 mt-4">
+          {onEdit && (
+            <Button size="sm" onPress={() => onEdit(feature.id)}>
+              Edit
+            </Button>
+          )}
+          {onDelete && (
+            <Button
+              size="sm"
+              variant="light"
+              color="danger"
+              onPress={() => onDelete(feature.id)}
+            >
+              Delete
+            </Button>
+          )}
+        </div>
+      </CardBody>
+    </Card>
+  );
+}
+```
+
+---
+
+## Quality Checklist
+
+Before marking implementation as complete:
+
+### Code Quality
+
+- [ ] TypeScript types are defined for all data
+- [ ] No `any` types used
+- [ ] ESLint shows no errors
+- [ ] Code follows existing patterns
+- [ ] Functions have JSDoc comments
+- [ ] Complex logic is documented
+
+### Functionality
+
+- [ ] All CRUD operations work correctly
+- [ ] Form validation works as expected
+- [ ] Error handling is implemented
+- [ ] Loading states are shown
+- [ ] Success/error messages are displayed
+- [ ] Data refreshes after mutations
+
+### Translations
+
+- [ ] All strings use translations
+- [ ] English translations added
+- [ ] German translations added
+- [ ] Translation keys are organized
+- [ ] No hardcoded text
+
+### UI/UX
+
+- [ ] Responsive design works on all screens
+- [ ] Components use existing UI library
+- [ ] Styling follows design system
+- [ ] Accessibility considerations met
+- [ ] Loading states are user-friendly
+- [ ] Error states are clear
+
+### Performance
+
+- [ ] React Query cache configured correctly
+- [ ] Unnecessary re-renders avoided
+- [ ] Images are optimized
+- [ ] Data fetching is efficient
+
+### Testing
+
+- [ ] Manual testing completed
+- [ ] Edge cases tested
+- [ ] Error scenarios tested
+- [ ] Browser compatibility checked
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Issue: Form validation not working
+
+**Solution:**
+- Ensure `resolver: zodResolver(schema)` is in `useForm`
+- Verify Zod schema is correct
+- Check that field names match schema keys
+- Ensure `validationSchema` prop is passed to `<Form>`
+
+#### Issue: React Query not refetching
+
+**Solution:**
+- Check `queryKey` is unique and consistent
+- Verify `invalidateQueries` is called after mutations
+- Check `staleTime` configuration
+- Ensure `enabled` condition is correct
+
+#### Issue: Translations not showing
+
+**Solution:**
+- Verify translation keys exist in both `en.json` and `de.json`
+- Check namespace matches `useTranslations('Namespace')`
+- Ensure JSON syntax is valid
+- Restart dev server after changing translations
+
+#### Issue: TypeScript errors
+
+**Solution:**
+- Run `pnpm check:types` to see all errors
+- Ensure types are imported correctly
+- Check that API response types match actual API
+- Verify generic types in React Query hooks
+
+#### Issue: Components not updating
+
+**Solution:**
+- Check if component is wrapped in 'use client'
+- Verify state updates are triggering re-renders
+- Check React Query cache invalidation
+- Ensure Zustand selectors are correct
+
+---
+
+## Complete Example
+
+Here's a complete example implementing a "Tasks" feature:
+
+### 1. Types
+
+```typescript
+// src/services/tasks/types/tasks.types.ts
+export interface TaskApiResponse {
+  id: string;
+  title: string;
+  description: string;
+  completed: boolean;
+  created_at: string;
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  description: string;
+  completed: boolean;
+  createdAt: Date;
+}
+
+export interface CreateTaskRequest {
+  title: string;
+  description: string;
+}
+```
+
+### 2. API Client
+
+```typescript
+// src/services/tasks/api/tasks.api.ts
+import { apiRequest } from '@/lib/apiRequest';
+import type { Task, TaskApiResponse, CreateTaskRequest } from '../types/tasks.types';
+
+export async function getTasks(): Promise<Task[]> {
+  const response = await apiRequest<TaskApiResponse[]>({
+    url: '/api/tasks',
+    method: 'GET',
+  });
+
+  return response.map(task => ({
+    ...task,
+    createdAt: new Date(task.created_at),
+  }));
+}
+
+export async function createTask(data: CreateTaskRequest): Promise<Task> {
+  const response = await apiRequest<TaskApiResponse>({
+    url: '/api/tasks',
+    method: 'POST',
+    data,
+  });
+
+  return {
+    ...response,
+    createdAt: new Date(response.created_at),
+  };
+}
+```
+
+### 3. Queries
+
+```typescript
+// src/services/tasks/queries/tasks.queries.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { getTasks, createTask } from '../api/tasks.api';
+
+export const taskKeys = {
+  all: ['tasks'] as const,
+  lists: () => [...taskKeys.all, 'list'] as const,
+};
+
+export function useTasksQuery() {
+  return useQuery({
+    queryKey: taskKeys.lists(),
+    queryFn: getTasks,
+  });
+}
+
+export function useCreateTaskMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createTask,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
+      toast.success('Task created');
+    },
+  });
+}
+```
+
+### 4. Component
+
+```tsx
+// src/app/[locale]/tasks/page.tsx
+'use client';
+
+import { useTasksQuery, useCreateTaskMutation } from '@/services/tasks';
+
+export default function TasksPage() {
+  const { data: tasks, isLoading } = useTasksQuery();
+  const createMutation = useCreateTaskMutation();
+
+  const handleCreate = () => {
+    createMutation.mutate({
+      title: 'New Task',
+      description: 'Task description',
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>Tasks</h1>
+      <button onClick={handleCreate}>Create Task</button>
+      <ul>
+        {tasks?.map(task => (
+          <li key={task.id}>{task.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+## Summary
+
+Follow this implementation guide to:
+
+1. **Maintain consistency** across the codebase
+2. **Ensure quality** through checklists
+3. **Avoid common pitfalls** with troubleshooting guide
+4. **Speed up development** with complete examples
+
+## Need More Information?
+
+- **Quick Reference** → See `AI_QUICK_REFERENCE.md`
+- **UI Components** → See `UI_COMPONENTS_GUIDE.md`
+- **Architecture** → See `ARCHITECTURE_PATTERNS.md`
+- **Figma to Code** → See `FIGMA_TO_CODE_GUIDE.md`