Merge pull request #56 from bartstc/feat/rate-product

feat: add interactive product star rating

Author: bartstc

public/locales/en-GB/translation.json

@@ -57,7 +57,13 @@
   "features": {
     "products": {
       "rating": {
-        "tooltip": "Average customer rating: {rating}"
+        "tooltip": "Average customer rating: {rating}",
+        "notifications": {
+          "title": "Product rating",
+          "not-authenticated": "You have to log in to rate the product",
+          "success": "Thank you! Your rating has been submitted.",
+          "error": "Something went wrong with submitting your rating. Please try again or contact us."
+        }
       },
       "categories": {
         "clothing": "Clothing",

specs/004-product-rating/spec.md

@@ -0,0 +1,100 @@
+# Product Rating
+
+## Meta
+
+| Field          | Value                       |
+| -------------- | --------------------------- |
+| Status         | `approved`                  |
+| Author         | bartstc                     |
+| Created        | 2026-04-17                  |
+| Last updated   | 2026-04-17                  |
+| Spec directory | `specs/004-product-rating/` |
+
+---
+
+## 1. Goal & Context
+
+The `StarRating` component currently renders read-only stars derived from the marketing product's aggregate rating. Users have no way to contribute their own rating. This feature makes the stars interactive: clicking a star submits a 1–5 integer rating to `PATCH /api/marketing/products/:id/rate`, updates the displayed rating optimistically, and disables further rating in that session. Unauthenticated users see a warning toast instead.
+
+## 2. Requirements
+
+- **R1**: WHEN a logged-in user clicks a star (1–5), THE SYSTEM SHALL immediately update the displayed rating optimistically and call `PATCH /api/marketing/products/:id/rate` with the selected integer.
+- **R2**: WHEN the API call fails, THE SYSTEM SHALL revert the displayed rating to its pre-click value and show an error toast.
+- **R3**: WHEN an unauthenticated user clicks a star, THE SYSTEM SHALL show a warning toast "You have to log in to rate the product" and make no API call.
+- **R4**: WHEN a user has submitted a rating in the current session, THE SYSTEM SHALL disable the star controls so no further rating is possible.
+- **R5**: WHEN the rating mutation is pending, THE SYSTEM SHALL visually disable the star controls to prevent double submission.
+
+## 3. Non-Goals / Out of Scope
+
+- Persisting "already rated" state across sessions (no localStorage / server-side deduplication).
+- Half-star or decimal rating input.
+- Showing the user's own previously submitted rating vs. the aggregate.
+- Any changes to the "see reviews" button behaviour.
+- Rate-limiting or throttling beyond disabling after one submission.
+
+## 4. Building Blocks Diff
+
+### Added
+
+- `useRateProductMutation` (mutation-hook) — `src/lib/api/marketing/{product-id}/use-rate-product-mutation.ts` — calls `PATCH /api/marketing/products/:id/rate`, applies optimistic update to cached `MarketingProductDto`, rolls back on error
+- `useRateProductMutation` (mutation-hook, providers re-export) — `src/features/products/providers/use-rate-product-mutation.ts`
+- `useRateProductNotifications` (notification-hook) — `src/features/products/application/use-rate-product-notifications.ts` — warning toast for unauthenticated, error toast on failure
+- `useRateProduct` (use-case-hook) — `src/features/products/application/use-rate-product.ts` — checks auth, calls mutation, dispatches notifications; returns `{ rate, isPending, hasRated }`
+
+### Modified
+
+- `StarRating` (component) — `src/features/products/components/StarRating.tsx` — add `productId` prop, wire `useRateProduct`, make stars clickable, disable after rating or while pending
+- `ProductDetails` (component) — `src/features/products/components/ProductDetails.tsx` — pass `product.id` as `productId` to `StarRating`
+- `public/locales/en/translation.json` — add toast keys under `features.products.rating`
+
+## 5. Design Decisions
+
+- **Optimistic update in the mutation, not local state**: The cache already holds `MarketingProductDto`; mutating it directly keeps one source of truth. A separate `useState` would duplicate state and diverge on rollback.
+- **Auth check in `useRateProduct`**: Consistent with `useAddToCart` — auth guard lives in the use-case hook, not in the component or mutation. Component stays presentational.
+- **`hasRated` as local state in `useRateProduct`**: Session-only disable with no persistence, per requirements. Clean `useState<boolean>` inside the hook keeps the mutation layer unaware.
+
+## 6. Boundaries
+
+### ✅ Always
+
+- Create/modify files under `src/features/products/`
+- Create files under `src/lib/api/marketing/`
+- Add translation keys to `public/locales/en/translation.json`
+
+### ⚠️ Ask First
+
+- Any change to `MarketingProductDto` in `src/lib/api/marketing/{product-id}/marketing-product-dto.ts`
+
+### 🚫 Never
+
+- Modify `server/` source files
+- Remove or skip existing tests
+- Change the `rateMarketingProductHandler` API contract
+
+## 7. Task Breakdown
+
+1. [S] Add `useRateProductMutation` with optimistic update and rollback — `src/lib/api/marketing/{product-id}/use-rate-product-mutation.ts` (R1, R2)
+2. [S] Re-export `useRateProductMutation` from providers — `src/features/products/providers/use-rate-product-mutation.ts` (R1, R2)
+3. [P] Add `useRateProductNotifications` — `src/features/products/application/use-rate-product-notifications.ts` (R2, R3)
+4. [P] Add translation keys for rating toasts — `public/locales/en/translation.json` (R2, R3)
+5. [S] Add `useRateProduct` use-case hook — `src/features/products/application/use-rate-product.ts` (R1, R2, R3, R4, R5)
+6. [S] Modify `StarRating` — add `productId` prop, wire `useRateProduct`, clickable + disabled states — `src/features/products/components/StarRating.tsx` (R1, R4, R5)
+7. [S] Pass `productId` from `ProductDetails` to `StarRating` — `src/features/products/components/ProductDetails.tsx` (R1)
+
+## 8. Error & Edge Cases
+
+- GIVEN the API returns a non-2xx response, WHEN the mutation settles, THEN revert the optimistic rating to the pre-click cached value and show an error toast.
+- GIVEN the user is unauthenticated, WHEN a star is clicked, THEN show the warning toast and do not call the mutation; stars remain enabled so the user can log in and retry.
+- GIVEN the mutation is in-flight, WHEN the user attempts to click another star, THEN controls are disabled and no second request is made.
+- GIVEN the user has successfully rated, WHEN the component re-renders due to a query refetch, THEN `hasRated` persists in hook state and stars remain disabled.
+- GIVEN the cached `MarketingProductDto` is absent, WHEN a star is clicked, THEN the optimistic update is skipped gracefully and the mutation still fires; rollback is a no-op.
+
+## 10. Open Questions
+
+_(none)_
+
+## 11. References
+
+- `server/src/modules/marketing/marketing.handlers.ts` — `rateMarketingProductHandler` implementation
+- `server/src/modules/marketing/marketing.routes.ts` — `PATCH /api/marketing/products/:id/rate` route
+- `src/features/carts/application/use-add-to-cart.ts` — auth-check pattern to follow

specs/lessons.md

@@ -39,3 +39,41 @@ Patterns captured after corrections. Review at session start.
 **How to apply:** Before using any type from `src/lib/api/` in a component or page, check whether a domain alias exists in the feature's `models/`. If not, create one following the pattern in `product.ts`: `export type { XxxDto as Xxx } from "@/lib/api/..."`.
 
 **Source:** Correction 2026-04-12 — `MarketingProductDto` leaked into `ProductDetails.tsx` component props.
+
+---
+
+## L003 — Mutation building blocks in specs must be named as hooks (use\* prefix)
+
+**Rule:** Mutation hooks in `lib/api/` and `providers/` are React hooks and must follow the `use` prefix convention. In specs, name them `useXxxMutation`, never `xxxMutation`.
+
+**Why it failed:** `rateMarketingProductMutation` was listed in the Building Blocks Diff without the `use` prefix, despite being a hook that calls `useMutation` internally.
+
+**How to apply:** In any spec Building Blocks Diff, check every mutation-hook entry — if it wraps `useMutation`, prefix it with `use`. File name uses kebab-case: `use-rate-product-mutation.ts`.
+
+Also, we might have inconsistency, as queries from lib/api are exposed by query factories, not query hooks, which might be confusing. Maybe we should always export useQuery (default version) as well, then we would have consistent exports there: useSmthMutation (use-smth-mutation) and useSmthQuery (use-smth-query.ts).
+
+**Source:** Correction 2026-04-17 — spec 004-product-rating Building Blocks Diff.
+
+---
+
+## L004 — Spec boundaries must only list items within the feature's scope
+
+**Rule:** The ⚠️ Ask First boundary tier must only include items that are plausible within the current feature's scope. Generic project-wide concerns (e.g. "adding npm dependencies") that have no connection to the feature being specced must be omitted.
+
+**Why it failed:** "Adding new npm dependencies" was added to ⚠️ Ask First in a spec that adds no dependencies — it was a boilerplate copy-paste rather than a scope-specific boundary.
+
+**How to apply:** Before finalising the Boundaries section, ask: "Is this item actually reachable during implementation of this feature?" If no, remove it.
+
+**Source:** Correction 2026-04-17 — spec 004-product-rating Boundaries section.
+
+---
+
+## L005 — Never explore the codebase for patterns during implementation — read spec and building-blocks rules instead
+
+**Rule:** Before implementing any building block, read the spec's Building Blocks Diff and the corresponding rule file in `.agents/skills/building-blocks/rules/`. Do not open existing feature files to reverse-engineer patterns. If a rule file is missing or ambiguous, raise that gap — do not substitute with file exploration.
+
+**Why it failed:** An agent issued broad `read`/`list` calls across multiple feature folders (`providers/`, `application/`, `models/`, `lib/api/`) to infer patterns from live code. The spec already listed every building block to create, and the building-blocks skill already documents the canonical pattern for each one. The exploration was pure redundancy — and risks drifting toward the existing code's quirks rather than the authoritative pattern.
+
+**How to apply:** At the start of every implementation task: (1) open the spec, identify every block in the Building Blocks Diff, (2) for each block, load the matching rule file from `.agents/skills/building-blocks/rules/<block>.md`, (3) implement against the rule, not against existing files. Only read an existing file when the spec explicitly says "follow the pattern in `path/to/file.ts`" or when you need to find the exact symbol to import (e.g. a query key or provider name).
+
+**Source:** Correction 2026-04-17 — spec 004-product-rating implementation; agent explored 9+ existing files instead of reading building-blocks rules.

src/features/products/application/use-rate-product-notifications.ts

@@ -0,0 +1,30 @@
+import { useToast } from "@/lib/components/Toast/use-toast";
+import { useTranslations } from "@/lib/i18n/use-transations";
+
+export const useRateProductNotifications = () => {
+  const t = useTranslations("features.products.rating.notifications");
+  const toast = useToast();
+
+  const notifyNotAuthenticated = () =>
+    toast({
+      status: "warning",
+      title: t("title"),
+      description: t("not-authenticated"),
+    });
+
+  const notifySuccess = () =>
+    toast({
+      status: "success",
+      title: t("title"),
+      description: t("success"),
+    });
+
+  const notifyFailure = () =>
+    toast({
+      status: "error",
+      title: t("title"),
+      description: t("error"),
+    });
+
+  return { notifyNotAuthenticated, notifySuccess, notifyFailure } as const;
+};

src/features/products/application/use-rate-product.ts

@@ -0,0 +1,31 @@
+import { useState } from "react";
+
+import { useAuthStore } from "@/features/auth/application/auth-store";
+import { useRateProductMutation } from "@/features/products/providers/use-rate-product-mutation";
+
+import { useRateProductNotifications } from "./use-rate-product-notifications";
+
+export const useRateProduct = () => {
+  const isAuthenticated = useAuthStore((store) => store.isAuthenticated);
+  const [mutateAsync, isPending] = useRateProductMutation();
+  const { notifyNotAuthenticated, notifySuccess, notifyFailure } =
+    useRateProductNotifications();
+  const [hasRated, setHasRated] = useState(false);
+
+  const rate = async (productId: string, rating: number) => {
+    if (!isAuthenticated) {
+      notifyNotAuthenticated();
+      return;
+    }
+
+    try {
+      await mutateAsync(productId, rating);
+      setHasRated(true);
+      notifySuccess();
+    } catch {
+      notifyFailure();
+    }
+  };
+
+  return { rate, isPending, hasRated };
+};

src/features/products/components/ProductDetails.tsx

@@ -74,7 +74,10 @@ const ProductDetails = ({ product, marketingProduct, onBack }: IProps) => {
               {moneyVO.format(product.price.amount, product.price.currency)}
             </Text>
             <Separator orientation="vertical" />
-            <StarRating rating={marketingProduct?.rating.rate ?? 0} />
+            <StarRating
+              rating={marketingProduct?.rating.rate ?? 0}
+              productId={product.id}
+            />
             <Button variant="plain" colorPalette="orange">
               {t("see-reviews", {
                 number: marketingProduct?.rating.count ?? 0,

src/features/products/components/StarRating.stories.tsx

@@ -16,5 +16,6 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     rating: 3.7,
+    productId: "1",
   },
 };

src/features/products/components/StarRating.tsx

@@ -1,28 +1,55 @@
 import { HStack, Icon, Portal, Tooltip } from "@chakra-ui/react";
 import { Star } from "lucide-react";
+import { useState } from "react";
 
+import { useRateProduct } from "@/features/products/application/use-rate-product";
 import { useTranslations } from "@/lib/i18n/use-transations";
 import { useColorModeValue } from "@/lib/theme/use-color-mode";
 
 interface IProps {
   rating: number;
+  productId: string;
 }
 
-const StarRating = ({ rating }: IProps) => {
-  const idleStar = useColorModeValue("gray.400", "gray.600");
+const StarRating = ({ rating, productId }: IProps) => {
+  const idleStar = useColorModeValue("gray.300", "gray.600");
   const activeStar = useColorModeValue("gray.700", "gray.300");
   const t = useTranslations("features.products.rating");
+  const { rate, isPending, hasRated } = useRateProduct();
+  const isDisabled = isPending || hasRated;
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
 
-  const countColor = (index: number) => {
+  const starColor = (index: number) => {
+    if (!isDisabled && hoveredIndex !== null) {
+      return index <= hoveredIndex ? "yellow.400" : idleStar;
+    }
     return Math.round(rating) >= index ? activeStar : idleStar;
   };
 
   return (
     <Tooltip.Root>
       <Tooltip.Trigger asChild>
-        <HStack gap={1} display="flex" alignItems="center" mt={2}>
+        <HStack
+          gap={1}
+          display="flex"
+          alignItems="center"
+          mt={2}
+          opacity={isDisabled ? 0.5 : 1}
+          cursor={isDisabled ? "not-allowed" : "pointer"}
+          onMouseLeave={() => setHoveredIndex(null)}
+        >
           {Array.from([1, 2, 3, 4, 5]).map((number) => (
-            <Icon key={number} color={countColor(number)} boxSize={3}>
+            <Icon
+              key={number}
+              color={starColor(number)}
+              boxSize={3}
+              style={{ transition: "color 0.15s ease" }}
+              onMouseEnter={
+                isDisabled ? undefined : () => setHoveredIndex(number)
+              }
+              onClick={isDisabled ? undefined : () => rate(productId, number)}
+              cursor={isDisabled ? "not-allowed" : "pointer"}
+            >
               <Star fill="currentColor" />
             </Icon>
           ))}

src/features/products/providers/use-rate-product-mutation.ts

@@ -0,0 +1 @@
+export { useRateProductMutation } from "@/lib/api/marketing/{product-id}/use-rate-product-mutation";

src/lib/api/marketing/{product-id}/use-rate-product-mutation.ts

@@ -0,0 +1,74 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { marketingQueryKeys } from "@/lib/api/marketing/marketing-query-keys";
+import { httpService } from "@/lib/http";
+import { Logger } from "@/lib/logger";
+import { UnknownError } from "@/lib/types/unknown-error";
+
+import type { MarketingProductDto } from "./marketing-product-dto";
+
+interface RateProductDto {
+  productId: string;
+  rating: number;
+}
+
+interface MutationContext {
+  previous: MarketingProductDto | undefined;
+  productId: string;
+}
+
+export const useRateProductMutation = () => {
+  const queryClient = useQueryClient();
+
+  const { mutateAsync, isPending } = useMutation<
+    MarketingProductDto,
+    unknown,
+    RateProductDto,
+    MutationContext
+  >({
+    mutationFn: ({ productId, rating }) =>
+      httpService.patch<MarketingProductDto, { rating: number }>(
+        `marketing/products/${productId}/rate`,
+        { rating }
+      ),
+    onMutate: async ({ productId, rating }) => {
+      const queryKey = marketingQueryKeys.product(productId);
+      await queryClient.cancelQueries({ queryKey });
+
+      const previous = queryClient.getQueryData<MarketingProductDto>(queryKey);
+
+      if (previous) {
+        const { rate: oldRate, count: oldCount } = previous.rating;
+        const newCount = oldCount + 1;
+        const newRate =
+          Math.round(((oldRate * oldCount + rating) / newCount) * 100) / 100;
+
+        queryClient.setQueryData<MarketingProductDto>(queryKey, {
+          ...previous,
+          rating: { rate: newRate, count: newCount },
+        });
+      }
+
+      return { previous, productId };
+    },
+    onError: (_err, _vars, context) => {
+      if (context?.previous) {
+        queryClient.setQueryData(
+          marketingQueryKeys.product(context.productId),
+          context.previous
+        );
+      }
+    },
+  });
+
+  const handler = async (productId: string, rating: number) => {
+    try {
+      return await mutateAsync({ productId, rating });
+    } catch (e) {
+      Logger.error("An error occurred during rating the product", e as Error);
+      throw new UnknownError();
+    }
+  };
+
+  return [handler, isPending] as const;
+};