[TASK] Deuda técnica del admin de categorías (#246): separar proyección pública/interna, ISP en el puerto y regla de dominio fuera del controller

[vgpastor]

Parte de la épica #228. Deuda detectada al revisar #246 (que cerró #221 y quedó mergeada en main). No bloquea; refactor de calidad (DDD/SOLID) sobre código ya en producción.

Contexto

El CRUD admin de categorías entró vía #246. La review dejó varios puntos de DDD/Clean Code que se mergearon sin resolver. Este issue los agrupa para saldarlos en un refactor acotado, sin cambiar comportamiento observable (salvo el punto 1, que es una decisión de exposición pública).

Puntos

1. La proyección pública filtra campos internos

CategoryDefinition (que sirve GET /categories público) carga kind, archivedAt y codePrefix, y el DTO público CategoryDto expone kind. Contradice el contrato documentado en category-definition.ts (introducido en #245): "proyección PÚBLICA… no debe crecer con datos de gestión interna".

• Propuesta: modelo interno propio (p. ej. CategoryRecord con archivedAt/kind/codePrefix) para la API admin, dejando CategoryDefinition como proyección pública mínima. Decidir explícitamente si kind debe ser público (si sí, documentarlo en el contrato; si no, quitarlo del GET /categories).
• Archivos: supplies/domain/category-definition.ts, infrastructure/http/category-response.dto.ts, categories.controller.ts.

2. El puerto CategoryRepository no respeta ISP

Un único CategoryRepository mezcla lectura pública (listCategories) con escritura/gestión admin (findBySlug con includeArchived, createCategory, updateCategory).

• Propuesta: separar en puerto de lectura pública + puerto admin (escritura + lectura con archivadas), como sugería la review. Un mismo adaptador Drizzle puede implementar ambos.
• Archivos: supplies/domain/ports/category.repository.ts, infrastructure/drizzle/drizzle-category.repository.ts.

3. Regla de dominio y mapeo de error en el controller

CategoriesAdminController.delete() hace isCoreCategory(slug) y lanza BadRequestException directamente, mientras el resto de invariantes se lanzan como errores de dominio desde los casos de uso. Manejo de errores inconsistente (parte en filtro, parte inline en el controller).

• Propuesta: mover la protección de slug núcleo al caso de uso (error de dominio CategoryProtectedError o equivalente) y mapear todos los errores de categoría en el SuppliesDomainExceptionFilter global (o un filtro de categorías), quitando el throw HTTP del controller.
• Archivos: infrastructure/http/categories-admin.controller.ts, application/*category*.ts, infrastructure/http/supplies-domain-exception.filter.ts.

Criterios de aceptación

• GET /categories público no expone campos de gestión interna (o kind queda documentado como público a propósito).
• Lectura pública y escritura/gestión admin viven en puertos separados (ISP).
• Ninguna regla de dominio ni HttpException se lanza desde el controller admin; los errores de categoría se mapean en el filtro.
• Sin cambios en los criterios funcionales de [FEATURE] Admin CRUD de categorias y subcategorias (jerarquia, orden, i18n, slugs nucleo protegidos) #221; suite verde + pnpm gen:api si cambian DTOs.

Referencias

Review con el detalle: PR #246 (comentarios de review). Contrato público/interno: #245. Feature original: #221.

[vgpastor]

PR #329 aborda el punto 3 (regla de slug núcleo fuera del controller → CategoryProtectedError/409 vía filtro) y arregla de paso una regresión latente: PATCH/DELETE de una categoría inexistente devolvía 500 en vez de 404 (había dos clases CategoryNotFoundError, una en domain/supply-errors y otra en application/category-admin.errors; el filtro solo capturaba la primera).

Quedan abiertos los puntos 1 y 2, y con un matiz descubierto al implementar: CategoryRepository.findBySlug lo usan también create-supply/edit-supply para validar la categoría, así que la separación ISP correcta es reads vs writes (no solo público vs admin) y toca otros casos de uso de supplies + el modelo interno (archivedAt fuera de CategoryDefinition). Es un cambio transversal; conviene abordarlo aparte y con cuidado. Dejo el issue abierto para eso.

---

Generated by Claude Code