109 lines
5.9 KiB
Markdown
109 lines
5.9 KiB
Markdown
# F-136 — Design: Brand names Title Case + SEO title auto-fill
|
|
|
|
**Author:** architect
|
|
**Date:** 2026-08-21
|
|
**Stage:** design
|
|
|
|
## Context (problem)
|
|
|
|
- DB inspection (`SELECT name FROM brands_brands`) shows 28 of 33 brands have ALL-CAPS names imported from OpenCart (e.g. `A.VOGEL`, `BIOCOP`, `COMPLEMENTOS Y NUTRICIÓN`, `EL GRANERO INTEGRAL`).
|
|
- The same 28 brands have `seo_title IS NULL OR ''` because the legacy seed script never set it.
|
|
- The admin `brands/page.tsx` form already auto-fills `seo_title` from `name` on create via `handleNameChange`, so **new brands get it right**. The problem is purely with the existing imported data.
|
|
- Operator's two-part request:
|
|
1. "poner las marcas en formato 'capital case'" → Title Case the existing names.
|
|
2. "SEO title igual al nombre de la marca" → for new brands the auto-fill already handles this; for existing brands we need to backfill.
|
|
|
|
## Constraints
|
|
|
|
- C-1. Pure data fix: no API changes, no UI behavior changes, no new endpoints.
|
|
- C-2. The migration must be **idempotent** — safe to re-run after partial application (the orchestre may apply it more than once if a feature is reopened).
|
|
- C-3. Slugs (`a-vogel`, `biocop`) are derived from `slugify()` which lowercases everything; they don't need updating.
|
|
- C-4. The Title Case function must:
|
|
- Preserve dots, hyphens, ampersands as word boundaries (`A.VOGEL` → `A.Vogel`, not `A.vogel`).
|
|
- Handle Spanish accented characters (`NUTRICIÓN` → `Nutrición`).
|
|
- Handle multi-word names (`EL GRANERO INTEGRAL` → `El Granero Integral`).
|
|
- Leave already-correct names untouched (idempotency for re-runs).
|
|
- C-5. We do NOT want to lowercase Spanish articles/prepositions like `y`, `e`, `o`, `de`, `la`, `el` — for brand names, the standard is to capitalize every word (`El Granero Integral`, not `El Granero integral`). Keeping it simple.
|
|
|
|
## Design
|
|
|
|
### Decision: shared helper + data migration
|
|
|
|
Two deliverables:
|
|
|
|
1. **`project/src/shared/text.ts`** — new pure helper `toTitleCase(input: string): string` that handles dot/hyphen/space/ampersand word boundaries. Unit-tested in `project/src/shared/tests/text.test.ts`.
|
|
- Lives in `shared/` because it's pure (no DB / no HTTP) and could be reused by categories/products later if the operator requests it.
|
|
|
|
2. **`project/migrations/042_brand_title_case.js`** — node-pg-migrate data migration:
|
|
- Selects all rows from `brands_brands`.
|
|
- For each row, computes `titleCased = toTitleCase(name)`.
|
|
- Updates the row IFF `titleCased !== name` OR `seo_title IS NULL OR seo_title = ''`.
|
|
- When updating: `name = titleCased`, `seo_title = (existing || titleCased)`, `updated_at = NOW()`.
|
|
|
|
### Helper signature
|
|
|
|
```ts
|
|
/**
|
|
* Convert an ALL-CAPS brand/category name to Title Case.
|
|
* Splits on word boundaries (space, hyphen, dot, ampersand, slash)
|
|
* and uppercases the first letter of each word, lowercasing the rest.
|
|
*
|
|
* Examples:
|
|
* toTitleCase('A.VOGEL') // 'A.Vogel'
|
|
* toTitleCase('BIOCOP') // 'Biocop'
|
|
* toTitleCase('EL GRANERO INTEGRAL') // 'El Granero Integral'
|
|
* toTitleCase('COMPLEMENTOS Y NUTRICIÓN') // 'Complementos y Nutrición'
|
|
* toTitleCase('DULCES LISSEN') // 'Dulces Lissen'
|
|
* toTitleCase('La Finestra Sul Cielo') // 'La Finestra Sul Cielo' (unchanged)
|
|
* toTitleCase('') // ''
|
|
*/
|
|
export function toTitleCase(input: string): string;
|
|
```
|
|
|
|
### Idempotency
|
|
|
|
Re-running the migration is a no-op because:
|
|
- For ALL-CAPS rows that were already converted, `toTitleCase(name) === name` (case-insensitive split produces the same word capitalizations), so the `UPDATE` never fires.
|
|
- For rows where `seo_title` was already set, the CASE expression preserves it.
|
|
|
|
We add a `whereNeedsUpdate` check so we don't bump `updated_at` unnecessarily.
|
|
|
|
### Test cases for the helper (vitest)
|
|
|
|
1. Empty string → empty string.
|
|
2. Single word all caps → title case.
|
|
3. Multi-word with spaces → each word capitalized.
|
|
4. Names with dots (`A.VOGEL`) → dots preserved as boundaries.
|
|
5. Names with hyphens (`DAS-BROT`) → hyphen preserved, both sides capitalized.
|
|
6. Names with `&` (`TEA & INFUSIONS`) → `&` preserved.
|
|
7. Spanish accents (`NUTRICIÓN`) → `Nutrición` (correct NFD handling).
|
|
8. Already Title Case (`La Finestra Sul Cielo`) → unchanged (idempotency).
|
|
9. Mixed case (`BioSana`) → unchanged.
|
|
10. Numbers (`500 Kilos`) → `500 Kilos` (digits unaffected).
|
|
|
|
### Files affected
|
|
|
|
| File | Change |
|
|
|---|---|
|
|
| `project/src/shared/text.ts` | NEW — `toTitleCase()` helper |
|
|
| `project/src/shared/tests/text.test.ts` | NEW — vitest unit tests |
|
|
| `project/migrations/042_brand_title_case.js` | NEW — data migration |
|
|
|
|
### Out of scope
|
|
|
|
- Frontend changes. The auto-fill in `brands/page.tsx` already works for new brands.
|
|
- Categories: the operator asked about brands specifically. F-116 already fixed categories (see `LEGACY_TRANSLATIONS` in `legacy-catalog.ts`). If the operator later asks, the same `toTitleCase` helper can be reused in a future migration.
|
|
- Slug changes: slugs are already lowercase; they don't depend on name case.
|
|
|
|
## Acceptance criteria
|
|
|
|
- AC-1. `npm test -- text.test.ts` passes with all 10 test cases.
|
|
- AC-2. `node-pg-migrate up` applies migration 042 without errors.
|
|
- AC-3. After migration: `SELECT name FROM brands_brands` shows all 33 names in Title Case (or unchanged if already correct). No ALL-CAPS remain.
|
|
- AC-4. After migration: `SELECT COUNT(*) FROM brands_brands WHERE seo_title IS NULL OR seo_title = ''` returns 0.
|
|
- AC-5. Re-running the migration (`node-pg-migrate up` again) is a no-op: 0 rows updated, no errors.
|
|
- AC-6. Slugs unchanged (still lowercase). Verify with `SELECT slug FROM brands_brands ORDER BY name LIMIT 5`.
|
|
- AC-7. The frontend admin form still works: creating a new brand with name "TestBrand" sets `seo_title` to "TestBrand" automatically.
|
|
- AC-8. Backend typecheck + admin typecheck + lint green.
|
|
- AC-9. `verify.sh` exit 0.
|