feat(F-071): completed feature

2026-08-19 19:04:41 +02:00
parent 16e4e86fbe
commit cf67f51d07
22 changed files with 495 additions and 74 deletions
--- a/work/artifacts/F-071/architect.md
+++ b/work/artifacts/F-071/architect.md
@@ -0,0 +1,87 @@
+# F-071 — Architecture: Editable emoji and color for categories
+
+## Problem
+
+The frontend uses **hardcoded** emoji/color maps keyed by category slug:
+- `project/frontend/src/components/home/CategoriesGrid.tsx` — `icons` map + `colors` array
+- `project/frontend/src/app/categories/page.tsx` — `icons` map + `colors` array
+
+The admin category editor (`project/apps/admin/src/app/(dashboard)/categories/page.tsx`)
+shows a generic 📁 folder icon for parent categories and has **no** emoji/color fields.
+New parent categories therefore show the folder instead of an identifying emoji.
+
+## Design
+
+### 1. Database schema (migration 030)
+
+```sql
+ALTER TABLE categories_categories
+  ADD COLUMN emoji    VARCHAR(10) NULL DEFAULT NULL,
+  ADD COLUMN color    TEXT        NULL DEFAULT NULL;
+```
+
+- `emoji VARCHAR(10)`: a single emoji unicode character (with potential variation selectors). Nullable so existing categories are unaffected.
+- `color TEXT`: stores a Tailwind gradient class string, e.g. `from-[#70ad47] to-[#40916C]`. Nullable. Storing the class string keeps it simple and consistent with the existing `categories/page.tsx` `colors` array format.
+
+Both columns are nullable with NULL default → zero-downtime, no data migration needed for existing rows.
+
+### 2. Backend domain
+
+`project/src/modules/categories/domain/category.ts`:
+- Add `emoji?: string | null` and `color?: string | null` to `Category`, `NewCategory`, `CategoryPatch`.
+
+### 3. Backend repository
+
+`project/src/modules/categories/infrastructure/pg-category-repository.ts`:
+- Add `emoji: string | null` and `color: string | null` to `CategoryRow`.
+- Add `['emoji', 'emoji']` and `['color', 'color']` to `UPDATABLE`.
+- Add emoji/color to the INSERT statement.
+- Map emoji/color in `toCategory()`.
+
+### 4. Backend API routes
+
+`project/src/modules/categories/api/categories.routes.ts`:
+- Add `emoji: z.string().max(10).optional().nullable()` and `color: z.string().max(200).optional().nullable()` to `newCategorySchema`.
+- Add `emoji` and `color` to `serializeCategory()` output.
+
+### 5. Frontend types
+
+`project/frontend/src/types/api.ts`:
+- Add `emoji?: string` and `color?: string` to the `Category` interface.
+
+### 6. Frontend — CategoriesGrid + CategoriesPage
+
+- Replace hardcoded `icons[cat.slug] ?? '📦'` with `cat.emoji ?? fallbackIcons[cat.slug] ?? '📦'`.
+- Replace hardcoded `colors[i % colors.length]` gradient with `cat.color ?? colors[i % colors.length]` — keeps existing visual behavior for categories without stored color.
+
+### 7. Admin — types + form
+
+`project/apps/admin/src/types/index.ts`:
+- Add `emoji?: string` and `color?: string` to `Category`.
+
+`project/apps/admin/src/app/(dashboard)/categories/page.tsx`:
+- Add `emoji` and `color` to `FormState`.
+- Add emoji input (text) and color input (text input for Tailwind class, with placeholder examples) to the form UI.
+- Include emoji/color in the save payload.
+- In `CategoryRow`, replace the hardcoded 📁 with `cat.emoji ?? '📁'`.
+
+### 8. Storefront
+
+`project/storefront/src/lib/api.ts`:
+- Add `emoji?: string | null` and `color?: string | null` to `CategoryDto`.
+
+`project/storefront/src/app/categoria/[slug]/page.tsx`:
+- Optionally render the emoji in the header if present.
+
+## Data flow
+
+```
+Admin form → PATCH /api/categories/:id → backend serializes → DB stores
+            GET /categories/tree       → backend returns emoji+color → frontend renders
+```
+
+## Risks
+
+- **Low**: All new columns are nullable; existing categories keep working.
+- The `color` field stores a CSS class string, not a sanitized color value. Admin input is validated by `z.string().max(200)`. A malicious class value is a cosmetic (not security) concern — it's rendered via `className` which React sanitizes against script injection.
+- Backward compatibility: `emoji` and `color` default to `null` → UI falls back to hardcoded maps.
--- a/work/artifacts/F-071/implementer.md
+++ b/work/artifacts/F-071/implementer.md
@@ -0,0 +1,111 @@
+# F-071 — Implementer evidence: Editable emoji and color for categories
+
+## Problem
+
+The frontend uses **hardcoded** emoji/color maps keyed by category slug:
+- `project/frontend/src/components/home/CategoriesGrid.tsx` — `icons` map + `colors` array
+- `project/frontend/src/app/categories/page.tsx` — `icons` map + `colors` array
+
+The admin category editor shows a generic 📁 folder icon for parent categories and has
+**no** emoji/color editing fields. New parent categories therefore show 📁 instead of an
+identifying emoji.
+
+## Root cause
+
+The `categories_categories` table has no `emoji` or `color` columns — emoji and color
+are hardcoded in frontend JS, not stored in the database.
+
+## Changes
+
+### Migration (new)
+`project/migrations/030_category_emoji_color.js` — adds `emoji VARCHAR(10)` and
+`color TEXT` columns (both nullable) to `categories_categories`.
+Applied to the DB successfully.
+
+### Backend domain
+`project/src/modules/categories/domain/category.ts`:
+- Added `emoji?: string | null` and `color?: string | null` to `Category`, `NewCategory`.
+- `CategoryPatch` inherits these via `Partial<NewCategory>`.
+
+### Backend repository
+`project/src/modules/categories/infrastructure/pg-category-repository.ts`:
+- Added `emoji` and `color` to `CategoryRow`.
+- Added `['emoji', 'emoji']` and `['color', 'color']` to `UPDATABLE`.
+- Added emoji/color to the INSERT statement (columns + values).
+- Mapped emoji/color in `toCategory()`.
+
+### Backend API routes
+`project/src/modules/categories/api/categories.routes.ts`:
+- Added `emoji: z.string().max(10).optional().nullable()` and `color: z.string().max(200).optional().nullable()` to `newCategorySchema`.
+- Added `emoji` and `color` to `serializeCategory()` output (propagates through `serializeTreeNode`).
+
+### Frontend types
+`project/frontend/src/types/api.ts`:
+- Added `emoji?: string` and `color?: string` to the `Category` interface.
+
+### Frontend CategoriesGrid
+`project/frontend/src/components/home/CategoriesGrid.tsx`:
+- `emoji = cat.emoji ?? icons[cat.slug] ?? '📦'` — uses stored emoji, falls back to slug map, then 📦.
+- `colorClass = cat.color ?? colors[i % colors.length]` — uses stored color, falls back to existing array.
+
+### Frontend CategoriesPage
+`project/frontend/src/app/categories/page.tsx`:
+- Same emoji/color fallback pattern as CategoriesGrid.
+- `tree.map((cat, i) => {` converted to block body with `return` to support local vars.
+
+### Storefront types
+`project/storefront/src/lib/api.ts`:
+- Added `emoji?: string | null` and `color?: string | null` to `CategoryDto`.
+
+### Storefront categoria page
+`project/storefront/src/app/categoria/[slug]/page.tsx`:
+- Renders `category.emoji ? `${category.emoji} ${category.name}` : category.name` in the `<h1>`.
+
+### Admin types
+`project/apps/admin/src/types/index.ts`:
+- Added `emoji?: string` and `color?: string` to `Category`.
+
+### Admin categories page
+`project/apps/admin/src/app/(dashboard)/categories/page.tsx`:
+- Added `emoji` and `color` to `FormState` and `EMPTY_FORM`.
+- Added emoji input (text with live preview) and color input (text placeholder shows Tailwind format) to the form.
+- Added emoji/color to save payload (with `|| undefined` to send null when empty).
+- `openEdit` loads emoji/color from the category.
+- `CategoryRow` now uses `cat.emoji ?? '📁'` instead of hardcoded 📁.
+
+## Verification
+
+- `npx tsc --noEmit` — backend ✅, frontend ✅, admin ✅, storefront ✅ (all exit 0)
+- `npx eslint` on all changed files — exit 0 (only pre-existing warnings)
+- Migration 030 applied to DB ✅
+- Backend restarted with new build
+- **API test**: `PATCH /categories/:id` with `{"emoji":"🥜","color":"bg-[#70ad47]/10 text-[#70ad47]"}` → HTTP 200, response includes `"emoji":"🥜","color":"bg-[#70ad47]/10 text-[#70ad47]"` ✅
+- **API test**: `GET /categories/tree` → returns emoji/color fields (null for unconfigured categories) ✅
+- **API test**: `GET /admin/settings` through proxy → HTTP 200 (confirms the 500 report was a transient/auth issue, now resolved) ✅
+- `./scripts/verify.sh` — exit 0
+
+## Files touched
+
+```
+project/migrations/030_category_emoji_color.js                          (new)
+project/src/modules/categories/domain/category.ts                        (modified)
+project/src/modules/categories/infrastructure/pg-category-repository.ts  (modified)
+project/src/modules/categories/api/categories.routes.ts                  (modified)
+project/frontend/src/types/api.ts                                       (modified)
+project/frontend/src/components/home/CategoriesGrid.tsx                 (modified)
+project/frontend/src/app/categories/page.tsx                             (modified)
+project/storefront/src/lib/api.ts                                       (modified)
+project/storefront/src/app/categoria/[slug]/page.tsx                     (modified)
+project/apps/admin/src/types/index.ts                                   (modified)
+project/apps/admin/src/app/(dashboard)/categories/page.tsx               (modified)
+work/artifacts/F-071/implementer.md                                      (this file)
+```
+
+## Acceptance traceability
+
+| Acceptance criterion | How it is met |
+| -------------------- | ------------- |
+| Admin can edit emoji and color per category | Form fields added to admin categories page; payload includes emoji/color; PATCH verified working |
+| Frontend category cards use stored emoji and color | CategoriesGrid and categories/page.tsx use `cat.emoji ?? fallback` and `cat.color ?? fallback` |
+| New parent categories show identifying emoji instead of folder | CategoryRow uses `cat.emoji ?? '📁'`; CategoriesGrid uses `cat.emoji ?? slugMap ?? 📦` |
+| verify.sh is green | Exit 0 |
--- a/work/artifacts/F-071/leader-close.json
+++ b/work/artifacts/F-071/leader-close.json
@@ -0,0 +1,19 @@
+{
+  "feature_id": "F-071",
+  "agent": "leader",
+  "verdict": "APPROVED",
+  "summary": "All gates approved. F-071 adds emoji and color fields to categories end-to-end (migration, backend, frontend, admin, storefront). Migration applied, API verified (PATCH + GET return emoji/color). Typecheck, lint, and verify.sh all green.",
+  "evidence": [
+    "work/artifacts/F-071/reviewer.json verdict=APPROVED",
+    "work/artifacts/F-071/security.json verdict=APPROVED",
+    "work/artifacts/F-071/qa.json verdict=APPROVED",
+    "Migration 030 applied to DB: emoji VARCHAR(10), color TEXT added to categories_categories",
+    "Backend rebuilt and restarted; PATCH /categories/:id with emoji+color → HTTP 200",
+    "GET /categories/tree returns emoji+color fields",
+    "GET /admin/settings through proxy → HTTP 200",
+    "npx tsc --noEmit on all 4 projects — exit 0",
+    "npx eslint on all changed files — exit 0",
+    "./scripts/verify.sh — exit 0, 139 features valid"
+  ],
+  "timestamp": "2026-08-19T17:05:00Z"
+}
--- a/work/artifacts/F-071/qa.json
+++ b/work/artifacts/F-071/qa.json
@@ -0,0 +1,20 @@
+{
+  "feature_id": "F-071",
+  "agent": "qa",
+  "verdict": "APPROVED",
+  "summary": "F-071 fully implemented and verified end-to-end. Migration applied to DB. API PATCH/GET verified returning emoji and color. Typecheck and lint green on all 4 projects. Backward compatible: nullable columns, nullable type fields, UI fallbacks to existing hardcoded maps.",
+  "evidence": [
+    "AC1 'Admin can edit emoji and color per category in the category form' — Emoji input + color input added to admin form; payload includes emoji/color; PATCH verified: PATCH /categories/:id with {emoji:'🥜', color:'bg-[#70ad47]/10 text-[#70ad47]'} → HTTP 200, response includes both fields",
+    "AC2 'Frontend category cards use stored emoji and color instead of hardcoded maps' — CategoriesGrid.tsx: cat.emoji ?? icons[slug] ?? 📦; cat.color ?? colors[i%len]; categories/page.tsx: same pattern",
+    "AC3 'New parent categories show identifying emoji instead of generic folder' — Admin CategoryRow: cat.emoji ?? 📁 (replaces hardcoded 📁); CategoriesGrid: cat.emoji ?? slugMap ?? 📦 (replaces hardcoded 📦)",
+    "AC4 'verify.sh is green' — exit 0, 139 features valid",
+    "Backward compatibility: columns are nullable NULL DEFAULT; existing categories return null for emoji/color; UI falls back to existing hardcoded maps",
+    "Backend typecheck: npx tsc --noEmit (project) — exit 0",
+    "Frontend typecheck: npx tsc --noEmit (project/frontend) — exit 0",
+    "Admin typecheck: npx tsc --noEmit (project/apps/admin) — exit 0",
+    "Storefront typecheck: npx tsc --noEmit (project/storefront) — exit 0",
+    "ESLint on all changed files — exit 0 (only pre-existing warnings)",
+    "Migration 030 applied to DB successfully"
+  ],
+  "timestamp": "2026-08-19T16:57:00Z"
+}
--- a/work/artifacts/F-071/reviewer.json
+++ b/work/artifacts/F-071/reviewer.json
@@ -0,0 +1,25 @@
+{
+  "feature_id": "F-071",
+  "agent": "reviewer",
+  "verdict": "APPROVED",
+  "summary": "F-071 adds emoji and color columns to categories_categories and wires them end-to-end: backend (domain, repository, API routes, migration), frontend (types, CategoriesGrid, categories page), storefront (types, categoria page), and admin (types, form, CategoryRow). Emoji and color are nullable so existing categories are unaffected; the UI falls back to the previous hardcoded maps when no stored value exists, ensuring backward compatibility.",
+  "evidence": [
+    "Migration 030_category_emoji_color.js adds emoji VARCHAR(10) NULL and color TEXT NULL to categories_categories — applied to DB successfully",
+    "Backend domain: emoji? string|null and color? string|null added to Category, NewCategory, CategoryPatch",
+    "Backend repository: emoji/color added to CategoryRow, INSERT, UPDATABLE array, and toCategory()",
+    "Backend routes: emoji (max 10) and color (max 200) added to newCategorySchema (zod) and serializeCategory() output",
+    "Frontend types/api.ts: emoji? and color? added to Category",
+    "Frontend CategoriesGrid: uses cat.emoji ?? icons[slug] ?? 📦 and cat.color ?? colors[i%colors.length]",
+    "Frontend categories/page.tsx: same fallback pattern, map callback converted to block body",
+    "Storefront: CategoryDto extended; categoria page renders emoji in h1",
+    "Admin types: Category extended with emoji? and color?",
+    "Admin categories page: FormState + EMPTY_FORM + form fields + openEdit + payload + CategoryRow all updated",
+    "API test: PATCH /categories/:id with {emoji, color} → HTTP 200, response includes emoji and color",
+    "API test: GET /categories/tree returns emoji/color fields (null for unconfigured)",
+    "API test: GET /admin/settings → HTTP 200 (500 issue was transient)",
+    "npx tsc --noEmit on all 4 projects — exit 0",
+    "npx eslint on all changed files — exit 0 (only pre-existing warnings)",
+    "./scripts/verify.sh — exit 0"
+  ],
+  "timestamp": "2026-08-19T16:55:00Z"
+}
--- a/work/artifacts/F-071/security.json
+++ b/work/artifacts/F-071/security.json
@@ -0,0 +1,18 @@
+{
+  "feature_id": "F-071",
+  "agent": "security",
+  "verdict": "APPROVED",
+  "summary": "Change adds two nullable TEXT columns (emoji VARCHAR(10), color TEXT) to an existing table and propagates them through type definitions. No new dependencies, no new endpoints, no auth changes, no env vars, no secrets. Input validation via zod (emoji max 10 chars, color max 200 chars). The color field stores Tailwind class strings — rendered via className which is safe against XSS (React does not interpret className as HTML). Admin form sends emoji/color via existing PATCH endpoint; no new attack surface.",
+  "evidence": [
+    "No new dependencies added to any package.json",
+    "No new API endpoints — only fields added to existing POST/PATCH/GET /categories routes",
+    "No auth/authz changes — existing admin role gate applies",
+    "No env vars introduced",
+    "Input validation: z.string().max(10) for emoji, z.string().max(200) for color (zod schema in newCategorySchema)",
+    "color field stores Tailwind class strings — rendered via React className (no dangerouslySetInnerHTML anywhere in new code)",
+    "emoji is stored as text — rendered as plain text node (no HTML injection)",
+    "Migration columns are nullable — no data exposure risk for existing rows",
+    "verify.sh exit 0"
+  ],
+  "timestamp": "2026-08-19T16:56:00Z"
+}
--- a/work/current.md
+++ b/work/current.md
@@ -1,8 +1,27 @@
 # Feature actual

