@tacuchi/agent-workflow-cli 6.2.0 → 7.0.0

package/skills/agent-workflow/standards/coding-standards/references/java-spring.md

@@ -0,0 +1,244 @@
+# Java / Spring Boot — Convenciones detalladas
+
+## Inyección de dependencias
+
+Usar Constructor Injection. Nunca Field Injection en código de producción.
+
+```java
+// Correcto: Constructor Injection
+@Service
+@RequiredArgsConstructor
+public class NotificacionService {
+    private final EmailProvider emailProvider;
+    private final NotificacionRepository repository;
+}
+
+// Incorrecto: Field Injection
+@Service
+public class NotificacionService {
+    @Autowired  // NO en producción
+    private EmailProvider emailProvider;
+}
+```
+
+## DTOs con Java Records
+
+Usar records para Request y Response. Clases tradicionales para entidades JPA.
+
+```java
+// Request DTO — record
+public record NotificacionRequest(
+    @NotBlank String destinatario,
+    @NotBlank String asunto,
+    @NotNull String templateId,
+    Map<String, Object> variables
+) {}
+
+// Response DTO — record
+public record NotificacionResponse(
+    Long id,
+    String destinatario,
+    String estado,
+    LocalDateTime fechaEnvio
+) {}
+
+// Entidad JPA — clase (NO record)
+@Entity
+@Table(name = "notificaciones")
+public class Notificacion {
+    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+    private String destinatario;
+    private String estado;
+    // getters, setters
+}
+```
+
+## Transacciones
+
+```java
+// Lectura — readOnly para optimización
+@Transactional(readOnly = true)
+public NotificacionResponse buscarPorId(Long id) { ... }
+
+// Escritura
+@Transactional
+public NotificacionResponse enviar(NotificacionRequest request) { ... }
+```
+
+## Validación con Jakarta
+
+```java
+@PostMapping("/notificaciones")
+public ResponseEntity<NotificacionResponse> enviar(
+        @Valid @RequestBody NotificacionRequest request) {
+    return ResponseEntity.ok(service.enviar(request));
+}
+```
+
+## PATCH + Sparse DTO unificado (qtc-dev v2.6+)
+
+Para mantenimientos CRUD seguir las reglas de `references/fe-be-integration.md`:
+
+- **DTO único** `<Feature>SaveRequest` para POST y PATCH, todos los campos nullable.
+- **POST** acepta el DTO con required cargados; **PATCH** acepta el DTO con solo los campos modificados (null = no tocar).
+- Validation groups (`OnCreate.class`) cuando se necesita exigir `@NotNull` solo en POST.
+
+```java
+public record CategoriaSaveRequest(
+    @Size(min = 1, max = 100)
+    @NotNull(groups = OnCreate.class)
+    String nombre,
+    @Size(max = 500) String descripcion,
+    @NotNull(groups = OnCreate.class) Boolean activo,
+    @PositiveOrZero Integer ordenVisual
+) {}
+
+@RestController
+@RequestMapping("/api/categorias")
+@RequiredArgsConstructor
+public class CategoriasController {
+    private final CategoriasService service;
+
+    @PostMapping
+    public ResponseEntity<CategoriaResponse> create(
+        @Validated(OnCreate.class) @RequestBody CategoriaSaveRequest req
+    ) { return ResponseEntity.ok(service.create(req)); }
+
+    @PatchMapping("/{id}")
+    public ResponseEntity<CategoriaResponse> patch(
+        @PathVariable Long id,
+        @Valid @RequestBody CategoriaSaveRequest req
+    ) { return ResponseEntity.ok(service.patch(id, req)); }
+}
+```
+
+En el service, el método `patch` ignora campos `null`:
+
+```java
+@Transactional
+public CategoriaResponse patch(Long id, CategoriaSaveRequest req) {
+    Categoria entity = repo.findById(id).orElseThrow(NotFoundException::new);
+    if (req.nombre() != null) entity.setNombre(req.nombre());
+    if (req.descripcion() != null) entity.setDescripcion(req.descripcion());
+    if (req.activo() != null) entity.setActivo(req.activo());
+    if (req.ordenVisual() != null) entity.setOrdenVisual(req.ordenVisual());
+    return mapper.toResponse(repo.save(entity));
+}
+```
+
+Tradeoff aceptado: no se puede setear un campo a `null` intencionalmente (semántica "no tocar"). Para "limpiar a null", usar endpoint dedicado o flag explícita en el DTO. Detalles + ejemplos completos: `references/fe-be-integration.md`.
+
+## Fail fast / Early returns
+
+```java
+public NotificacionResponse enviar(NotificacionRequest request) {
+    if (request.destinatario().isBlank()) {
+        throw new BadRequestException("Destinatario requerido");
+    }
+
+    var template = templateRepository.findById(request.templateId())
+        .orElseThrow(() -> new NotFoundException("Template no encontrado"));
+
+    // Lógica principal después de validaciones
+    return procesarEnvio(request, template);
+}
+```
+
+## Manejo de errores
+
+```java
+@RestControllerAdvice
+public class ControllerExceptionHandler {
+
+    @ExceptionHandler(BadRequestException.class)
+    public ResponseEntity<ErrorResponse> handleBadRequest(BadRequestException ex) {
+        log.warn("Bad request: {}", ex.getMessage());
+        return ResponseEntity.badRequest()
+            .body(new ErrorResponse(ex.getMessage()));
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ErrorResponse> handleGeneral(Exception ex) {
+        log.error("Error inesperado", ex);
+        return ResponseEntity.internalServerError()
+            .body(new ErrorResponse("Error interno del servidor"));
+    }
+}
+```
+
+## Estructura de proyecto
+
+Ver `references/project-structure.md` para la estructura completa de paquetes, entidades, repositories, services, wrappers request/response y convención de DTOs del tu ecosistema.
+
+## Queries SQL
+
+- Siempre parametrizar (nunca concatenar strings)
+- Usar `@Query` con parámetros nombrados o JPA Criteria
+- En native queries, siempre schema explícito: `esq_xxx.tb_xxx`
+- Documentar queries complejas en CONSULTASSQL.md de la sesión
+
+```java
+// Correcto
+@Query("SELECT n FROM Notificacion n WHERE n.destinatario = :email")
+List<Notificacion> findByDestinatario(@Param("email") String email);
+
+// Incorrecto — SQL injection
+@Query("SELECT n FROM Notificacion n WHERE n.destinatario = '" + email + "'")
+```
+
+Ver `references/database-conventions.md` para nomenclatura de tablas, columnas, sequences, funciones y el patrón maestra-detalle.
+
+## Build y verificación
+
+- Compilar: `./mvnw compile` (Windows: `mvnw.cmd compile`)
+- Tests: `./mvnw test`
+- Verificación completa: `./mvnw verify`
+- Nunca usar `mvn` directo — siempre el wrapper del proyecto
+
+## Patrones de sincronización single-slot
+
+Patrones al sincronizar relaciones donde la BD admite N filas pero la UX expone 1 seleccionada. Para la decisión de diseño UX (por qué single-slot), ver skill `frontend-design` (§1).
+
+### Reemplazo preservando fila coincidente
+
+Al guardar con single-slot, **no** "borrar todo e insertar uno" (genera churn en auditoría y consume secuencias innecesariamente). Recorrer las filas existentes, preservar la que coincide con el valor nuevo y eliminar las demás:
+
+```java
+List<EntidadRelacion> existentes = repository.findByIdMaestro(maestro.getIdMaestro());
+boolean coincide = false;
+for (EntidadRelacion e : existentes) {
+    if (!coincide && idValorNuevo.equals(e.getIdValor())) {
+        coincide = true;                 // preservar UNA fila que coincide
+    } else {
+        repository.delete(e);            // eliminar sobrantes o cambios
+    }
+}
+if (!coincide) {
+    // crear fila nueva con estado=1, fecha_registro, usuario_registro
+}
+```
+
+### Fallback cross-tabla en GET con autoritativa única
+
+Cuando un campo vive en dos tablas por historia (p. ej. `usuario.celular` y `cliente.celular`), declarar **una tabla autoritativa** y aplicar fallback silencioso a la otra **sólo en el GET**. El UPDATE toca únicamente la autoritativa:
+
+```java
+if (dto.getCelular() == null || dto.getCelular().isBlank()) {
+    clienteRepository.findByIdPersona(entidad.getIdPersona())
+        .ifPresent(c -> dto.setCelular(c.getCelular()));
+}
+```
+
+Regla: no replicar esta lógica en el frontend; la resolución vive en el GET del backend. Evitar asumir que un campo "personal" vive en la tabla de personas sin verificar — a veces la autoritativa es la tabla de negocio.
+
+### Filtros `estado=1` en query, no en frontend
+
+Queries de catálogo (roles asignables, negocios, sucursales, etc.) filtran activos en la query nativa / JPA. El frontend recibe sólo activos y **no debe re-filtrar**:
+
+```java
+@Query("SELECT r FROM Rol r WHERE r.estado = 1 ORDER BY r.nombre")
+List<Rol> findAsignables();
+```
+
+Si el frontend termina filtrando de nuevo, es indicio de que la query está mal — corregir la query, no el frontend.

