From e94d5e6c71388d305d4f37b9cd6d8770718dae72 Mon Sep 17 00:00:00 2001 From: David Date: Thu, 17 Sep 2026 22:11:39 +0200 Subject: [PATCH] Add project documentation and architectural guidelines - Created project overview document for UECKO application. - Added README file for project documentation structure. - Introduced template for architectural decision records (ADR). - Defined backend architecture guidelines. - Established conventions for project-wide consistency. - Documented data persistence architecture. - Outlined frontend architecture principles. - Developed testing strategy documentation. - Provided a general architecture overview. - Created guides for task closure and ChatGPT-Codex workflow. - Organized chat management guidelines for development projects. - Added template for current work status reporting. --- AGENTS.md | 1388 +++++++++++++++++++++ docs/Ficha del proyecto UECKO.md | 194 +++ docs/README.md | 37 + docs/adr/0000-plantilla.md | 45 + docs/arquitectura/backend.md | 64 + docs/arquitectura/convenciones.md | 55 + docs/arquitectura/datos-persistencia.md | 46 + docs/arquitectura/frontend.md | 52 + docs/arquitectura/testing.md | 55 + docs/arquitectura/vision-general.md | 39 + docs/guias/cierre-de-tareas.md | 124 ++ docs/guias/flujo-chatgpt-codex.md | 226 ++++ docs/guias/gestion-de-chats-degradados.md | 0 docs/guias/organizacion-de-chats.md | 246 ++++ docs/trabajo/plantilla-estado-actual.md | 39 + 15 files changed, 2610 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/Ficha del proyecto UECKO.md create mode 100644 docs/README.md create mode 100644 docs/adr/0000-plantilla.md create mode 100644 docs/arquitectura/backend.md create mode 100644 docs/arquitectura/convenciones.md create mode 100644 docs/arquitectura/datos-persistencia.md create mode 100644 docs/arquitectura/frontend.md create mode 100644 docs/arquitectura/testing.md create mode 100644 docs/arquitectura/vision-general.md create mode 100644 docs/guias/cierre-de-tareas.md create mode 100644 docs/guias/flujo-chatgpt-codex.md create mode 100644 docs/guias/gestion-de-chats-degradados.md create mode 100644 docs/guias/organizacion-de-chats.md create mode 100644 docs/trabajo/plantilla-estado-actual.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d85379b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,1388 @@ +# AGENTS.md + +## Ámbito + +Estas instrucciones se aplican a todo el monorepo, salvo que exista un archivo `AGENTS.md` más específico en un subdirectorio. + +Los archivos `AGENTS.md` descendientes pueden añadir, concretar o restringir reglas para su ámbito. + +No deben duplicar innecesariamente las reglas de este documento. + +--- + +## Objetivo + +Trabajar sobre el proyecto mediante cambios: + +* correctos; +* mínimos; +* comprobables; +* coherentes con la arquitectura existente; +* seguros; +* fáciles de revisar; +* fáciles de entender y mantener. + +Antes de modificar código, revisar las implementaciones y patrones existentes en el área afectada. + +No introducir un patrón nuevo cuando ya exista una solución equivalente y adecuada dentro del proyecto. + +--- + +## 1. Principios generales + +Antes de realizar cambios: + +1. Inspeccionar el código relevante. +2. Comprender la implementación y el flujo actual. +3. Buscar patrones equivalentes dentro del repositorio. +4. Identificar el alcance real de la tarea. +5. Consultar la documentación normativa relevante. +6. Evitar suposiciones que puedan verificarse directamente. +7. Determinar cómo se validará el cambio antes de implementarlo cuando la tarea sea relevante. + +Aplicar de forma pragmática: + +* SOLID; +* Clean Code; +* DRY; +* KISS; +* YAGNI; +* SSOT; +* Fail Fast; +* programación defensiva; +* inmutabilidad cuando resulte adecuada; +* idempotencia; +* principio de menor privilegio; +* observabilidad en APIs y servicios. + +Estos principios no justifican por sí solos una refactorización o abstracción nueva. + +Priorizar: + +```text +claridad y explicitud + > +abstracción prematura +``` + +Preferir: + +* cambios mínimos y focalizados; +* soluciones explícitas; +* reutilización de abstracciones existentes; +* coherencia con el proyecto frente a buenas prácticas genéricas; +* evidencia comprobable frente a especulación; +* simplicidad frente a generalización prematura. + +No introducir capas, adaptadores, factories, genéricos, eventos, contenedores DI u otras abstracciones sin una necesidad real y actual. + +--- + +## 2. Entorno de desarrollo + +### Stack principal + +* Node.js 24.x +* TypeScript +* PNPM +* Turborepo +* ExpressJS +* React +* MariaDB +* Sequelize v6 +* Zod v4 +* Biome + +### Entorno esperado + +```text +Sistema operativo: WSL2 Ubuntu 24.04 +Ruta canónica del repositorio: /home/david/dev/uecko-control-tiempos +Runtime: Node.js 24.x +Gestor de paquetes: pnpm 11.25.0 +``` + +Todos los comandos de desarrollo deben ejecutarse dentro de WSL2 usando Linux y `bash`. + +Trabajar sobre el entorno canónico salvo que la tarea requiera expresamente otro. + +No utilizar como entorno de desarrollo: + +* Windows; +* PowerShell; +* rutas UNC; +* `\\wsl$\...`; +* unidades Windows o de red; +* rutas bajo `/mnt/c`; +* copias antiguas del repositorio; +* workspaces alternativos; + +salvo que la tarea lo requiera expresamente. + +Abrir y manipular el repositorio mediante su ruta Linux real: + +```text +/home/david/dev/uecko-control-tiempos +``` + +Antes de una tarea de código relevante, comprobar como mínimo: + +```bash +pwd +git rev-parse --show-toplevel +git status --short +node --version +pnpm --version +``` + +Se espera: + +```text +Repositorio: /home/david/dev/uecko-control-tiempos +Sistema: Linux bajo WSL2 +Node.js: 24.x +PNPM: 11.25.0 +``` + +Si el entorno no coincide con el definido por el proyecto, identificar la causa antes de modificar código. + +No cambiar versiones de runtime, gestores de paquetes o configuración del entorno como efecto colateral de una tarea no relacionada. + +La versión de PNPM declarada mediante `packageManager` en el `package.json` raíz es vinculante. + +No modificar `packageManager` como consecuencia incidental de otra tarea. + +--- + +## 3. Secretos y configuración local + +Los archivos locales de configuración que puedan contener secretos no deben: + +* mostrarse innecesariamente; +* copiarse completos a respuestas; +* incluirse en logs; +* versionarse accidentalmente. + +Nunca exponer: + +* contraseñas; +* tokens; +* API keys; +* claves privadas; +* secretos; +* cadenas de conexión completas; +* credenciales. + +No modificar archivos de configuración local salvo que la tarea lo requiera expresamente. + +--- + +## 4. Auditar antes de implementar + +Para cambios no triviales, inspeccionar la implementación existente antes de modificarla. + +Determinar, cuando corresponda: + +* puntos de entrada; +* módulos afectados; +* flujo funcional; +* flujo de dominio y aplicación; +* persistencia; +* contratos públicos; +* consumidores; +* dependencias; +* tests; +* documentación relevante; +* efectos laterales. + +Para bugs, localizar la causa raíz antes de aplicar una corrección. + +No aplicar fixes especulativos únicamente porque hagan desaparecer un error. + +--- + +## 5. Buscar patrones existentes primero + +Antes de crear una nueva: + +* abstracción; +* clase; +* servicio; +* hook; +* componente; +* mapper; +* repositorio; +* utilidad; +* schema; +* tipo; +* tipo de error; +* capa arquitectónica; +* mecanismo de validación; + +buscar si ya existe una solución equivalente en el repositorio. + +Preferir reutilizar o extender patrones existentes cuando sean adecuados. + +No duplicar funcionalidad sin justificación. + +Tampoco crear una abstracción nueva únicamente para eliminar una duplicación pequeña y local. + +--- + +## 6. Control del alcance + +Modificar únicamente lo necesario para completar la tarea solicitada. + +No realizar automáticamente: + +* refactors ajenos a la tarea; +* renombrados no relacionados; +* movimientos de archivos innecesarios; +* reformateos masivos; +* corrección de warnings no relacionados; +* actualización de dependencias; +* cambios de configuración global; +* cambios en APIs públicas; +* limpieza general del repositorio. + +Si se detectan problemas adicionales: + +1. indicar que existen; +2. explicar si afectan a la tarea; +3. no corregirlos salvo que bloqueen el trabajo o estén incluidos explícitamente en el alcance. + +--- + +## 7. Arquitectura general + +El backend sigue: + +* DDD pragmático; +* Clean Architecture; +* arquitectura hexagonal. + +Separación obligatoria: + +```text +Domain + no conoce Application ni Infrastructure + +Application + depende de Domain, contratos y Core + no conoce Express, Sequelize ni modelos ORM + +Infrastructure + depende de Application, Domain y Core +``` + +No se permite: + +* `Domain -> Application`; +* `Domain -> Infrastructure`; +* `Application -> Infrastructure`; +* importar infraestructura interna de otro módulo; +* compartir repositorios entre módulos; +* utilizar Service Locator; +* introducir DI implícita o mágica. + +Preservar: + +* dirección de dependencias; +* límites de módulo; +* límites de dominio; +* encapsulación; +* contratos públicos; +* límites transaccionales; +* aislamiento de datos; +* controles de seguridad. + +El composition root de cada módulo debe construir explícitamente sus dependencias. + +Antes de modificar una frontera arquitectónica, identificar productores, consumidores y efectos derivados. + +La documentación arquitectónica específica del proyecto prevalece sobre estas reglas resumidas. + +### Invariantes funcionales del proyecto + +Respetar además: + +* aplicación y datos deben permanecer separados; +* una actualización no puede destruir ni sobrescribir información histórica; +* los datos deben sobrevivir a cambios de versión; +* los cambios estructurales de datos deben realizarse mediante mecanismos controlados; +* las migraciones deben preservar información existente; +* ninguna evolución debe exigir reintroducción manual de históricos; +* las operaciones relevantes deben mantener trazabilidad; +* Oficina Comercial y Oficina Técnica son módulos funcionales diferenciados; +* cada módulo es propietario de los datos que genera; +* un módulo no debe modificar datos propiedad de otro sin permiso expreso; +* los identificadores de presupuesto y OF procedentes de Factuges son identificadores maestros externos; +* la aplicación no debe inventar, sustituir ni reutilizar esos identificadores. + +--- + +## 8. Documentación normativa + +La documentación normativa constituye la fuente de verdad para arquitectura, contratos e invariantes del producto. + +No duplicar innecesariamente su contenido en `AGENTS.md`. + +Referencias arquitectónicas normativas: + +```text +- docs/architecture/backend-architecture.md +- docs/architecture/dependency-injection.md +- docs/architecture/http-request-flow.md +- docs/architecture/dto-guidelines.md +- docs/architecture/testing-guidelines.md +``` + +Referencias funcionales: + +```text +- Respaldo_Arquitectura_Tecnica_Aplicacion_v1.1.md +- Documento funcional de Oficina Comercial +- Documento funcional de Oficina Técnica +``` + +Las rutas deben ajustarse a la ubicación real de dichos documentos en el repositorio. + +Las reglas incluidas en este `AGENTS.md` funcionan principalmente como instrucciones operativas. + +--- + +## 9. Idioma y convenciones de nombres + +* Código e identificadores en inglés. +* Comentarios y TSDoc en castellano. +* Documentación en castellano. +* Ficheros y directorios en `kebab-case`. +* Clases, tipos e interfaces en `PascalCase`. +* Variables, funciones y métodos en `camelCase`. +* Constantes globales en `UPPER_SNAKE_CASE` solo cuando realmente sean constantes globales. +* Mantener prefijo `I` para interfaces cuando el área existente ya utilice esa convención. + +Las convenciones existentes en cada área prevalecen frente a introducir una variación aislada. + +--- + +## 10. TypeScript + +Preservar la seguridad de tipos. + +### Imports de tipos + +Usar imports explícitos mediante `import type` para dependencias utilizadas exclusivamente como tipos: + +```ts +import type { UniqueID } from "@repo/rdx-ddd"; +import type { Result } from "@repo/rdx-utils"; +``` + +No usar referencias inline en código fuente ordinario: + +```ts +// No permitido +companyId: import("@repo/rdx-ddd").UniqueID; +``` + +Reglas: + +* usar `import type { ... } from "..."` para toda dependencia utilizada exclusivamente como tipo; +* mantener imports de tipos en la cabecera del fichero; +* separar imports de tipos y runtime cuando sea claro hacerlo; +* no introducir imports de runtime para símbolos usados solo como tipos; +* permitir tipos inline únicamente en `.d.ts`, module augmentation, código generado o casos excepcionales técnicamente justificados. + +### Seguridad de tipos + +* Evitar `any`. +* Usar `unknown` cuando el tipo todavía no sea conocido. +* No usar type assertions salvo que exista una garantía verificable que el compilador no pueda inferir. +* Evitar `!` salvo que la invariante esté demostrada localmente. +* Preferir tipos semánticos frente a primitivas genéricas. +* Modelar conjuntos cerrados mediante unions o enums existentes. +* Mantener exhaustividad en `switch` para conjuntos cerrados. +* No introducir `default` cuando oculte casos no contemplados que puedan comprobarse exhaustivamente. +* No duplicar tipos derivados de schemas Zod. +* No utilizar `Partial` cuando el schema o tipo de entrada ya modele explícitamente la opcionalidad. +* Mantener inmutabilidad cuando no exista necesidad real de mutación. + +No modificar contratos públicos sin revisar previamente productores y consumidores. + +Al modificar: + +* DTOs; +* schemas; +* APIs; +* eventos; +* modelos persistidos; +* tipos compartidos; + +revisar su uso completo. + +--- + +## 11. `Result`, `Maybe` y `Collection` + +Usar los patrones del proyecto: + +* `Result` para operaciones que pueden fallar; +* `Maybe` para ausencia semántica; +* `Collection` para conjuntos de objetos del mismo tipo cuando el dominio requiera comportamiento propio. + +No sustituirlos por: + +* excepciones; +* `null`; +* arrays; +* tipos ad hoc; + +cuando el patrón correspondiente sea aplicable. + +No utilizar excepciones para representar flujo de negocio esperado salvo que el diseño concreto del módulo lo establezca expresamente. + +Los errores esperables deben modelarse mediante contratos explícitos. + +--- + +## 12. Zod y DTOs + +Zod es la fuente única de verdad para los contratos HTTP. + +Reglas: + +* inferir tipos mediante `z.infer`; +* no duplicar DTOs mediante interfaces manuales equivalentes; +* cada endpoint debe disponer de DTOs de request y response; +* reutilizar subschemas únicamente cuando sean estables y realmente compartidos; +* no mezclar validación de transporte con lógica de negocio; +* evitar `.default()` en DTOs de negocio salvo necesidad justificada; +* evitar `.transform()` en DTOs de negocio salvo necesidad justificada; +* diferenciar explícitamente: + + * campo omitido; + * `null`; + * cadena vacía; + * colección vacía; +* utilizar schemas semánticos para: + + * UUID; + * fechas; + * timestamps; + * porcentajes; + * importes; + * cantidades; +* los valores decimales exactos no deben viajar como `number`. + +No mantener una interfaz manual que reproduzca exactamente un schema Zod. + +--- + +## 13. Flujo de entrada backend + +Para el flujo habitual: + +```text +RequestDTO + ↓ +UseCase({ dto, context }) + ↓ +InputMapper + ↓ +Value Objects / Props +``` + +`RequestMapper -> Command` es opcional. + +Solo debe utilizarse cuando exista una adaptación HTTP real, por ejemplo: + +* combinar `body`, `params` y `query`; +* adaptar estructuras de transporte; +* resolver diferencias reales entre transporte y aplicación. + +No crear `RequestMapper` únicamente para renombrar campos que Application volverá a transformar. + +--- + +## 14. Casos de uso + +Los casos de uso deben: + +* orquestar; +* gestionar transacciones cuando corresponda; +* delegar responsabilidades específicas en servicios de aplicación; +* devolver `Result`; +* construir respuestas mediante builders o mappers de salida. + +No deben: + +* contener lógica HTTP; +* utilizar Express; +* utilizar Sequelize directamente; +* utilizar modelos ORM; +* construir agregados directamente desde DTOs HTTP; +* asumir responsabilidades propias de repositorios; +* asumir responsabilidades propias de controllers; +* asumir responsabilidades propias de infraestructura. + +--- + +## 15. Servicios de aplicación + +Preferir servicios: + +* pequeños; +* explícitos; +* con una responsabilidad concreta; +* nombrados según su función real. + +Evitar nombres genéricos como: + +* `Manager`; +* `GenericService`; +* `CommandService`; +* `BaseRepository`; +* `Helper` sin semántica concreta. + +No convertir un servicio de aplicación en un contenedor genérico de lógica no relacionada. + +--- + +## 16. Repositorios + +* Cada repositorio gestiona un agregado o una responsabilidad concreta. +* Sequelize no debe salir de Infrastructure. +* Los repositorios deben usar mappers de persistencia. +* No crear repositorios base genéricos sin necesidad demostrada. +* Los repositorios no se comparten entre módulos. +* No exponer repositorios como API pública de un módulo. +* Mantener aislamiento por `companyId` y `branchId` cuando corresponda. + +No utilizar modelos Sequelize como contratos públicos. + +--- + +## 17. Mappers de persistencia + +Utilizar un mapper bidireccional por agregado: + +```ts +toPersistence(); +toDomain(); +``` + +El mapper es responsable de traducir entre: + +* representación de dominio; +* representación persistida. + +Infrastructure debe reconstruir entidades mediante `rehydrate()`. + +No introducir lógica de negocio nueva dentro del mapper. + +--- + +## 18. `create()` y `rehydrate()` + +Mantener separadas ambas operaciones. + +```text +create() + + creación funcional + valida invariantes + puede fallar + devuelve Result +``` + +```text +rehydrate() + + reconstrucción desde persistencia + no valida reglas de creación + no genera eventos + no devuelve Result +``` + +Reglas: + +* Infrastructure utiliza `rehydrate()`. +* Application y Domain utilizan `create()` para instancias nuevas. +* `update()` no utiliza `create()` ni `rehydrate()`. +* Los Value Objects no tienen `rehydrate()`. +* Los Value Objects se reconstruyen mediante `create()`. + +No utilizar `create()` para reconstruir automáticamente una entidad ya válida almacenada en persistencia. + +--- + +## 19. Comunicación entre módulos + +Los módulos únicamente deben colaborar mediante servicios públicos explícitos. + +No exponer entre módulos: + +* repositorios; +* modelos Sequelize; +* mappers internos; +* servicios de escritura internos; +* detalles de Infrastructure. + +No importar Infrastructure interna de otro módulo. + +Cada módulo debe mantener su propio composition root. + +Las dependencias entre módulos deben ser explícitas. + +--- + +## 20. Snapshots y builders de respuesta + +Los schemas Zod definen el contrato de salida. + +Los snapshot builders materializan ese contrato. + +Reglas: + +* tipar el builder mediante el DTO inferido del schema exacto; +* no crear interfaces `I*Snapshot` que dupliquen un DTO; +* el builder debe ser determinista; +* el builder no debe contener lógica de negocio; +* puede transformar `Maybe` a `null`; +* puede transformar Value Objects a primitivas; +* puede transformar enums internos a valores del contrato; +* no puede acceder a repositorios; +* no puede acceder a Infrastructure; +* si cambia el schema, el builder debe producir un error de compilación si deja de satisfacer el contrato. + +--- + +## 21. Comentarios + +Los comentarios deben aportar información que el código no expresa por sí solo. + +Deben explicar cuando corresponda: + +* por qué existe una decisión; +* qué riesgo evita; +* qué contrato debe respetarse; +* qué efectos laterales son relevantes; +* qué error se evita; +* qué invariantes existen; +* qué limitaciones no son evidentes. + +No deben limitarse a traducir el código a lenguaje natural. + +Documentar con TSDoc las APIs públicas cuando aporte información sobre: + +* propósito; +* parámetros; +* valor devuelto; +* errores; +* efectos laterales; +* invariantes; +* restricciones. + +Después de un refactor, actualizar o eliminar comentarios obsoletos. + +--- + +## 22. Documentación del proyecto + +La documentación: + +* se redacta en castellano; +* reside en `/docs`; +* utiliza Markdown; +* utiliza nombres de fichero en castellano. + +Reglas de estilo: + +* lenguaje claro; +* frases directas; +* evitar ambigüedad; +* evitar frases rebuscadas o innecesariamente largas; +* evitar tecnicismo innecesario; +* utilizar terminología técnica cuando sea necesaria para ser preciso; +* no convertir documentación en una transcripción del código; +* evitar párrafos densos cuando una explicación más breve sea suficiente. + +Priorizar explicar: + +```text +qué hace el sistema +por qué existe una regla +qué comportamiento debe esperarse +qué restricciones deben respetarse +``` + +No duplicar documentación. + +Cuando exista un documento autoritativo, actualizarlo en lugar de crear otro equivalente. + +--- + +## 23. Manejo de errores + +Seguir la estrategia de errores existente. + +No: + +* ocultar errores silenciosamente; +* transformar fallos en resultados exitosos para continuar; +* sustituir errores específicos por errores genéricos sin motivo; +* utilizar logging como sustituto del tratamiento de errores; +* ignorar promesas rechazadas; +* ocultar excepciones inesperadas. + +Preservar contexto suficiente para diagnosticar fallos sin exponer información sensible. + +Usar errores tipados y predecibles. + +Mantener contratos de error estables. + +Mapear errores de Domain y Application a HTTP en Infrastructure. + +No devolver: + +* SQL; +* stack traces; +* detalles internos; +* información sensible. + +--- + +## 24. Operaciones asíncronas + +El proyecto aplica: + +```text +lint/complexity/noVoid +``` + +Está prohibido utilizar `void` para descartar una promesa. + +No generar: + +```ts +void handleDuplicate(); +void handleDownload(); +void asyncOperation(); +``` + +Toda `Promise` debe gestionarse explícitamente. + +### Esperar + +```ts +await operation(); +``` + +### Devolver + +```ts +return operation(); +``` + +### Gestionar explícitamente el fallo + +```ts +operation().catch(handleUnexpectedError); +``` + +La última opción solo procede en operaciones deliberadamente no bloqueantes. + +Reglas: + +* no eliminar `void` dejando una promesa flotante; +* no utilizar `.catch(() => undefined)` para silenciar errores; +* antes de convertir un callback a `async`, comprobar su contrato; +* si el contrato exige `void`, encapsular la operación y gestionar explícitamente el error; +* no utilizar `void` como mecanismo para indicar intención. + +--- + +## 25. Integridad de datos + +Cuando se modifique persistencia o lógica transaccional, comprobar: + +* atomicidad; +* consistencia; +* rollback; +* concurrencia; +* aislamiento; +* integridad referencial; +* compatibilidad con datos existentes. + +No asumir que una escritura satisfactoria implica que la operación funcional completa haya terminado correctamente. + +Cuando una invariante crítica pueda garantizarse también en base de datos, aplicar esa protección además de la validación de aplicación cuando resulte razonable. + +Preservar especialmente: + +* usuarios; +* expedientes; +* OF; +* tareas; +* imputaciones de tiempo; +* errores; +* históricos; +* registros de actividad; +* configuraciones funcionales; +* trazabilidad. + +No eliminar físicamente información con histórico cuando corresponda desactivarla. + +--- + +## 26. Seguridad + +Aplicar el principio de menor privilegio. + +No: + +* introducir secretos en el repositorio; +* registrar datos sensibles; +* confiar automáticamente en identificadores enviados por el cliente; +* confiar en permisos enviados por el cliente; +* interpolar manualmente SQL. + +Validar toda entrada externa. + +Usar consultas parametrizadas y APIs seguras de Sequelize. + +Revisar: + +* autenticación; +* autorización; +* aislamiento tenant; +* permisos; +* contexto autenticado. + +Validar autorización además de autenticación. + +No confiar en identificadores de compañía enviados por el cliente sin contrastarlos con el contexto autenticado. + +Mantener aislamiento multiempresa en todas las consultas y mutaciones. + +--- + +## 27. Idempotencia + +Aplicar idempotencia en operaciones que puedan repetirse. + +Especialmente revisar: + +* comandos repetibles; +* peticiones reenviadas; +* reintentos de infraestructura; +* operaciones de creación; +* integraciones; +* migraciones; +* procesos de actualización. + +Una repetición accidental no debe producir efectos duplicados cuando la semántica de la operación requiera idempotencia. + +--- + +## 28. Base de datos y Sequelize + +* Mantener nombres de tablas y columnas coherentes con las convenciones existentes. +* No introducir modelos Sequelize fuera de Infrastructure. +* No permitir acceso directo a modelos Sequelize desde Application o Domain. +* Ejecutar operaciones agregadas dentro de una transacción cuando deban ser atómicas. +* Diseñar migraciones idempotentes cuando corresponda al procedimiento del proyecto. +* No eliminar columnas, tablas o datos legacy sin auditoría previa. +* No confiar exclusivamente en validaciones de aplicación cuando una invariante crítica pueda reforzarse en base de datos. +* No utilizar `JSON.stringify` para detectar cambios de dominio. +* Comparar Value Objects semánticamente mediante primitivas o métodos de igualdad apropiados. +* Preservar compatibilidad con datos existentes. + +Sequelize no debe convertirse en parte de contratos públicos. + +--- + +## 29. Frontend + +Mantener según los patrones existentes: + +* React; +* TanStack Query; +* TanStack Table; +* React Hook Form; +* Zod; +* shadcn/ui; +* Tailwind; +* i18n. + +Reglas: + +* no duplicar estado remoto en estado local sin necesidad; +* mantener operaciones de servidor en TanStack Query; +* centralizar query keys según la convención existente; +* invalidar o actualizar caché explícitamente después de mutaciones; +* no introducir efectos para derivar estado calculable durante render; +* evitar componentes monolíticos; +* extraer responsabilidades cuando exista una frontera semántica clara; +* no extraer componentes triviales que solo oculten JSX; +* mantener accesibilidad; +* contemplar estados: + + * `disabled`; + * `loading`; + * `empty`; + * `error`; +* no eliminar acciones no disponibles si la UX requiere mostrarlas deshabilitadas; +* mantener traducciones en `es` y `en` al añadir textos visibles; +* no insertar textos directamente cuando el área utilice i18n; +* utilizar `tabular-nums` en columnas monetarias cuando corresponda; +* preservar comportamiento responsive. + +--- + +## 30. APIs + +* Usar errores tipados y predecibles. +* Mantener contratos de error estables. +* Mapear errores de Domain y Application a HTTP en Infrastructure. +* Aplicar idempotencia en operaciones repetibles. +* Validar autorización antes de acceder o modificar datos. +* Mantener aislamiento tenant. +* No confiar en identificadores de compañía proporcionados por el cliente sin verificar el contexto autenticado. +* Registrar información suficiente para diagnosticar fallos sin exponer información sensible. +* No devolver detalles internos. + +--- + +## 31. Dependencias + +No añadir ni actualizar dependencias salvo necesidad real. + +Antes de añadir una dependencia: + +1. comprobar si el proyecto ya proporciona funcionalidad equivalente; +2. justificar por qué es necesaria; +3. evaluar mantenimiento; +4. evaluar compatibilidad; +5. revisar impacto en bundle o runtime. + +No modificar lockfiles innecesariamente. + +No actualizar PNPM como efecto colateral de otra tarea. + +No añadir supresiones de: + +* TypeScript; +* Biome; +* ESLint; +* otras herramientas de análisis; + +sin justificar el motivo. + +--- + +## 32. Tests + +Añadir o actualizar tests cuando cambie comportamiento observable. + +Preferir tests de: + +* comportamiento; +* contratos; +* invariantes; +* casos límite; + +frente a detalles accidentales de implementación. + +En bugs, añadir test de regresión cuando sea viable. + +Cubrir cuando corresponda: + +* caso válido; +* caso inválido; +* límites; +* errores; +* idempotencia; +* autorización; +* concurrencia. + +Mantener tests deterministas. + +No utilizar esperas arbitrarias. + +No desactivar tests para conseguir una suite verde. + +--- + +## 33. Estrategia de validación + +Usar primero la validación más acotada que aporte evidencia suficiente. + +Orden habitual: + +```text +test específico +↓ +tests del módulo / paquete +↓ +typecheck del módulo +↓ +lint del módulo +↓ +integration tests +↓ +E2E +↓ +validación global +``` + +Preferir: + +```bash +pnpm --filter typecheck +pnpm --filter lint +pnpm --filter test +``` + +cuando la validación del workspace resulte suficiente. + +Ejecutar validación global cuando el cambio afecte: + +* paquetes compartidos; +* contratos públicos; +* configuración transversal; +* varios módulos; +* infraestructura común. + +Antes de finalizar, ejecutar según corresponda: + +```bash +pnpm typecheck +pnpm lint +pnpm test +``` + +Y cuando sea aplicable: + +```bash +pnpm check +pnpm build +``` + +No ejecutar validaciones globales costosas si una comprobación dirigida aporta evidencia suficiente, salvo que el riesgo lo justifique. + +Informar exactamente de los comandos ejecutados. + +No considerar completada una tarea con errores conocidos de: + +* typecheck; +* lint; +* tests; +* build; + +salvo que el usuario haya limitado expresamente el alcance. + +--- + +## 34. Fallos preexistentes + +Distinguir claramente: + +* fallos causados por el cambio actual; +* fallos preexistentes; +* fallos ajenos al área modificada; +* validaciones no ejecutadas. + +No atribuir un fallo existente al cambio sin evidencia. + +No declarar un fallo como preexistente sin haberlo comprobado cuando la distinción resulte relevante. + +No ocultar fallos de: + +* compilación; +* typecheck; +* lint; +* tests; +* build. + +--- + +## 35. Comandos + +Usar herramientas y scripts propios del repositorio. + +Antes de ejecutar comandos, revisar: + +* `package.json`; +* scripts; +* configuración; +* workspaces; +* documentación. + +No inventar comandos si pueden obtenerse directamente del repositorio. + +### Instalación + +```bash +N/A — obtener del package.json/documentación del repositorio +``` + +### Desarrollo + +```bash +N/A — obtener del package.json/documentación del repositorio +``` + +### Tests + +```bash +pnpm test +``` + +### Typecheck + +```bash +pnpm typecheck +``` + +### Lint + +```bash +pnpm lint +``` + +### Check + +```bash +pnpm check +``` + +### Build + +```bash +pnpm build +``` + +Los comandos anteriores deben utilizarse únicamente si existen como scripts reales del repositorio. + +Preferir comandos acotados al workspace cuando sean suficientes. + +--- + +## 36. Refactors + +Un refactor debe preservar comportamiento salvo indicación expresa en contrario. + +No mezclar refactors amplios con cambios funcionales sin necesidad. + +Para refactors grandes: + +1. auditar el estado actual; +2. identificar referencias y consumidores; +3. definir fases; +4. ejecutar cambios incrementales; +5. validar entre fases; +6. eliminar legacy únicamente cuando se haya demostrado que ya no es necesario. + +--- + +## 37. Eliminación de código legacy + +Antes de eliminar código aparentemente obsoleto: + +1. buscar referencias en todo el monorepo; +2. revisar imports; +3. revisar rutas; +4. revisar entry points; +5. revisar composition roots; +6. revisar DI; +7. revisar modelos; +8. revisar repositorios; +9. revisar mappers; +10. revisar tests; +11. revisar scripts; +12. revisar documentación. + +Clasificar las referencias como: + +* activas; +* legacy no cableado; +* migraciones; +* documentación; +* tests; +* falsos positivos. + +Eliminar únicamente aquello demostrado como no utilizado. + +Ejecutar después: + +* typecheck relevante; +* lint relevante; +* tests relevantes. + +Documentar cualquier referencia residual y el motivo de conservarla. + +--- + +## 38. Archivos generados + +No modificar manualmente archivos generados salvo que el proyecto lo requiera. + +Cuando un cambio necesite regenerarlos, utilizar el procedimiento oficial. + +No incluir artefactos generados no relacionados con la tarea. + +--- + +## 39. Higiene Git + +Mantener cambios pequeños y revisables. + +Preferir una unidad lógica por conjunto de cambios. + +Antes de finalizar: + +```bash +git status --short +git diff +``` + +Revisar el diff para detectar: + +* modificaciones no relacionadas; +* cambios accidentales de formato; +* código temporal; +* logs de depuración; +* archivos generados inesperados; +* secretos; +* cambios en lockfiles no justificados. + +No reescribir historial ajeno a la tarea. + +No realizar: + +* commits; +* pushes; +* resets destructivos; +* modificaciones de historial; + +salvo petición expresa o flujo explícito del proyecto. + +--- + +## 40. Criterios de finalización + +Una tarea solo debe marcarse como completa cuando: + +* se haya implementado el comportamiento solicitado; +* se respete la arquitectura; +* el alcance solicitado esté cubierto; +* las validaciones relevantes se hayan ejecutado; +* los errores introducidos por el cambio estén resueltos; +* no existan cambios accidentales; +* se hayan indicado las limitaciones conocidas. + +Estados: + +```text +COMPLETA +PARCIAL +BLOQUEADA +``` + +Si una validación requerida no puede realizarse, indicarlo. + +No afirmar que algo: + +* compila; +* funciona; +* pasa tests; +* está corregido; +* está validado; + +sin evidencia. + +--- + +## 41. Informe final + +Al terminar una tarea relevante, indicar: + +1. **Estado:** COMPLETA / PARCIAL / BLOQUEADA +2. **Diagnóstico o causa raíz** +3. **Cambios realizados** +4. **Decisiones relevantes** +5. **Archivos principales modificados** +6. **Comandos de validación ejecutados** +7. **Resultado de las validaciones** +8. **Riesgos o pendientes reales** + +Evitar informes excesivamente largos para tareas sencillas. + +--- + +## 42. Fuente de verdad + +Cuando exista información contradictoria, no asumir automáticamente qué fuente es correcta. + +### Instrucciones operativas + +Orden general: + +1. requisitos explícitos de la tarea; +2. `AGENTS.md` más cercano al archivo modificado; +3. `AGENTS.md` de niveles superiores; +4. este `AGENTS.md` raíz; +5. convenciones existentes en el área; +6. preferencias generales del agente. + +### Comportamiento e invariantes del producto + +Orden general: + +1. requisitos explícitos y vigentes del producto; +2. documentación normativa vigente; +3. contratos públicos e invariantes establecidas; +4. tests que expresen comportamiento intencionado; +5. implementación actual; +6. documentación auxiliar; +7. contexto de conversaciones; +8. suposiciones. + +Los tests no deben considerarse automáticamente correctos cuando contradigan de forma evidente una fuente normativa vigente. + +Un `AGENTS.md` no debe utilizarse para invalidar silenciosamente una regla funcional o arquitectónica normativa. + +Si código, tests y documentación discrepan de forma relevante, investigar la discrepancia antes de modificar comportamiento. + +--- + +## 43. Regla de precedencia + +En caso de conflicto entre instrucciones operativas: + +1. instrucciones explícitas del usuario para la tarea actual; +2. `AGENTS.md` más cercano al archivo modificado; +3. `AGENTS.md` de niveles superiores; +4. este `AGENTS.md` raíz; +5. convenciones existentes del área; +6. preferencias generales del agente. + +Una instrucción de nivel inferior puede concretar o restringir otra superior dentro de su ámbito. + +La documentación normativa gobierna: + +* comportamiento funcional; +* arquitectura; +* contratos; +* invariantes del producto. + +Si una instrucción contradice: + +* arquitectura normativa; +* una invariante crítica; +* una regla de seguridad; +* un contrato público establecido; + +investigar y señalar el conflicto antes de introducir el cambio. diff --git a/docs/Ficha del proyecto UECKO.md b/docs/Ficha del proyecto UECKO.md new file mode 100644 index 0000000..25563e3 --- /dev/null +++ b/docs/Ficha del proyecto UECKO.md @@ -0,0 +1,194 @@ +# Ficha del proyecto + +## 1. Identificación + +**Nombre del proyecto:** +Aplicación de Control de Tiempos y Gestión UECKO + +**Objetivo principal:** +Desarrollar una aplicación para la gestión de tiempos, tareas, actividad, incidencias y procesos de Oficina Técnica y Oficina Comercial para Uecko. La aplicación debe centralizar la operativa de ambos módulos, conservar la trazabilidad y el histórico de la información y permitir la evolución funcional mediante nuevas versiones sin pérdida ni reconstrucción manual de datos. + +**Estado actual:** +En pruebas con datos demo + +## 2. Repositorio + +**Repositorio principal:** +N/A + +**Estructura general:** +N/A + +## 3. Stack tecnológico + +**Backend:** +N/A + +**Frontend:** +N/A + +**Base de datos:** +N/A + +**Testing:** +N/A + +**Infraestructura / despliegue:** +N/A + +## 4. Arquitectura + +**Estilo arquitectónico:** +N/A + +**Organización principal:** +La aplicación se divide inicialmente en dos módulos funcionales: + +* Oficina Comercial. +* Oficina Técnica. + +Existe además una base común transversal que contiene las reglas compartidas de arquitectura, personas, perfiles, permisos, tareas, contextos, imputación de tiempos, trazabilidad, actualización y continuidad de datos. + +Cada módulo mantiene su responsabilidad funcional y es propietario de los datos que genera. Los flujos, campos y permisos específicos deben definirse en el documento funcional correspondiente a cada módulo. + +La aplicación y la base de datos deben mantenerse separadas conceptualmente: + +* la aplicación contiene interfaz, lógica de negocio, pantallas, navegación y funcionalidades; +* la base de datos contiene usuarios, perfiles, permisos, presupuestos, expedientes, OF, estados, tareas, tiempos, errores, comentarios, trazabilidad e históricos. + +**Reglas arquitectónicas importantes:** + +* El programa y los datos deben permanecer separados. +* Una actualización de la aplicación no puede sobrescribir ni eliminar información operativa o histórica. +* Los datos deben sobrevivir a cualquier cambio de versión. +* Los cambios de estructura de datos deben realizarse mediante actualizaciones controladas. +* Antes de modificar la estructura de datos debe existir una copia de seguridad recuperable. +* Las nuevas versiones no pueden exigir reintroducir manualmente datos históricos. +* Las ampliaciones futuras deben integrarse sobre la base existente sin reconstruir usuarios, históricos ni datos comunes. +* Las migraciones de datos y actualizaciones deben quedar registradas. +* Los módulos pueden consultar información del otro módulo cuando sea necesario, pero no modificar datos ajenos salvo permiso expreso. +* Los cambios relevantes deben poder probarse en un entorno Beta antes de aplicarse a Producción. +* El desarrollador no debe operar directamente sobre datos de Producción fuera de los mecanismos previstos por la aplicación. + +## 5. Convenciones relevantes + +* Los perfiles se definen por puesto o función y se reutilizan entre las personas que desempeñen ese puesto. +* Una misma persona puede disponer de varios perfiles. +* El Máster asigna perfiles y permisos; el usuario no puede modificarlos por sí mismo. +* Tarea y contexto son conceptos diferentes: + * la tarea indica qué trabajo se realiza; + * el contexto indica para qué se realiza. +* Los contextos principales de la primera fase son: + * Presupuesto; + * OF; + * Actividad general. +* Los grupos funcionales de tareas contemplados inicialmente son, como mínimo: + * OT; + * OC · Presupuestos; + * OC · Back Office; + * OC · Pedidos; + * Comunes. +* Una tarea puede pertenecer a uno o varios grupos. +* Las tareas o grupos con histórico no se eliminan físicamente; se desactivan para nuevos usos. +* Solo puede existir una actividad activa a la vez. +* Debe permitirse tanto la imputación de tiempo en tiempo real como la imputación diferida. +* La imputación debe disponer de controles de solape y mantener trazabilidad. +* Back Office puede iniciar tareas sin número de presupuesto ni OF mediante un identificador interno y vincularlas posteriormente sin reescribir el tiempo registrado. +* Presupuestos imputa normalmente contra número de presupuesto, con posibilidad excepcional de hacerlo contra OF. +* Pedidos imputa contra OF. +* Oficina Técnica trabaja fundamentalmente contra OF. +* Cuando un expediente cambia de fase, los datos consolidados de la fase anterior quedan bloqueados para la edición ordinaria. +* Las correcciones posteriores a un cambio de fase deben realizarse mediante un procedimiento formal y quedar registradas. +* Un expediente puede existir incompleto, pero no puede avanzar de fase mientras falten datos obligatorios para dicha transición. +* Las fechas y horas de cambios de estado, el usuario que ejecuta las acciones y los registros automáticos del sistema no son editables por usuarios ordinarios. +* Las correcciones excepcionales realizadas por el Máster deben conservar: + * valor anterior; + * valor nuevo; + * fecha; + * hora; + * usuario. +* Los números de presupuesto y OF son identificadores maestros externos procedentes de Factuges. +* La aplicación no debe generar, sustituir ni reutilizar números de presupuesto u OF. +* El presupuesto debe conservar su identidad de origen y las OF deben mantener su vínculo con el presupuesto del que proceden. + +## 6. Comandos habituales + +**Instalación:** + +```bash +N/A +``` + +**Desarrollo:** + +```bash +N/A +``` + +**Tests:** + +```bash +N/A +``` + +**Typecheck:** + +```bash +N/A +``` + +**Lint:** + +```bash +N/A +``` + +## 7. Documentación de referencia + +Principales documentos que deben consultarse antes de tomar decisiones: + +* `Respaldo_Arquitectura_Tecnica_Aplicacion_v1.1.md` — Arquitectura técnica y reglas comunes de la aplicación. +* Documento funcional de Oficina Comercial. +* Documento funcional de Oficina Técnica. + +## 8. Restricciones importantes + +* No debe perderse información existente como consecuencia de una actualización. +* No deben sobrescribirse ni eliminarse usuarios, expedientes, OF, tareas, imputaciones de tiempo, errores, históricos, registros de actividad ni configuraciones funcionales durante una actualización. +* Debe mantenerse compatibilidad con los datos existentes entre versiones. +* Ninguna evolución futura debe requerir la reintroducción manual de datos históricos. +* Antes de cualquier cambio estructural de base de datos debe existir una copia de seguridad recuperable. +* Toda actualización debe realizar una copia automática de seguridad cuando corresponda. +* Debe existir un mecanismo de restauración o rollback que no dependa de conocimientos técnicos del usuario Máster. +* La aplicación debe impedir la instalación de paquetes de actualización no válidos o incompatibles. +* En la primera etapa, las actualizaciones se distribuyen como paquetes completos de versión, no como conjuntos de archivos sueltos. +* Las modificaciones relevantes deben poder validarse en Beta antes de pasar a Producción. +* El perfil Informática / Soporte no debe modificar por defecto reglas funcionales del negocio. +* El perfil Desarrollador no debe modificar directamente datos de Producción fuera de los mecanismos previstos. +* Los módulos no deben modificar datos propiedad de otros módulos salvo permiso expreso. +* No deben eliminarse físicamente tareas o grupos que tengan histórico. +* Los datos consolidados de una fase no deben modificarse mediante edición ordinaria después del avance de fase. +* Los registros automáticos, fechas de cambio de estado y usuarios asociados a acciones no deben ser editables por usuarios ordinarios. +* Los identificadores de presupuesto y OF procedentes de Factuges no pueden ser inventados, sustituidos ni reutilizados por la aplicación. +* Las nuevas decisiones funcionales deben incorporarse previamente al documento marco correspondiente antes de pasar a Producción. +* La aplicación debe limitarse a registrar, conservar, relacionar, mostrar, filtrar y exportar información. No debe emitir automáticamente juicios de rendimiento ni conclusiones de gestión. + +## 9. Observaciones + +La responsabilidad transversal de la primera fase corresponde a Dirección Técnica. Cada módulo conserva además su propia responsabilidad funcional mediante el Responsable de Oficina Comercial y el Responsable de Oficina Técnica. + +Existe un perfil Máster con responsabilidad sobre permisos y decisiones funcionales, diferenciado de los perfiles Informática / Soporte y Desarrollador. + +La aplicación contempla un nivel de experiencia UECKO calculado automáticamente a partir de la fecha de incorporación: + +* Nivel 1: hasta 3 meses. +* Nivel 2: más de 3 y hasta 6 meses. +* Nivel 3: más de 6 y hasta 9 meses. +* Nivel 4: más de 9 y hasta 12 meses. +* Nivel 5: más de 12 meses. + +Este nivel representa antigüedad y adaptación al entorno UECKO, no una calificación profesional. Cuando sea relevante para análisis posteriores, debe conservarse el nivel existente en el momento de asignación del trabajo. + +Las actualizaciones deben generar un registro técnico independiente del histórico funcional, incluyendo fecha y hora, usuario, versión anterior, versión nueva, resultado y, cuando proceda, restauración posterior. + +Mientras no exista integración automática con Factuges, los números de presupuesto y OF pueden incorporarse manualmente o mediante importación, manteniendo siempre Factuges como sistema de origen de dichos identificadores. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5714733 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# Documentación del proyecto + +Este directorio contiene la documentación técnica y operativa del proyecto. + +## Estructura + +```text +docs/ +├── architecture/ +├── adr/ +├── work/ +├── guides/ +└── README.md +``` + +### `architecture/` + +Documentación estable sobre la arquitectura y las reglas generales del sistema. + +### `adr/` + +Decisiones arquitectónicas o técnicas relevantes y duraderas. + +### `work/` + +Estado de trabajos largos, migraciones, refactors o iniciativas en curso. + +### `guides/` + +Procedimientos operativos y guías para desarrolladores. + +## Principios + +- Evitar duplicar información. +- Mantener una única fuente de verdad por tema. +- Actualizar la documentación cuando cambien decisiones o contratos relevantes. +- No documentar detalles triviales que ya se expresen claramente en el código. diff --git a/docs/adr/0000-plantilla.md b/docs/adr/0000-plantilla.md new file mode 100644 index 0000000..208be32 --- /dev/null +++ b/docs/adr/0000-plantilla.md @@ -0,0 +1,45 @@ +# ADR-0000 — Título + +## Estado + +Propuesta / Aceptada / Sustituida / Rechazada + +## Contexto + +[Qué problema existe y por qué requiere una decisión.] + +## Decisión + +[Qué se ha decidido.] + +## Motivos + +[Por qué se elige esta opción.] + +## Consecuencias + +### Positivas + +- ... + +### Negativas + +- ... + +### Restricciones + +- ... + +## Alternativas consideradas + +### Alternativa A + +[Descripción y motivo de descarte.] + +### Alternativa B + +[Descripción y motivo de descarte.] + +## Referencias + +- [Issue / documento / código] diff --git a/docs/arquitectura/backend.md b/docs/arquitectura/backend.md new file mode 100644 index 0000000..ca3a398 --- /dev/null +++ b/docs/arquitectura/backend.md @@ -0,0 +1,64 @@ +# Arquitectura backend + +## Objetivo + +Definir la estructura, responsabilidades y reglas principales del backend. + +## Organización + +[Capas, módulos, bounded contexts o estructura principal.] + +## Flujo de entrada + +[Request → aplicación → dominio → persistencia → respuesta.] + +## Responsabilidades + +### Entrada / API + +[Responsabilidades.] + +### Aplicación + +[Responsabilidades.] + +### Dominio + +[Responsabilidades.] + +### Infraestructura + +[Responsabilidades.] + +## Casos de uso + +[Convenciones y responsabilidades.] + +## Servicios + +[Convenciones y responsabilidades.] + +## Repositorios + +[Reglas y límites.] + +## Persistencia + +[ORM, mappers, modelos, transacciones.] + +## Errores + +[Estrategia de errores y mapeo.] + +## Transacciones + +[Reglas de atomicidad y rollback.] + +## Seguridad + +[Autenticación, autorización, tenancy, validación.] + +## Referencias + +- [ADR relacionado] +- [Documento relacionado] diff --git a/docs/arquitectura/convenciones.md b/docs/arquitectura/convenciones.md new file mode 100644 index 0000000..8818050 --- /dev/null +++ b/docs/arquitectura/convenciones.md @@ -0,0 +1,55 @@ +# Convenciones del proyecto + +## Objetivo + +Centralizar convenciones generales que afecten a todo el repositorio. + +## Idioma + +- Código e identificadores: [definir] +- Comentarios: [definir] +- Documentación: [definir] + +## Naming + +- Ficheros: [convención] +- Directorios: [convención] +- Clases / tipos: [convención] +- Variables / funciones: [convención] +- Constantes: [convención] + +## Estructura de carpetas + +[Convenciones principales.] + +## Tipado + +[Reglas principales.] + +## Validación + +[Reglas principales.] + +## Errores + +[Reglas principales.] + +## Async + +[Reglas principales.] + +## Imports + +[Reglas principales.] + +## Dependencias + +[Reglas para añadir o actualizar dependencias.] + +## Git + +[Convenciones relevantes.] + +## Documentación + +[Convenciones de actualización y SSOT.] diff --git a/docs/arquitectura/datos-persistencia.md b/docs/arquitectura/datos-persistencia.md new file mode 100644 index 0000000..1257b20 --- /dev/null +++ b/docs/arquitectura/datos-persistencia.md @@ -0,0 +1,46 @@ +# Arquitectura de datos y persistencia + +## Objetivo + +Definir las reglas de persistencia, integridad y evolución de datos. + +## Base de datos + +[Motor, versión y configuración relevante.] + +## Modelado + +[Convenciones para tablas, columnas, claves y relaciones.] + +## Persistencia + +[ORM, repositorios y mappers.] + +## Transacciones + +[Reglas de atomicidad.] + +## Integridad + +[Constraints, foreign keys, invariantes críticas.] + +## Concurrencia + +[Locks, versionado, idempotencia, etc.] + +## Migraciones + +[Estrategia de migraciones.] + +## Índices y rendimiento + +[Convenciones y criterios.] + +## Datos legacy + +[Reglas para compatibilidad y eliminación.] + +## Referencias + +- [ADR relacionado] +- [Documento relacionado] diff --git a/docs/arquitectura/frontend.md b/docs/arquitectura/frontend.md new file mode 100644 index 0000000..a53bc5f --- /dev/null +++ b/docs/arquitectura/frontend.md @@ -0,0 +1,52 @@ +# Arquitectura frontend + +## Objetivo + +Definir la estructura y las reglas generales del frontend. + +## Organización + +[Aplicaciones, módulos, features, pages, components, hooks, etc.] + +## Estado + +### Estado remoto + +[Herramienta y reglas.] + +### Estado local + +[Reglas.] + +## Formularios + +[Convenciones de formularios y validación.] + +## Componentes + +[Reutilización, sistema de diseño y composición.] + +## Navegación + +[Routing y layouts.] + +## UI / UX + +[Patrones visuales, loading, empty, error, disabled, responsive.] + +## Internacionalización + +[Convenciones i18n.] + +## Accesibilidad + +[Reglas mínimas.] + +## Errores + +[Manejo de errores de UI y API.] + +## Referencias + +- [ADR relacionado] +- [Documento relacionado] diff --git a/docs/arquitectura/testing.md b/docs/arquitectura/testing.md new file mode 100644 index 0000000..de474e3 --- /dev/null +++ b/docs/arquitectura/testing.md @@ -0,0 +1,55 @@ +# Estrategia de testing + +## Objetivo + +Definir qué se prueba, dónde y con qué nivel de profundidad. + +## Niveles + +### Unitarios + +[Qué deben cubrir.] + +### Integración + +[Qué deben cubrir.] + +### E2E + +[Qué deben cubrir.] + +## Criterios + +- Validar comportamiento observable. +- Evitar depender de detalles internos irrelevantes. +- Añadir regresión para bugs cuando sea viable. +- Mantener tests deterministas. + +## Fixtures y datos de prueba + +[Convenciones.] + +## Mocks + +[Cuándo y cómo usarlos.] + +## Validación por cambio + +```text +tests específicos +→ tests del módulo +→ typecheck +→ lint +→ integración +→ E2E +→ validación global +``` + +## Fallos preexistentes + +[Cómo distinguirlos y documentarlos.] + +## Referencias + +- [ADR relacionado] +- [Documento relacionado] diff --git a/docs/arquitectura/vision-general.md b/docs/arquitectura/vision-general.md new file mode 100644 index 0000000..854eeb7 --- /dev/null +++ b/docs/arquitectura/vision-general.md @@ -0,0 +1,39 @@ +# Visión general de arquitectura + +## Objetivo + +Describir la arquitectura general del sistema y sus principales límites. + +## Sistema + +[Descripción breve del producto y su propósito.] + +## Principales módulos o áreas + +- [Módulo 1] +- [Módulo 2] +- [Módulo 3] + +## Relaciones principales + +[Describir dependencias y comunicación entre módulos.] + +## Límites arquitectónicos + +- [Regla 1] +- [Regla 2] +- [Regla 3] + +## Flujos principales + +[Describir los flujos más importantes a alto nivel.] + +## Dependencias externas + +- [Servicio / API / infraestructura] +- [Servicio / API / infraestructura] + +## Referencias + +- [ADR relacionado] +- [Documento relacionado] diff --git a/docs/guias/cierre-de-tareas.md b/docs/guias/cierre-de-tareas.md new file mode 100644 index 0000000..9c5d012 --- /dev/null +++ b/docs/guias/cierre-de-tareas.md @@ -0,0 +1,124 @@ +# Cierre de tareas + +## Objetivo + +Definir cuándo una tarea puede considerarse realmente terminada y qué evidencias deben existir antes de cerrarla. + +--- + +## Checklist de cierre + +- [ ] El objetivo solicitado está implementado. +- [ ] El alcance real coincide con el solicitado. +- [ ] No se han introducido cambios innecesarios. +- [ ] La solución respeta la arquitectura y los patrones existentes. +- [ ] Los contratos afectados siguen siendo coherentes. +- [ ] Se han añadido o actualizado tests cuando corresponde. +- [ ] Se han ejecutado las validaciones relevantes. +- [ ] Los errores introducidos por el cambio están resueltos. +- [ ] Los fallos preexistentes están diferenciados de los nuevos. +- [ ] Se ha revisado el diff final. +- [ ] No quedan logs, código temporal, archivos accidentales o secretos. +- [ ] La documentación se ha actualizado si el cambio lo requiere. +- [ ] Los riesgos, limitaciones o pendientes están identificados. + +--- + +## Validación + +Según el alcance y riesgo del cambio, utilizar: + +```text +tests específicos +→ tests del módulo +→ typecheck +→ lint +→ integración +→ E2E +→ validación global +``` + +No es obligatorio ejecutar siempre toda la cadena. + +La validación debe ser proporcional al impacto del cambio. + +No declarar una validación como superada si no se ha ejecutado correctamente. + +--- + +## Estados finales + +### COMPLETA + +Usar cuando: + +- el objetivo está cumplido; +- las validaciones necesarias se han ejecutado; +- no quedan defectos conocidos dentro del alcance. + +### PARCIAL + +Usar cuando: + +- parte de la tarea está completada; +- faltan puntos del alcance; +- faltan validaciones relevantes; +- existe algún bloqueo que impide cerrar completamente. + +Debe indicarse exactamente qué queda pendiente. + +### BLOQUEADA + +Usar cuando no puede avanzarse correctamente por: + +- falta de información; +- dependencia externa; +- error de entorno; +- problema del repositorio; +- decisión pendiente; +- requisito incompatible. + +Debe indicarse qué impide continuar. + +--- + +## No considerar completa una tarea solo porque + +- compila; +- un test concreto pasa; +- desaparece el error visible; +- Codex afirma que funciona; +- el diff parece correcto; +- no aparecen errores de TypeScript. + +El criterio es el cumplimiento verificable del objetivo. + +--- + +## Informe final recomendado + +```text +Estado: + +Objetivo: + +Cambios realizados: + +Archivos principales: + +Validaciones ejecutadas: + +Resultados: + +Problemas preexistentes: + +Riesgos o pendientes: +``` + +--- + +## Regla principal + +No cerrar una tarea por sensación de finalización. + +Cerrar únicamente cuando exista evidencia suficiente de que el resultado esperado funciona y el alcance está controlado. diff --git a/docs/guias/flujo-chatgpt-codex.md b/docs/guias/flujo-chatgpt-codex.md new file mode 100644 index 0000000..452b0c9 --- /dev/null +++ b/docs/guias/flujo-chatgpt-codex.md @@ -0,0 +1,226 @@ +# Flujo ChatGPT → Codex + +## Objetivo + +Definir un flujo de trabajo consistente para analizar, implementar y validar cambios de desarrollo utilizando ChatGPT y Codex. + +--- + +## Flujo general + +```text +Necesidad +→ Análisis +→ Auditoría +→ Diseño +→ Prompt para Codex +→ Implementación +→ Validación +→ Revisión +→ Cierre +``` + +--- + +## 1. Plantear la necesidad + +Definir: + +- qué problema se quiere resolver; +- qué comportamiento se espera; +- qué módulo o área está afectada; +- qué restricciones conocidas existen. + +Evitar empezar por una solución técnica concreta si todavía no se ha auditado el código. + +--- + +## 2. Analizar el contexto + +Antes de pedir cambios: + +- revisar decisiones previas; +- identificar documentación relevante; +- comprobar si existe contexto suficiente; +- determinar el nivel de complejidad de la tarea. + +--- + +## 3. Auditar el estado actual + +Para cambios no triviales: + +- localizar el flujo actual; +- identificar archivos, clases, hooks, casos de uso o servicios implicados; +- buscar patrones equivalentes; +- identificar contratos y consumidores; +- localizar causa raíz si existe un bug. + +No modificar código cuando la fase tenga como objetivo exclusivo comprender el sistema. + +--- + +## 4. Diseñar la solución + +Definir: + +- resultado esperado; +- alcance; +- invariantes; +- restricciones; +- componentes afectados; +- compatibilidad necesaria; +- validaciones requeridas. + +Preferir la solución mínima compatible con la arquitectura existente. + +--- + +## 5. Preparar el prompt para Codex + +El prompt debe incluir, cuando corresponda: + +```text +CONTEXTO + +OBJETIVO + +ALCANCE + +RESTRICCIONES + +PROCEDIMIENTO + +CRITERIOS DE VALIDACIÓN + +FORMATO DE RESPUESTA +``` + +No repetir reglas ya definidas claramente en `AGENTS.md` salvo que sean especialmente relevantes para la tarea. + +--- + +## 6. Implementación con Codex + +Codex debe: + +- inspeccionar el repositorio antes de modificar; +- respetar `AGENTS.md`; +- trabajar dentro del alcance; +- reutilizar patrones existentes; +- evitar cambios colaterales; +- mantener el código validable durante el proceso. + +Para trabajos grandes, dividir la implementación en fases verificables. + +--- + +## 7. Validación + +Después de implementar: + +```text +tests específicos +→ tests del módulo +→ typecheck +→ lint +→ integración +→ E2E +→ validación global si corresponde +``` + +No ejecutar toda la cadena automáticamente si el alcance no lo requiere. + +Exigir siempre evidencia de qué validaciones se han ejecutado realmente. + +--- + +## 8. Revisar el resultado + +Comprobar: + +- que se ha resuelto el objetivo original; +- que el alcance no se ha ampliado innecesariamente; +- que las decisiones coinciden con el diseño; +- que no existen regresiones evidentes; +- que los tests cubren el comportamiento relevante; +- que los fallos preexistentes están diferenciados. + +Si algo no está claro, auditar antes de pedir nuevas modificaciones. + +--- + +## 9. Iterar si es necesario + +Si aparecen defectos: + +```text +Diagnosticar +→ corregir causa +→ validar +→ volver a revisar +``` + +Evitar encadenar instrucciones correctivas sin reconstruir primero el problema cuando Codex empiece a desviarse. + +--- + +## 10. Cerrar la tarea + +Antes de considerar terminada una tarea: + +- objetivo cumplido; +- alcance revisado; +- tests relevantes ejecutados; +- typecheck y lint revisados cuando corresponda; +- pendientes reales identificados; +- documentación actualizada si el cambio lo requiere. + +Estados: + +```text +COMPLETA +PARCIAL +BLOQUEADA +``` + +--- + +## Nivel de proceso según la tarea + +### Cambio pequeño + +```text +Analizar +→ Implementar +→ Validar +``` + +### Cambio normal + +```text +Auditar +→ Diseñar +→ Implementar +→ Validar +→ Revisar +``` + +### Cambio complejo o delicado + +```text +Auditoría independiente +→ Diseño +→ Implementación por fases +→ Validación entre fases +→ Verificación final +→ Documentación +``` + +--- + +## Regla principal + +No convertir el proceso en burocracia. + +Aplicar únicamente el nivel de análisis, documentación y validación proporcional al riesgo, complejidad y alcance de la tarea. diff --git a/docs/guias/gestion-de-chats-degradados.md b/docs/guias/gestion-de-chats-degradados.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guias/organizacion-de-chats.md b/docs/guias/organizacion-de-chats.md new file mode 100644 index 0000000..8d42e55 --- /dev/null +++ b/docs/guias/organizacion-de-chats.md @@ -0,0 +1,246 @@ +# Organización de chats en proyectos de desarrollo + +## Objetivo + +Organizar los chats de un Proyecto de ChatGPT de forma que cada conversación mantenga un contexto claro, estable y reutilizable. + +--- + +## Chats básicos + +### `[ARCH] Arquitectura y decisiones` + +Para: + +- arquitectura; +- patrones; +- convenciones; +- decisiones transversales; +- ADR; +- límites entre módulos. + +### `[BACKEND] Backend transversal` + +Para aspectos de backend que afecten a varios módulos: + +- APIs; +- middleware; +- DI; +- errores; +- transacciones; +- autenticación/autorización; +- infraestructura común. + +### `[FRONTEND] Frontend / UI / UX` + +Para: + +- layouts; +- componentes compartidos; +- sistema de diseño; +- navegación; +- UX; +- accesibilidad; +- responsive; +- patrones frontend. + +### `[TESTS] Testing / E2E` + +Para: + +- estrategia de tests; +- infraestructura de testing; +- E2E; +- fixtures; +- mocks; +- problemas generales de testing. + +### `[INFRA] Infraestructura / DevOps` + +Para: + +- Docker; +- CI/CD; +- despliegues; +- servidores; +- observabilidad; +- logging; +- monitorización; +- backups; +- entornos. + +### `[DATA] Base de datos / persistencia` + +Opcional. + +Para: + +- migraciones; +- índices; +- rendimiento; +- integridad; +- concurrencia; +- persistencia transversal. + +### `[DOCS] Documentación` + +Opcional. + +Para: + +- estructura documental; +- ADR; +- revisión de documentación; +- documentación técnica transversal. + +--- + +## Chats por módulo o área funcional + +Crear un chat por cada módulo o área con suficiente entidad propia. + +Formato: + +```text +[MODULO] Nombre +``` + +Ejemplos: + +```text +[CUSTOMERS] Customers +[COMPANIES] Companies +[CATALOGS] Catalogs +[PROFORMAS] Proformas +[INVOICES] Issued Invoices +[IDENTITY] Identity +``` + +Usar estos chats para todo el trabajo específico del módulo: + +- dominio; +- backend; +- frontend; +- persistencia; +- tests; +- bugs; +- pequeñas refactorizaciones. + +--- + +## Chats temporales + +Crear solo cuando el trabajo tenga suficiente entidad propia: + +```text +[AUDIT] ... +[BUG] ... +[REFACTOR] ... +[MIGRATION] ... +[FEATURE] ... +``` + +No crear un chat nuevo para tareas pequeñas que encajen correctamente en un chat existente. + +--- + +## Regla para elegir chat + +```text +¿Pertenece claramente a un módulo? +→ Chat del módulo + +¿Afecta a varios módulos dentro de una disciplina? +→ BACKEND / FRONTEND / TESTS / DATA / INFRA + +¿Es una decisión transversal? +→ ARCH + +¿Es un trabajo grande e independiente? +→ AUDIT / BUG / REFACTOR / MIGRATION / FEATURE +``` + +--- + +## Cuándo abrir un chat nuevo + +Abrir uno cuando: + +- cambie sustancialmente el contexto; +- el trabajo tenga entidad propia; +- existan muchas fases; +- sea una investigación independiente; +- el chat anterior sea demasiado largo; +- mezclar el nuevo trabajo dificulte entender decisiones anteriores. + +No abrir un chat nuevo simplemente porque empieza una nueva tarea. + +--- + +## Chats demasiado largos + +Cuando un chat acumule demasiado histórico, cerrarlo conceptualmente y continuar en otro. + +Ejemplo: + +```text +[PROFORMAS] Fiscalidad I +[PROFORMAS] Fiscalidad II +``` + +Al iniciar el nuevo chat, trasladar únicamente: + +```text +Objetivo actual: +Estado: +Decisiones vigentes: +Completado: +Pendientes: +Restricciones: +Fuentes de verdad: +Siguiente tarea: +``` + +No copiar toda la conversación anterior. + +--- + +## Convención de nombres + +Usar: + +```text +[CATEGORIA] Descripción +``` + +Ejemplos: + +```text +[ARCH] Arquitectura general +[FRONTEND] Layouts +[PROFORMAS] Fiscalidad +[BUG] Error al emitir factura +[REFACTOR] Inyección de dependencias +``` + +Evitar nombres ambiguos: + +```text +Dudas +Cambios varios +Problema de hoy +Nuevo chat +``` + +--- + +## Principio general + +Un chat debe representar un **contexto de trabajo estable**. + +No debe representar necesariamente: + +- todo el proyecto; +- ni una única tarea. + +Debe agrupar conversaciones que realmente se beneficien de compartir contexto entre sí. diff --git a/docs/trabajo/plantilla-estado-actual.md b/docs/trabajo/plantilla-estado-actual.md new file mode 100644 index 0000000..b561874 --- /dev/null +++ b/docs/trabajo/plantilla-estado-actual.md @@ -0,0 +1,39 @@ +# Estado de trabajo — Título + +## Objetivo + +[Qué se quiere conseguir.] + +## Estado actual + +EN CURSO / BLOQUEADA / COMPLETA + +## Completado + +- [P1] +- [P2] + +## Decisiones vigentes + +- [Decisión 1] +- [Decisión 2] + +## Pendiente + +- [Pendiente 1] +- [Pendiente 2] + +## Riesgos / bloqueos + +- [Riesgo o bloqueo] + +## Fuentes de verdad + +- `AGENTS.md` +- [ADR] +- [Documento] +- [Código relevante] + +## Siguiente paso + +[Próxima tarea concreta]