@akinon/projectzero 1.99.0-rc.69 → 1.99.0-snapshot-ZERO-3640-20250919140314

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

@@ -1,749 +0,0 @@
----
-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>
-  );
-};
-```