package/skills/agent-workflow/standards/coding-standards/references/project-structure.md

@@ -0,0 +1,197 @@
+# Estructura de Proyecto Backend
+
+Convenciones de estructura para microservicios Spring Boot del tu ecosistema.
+
+## Paquete base
+
+`com.qtc.[dominio]` → `com.qtc.credito`, `com.qtc.mantenimiento`, `com.qtc.solicitud`
+
+## Estructura de paquetes
+
+Dos variantes en uso (ambas válidas, seguir la del proyecto actual):
+
+```
+com.qtc.[dominio].core.controller
+com.qtc.[dominio].core.service
+com.qtc.[dominio].core.service.impl
+com.qtc.[dominio].core.service.generico
+com.qtc.[dominio].core.repository
+com.qtc.[dominio].core.model
+com.qtc.[dominio].core.request
+com.qtc.[dominio].core.request.dto
+com.qtc.[dominio].core.response
+com.qtc.[dominio].core.response.dto
+com.qtc.[dominio].core.config
+com.qtc.[dominio].core.exception
+com.qtc.[dominio].core.common
+com.qtc.[dominio].core.util
+com.qtc.[dominio].core.feign
+com.qtc.[dominio].core.seguridad
+com.qtc.[dominio].core.aspect
+com.qtc.[dominio].core.advice
+```
+
+Variante sin `core`:
+```
+com.qtc.[dominio].controller
+com.qtc.[dominio].service / service.impl
+com.qtc.[dominio].repository
+com.qtc.[dominio].model
+com.qtc.[dominio].dto.request / dto.response
+```
+
+## Flujo de capas
+
+```
+Controller → Service (interface) → ServiceImpl → Repository → Entity/BD
+```
+
+## Entidades JPA
+
+Nombre = tabla sin `tb_` en PascalCase: `tb_credito` → `Credito`, `tb_cliente` → `Cliente`
+
+```java
+@Entity
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "tb_credito", schema = "esq_credito")
+@Getter
+@Setter
+public class Credito extends Auditoria implements Serializable {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "seq_tb_credito")
+    @SequenceGenerator(name = "seq_tb_credito", sequenceName = "seq_tb_credito",
+            schema = "esq_credito", allocationSize = 1)
+    @Column(name = "id_credito")
+    private Long idCredito;
+}
+```
+
+Reglas:
+- Siempre `schema` explícito en `@Table` y `@SequenceGenerator`
+- Extender `Auditoria` para campos de auditoría
+- `@Getter @Setter` (no `@Data`) en entities
+- `@Column(name = "...")` con el nombre exacto de la columna en BD
+- Stored procedures: `@NamedStoredProcedureQuery` en la entidad que las invoca
+
+## Clase base Auditoria
+
+`@MappedSuperclass` que provee 5 campos estándar:
+
+```java
+@MappedSuperclass
+@Data
+public abstract class Auditoria {
+    @Column(nullable = false, name = "ESTADO")
+    protected Integer estado;
+
+    @Column(nullable = false, updatable = false, name = "USUARIO_REGISTRO")
+    protected String usuarioRegistro;
+
+    @Column(nullable = false, updatable = false, name = "FECHA_REGISTRO")
+    protected Date fechaRegistro;
+
+    @Column(insertable = false, name = "USUARIO_MODIFICACION")
+    protected String usuarioModificacion;
+
+    @Column(insertable = false, name = "FECHA_MODIFICACION")
+    protected Date fechaModificacion;
+}
+```
+
+Al insertar: llamar `setCampoSegIns(usuario, fecha)`.
+Al actualizar: llamar `setCampoSegUpd(estado, usuario, fecha)`.
+
+## Repositories
+
+```java
+@Repository
+public interface CreditoRepository extends JpaRepository<Credito, Long> {
+
+    // JPQL
+    @Query("SELECT c FROM Credito c WHERE c.solicitud.idSolicitud = :id")
+    List<Credito> obtenerPorSolicitud(@Param("id") Long id);
+
+    // Native query con schema explícito
+    @Query(value = "SELECT ... FROM esq_credito.tb_credito c "
+            + "INNER JOIN esq_seguridad.tb_persona p ON ...",
+            nativeQuery = true)
+    List<PCreditoDTO> obtenerPorDocumento(@Param("doc") String doc);
+
+    // Stored procedure
+    @Procedure(name = "credito.generaCredito")
+    Integer generaCredito(@Param("var_usuario") String usuario);
+}
+```
+
+Native queries siempre con `esq_xxx.tb_xxx` (schema explícito).
+
+## Services
+
+```java
+// Interface
+public interface CreditoService {
+    RespBase<ResponseDTO> generaCredito(ReqBase<ReqCredito> request, String usuario);
+}
+
+// Implementación
+@AllArgsConstructor
+@Service
+public class CreditoServiceImpl implements CreditoService {
+    private static final Logger LOGGER = LoggerFactory.getLogger(CreditoServiceImpl.class);
+    private final CreditoRepository creditoRepository;
+    private final ClienteRepository clienteRepository;
+
+    @Transactional
+    @Override
+    public RespBase<ResponseDTO> generaCredito(ReqBase<ReqCredito> request, String usuario) {
+        // ...
+    }
+}
+```
+
+Reglas:
+- Constructor injection vía `@AllArgsConstructor` (no `@Autowired`)
+- `@Transactional` en métodos de escritura
+- Logger SLF4J estático por clase
+- Siempre interface + impl
+
+## Wrappers Request/Response
+
+### Request
+```java
+public class ReqBase<T> {
+    private Trace trace;       // traceId para trazabilidad
+    @NotNull @Valid
+    private T payload;
+}
+```
+
+### Response
+```java
+public class RespBase<T> {
+    private Trace trace;
+    private Status status;     // success + error (code, httpCode, messages)
+    private T payload;
+}
+```
+
+Uso: `return new RespBase<ResponseDTO>().ok(payload);`
+Error: `return new RespBase<>().error(response, false, "mensaje");`
+
+## Convención de DTOs
+
+- **`Req` prefix** → Request DTOs: `ReqCredito`, `ReqSituacion` (clases con `@Data`)
+- **`P` prefix** → Projection interfaces para native queries: `PCreditoDTO`, `PClienteDTO`
+- **`R` prefix** → Response DTOs mapeados: `RCreditoDTO`, `RCronogramaDTO` (clases con mapper)
+- **`ResponseDTO`** → DTO genérico con id, data y mensaje
+
+## Comunicación entre microservicios
+
+- Feign clients en paquete `feign`
+- Paquete `seguridad` para interceptors de autenticación
+
+## Build
+
+Maven wrapper: `./mvnw` (Linux) o `mvnw.cmd` (Windows). Nunca `mvn` global.