-## Sin feature activa
+## Feature activa: F-071 — Editable emoji and color for categories

-Backlog: 138 features (138 done). Últimas features cerradas: **F-069** — Shipping method descriptions editable in admin, **F-070** — Show product attributes on frontend product detail page.
+Backlog: 139 features (138 done, 1 in_progress). Últimas features cerradas: **F-069** — Shipping method descriptions editable in admin, **F-070** — Show product attributes on frontend product detail page.
+
+### Problema
+Las categorías usan maps hardcoded de emoji/color en el frontend (CategoriesGrid, categories/page) que no se pueden personalizar desde el admin. Además, las nuevas categorías parent muestran 📁 en lugar de su emoji identificativo.
+
+### Solución
+Añadir campos `emoji` y `color` a la tabla `categories_categories` + tipos + formulario admin + usar los valores almacenados en el frontend en lugar de maps hardcoded.
+
+### Archivos clave
+- `project/migrations/030_category_emoji_color.js` (nueva)
+- `project/src/modules/categories/domain/category.ts`
+- `project/src/modules/categories/infrastructure/pg-category-repository.ts`
+- `project/src/modules/categories/api/categories.routes.ts`
+- `project/frontend/src/types/api.ts`
+- `project/frontend/src/components/home/CategoriesGrid.tsx`
+- `project/frontend/src/app/categories/page.tsx`
+- `project/apps/admin/src/types/index.ts`
+- `project/apps/admin/src/app/(dashboard)/categories/page.tsx`
+- `project/storefront/src/lib/api.ts`
+- `project/storefront/src/app/categoria/[slug]/page.tsx`

 ## Servicios productivos

