feat(F-096): completed feature

backlog/features.json

@@ -4299,6 +4299,44 @@
         "close": true
       },
       "completed_at": "2026-08-20T20:05:54Z"
+    },
+    {
+      "id": "F-096",
+      "type": "feature",
+      "title": "Configure AI model and generate missing product SEO fields",
+      "problem": "Settings has no AI provider/model/API configuration or field-specific prompts. Product SEO fields therefore remain empty even when operators want missing SEO title and description generated automatically.",
+      "goal": "Add settings fields for an OpenAI-compatible AI provider, model, API key, and separate SEO title/description prompts. When a product is saved with an empty SEO field, generate that field with the configured model and prompt while preserving manually entered values.",
+      "scope_in": [
+        "settings",
+        "backend AI provider",
+        "product SEO generation",
+        "admin product editor"
+      ],
+      "scope_out": [
+        "No automatic overwrite of non-empty SEO values",
+        "no provider-specific SDK dependency"
+      ],
+      "priority": "high",
+      "risk": "med",
+      "description": "Problem: Settings has no AI provider/model/API configuration or field-specific prompts. Product SEO fields therefore remain empty even when operators want missing SEO title and description generated automatically.. Goal: Add settings fields for an OpenAI-compatible AI provider, model, API key, and separate SEO title/description prompts. When a product is saved with an empty SEO field, generate that field with the configured model and prompt while preserving manually entered values.. Scope IN: settings, backend AI provider, product SEO generation, admin product editor. Scope OUT: No automatic overwrite of non-empty SEO values, no provider-specific SDK dependency. Type: feature. Priority: high. Risk: med.",
+      "acceptance": [
+        "- Settings exposes provider/base URL/model/API key and separate SEO title/description prompts",
+        "- Settings values save and load through the admin settings API",
+        "- Empty SEO title/description can be generated with the configured model and field prompt",
+        "- Non-empty manually entered SEO fields are never overwritten",
+        "- Missing configuration returns a clear actionable error",
+        "- Secrets are not exposed in normal API responses",
+        "- Typecheck, tests, and verify.sh pass"
+      ],
+      "status": "done",
+      "created_at": "2026-08-20",
+      "gates": {
+        "reviewer": true,
+        "security": true,
+        "qa": true,
+        "close": true
+      },
+      "completed_at": "2026-08-20T20:12:01Z"
     }
   ]
 }

project/apps/admin/src/app/(dashboard)/settings/page.tsx

@@ -8,6 +8,7 @@ const TABS = [
   { id: 'general', label: 'General', icon: '⚙️' },
   { id: 'social', label: 'Redes sociales', icon: '🌐' },
   { id: 'footer', label: 'Footer', icon: '📄' },
+  { id: 'ai', label: 'IA para SEO', icon: '✨' },
 ] as const;
 type TabId = (typeof TABS)[number]['id'];
 
