@akinon/projectzero 2.0.0-beta.2 → 2.0.0-beta.20

package/app-template/.github/instructions/account.instructions.md

@@ -0,0 +1,749 @@
+---
+applyTo: 'src/app/[commerce]/[locale]/[currency]/account/**'
+---
+
+# Account Pages Development Instructions
+
+## Overview
+
+Account pages in Project Zero Next.js provide e-commerce account functionality using Next.js 14 App Router structure. These instructions apply to files in the `src/app/[commerce]/[locale]/[currency]/account/` directory.
+
+## App Router Page Structure
+
+### Basic Page Pattern
+
+```tsx
+// src/app/[commerce]/[locale]/[currency]/account/page.tsx
+import { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Account | Project Zero',
+  description: 'User account page'
+};
+
+interface Props {
+  params: {
+    commerce: string;
+    locale: string;
+    currency: string;
+  };
+}
+
+export default function AccountPage({ params }: Props) {
+  return (
+    <div>
+      <h1>Account Page</h1>
+      {/* Page content */}
+    </div>
+  );
+}
+```
+
+### Layout Pattern
+
+```tsx
+// src/app/[commerce]/[locale]/[currency]/account/layout.tsx
+interface Props {
+  children: React.ReactNode;
+  params: {
+    commerce: string;
+    locale: string;
+    currency: string;
+  };
+}
+
+export default function AccountLayout({ children, params }: Props) {
+  return <div className="account-layout">{children}</div>;
+}
+```
+
+## Component Import Patterns
+
+### Theme Components
+
+```tsx
+import { Button, Input, Card } from '@theme/components';
+```
+
+### Akinon Next Components
+
+```tsx
+import { Image } from '@akinon/next/components/image';
+import { Link } from '@akinon/next/components/link';
+```
+
+## Data Fetching
+
+### Client-Side Hooks
+
+Hooks used for fetching account data in Project Zero:
+
+```tsx
+'use client';
+
+import {
+  useGetProfileInfoQuery,
+  useUpdateProfileMutation,
+  useGetOrdersQuery,
+  useGetOrderQuery,
+  useGetOldOrdersQuery,
+  useGetQuotationsQuery,
+  useUpdateEmailMutation,
+  useUpdatePasswordMutation,
+  useSendContactMutation,
+  useCancelOrderMutation,
+  useBulkCancellationMutation,
+  useGetCancellationReasonsQuery,
+  useGetContactSubjectsQuery,
+  usePasswordResetMutation,
+  useGetBasketOffersQuery,
+  useGetFutureBasketOffersQuery,
+  useGetExpiredBasketOffersQuery,
+  useGetDiscountItemsQuery,
+  useAnonymizeMutation,
+  useGetLoyaltyBalanceQuery,
+  useGetLoyaltyTransactionsQuery
+} from '@akinon/next/data/client/account';
+
+// User profile information
+const UserProfile = () => {
+  const { data: profile, isLoading, error } = useGetProfileInfoQuery();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error occurred</div>;
+
+  return <div>Welcome, {profile?.first_name}</div>;
+};
+
+// Orders - with pagination support
+const OrdersList = () => {
+  const { data: orders, isLoading } = useGetOrdersQuery({
+    page: 1,
+    limit: 10
+  });
+
+  return (
+    <div>
+      <h2>Orders ({orders?.count})</h2>
+      {orders?.results?.map((order) => (
+        <div key={order.id}>
+          <span>Order #{order.number}</span>
+          <span>{order.status}</span>
+          <span>{order.total} USD</span>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+// Order detail
+const OrderDetail = ({ orderId }) => {
+  const { data: order, isLoading, error } = useGetOrderQuery(orderId);
+
+  if (isLoading) return <div>Loading order...</div>;
+  if (error) return <div>Order not found</div>;
+
+  return (
+    <div>
+      <h1>Order #{order?.number}</h1>
+      <p>Status: {order?.status}</p>
+      <p>Total: {order?.total} USD</p>
+      {/* Order products and details */}
+    </div>
+  );
+};
+
+// Old orders
+const OldOrdersList = () => {
+  const { data: oldOrders, isLoading } = useGetOldOrdersQuery({
+    page: 1,
+    limit: 10
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h2>Order History</h2>
+      {oldOrders?.results?.map((order) => (
+        <div key={order.id}>
+          <span>#{order.number}</span>
+          <span>{new Date(order.created_date).toLocaleDateString()}</span>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+// B2B Quotations (if available)
+const QuotationsList = () => {
+  const { data: quotations, isLoading } = useGetQuotationsQuery({
+    page: 1,
+    limit: 10
+  });
+
+  if (isLoading) return <div>Loading quotations...</div>;
+
+  return (
+    <div>
+      <h2>Active Quotations</h2>
+      {quotations?.results?.map((quotation) => (
+        <div key={quotation.id}>
+          <h3>{quotation.title}</h3>
+          <p>Status: {quotation.status}</p>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+// Loyalty points (if available)
+const LoyaltyInfo = () => {
+  const { data: balance, isLoading: balanceLoading } =
+    useGetLoyaltyBalanceQuery();
+  const { data: transactions, isLoading: transactionsLoading } =
+    useGetLoyaltyTransactionsQuery();
+
+  if (balanceLoading || transactionsLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h2>Loyalty Points</h2>
+      <p>Current Balance: {balance?.balance || 0} points</p>
+
+      <h3>Recent Transactions</h3>
+      <div>
+        {transactions?.results?.map((transaction, index) => (
+          <div key={index} className="border-b py-2">
+            <span>{transaction.amount} points</span>
+            <span className="text-gray-500 ml-2">
+              {new Date(transaction.created_date).toLocaleDateString()}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+// Basket offers
+const BasketOffers = () => {
+  const { data: currentOffers } = useGetBasketOffersQuery();
+  const { data: futureOffers } = useGetFutureBasketOffersQuery();
+  const { data: expiredOffers } = useGetExpiredBasketOffersQuery();
+
+  return (
+    <div>
+      <h2>Basket Offers</h2>
+
+      {currentOffers && (
+        <div>
+          <h3>Active Offers</h3>
+          {/* Offer list */}
+        </div>
+      )}
+
+      {futureOffers && (
+        <div>
+          <h3>Future Offers</h3>
+          {/* Future offers */}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+### Mutation Hooks - Correct Usage Patterns
+
+```tsx
+'use client';
+
+const ProfileForm = () => {
+  const [updateProfile, { isLoading }] = useUpdateProfileMutation();
+  const [updateEmail, { isLoading: emailLoading }] = useUpdateEmailMutation();
+  const [updatePassword, { isLoading: passwordLoading }] =
+    useUpdatePasswordMutation();
+
+  const handleUpdateProfile = async (formData) => {
+    try {
+      const result = await updateProfile({
+        first_name: formData.firstName,
+        last_name: formData.lastName,
+        phone: formData.phone,
+        date_of_birth: formData.birthDate,
+        gender: formData.gender,
+        sms_allowed: formData.smsAllowed,
+        email_allowed: formData.emailAllowed
+      }).unwrap();
+
+      // Success handling
+      console.log('Profile updated:', result);
+    } catch (error) {
+      // Error handling
+      console.error('Profile update error:', error);
+    }
+  };
+
+  const handleChangeEmail = async (emailData) => {
+    try {
+      await updateEmail({
+        new_email: emailData.newEmail,
+        current_password: emailData.currentPassword
+      }).unwrap();
+    } catch (error) {
+      console.error('Email change error:', error);
+    }
+  };
+
+  const handleChangePassword = async (passwordData) => {
+    try {
+      await updatePassword({
+        old_password: passwordData.oldPassword,
+        new_password1: passwordData.newPassword,
+        new_password2: passwordData.confirmPassword
+      }).unwrap();
+    } catch (error) {
+      console.error('Password change error:', error);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Profile form */}
+      <button
+        onClick={handleUpdateProfile}
+        disabled={isLoading}
+        className="bg-blue-500 text-white p-2 rounded disabled:opacity-50"
+      >
+        {isLoading ? 'Saving...' : 'Update Profile'}
+      </button>
+    </div>
+  );
+};
+
+// Order cancellation
+const OrderActions = ({ orderId }) => {
+  const [cancelOrder, { isLoading }] = useCancelOrderMutation();
+  const { data: cancellationReasons } = useGetCancellationReasonsQuery();
+
+  const handleCancelOrder = async (reasonId) => {
+    try {
+      await cancelOrder({
+        id: orderId,
+        reason: reasonId
+      }).unwrap();
+
+      // Show success message
+    } catch (error) {
+      console.error('Order cancellation error:', error);
+    }
+  };
+
+  return (
+    <div>
+      <h3>Cancel Order</h3>
+      {cancellationReasons?.map((reason) => (
+        <button
+          key={reason.id}
+          onClick={() => handleCancelOrder(reason.id)}
+          disabled={isLoading}
+          className="block w-full text-left p-2 hover:bg-gray-100 disabled:opacity-50"
+        >
+          {reason.text}
+        </button>
+      ))}
+    </div>
+  );
+};
+
+// Contact form
+const ContactForm = () => {
+  const [sendContact, { isLoading }] = useSendContactMutation();
+  const { data: subjects } = useGetContactSubjectsQuery();
+
+  const handleSubmit = async (formData) => {
+    try {
+      const form = new FormData();
+      form.append('subject', formData.subject);
+      form.append('message', formData.message);
+      form.append('order_number', formData.orderNumber || '');
+
+      if (formData.attachment) {
+        form.append('attachment', formData.attachment);
+      }
+
+      await sendContact(form).unwrap();
+
+      // Success message
+    } catch (error) {
+      console.error('Contact form submission error:', error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <select name="subject" required>
+        <option value="">Select subject</option>
+        {subjects?.map((subject) => (
+          <option key={subject.id} value={subject.id}>
+            {subject.text}
+          </option>
+        ))}
+      </select>
+
+      <textarea name="message" required placeholder="Your message" />
+
+      <input type="file" name="attachment" />
+
+      <button
+        type="submit"
+        disabled={isLoading}
+        className="bg-blue-500 text-white p-2 rounded disabled:opacity-50"
+      >
+        {isLoading ? 'Sending...' : 'Send'}
+      </button>
+    </form>
+  );
+};
+
+// Account anonymization (GDPR)
+const AccountSettings = () => {
+  const [anonymize, { isLoading }] = useAnonymizeMutation();
+
+  const handleAnonymize = async () => {
+    if (confirm('Are you sure you want to permanently delete your account?')) {
+      try {
+        const result = await anonymize().unwrap();
+
+        // Redirect user to logout page
+        window.location.href = '/logout';
+      } catch (error) {
+        console.error('Account anonymization error:', error);
+      }
+    }
+  };
+
+  return (
+    <div className="bg-red-50 p-4 rounded border border-red-200">
+      <h3 className="text-red-800 font-semibold">Delete Account</h3>
+      <p className="text-red-700 text-sm mb-4">
+        This action cannot be undone. All your data will be permanently deleted.
+      </p>
+      <button
+        onClick={handleAnonymize}
+        disabled={isLoading}
+        className="bg-red-500 text-white px-4 py-2 rounded disabled:opacity-50"
+      >
+        {isLoading ? 'Deleting...' : 'Delete Account'}
+      </button>
+    </div>
+  );
+};
+```
+
+## State Management
+
+### Redux Store
+
+```tsx
+'use client';
+
+import { useAppSelector, useAppDispatch } from '@akinon/next/redux/store';
+
+const AccountComponent = () => {
+  const dispatch = useAppDispatch();
+  const { user, isLoading } = useAppSelector((state) => state.account);
+
+  // Redux actions
+  const handleUpdate = () => {
+    dispatch(/* account action */);
+  };
+
+  return <div>{/* Component */}</div>;
+};
+```
+
+## Form Handling
+
+### React Hook Form
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { yupResolver } from '@hookform/resolvers/yup';
+import * as yup from 'yup';
+import { useLocalization } from '@akinon/next/hooks/useLocalization';
+
+const profileSchema = yup.object({
+  first_name: yup.string().required('First name is required'),
+  last_name: yup.string().required('Last name is required'),
+  phone: yup.string().required('Phone is required'),
+  date_of_birth: yup.date().nullable(),
+  gender: yup.string(),
+  sms_allowed: yup.boolean(),
+  email_allowed: yup.boolean()
+});
+
+const ProfileForm = () => {
+  const { t } = useLocalization();
+  const [updateProfile, { isLoading }] = useUpdateProfileMutation();
+
+  const {
+    register,
+    handleSubmit,
+    formState: { errors }
+  } = useForm({
+    resolver: yupResolver(profileSchema)
+  });
+
+  const onSubmit = async (data) => {
+    try {
+      await updateProfile(data).unwrap();
+      // Success message
+    } catch (error) {
+      // Error handling
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input
+        {...register('first_name')}
+        placeholder="First Name"
+        className="border p-2 rounded"
+      />
+      {errors.first_name && (
+        <span className="text-red-500">{errors.first_name.message}</span>
+      )}
+
+      <input
+        {...register('last_name')}
+        placeholder="Last Name"
+        className="border p-2 rounded"
+      />
+      {errors.last_name && (
+        <span className="text-red-500">{errors.last_name.message}</span>
+      )}
+
+      <button
+        type="submit"
+        disabled={isLoading}
+        className="bg-blue-500 text-white p-2 rounded"
+      >
+        {isLoading ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  );
+};
+```
+
+## Styling
+
+### TailwindCSS
+
+```tsx
+const AccountPage = () => {
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+        <div className="bg-white rounded-lg shadow p-6">
+          <h2 className="text-xl font-semibold mb-4">Profile</h2>
+          {/* Content */}
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+### Conditional Classes
+
+```tsx
+import { clsx } from 'clsx';
+
+const StatusBadge = ({ status }) => {
+  return (
+    <span
+      className={clsx('px-2 py-1 rounded text-sm', {
+        'bg-green-100 text-green-800': status === 'completed',
+        'bg-yellow-100 text-yellow-800': status === 'pending',
+        'bg-red-100 text-red-800': status === 'cancelled'
+      })}
+    >
+      {status}
+    </span>
+  );
+};
+```
+
+## Localization
+
+### Usage
+
+```tsx
+import { useLocalization } from '@akinon/next/hooks/useLocalization';
+
+const AccountComponent = () => {
+  const { t } = useLocalization();
+
+  return (
+    <div>
+      <h1>{t('account.title')}</h1>
+      <p>{t('account.welcome_message', { name: 'User' })}</p>
+    </div>
+  );
+};
+```
+
+## Error Handling
+
+### API Errors
+
+```tsx
+const AccountComponent = () => {
+  const { data, error, isLoading } = useGetProfileInfoQuery();
+
+  if (error) {
+    return (
+      <div className="bg-red-50 border border-red-200 rounded p-4">
+        <p className="text-red-700">
+          {error.data?.message || 'An error occurred'}
+        </p>
+      </div>
+    );
+  }
+
+  if (isLoading) {
+    return <div className="animate-pulse">Loading...</div>;
+  }
+
+  return <div>{/* Normal content */}</div>;
+};
+```
+
+## Performance
+
+### Loading States
+
+```tsx
+const LoadingSkeleton = () => (
+  <div className="animate-pulse space-y-4">
+    <div className="h-4 bg-gray-200 rounded w-3/4"></div>
+    <div className="h-4 bg-gray-200 rounded w-1/2"></div>
+    <div className="h-32 bg-gray-200 rounded"></div>
+  </div>
+);
+```
+
+### Lazy Loading
+
+```tsx
+import { LazyComponent } from '@akinon/next/components/lazy-component';
+
+const LazyOrderHistory = LazyComponent(() => import('./OrderHistory'));
+```
+
+## Best Practices
+
+### TypeScript
+
+```tsx
+interface User {
+  id: number;
+  first_name: string;
+  last_name: string;
+  email: string;
+}
+
+interface Order {
+  id: number;
+  number: string;
+  status: string;
+  total: number;
+}
+
+interface Address {
+  id: number;
+  title: string;
+  address: string;
+  city: string;
+  district: string;
+}
+```
+
+### File Organization
+
+```
+account/
+├── page.tsx              # Main account page
+├── layout.tsx            # Layout (optional)
+├── profile/
+│   └── page.tsx         # Profile page
+├── orders/
+│   ├── page.tsx         # Orders list
+│   └── [id]/
+│       └── page.tsx     # Order detail
+└── addresses/
+    ├── page.tsx         # Address list
+    └── new/
+        └── page.tsx     # New address
+```
+
+---
+
+**Note:** These instructions are based on Project Zero's existing API and hook structures. Follow existing patterns when adding new features.
+
+## Important Notes
+
+### Hook Usage Rules
+
+1. **Query hooks** run automatically, no manual triggering required
+2. **Mutation hooks** return array destructuring with `[mutationFn, { isLoading, error }]`
+3. Use **unwrap()** for promise-based error handling
+4. **isLoading** state should be used in UI for loading states
+
+### Error Handling Best Practices
+
+```tsx
+// RTK Query error handling
+const { data, error, isLoading } = useGetOrdersQuery();
+
+if (error) {
+  // RTK Query error structure
+  const errorMessage =
+    error.data?.message || error.error || 'An error occurred';
+  return <div className="text-red-500">{errorMessage}</div>;
+}
+```
+
+### Conditional Rendering
+
+```tsx
+// Show alternative content when no data
+const OrdersList = () => {
+  const { data: orders, isLoading } = useGetOrdersQuery();
+
+  if (isLoading) return <LoadingSkeleton />;
+
+  if (!orders?.results?.length) {
+    return (
+      <div className="text-center py-8">
+        <p>You don't have any orders yet.</p>
+        <Link href="/products" className="text-blue-500">
+          Start shopping
+        </Link>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {orders.results.map((order) => (
+        <OrderCard key={order.id} order={order} />
+      ))}
+    </div>
+  );
+};
+```