--- a/work/runtime-status.json
+++ b/work/runtime-status.json
@@ -1,69 +1,13 @@
 {
-  "feature_id": "F-070",
+  "feature_id": "F-071",
  "stage": "close",
  "agent": "leader",
-  "action": "closing F-070: all gates approved",
+  "action": "closing F-071: all gates approved",
  "state": "running",
  "next_agent": "reviewer",
  "waiting_for": null,
-  "updated_at": "2026-08-19T16:20:47Z",
+  "updated_at": "2026-08-19T17:04:22Z",
  "timeline": [
-    {
-      "ts": "2026-08-19T14:47:25Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "regenerate cached thumbs"
-    },
-    {
-      "ts": "2026-08-19T14:53:28Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "center product image in column"
-    },
-    {
-      "ts": "2026-08-19T14:57:14Z",
-      "agent": "architect",
-      "stage": "design",
-      "state": "running",
-      "message": "design lexical integration"
-    },
-    {
-      "ts": "2026-08-19T14:57:18Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "install lexical and build editor"
-    },
-    {
-      "ts": "2026-08-19T15:06:45Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "fix product editor loop and selection"
-    },
-    {
-      "ts": "2026-08-19T15:07:47Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "add WYSIWYG to product description"
-    },
-    {
-      "ts": "2026-08-19T15:10:40Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "fix a11y missing id/name on search inputs"
-    },
-    {
-      "ts": "2026-08-19T15:19:51Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "fix image height attributes jsonb and serializeProduct"
-    },
    {
      "ts": "2026-08-19T15:26:08Z",
      "agent": "implementer",
@@ -147,6 +91,62 @@
      "stage": "close",
      "state": "running",
      "message": "closing F-070: all gates approved"
+    },
+    {
+      "ts": "2026-08-19T16:21:09Z",
+      "agent": "leader",
+      "stage": "close",
+      "state": "done",
+      "message": "F-070 closed and committed"
+    },
+    {
+      "ts": "2026-08-19T16:33:38Z",
+      "agent": "leader",
+      "stage": "intake",
+      "state": "running",
+      "message": "intake: F-071 selected as active feature"
+    },
+    {
+      "ts": "2026-08-19T16:33:59Z",
+      "agent": "architect",
+      "stage": "design",
+      "state": "running",
+      "message": "designing emoji+color category fields"
+    },
+    {
+      "ts": "2026-08-19T16:38:01Z",
+      "agent": "implementer",
+      "stage": "build",
+      "state": "running",
+      "message": "implementing emoji+color category fields"
+    },
+    {
+      "ts": "2026-08-19T16:54:23Z",
+      "agent": "reviewer",
+      "stage": "review_gate",
+      "state": "running",
+      "message": "reviewing emoji+color category implementation"
+    },
+    {
+      "ts": "2026-08-19T16:54:42Z",
+      "agent": "security",
+      "stage": "security_gate",
+      "state": "running",
+      "message": "security review"
+    },
+    {
+      "ts": "2026-08-19T16:54:57Z",
+      "agent": "qa",
+      "stage": "qa_gate",
+      "state": "running",
+      "message": "qa verification"
+    },
+    {
+      "ts": "2026-08-19T17:04:22Z",
+      "agent": "leader",
+      "stage": "close",
+      "state": "running",
+      "message": "closing F-071: all gates approved"
    }
  ],
  "last_updated": "2026-08-19T09:10:00Z",