@@ -31,7 +32,8 @@ export default function SettingsPage() {
     if (!form) return;
     setSaving(true); setErr(''); setMsg('');
     try {
-      const updated = await settingsApi.update(form);
+      const { aiApiKey, ...settingsWithoutKey } = form;
+      const updated = await settingsApi.update(aiApiKey ? form : settingsWithoutKey);
       setData(updated); setForm(updated);
       setMsg('Cambios guardados correctamente');
       setTimeout(() => setMsg(''), 4000);
@@ -42,7 +44,7 @@ export default function SettingsPage() {
     }
   };
 
-  const field = (key: keyof FormData, label: string, opts?: { type?: string; placeholder?: string; rows?: number; hint?: string }) => (
+  const field = (key: Exclude<keyof FormData, 'aiApiKeyConfigured'>, label: string, opts?: { type?: string; placeholder?: string; rows?: number; hint?: string }) => (
     <div key={key}>
       <label className="block text-sm font-medium text-gray-700 mb-1">{label}</label>
       {opts?.rows ? (
@@ -129,6 +131,23 @@ export default function SettingsPage() {
               </>
             )}
 
+            {tab === 'ai' && (
+              <>
+                <div className="px-6 py-4 bg-gray-50 border-b border-gray-200">
+                  <h2 className="text-base font-semibold text-gray-800">Modelo de IA para SEO</h2>
+                  <p className="text-xs text-gray-400 mt-0.5">Se usa solo para completar campos SEO que estén vacíos.</p>
+                </div>
+                <div className="p-6 space-y-5">
+                  {field('aiProvider', 'Proveedor', { placeholder: 'OpenAI compatible' })}
+                  {field('aiBaseUrl', 'URL base de la API', { type: 'url', placeholder: 'https://api.openai.com/v1' })}
+                  {field('aiModel', 'Modelo', { placeholder: 'gpt-4o-mini' })}
+                  {field('aiApiKey', 'API key', { type: 'password', placeholder: form?.aiApiKeyConfigured ? 'API key configurada (escribe para reemplazar)' : 'sk-...' })}
+                  {field('aiSeoTitlePrompt', 'Prompt para Título SEO', { rows: 4, hint: 'Usa {{name}}, {{description}} y {{brand}} como variables.' })}
+                  {field('aiSeoDescriptionPrompt', 'Prompt para Descripción SEO (Google)', { rows: 5, hint: 'Usa {{name}}, {{description}} y {{brand}} como variables.' })}
+                </div>
+              </>
+            )}
+
             {tab === 'footer' && (
               <>
                 <div className="px-6 py-4 bg-gray-50 border-b border-gray-200">

project/apps/admin/src/features/products/components/ProductEditor.tsx

@@ -152,13 +152,22 @@ export function ProductEditor({ productId }: ProductEditorProps) {
         featured,
         attributes,
         state,
-        seoTitle: seoTitle || undefined,
-        seoDescription: seoDesc || undefined,
+        seoTitle: seoTitle.trim() || null,
+        seoDescription: seoDesc.trim() || null,
         expirationDate: expirationDate || undefined,
       };
       let saved: Product;
       if (isCreate) saved = await productsApi.create(payload);
       else saved = await productsApi.update(productId, payload);
+      if (!seoTitle.trim() || !seoDesc.trim()) {
+        try {
+          saved = await productsApi.generateSeo(saved.id);
+          setSeoTitle(saved.seoTitle ?? '');
+          setSeoDesc(saved.seoDescription ?? '');
+        } catch (generationError) {
+          setError(generationError instanceof Error ? generationError.message : 'No se pudieron generar los campos SEO');
+        }
+      }
       snapRef.current = getSnap();
       dirtyRef.current = false;
       setSuccess(isCreate ? '¡Producto creado!' : 'Cambios guardados');

project/apps/admin/src/lib/api-client.ts

@@ -80,6 +80,8 @@ export const productsApi = {
   create: (data: unknown) => api.post<import('@/types').Product>('/api/products', data),
   update: (id: string, data: unknown) =>
     api.patch<import('@/types').Product>(`/api/products/${id}`, data),
+  generateSeo: (id: string) =>
+    api.post<import('@/types').Product>(`/api/products/${id}/generate-seo`),
   setState: (id: string, state: 'active' | 'archived') =>
     api.patch(`/api/products/${id}/state`, { state }),
   delete: (id: string) => api.delete(`/api/products/${id}`),
@@ -325,6 +327,13 @@ export interface StoreSettings {
   footerText: string;
   facebookUrl: string;
   instagramUrl: string;
+  aiProvider: string;
+  aiBaseUrl: string;
+  aiModel: string;
+  aiApiKey: string;
+  aiApiKeyConfigured?: boolean;
+  aiSeoTitlePrompt: string;
+  aiSeoDescriptionPrompt: string;
 }
 
 export const settingsApi = {

project/src/modules/catalog/api/catalog.routes.ts

@@ -257,6 +257,43 @@ export async function registerCatalogRoutes(
     return reply.send(serializeProduct(product, productImages));
   });
 
+  app.post('/products/:id/generate-seo', async (request, reply) => {
+    const user = await deps.authenticate(request);
+    requireRole(user, 'admin');
+    const { id } = parseJson(idParamSchema, request.params);
+    const product = await repository.findById(id);
+    if (!product) throw new AppError(404, 'NOT_FOUND', 'Product not found');
+
+    const settingsResult = await deps.pool.query<{ key: string; value: string }>(
+      `SELECT key, value FROM store_settings WHERE key = ANY($1::text[])`,
+      [['ai_base_url', 'ai_model', 'ai_api_key', 'ai_seo_title_prompt', 'ai_seo_description_prompt']],
+    );
+    const settings = Object.fromEntries(settingsResult.rows.map((row) => [row.key, row.value]));
+    const baseUrl = settings.ai_base_url?.trim();
+    const model = settings.ai_model?.trim();
+    const apiKey = settings.ai_api_key?.trim();
+    if (!baseUrl || !model || !apiKey) {
+      throw new AppError(422, 'AI_NOT_CONFIGURED', 'Configura proveedor, URL base, modelo y API key en Ajustes → IA para SEO');
+    }
+
+    const replacements: Record<string, string> = {
+      name: product.name,
+      description: product.description ?? '',
+      brand: product.brand?.name ?? '',
+    };
+    const promptFor = (template: string | undefined, fallback: string) =>
+      (template || fallback).replace(/\{\{(name|description|brand)\}\}/g, (_, key: string) => replacements[key] ?? '');
+    const patch: { seoTitle?: string; seoDescription?: string } = {};
+    if (!product.seoTitle?.trim()) {
+      patch.seoTitle = (await generateWithModel(baseUrl, model, apiKey, promptFor(settings.ai_seo_title_prompt, 'Genera un título SEO breve para {{name}}. Devuelve solo el título.'))).slice(0, 200);
+    }
+    if (!product.seoDescription?.trim()) {
+      patch.seoDescription = (await generateWithModel(baseUrl, model, apiKey, promptFor(settings.ai_seo_description_prompt, 'Genera una meta descripción SEO en español para {{name}}. Devuelve solo la descripción.'))).slice(0, 500);
+    }
+    const updated = await repository.update(id, patch);
+    return reply.send(serializeProduct(updated ?? product));
+  });
+
   const searchSchema: FastifySchema = {
     tags: ['Catalog'],
     summary: 'Search products (público)',
@@ -635,6 +672,20 @@ function mapProductError(error: unknown): Error {
   return error instanceof Error ? error : new Error('Unknown product error');
 }
 
+async function generateWithModel(baseUrl: string, model: string, apiKey: string, prompt: string): Promise<string> {
+  const response = await fetch(`${baseUrl.replace(/\/$/, '')}/chat/completions`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }], temperature: 0.4 }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  const payload = await response.json().catch(() => null) as { choices?: Array<{ message?: { content?: unknown } }>; error?: { message?: string } } | null;
+  if (!response.ok) throw new AppError(502, 'AI_PROVIDER_ERROR', payload?.error?.message ?? `El proveedor IA respondió ${response.status}`);
+  const content = payload?.choices?.[0]?.message?.content;
+  if (typeof content !== 'string' || !content.trim()) throw new AppError(502, 'AI_EMPTY_RESPONSE', 'El modelo IA no devolvió contenido');
+  return content.trim();
+}
+
 function sanitizeSearchTelemetryQuery(query: string | undefined): string | undefined {
   if (query === undefined) {
     return undefined;

project/src/modules/store-settings/api/settings.routes.ts

@@ -21,6 +21,12 @@ const updateSettingsSchema = z.object({
   footerText: z.string().max(400).optional(),
   facebookUrl: z.string().url().optional().or(z.literal('')),
   instagramUrl: z.string().url().optional().or(z.literal('')),
+  aiProvider: z.string().max(80).optional(),
+  aiBaseUrl: z.string().url().optional().or(z.literal('')),
+  aiModel: z.string().max(120).optional(),
+  aiApiKey: z.string().max(500).optional(),
+  aiSeoTitlePrompt: z.string().max(2000).optional(),
+  aiSeoDescriptionPrompt: z.string().max(4000).optional(),
 });
 
 const SETTING_KEYS: Record<string, string> = {
@@ -32,6 +38,12 @@ const SETTING_KEYS: Record<string, string> = {
   footerText: 'footer_text',
   facebookUrl: 'facebook_url',
   instagramUrl: 'instagram_url',
+  aiProvider: 'ai_provider',
+  aiBaseUrl: 'ai_base_url',
+  aiModel: 'ai_model',
+  aiApiKey: 'ai_api_key',
+  aiSeoTitlePrompt: 'ai_seo_title_prompt',
+  aiSeoDescriptionPrompt: 'ai_seo_description_prompt',
 };
 
 export async function registerStoreSettingsRoutes(
@@ -63,6 +75,13 @@ export async function registerStoreSettingsRoutes(
       footerText: map['footer_text'] ?? '',
       facebookUrl: map['facebook_url'] ?? '',
       instagramUrl: map['instagram_url'] ?? '',
+      aiProvider: map['ai_provider'] ?? '',
+      aiBaseUrl: map['ai_base_url'] ?? '',
+      aiModel: map['ai_model'] ?? '',
+      aiApiKey: '',
+      aiApiKeyConfigured: Boolean(map['ai_api_key']),
+      aiSeoTitlePrompt: map['ai_seo_title_prompt'] ?? 'Genera un título SEO breve y atractivo para este producto: {{name}}. Devuelve solo el título.',
+      aiSeoDescriptionPrompt: map['ai_seo_description_prompt'] ?? 'Genera una meta descripción SEO en español, clara y persuasiva, para este producto: {{name}}. Devuelve solo la descripción.',
     });
   });
 
@@ -118,6 +137,13 @@ export async function registerStoreSettingsRoutes(
       footerText: map['footer_text'] ?? '',
       facebookUrl: map['facebook_url'] ?? '',
       instagramUrl: map['instagram_url'] ?? '',
+      aiProvider: map['ai_provider'] ?? '',
+      aiBaseUrl: map['ai_base_url'] ?? '',
+      aiModel: map['ai_model'] ?? '',
+      aiApiKey: '',
+      aiApiKeyConfigured: Boolean(map['ai_api_key']),
+      aiSeoTitlePrompt: map['ai_seo_title_prompt'] ?? 'Genera un título SEO breve y atractivo para este producto: {{name}}. Devuelve solo el título.',
+      aiSeoDescriptionPrompt: map['ai_seo_description_prompt'] ?? 'Genera una meta descripción SEO en español, clara y persuasiva, para este producto: {{name}}. Devuelve solo la descripción.',
     });
   });
 }

work/artifacts/F-096/implementer.md

@@ -0,0 +1,14 @@
+# F-096 — Implementer evidence
+
+## Changes
+
+- Added AI settings to admin Ajustes: provider, OpenAI-compatible base URL, model, API key, and separate SEO title/description prompts with `{{name}}`, `{{description}}`, and `{{brand}}` variables.
+- API keys are never returned by GET settings; only `aiApiKeyConfigured` is exposed.
+- Added authenticated `POST /products/:id/generate-seo`, which calls the configured chat-completions endpoint only for empty SEO fields and persists generated values.
+- ProductEditor calls generation after save when either SEO field is empty; manually entered values are preserved.
+
+## Validation
+
+- Root `npm run typecheck` → exit 0
+- Admin `npx tsc --noEmit` → exit 0
+- Admin ESLint on touched files → 0 errors (warnings only)

work/artifacts/F-096/leader-close.json

@@ -0,0 +1,15 @@
+{
+  "feature_id": "F-096",
+  "agent": "leader",
+  "verdict": "APPROVED",
+  "summary": "F-096 adds configurable OpenAI-compatible AI SEO generation for empty product SEO fields without overwriting manual values.",
+  "evidence": [
+    "reviewer.json verdict=APPROVED",
+    "security.json verdict=APPROVED",
+    "qa.json verdict=APPROVED",
+    "Backend and admin production builds exit 0",
+    "Root tests: 133 passed, 56 skipped",
+    "scripts/verify.sh exit 0"
+  ],
+  "timestamp": "2026-08-20T20:12:20Z"
+}

work/artifacts/F-096/qa.json

@@ -0,0 +1,15 @@
+{
+  "feature_id": "F-096",
+  "agent": "qa",
+  "verdict": "APPROVED",
+  "summary": "AI settings and empty SEO generation pass typechecks, builds, tests, and harness verification.",
+  "evidence": [
+    "Root npm run typecheck exit 0",
+    "Root npm run build exit 0",
+    "Admin npx tsc --noEmit exit 0",
+    "Admin npm run build exit 0",
+    "Root tests: 133 passed, 56 skipped",
+    "scripts/verify.sh exit 0"
+  ],
+  "timestamp": "2026-08-20T20:12:10Z"
+}

work/artifacts/F-096/reviewer.json

@@ -0,0 +1,13 @@
+{
+  "feature_id": "F-096",
+  "agent": "reviewer",
+  "verdict": "APPROVED",
+  "summary": "Settings expose the requested AI configuration and field-specific prompts; product SEO generation is explicit about filling only empty fields.",
+  "evidence": [
+    "Ajustes includes provider, base URL, model, API key, and separate SEO prompts",
+    "POST /products/:id/generate-seo checks each field independently before generation",
+    "ProductEditor invokes generation after save only when a field is empty",
+    "Manual SEO values are not overwritten"
+  ],
+  "timestamp": "2026-08-20T20:11:00Z"
+}

work/artifacts/F-096/security.json

@@ -0,0 +1,14 @@
+{
+  "feature_id": "F-096",
+  "agent": "security",
+  "verdict": "APPROVED",
+  "summary": "The AI key stays server-side and is omitted from settings responses; generation is admin-authenticated and only writes empty SEO fields.",
+  "evidence": [
+    "GET settings returns aiApiKey as empty and only exposes aiApiKeyConfigured",
+    "AI provider calls occur in the backend with the key in an Authorization header",
+    "Generation endpoint requires admin authentication",
+    "No client-side provider call or API key exposure",
+    "Generated output is length-bounded before persistence"
+  ],
+  "timestamp": "2026-08-20T20:11:20Z"
+}

work/current.md

@@ -1,14 +1,22 @@
 # Feature actual
 
-## Feature activa: F-095 (in_progress) — Download remote image URL before attaching product image
+## Feature activa: F-096 (in_progress) — Configure AI model and generate missing product SEO fields
 
-Backlog: 163 features (153 done, 9 pending, 1 in_progress).
+Backlog: 164 features (154 done, 9 pending, 1 in_progress).
 
 Últimas features cerradas: **F-080**, **F-081**, **F-082**, **F-083**, **F-084**, **F-085**, **F-086**, **F-087**.
 
 ## Incidencia actual (2026-08-20)
 
-Añadir una imagen por URL devuelve 400 porque el flujo hace un PATCH vacío del producto y adjunta directamente la URL remota. F-095 descargará la imagen validada a uploads locales antes de adjuntarla.
+Ajustes no permite configurar un modelo IA, API key ni prompts específicos para SEO. Los campos SEO vacíos no se generan automáticamente. F-096 añade la configuración y generación sin sobrescribir valores manuales.
+
+## Última incidencia resuelta (2026-08-20)
+
+F-095 cerrada con todos los gates aprobados. Las imágenes URL se descargan y almacenan en uploads locales antes de adjuntarse.
+
+## Incidencia anterior (2026-08-20)
+
+Añadir una imagen por URL devolvía 400 porque el flujo hacía un PATCH vacío del producto y adjuntaba directamente la URL remota.
 
 ## Última incidencia resuelta (2026-08-20)
 

work/runtime-status.json

@@ -1,69 +1,13 @@
 {
-  "feature_id": "F-095",
+  "feature_id": "F-096",
   "stage": "close",
   "agent": "leader",
-  "action": "Validate F-095 gates and close remote image importer",
+  "action": "Validate F-096 gates and close AI SEO generation",
   "state": "running",
   "next_agent": "leader",
   "waiting_for": "verify.sh green",
-  "updated_at": "2026-08-20T20:05:44Z",
+  "updated_at": "2026-08-20T20:11:50Z",
   "timeline": [
-    {
-      "ts": "2026-08-20T19:55:40Z",
-      "agent": "leader",
-      "stage": "intake",
-      "state": "running",
-      "message": "Triage inventory search limited to product name; add EAN matching"
-    },
-    {
-      "ts": "2026-08-20T19:55:51Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "Extend admin catalog list query with partial EAN matching and update inventory search label"
-    },
-    {
-      "ts": "2026-08-20T19:57:04Z",
-      "agent": "reviewer",
-      "stage": "review_gate",
-      "state": "running",
-      "message": "Review inventory EAN/name search query and UI label"
-    },
-    {
-      "ts": "2026-08-20T19:57:14Z",
-      "agent": "security",
-      "stage": "security_gate",
-      "state": "running",
-      "message": "Check EAN search query parameterization and scope"
-    },
-    {
-      "ts": "2026-08-20T19:57:23Z",
-      "agent": "qa",
-      "stage": "qa_gate",
-      "state": "running",
-      "message": "Run inventory search checks and verify"
-    },
-    {
-      "ts": "2026-08-20T19:57:34Z",
-      "agent": "leader",
-      "stage": "close",
-      "state": "running",
-      "message": "Validate F-093 gates and close inventory EAN/name search"
-    },
-    {
-      "ts": "2026-08-20T19:58:08Z",
-      "agent": "leader",
-      "stage": "close",
-      "state": "done",
-      "message": "F-093 cerrado: búsqueda de Inventario por EAN o nombre"
-    },
-    {
-      "ts": "2026-08-20T19:58:26Z",
-      "agent": "leader",
-      "stage": "intake",
-      "state": "running",
-      "message": "Triage missing variant creation UI and explanation in Publish tab"
-    },
     {
       "ts": "2026-08-20T19:58:57Z",
       "agent": "implementer",
@@ -147,6 +91,62 @@
       "stage": "close",
       "state": "running",
       "message": "Validate F-095 gates and close remote image importer"
+    },
+    {
+      "ts": "2026-08-20T20:06:13Z",
+      "agent": "leader",
+      "stage": "close",
+      "state": "done",
+      "message": "F-095 cerrado: imágenes URL descargadas y almacenadas localmente"
+    },
+    {
+      "ts": "2026-08-20T20:07:05Z",
+      "agent": "leader",
+      "stage": "close",
+      "state": "done",
+      "message": "F-095 cerrado: importación de imágenes URL con descarga segura"
+    },
+    {
+      "ts": "2026-08-20T20:07:19Z",
+      "agent": "leader",
+      "stage": "intake",
+      "state": "running",
+      "message": "Triage AI configuration fields and generation of empty product SEO fields"
+    },
+    {
+      "ts": "2026-08-20T20:07:49Z",
+      "agent": "implementer",
+      "stage": "build",
+      "state": "running",
+      "message": "Add AI settings, OpenAI-compatible SEO generation endpoint, and empty-field product editor trigger"
+    },
+    {
+      "ts": "2026-08-20T20:10:53Z",
+      "agent": "reviewer",
+      "stage": "review_gate",
+      "state": "running",
+      "message": "Review AI settings, empty SEO generation, and manual-value preservation"
+    },
+    {
+      "ts": "2026-08-20T20:11:07Z",
+      "agent": "security",
+      "stage": "security_gate",
+      "state": "running",
+      "message": "Check AI key handling, provider calls, prompt scope, and response exposure"
+    },
+    {
+      "ts": "2026-08-20T20:11:20Z",
+      "agent": "qa",
+      "stage": "qa_gate",
+      "state": "running",
+      "message": "Run AI settings/product SEO typechecks, tests, build, and verify"
+    },
+    {
+      "ts": "2026-08-20T20:11:50Z",
+      "agent": "leader",
+      "stage": "close",
+      "state": "running",
+      "message": "Validate F-096 gates and close AI SEO generation"
     }
   ]
 }