package/skills/agent-workflow/standards/frontend-design/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: frontend-design
+description: "Principios de diseño UX para interfaces CRUD agnósticos al framework (HTML/CSS/UX, sin código Angular/React/Vue). Cubre formularios, listados, modales, navegación y feedback. Reglas de reutilización shared/ y framework-first CSS. Activar al diseñar o implementar mantenimientos CRUD. Para código del stack consultar coding-standards. Referencia transversal sin dependencia de sesiones."
+version: 0.2.0
+---
+
+# Frontend Design
+
+Principios de diseño UX para interfaces CRUD de mantenimiento: formularios, listados, modales, navegación y feedback. Contenido **agnóstico a framework** — sólo principios HTML/CSS/UX, sin código Angular/React/Vue. Para el código específico del stack, ver `coding-standards/references/<stack>.md`.
+
+## Qué cubre
+
+Cinco `references/*.md`, cada uno prescriptivo (qué sí hacer) con un checklist de replicación al final:
+
+- **`references/form-patterns.md`** — formularios editar/nuevo. Modelo mental single-slot, layout de 4 cards por dominio, readonly con candado, combos dependientes con hints, switch vs checkbox, campo opcional con switch que colapsa, estado vs bloqueado, placeholders con formato. Incluye los dos principios transversales de reutilización (`shared/`) y framework-first CSS (~90/10).
+
+- **`references/list-patterns.md`** — vistas de listado. Estructura header + filter card + data-table + pagination, acciones por fila (iconos + tooltips), empty states, loading global, badges de estado. FormBuilder reactivo preferido sobre `ngModel` directo.
+
+- **`references/modal-patterns.md`** — diálogos. Cuándo modal vs vista dedicada, layout (header/body/footer), tamaños categóricos (sm/md/lg), formularios dentro del modal, footer con cancelar + primario + loading state, convención de payload `{ saved: true, data }`, confirmación destructiva. NgbModal recomendado; MatDialog es legado.
+
+- **`references/navigation-patterns.md`** — layout de app admin. Sidebar colapsable desde catálogo dinámico, toolbar con contexto (sucursal/usuario/logout), page header con título + descripción + acción primaria, tabs con routing, breadcrumbs, back navigation, lazy loading por módulo.
+
+- **`references/feedback-toasts-patterns.md`** — toasts (4 tipos: success/info/warning/danger), loading global vs inline, validación inline de formularios, empty states, errores HTTP (regla: nunca silenciar con `catchError → []`), confirmación destructiva, skeletons.
+
+## Qué NO cubre
+
+Código de framework específico. Para:
+
+- **Angular/TypeScript** (`valueChanges`, `patchValue({emitEvent:false})`, async pipe, normalización de tipos, `concat` vs paralelo, FormBuilder): `coding-standards/references/angular-typescript.md`.
+- **Java/Spring** (sincronización single-slot preservando fila coincidente, fallback cross-tabla, filtros `estado=1` en query): `coding-standards/references/java-spring.md`.
+- **Estructura de proyecto frontend** (`@data`/`@presentation`, `shared/`, `ApiService`): `coding-standards/references/frontend-structure.md`.
+- **Seguridad, logging, git, errores HTTP**: `coding-standards/SKILL.md`.
+
+## Cuándo se activa
+
+Auto-trigger por contexto, como `coding-standards`. Señales típicas:
+
+- El usuario menciona mantenimientos, editar/nuevo, cards, layout, combo dependiente, switch, readonly, listado, filtros, paginación, tabla, modal, confirmación, sidebar, toolbar, breadcrumbs, toast, loading, empty state, validación.
+- El trabajo consiste en diseñar o implementar una vista CRUD nueva (lista, form, modal, navegación) o replicar el patrón a otra entidad.
+- El usuario pregunta por el patrón de un elemento visual ("¿cómo alineo el switch?", "¿uso checkbox o switch aquí?", "¿hay componente reutilizable?").
+- El usuario discute reutilización o framework-first CSS ("¿hay componente en shared?", "prefiero utilities Bootstrap").
+
+No depende de sesiones activas.
+
+## Convenciones comunes a los refs
+
+- **Principios prescriptivos** (lo que sí hacer). Alternativas legadas se mencionan en 1 línea como "no replicar" sin secciones dedicadas.
+- **`[shared-candidato]`** marca componentes compartidos pendientes de extracción — listado consolidado en `references/form-patterns.md` §10 y distribuido donde aparece cada candidato.
+- **Checklist de replicación** al final de cada ref, enumerando los pasos para aplicar los patrones a una vista nueva.
+- **Notas de stack** ("En el proyecto usa X; Y es legado, no replicar") donde las inconsistencias del codebase requieren postura.
+
+## Sandbox read-only
+
+Canon universal en `../session/references/sandbox-readonly-rules.md`. Esta skill es read-only por diseño — carga principios de UX/UI para mantenimientos CRUD (form patterns, listings, modales, navegación, feedback), no edita ni genera código.
+
+En plan mode: describir en el plan file qué refs aplicarían al contexto (form-patterns, list-patterns, modal-patterns, etc.) y los componentes `[shared-candidato]` que el caso justificaría extraer. NO ejecuta `Write`, `Edit`, `MultiEdit`, ni `Bash` con efectos colaterales.
+
+Compatible con plan mode sin restricciones adicionales.
+
+## Roadmap
+
+Los 5 refs cubren el alcance actual tras análisis dirigido del frontend `core-frontend-miscuotas/admin`. Si aparecen dominios nuevos (p. ej. wizards multi-step activos, upload flows complejos, dashboards) con suficiente repetición en el codebase, se añaden como refs adicionales siguiendo el mismo proceso: analizar → generalizar → documentar.