Refactor documentation for project architecture and guidelines
- Updated "Ficha del proyecto UECKO.md" to clarify architectural boundaries and continuity rules. - Revised "README.md" to enhance structure and clarify sources of truth for documentation. - Improved "backend.md" with clearer definitions of responsibilities and architectural layers. - Streamlined "convenciones.md" to emphasize naming conventions and TypeScript best practices. - Enhanced "datos-persistencia.md" to specify persistence rules and data integrity measures. - Updated "frontend.md" to define frontend rules and state management practices. - Refined "testing.md" to clarify testing levels and validation processes. - Revised "vision-general.md" to outline system architecture and module boundaries more clearly.
This commit is contained in:
parent
e94d5e6c71
commit
0e7106f30c
@ -56,7 +56,7 @@ 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 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.
|
* la base de datos contiene usuarios, perfiles, permisos, presupuestos, expedientes, OF, estados, tareas, tiempos, errores, comentarios, trazabilidad e históricos.
|
||||||
|
|
||||||
**Reglas arquitectónicas importantes:**
|
**Límites arquitectónicos y de continuidad:**
|
||||||
|
|
||||||
* El programa y los datos deben permanecer separados.
|
* 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.
|
* Una actualización de la aplicación no puede sobrescribir ni eliminar información operativa o histórica.
|
||||||
@ -70,6 +70,8 @@ La aplicación y la base de datos deben mantenerse separadas conceptualmente:
|
|||||||
* Los cambios relevantes deben poder probarse en un entorno Beta antes de aplicarse a Producción.
|
* 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.
|
* El desarrollador no debe operar directamente sobre datos de Producción fuera de los mecanismos previstos por la aplicación.
|
||||||
|
|
||||||
|
Las reglas técnicas que materializan estos límites se definen en los documentos de [arquitectura](arquitectura/), especialmente [visión general](arquitectura/vision-general.md), [backend](arquitectura/backend.md) y [datos y persistencia](arquitectura/datos-persistencia.md).
|
||||||
|
|
||||||
## 5. Convenciones relevantes
|
## 5. Convenciones relevantes
|
||||||
|
|
||||||
* Los perfiles se definen por puesto o función y se reutilizan entre las personas que desempeñen ese puesto.
|
* Los perfiles se definen por puesto o función y se reutilizan entre las personas que desempeñen ese puesto.
|
||||||
@ -147,9 +149,14 @@ N/A
|
|||||||
|
|
||||||
Principales documentos que deben consultarse antes de tomar decisiones:
|
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.
|
* [Visión general de arquitectura](arquitectura/vision-general.md).
|
||||||
* Documento funcional de Oficina Comercial.
|
* [Arquitectura backend](arquitectura/backend.md).
|
||||||
* Documento funcional de Oficina Técnica.
|
* [Arquitectura de datos y persistencia](arquitectura/datos-persistencia.md).
|
||||||
|
* [Arquitectura frontend](arquitectura/frontend.md).
|
||||||
|
* [Convenciones del proyecto](arquitectura/convenciones.md).
|
||||||
|
* [Estrategia de testing](arquitectura/testing.md).
|
||||||
|
|
||||||
|
El respaldo técnico y los documentos funcionales de Oficina Comercial y Oficina Técnica citados anteriormente no están disponibles en este repositorio. Cuando se incorporen, deberán declararse aquí como referencias normativas con su ruta real.
|
||||||
|
|
||||||
## 8. Restricciones importantes
|
## 8. Restricciones importantes
|
||||||
|
|
||||||
|
|||||||
@ -1,37 +1,37 @@
|
|||||||
# Documentación del proyecto
|
# Documentación del proyecto
|
||||||
|
|
||||||
Este directorio contiene la documentación técnica y operativa del proyecto.
|
Este directorio reúne la documentación técnica, funcional y operativa del proyecto. Cada tema debe tener una fuente de verdad principal; los demás documentos deben enlazarla sin duplicarla.
|
||||||
|
|
||||||
|
## Dónde consultar cada regla
|
||||||
|
|
||||||
|
- Arquitectura, contratos y convenciones técnicas: [`arquitectura/`](arquitectura/).
|
||||||
|
- Restricciones funcionales estables del producto: [`Ficha del proyecto UECKO.md`](Ficha%20del%20proyecto%20UECKO.md).
|
||||||
|
- Decisiones duraderas: [`adr/`](adr/).
|
||||||
|
- Procedimiento de trabajo y cierre: [`guias/`](guias/).
|
||||||
|
- Estado de iniciativas largas: [`trabajo/`](trabajo/).
|
||||||
|
|
||||||
## Estructura
|
## Estructura
|
||||||
|
|
||||||
```text
|
```text
|
||||||
docs/
|
docs/
|
||||||
├── architecture/
|
├── README.md
|
||||||
|
├── Ficha del proyecto UECKO.md
|
||||||
├── adr/
|
├── adr/
|
||||||
├── work/
|
├── arquitectura/
|
||||||
├── guides/
|
├── guias/
|
||||||
└── README.md
|
└── trabajo/
|
||||||
```
|
```
|
||||||
|
|
||||||
### `architecture/`
|
### Documentos normativos
|
||||||
|
|
||||||
Documentación estable sobre la arquitectura y las reglas generales del sistema.
|
Las reglas de arquitectura, contratos, persistencia, frontend, convenciones y testing se definen respectivamente en los documentos de `arquitectura/`. La ficha define el contexto e invariantes funcionales transversales disponibles en el repositorio.
|
||||||
|
|
||||||
### `adr/`
|
### Guías y plantillas
|
||||||
|
|
||||||
Decisiones arquitectónicas o técnicas relevantes y duraderas.
|
Las guías describen procedimientos operativos; no sustituyen las normas de arquitectura. Las plantillas de `adr/` y `trabajo/` no establecen reglas por sí mismas.
|
||||||
|
|
||||||
### `work/`
|
## Mantenimiento
|
||||||
|
|
||||||
Estado de trabajos largos, migraciones, refactors o iniciativas en curso.
|
- Redactar la documentación en castellano y Markdown.
|
||||||
|
- Actualizar el documento normativo aplicable cuando cambie una decisión, contrato o invariante.
|
||||||
### `guides/`
|
- No documentar detalles triviales ya expresados con claridad por el código.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|||||||
@ -2,63 +2,46 @@
|
|||||||
|
|
||||||
## Objetivo
|
## Objetivo
|
||||||
|
|
||||||
Definir la estructura, responsabilidades y reglas principales del backend.
|
Definir responsabilidades, contratos y límites del backend. La dirección general de dependencias está en [visión general](vision-general.md).
|
||||||
|
|
||||||
## Organización
|
## Capas y composición
|
||||||
|
|
||||||
[Capas, módulos, bounded contexts o estructura principal.]
|
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.
|
||||||
|
|
||||||
## Flujo de entrada
|
Cada módulo construye explícitamente sus dependencias en su composition root. No se permite Service Locator, DI implícita o mágica ni importar Infrastructure interna de otro módulo.
|
||||||
|
|
||||||
[Request → aplicación → dominio → persistencia → respuesta.]
|
## Entrada, DTOs y contratos HTTP
|
||||||
|
|
||||||
## Responsabilidades
|
Zod es la fuente única de verdad de los contratos HTTP. Los tipos se infieren mediante `z.infer<typeof Schema>` y no se mantienen interfaces manuales equivalentes. Cada endpoint dispone de DTOs de request y response; los decimales exactos no viajan como `number`.
|
||||||
|
|
||||||
### Entrada / API
|
Los schemas expresan semánticamente UUID, fechas, timestamps, porcentajes, importes y cantidades. Deben distinguir campo omitido, `null`, cadena vacía y colección vacía. No se mezclan validación de transporte y lógica de negocio; `.default()` y `.transform()` solo se usan en DTOs de negocio cuando estén justificados.
|
||||||
|
|
||||||
[Responsabilidades.]
|
El flujo habitual es:
|
||||||
|
|
||||||
### Aplicación
|
```text
|
||||||
|
RequestDTO → UseCase({ dto, context }) → InputMapper → Value Objects / Props
|
||||||
|
```
|
||||||
|
|
||||||
[Responsabilidades.]
|
`RequestMapper → Command` es opcional y solo procede ante una adaptación HTTP real, como combinar `body`, `params` y `query`. No se crea solo para renombrar campos que Application volverá a transformar.
|
||||||
|
|
||||||
### Dominio
|
## Application y Domain
|
||||||
|
|
||||||
[Responsabilidades.]
|
Los casos de uso orquestan, gestionan transacciones cuando corresponde, delegan en servicios de aplicación, devuelven `Result` y construyen respuestas mediante builders o mappers de salida. No contienen lógica HTTP, ORM, modelos Sequelize ni responsabilidades de controller, repositorio o Infrastructure; tampoco construyen agregados directamente desde DTOs HTTP.
|
||||||
|
|
||||||
### Infraestructura
|
Los servicios de aplicación son pequeños, explícitos y de responsabilidad concreta. Se evitan nombres genéricos como `Manager`, `GenericService`, `CommandService`, `BaseRepository` o `Helper` sin semántica.
|
||||||
|
|
||||||
[Responsabilidades.]
|
Se usan los patrones del proyecto: `Result` para operaciones que pueden fallar, `Maybe` para ausencia semántica y `Collection` cuando el dominio requiere comportamiento propio para un conjunto homogéneo. Los fallos de negocio esperables no se representan mediante excepciones, `null`, arrays ni tipos ad hoc cuando corresponda uno de esos patrones.
|
||||||
|
|
||||||
## Casos de uso
|
`create()` representa creación funcional: valida invariantes, puede fallar y devuelve `Result`. `rehydrate()` reconstruye persistencia válida: no valida creación, no genera eventos y no devuelve `Result`. Infrastructure usa `rehydrate()`; Application y Domain usan `create()` para instancias nuevas. `update()` no usa ninguna de las dos, y los Value Objects se reconstruyen con `create()`.
|
||||||
|
|
||||||
[Convenciones y responsabilidades.]
|
## Repositorios, mappers y respuestas
|
||||||
|
|
||||||
## Servicios
|
Cada repositorio gestiona un agregado o responsabilidad concreta, no se comparte entre módulos ni se expone como API pública. Los detalles de ORM permanecen en Infrastructure. Los mappers de persistencia e invariantes de almacenamiento se definen en [datos y persistencia](datos-persistencia.md).
|
||||||
|
|
||||||
[Convenciones y responsabilidades.]
|
Los snapshot builders materializan el DTO de salida exacto y se tipan con el tipo inferido del schema. Son deterministas, sin lógica de negocio ni acceso a repositorios o Infrastructure; pueden transformar `Maybe` en `null`, Value Objects en primitivas y enums internos en valores del contrato. No se crean interfaces `I*Snapshot` que dupliquen DTOs.
|
||||||
|
|
||||||
## Repositorios
|
## Errores, seguridad y API
|
||||||
|
|
||||||
[Reglas y límites.]
|
Los errores esperables son tipados y predecibles. Domain y Application se mapean a HTTP en Infrastructure sin exponer SQL, stack traces, detalles internos ni información sensible. No se ocultan fallos, no se convierten en éxito para continuar y el logging no sustituye su tratamiento.
|
||||||
|
|
||||||
## Persistencia
|
Toda entrada externa se valida. La autorización se verifica además de la autenticación; no se confía en permisos, compañía o identificadores enviados por el cliente sin contrastarlos con el contexto autenticado. Las consultas y mutaciones preservan aislamiento multiempresa. La idempotencia se aplica a operaciones repetibles según su semántica.
|
||||||
|
|
||||||
[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]
|
|
||||||
|
|||||||
@ -1,55 +1,33 @@
|
|||||||
# Convenciones del proyecto
|
# Convenciones del proyecto
|
||||||
|
|
||||||
## Objetivo
|
## Idioma y naming
|
||||||
|
|
||||||
Centralizar convenciones generales que afecten a todo el repositorio.
|
- Código e identificadores en inglés; comentarios, TSDoc y documentación en castellano.
|
||||||
|
- Ficheros y directorios en `kebab-case`.
|
||||||
|
- Clases, tipos e interfaces en `PascalCase`; variables, funciones y métodos en `camelCase`.
|
||||||
|
- `UPPER_SNAKE_CASE` solo para constantes globales reales.
|
||||||
|
- Mantener el prefijo `I` para interfaces cuando el área existente lo use.
|
||||||
|
|
||||||
## Idioma
|
Las convenciones existentes del área prevalecen sobre introducir una variación aislada.
|
||||||
|
|
||||||
- Código e identificadores: [definir]
|
## TypeScript
|
||||||
- Comentarios: [definir]
|
|
||||||
- Documentación: [definir]
|
|
||||||
|
|
||||||
## Naming
|
Preservar la seguridad de tipos. Usar `import type` para símbolos utilizados exclusivamente como tipos y mantenerlos en la cabecera; no usar imports runtime innecesarios ni referencias inline salvo en `.d.ts`, module augmentation, código generado o casos técnicamente justificados.
|
||||||
|
|
||||||
- Ficheros: [convención]
|
Evitar `any`; usar `unknown` cuando el tipo no se conozca. Las assertions y non-null assertions solo proceden con una garantía verificable que TypeScript no pueda inferir. Preferir tipos semánticos, unions o enums existentes y `switch` exhaustivos; no añadir `default` si ocultaría casos comprobables. No duplicar tipos derivados de schemas Zod, ni usar `Partial<T>` cuando el contrato modele la opcionalidad explícitamente. Mantener inmutabilidad cuando no sea necesaria la mutación.
|
||||||
- Directorios: [convención]
|
|
||||||
- Clases / tipos: [convención]
|
|
||||||
- Variables / funciones: [convención]
|
|
||||||
- Constantes: [convención]
|
|
||||||
|
|
||||||
## Estructura de carpetas
|
Al cambiar DTOs, schemas, APIs, eventos, modelos persistidos o tipos compartidos, revisar todos sus productores y consumidores.
|
||||||
|
|
||||||
[Convenciones principales.]
|
## Comentarios y TSDoc
|
||||||
|
|
||||||
## Tipado
|
Los comentarios explican decisiones, riesgos, contratos, efectos laterales, invariantes o limitaciones no evidentes; no traducen el código. Documentar con TSDoc APIs públicas cuando aporte propósito, parámetros, retorno, errores, efectos o restricciones. Tras un refactor se actualizan o eliminan comentarios obsoletos.
|
||||||
|
|
||||||
[Reglas principales.]
|
## Asincronía y errores locales
|
||||||
|
|
||||||
## Validación
|
La regla `lint/complexity/noVoid` prohíbe usar `void` para descartar promesas. Toda promesa se espera, se devuelve o gestiona explícitamente con un manejador de error. No dejar promesas flotantes ni silenciar errores con `.catch(() => undefined)`; si un callback debe devolver `void`, encapsular la operación y gestionar su fallo.
|
||||||
|
|
||||||
[Reglas principales.]
|
## Dependencias y documentación
|
||||||
|
|
||||||
## Errores
|
No añadir ni actualizar dependencias salvo necesidad real: comprobar alternativa existente, justificarla, evaluar mantenimiento, compatibilidad e impacto de bundle o runtime. No modificar lockfiles ni versiones de PNPM incidentalmente, ni introducir supresiones de análisis sin justificación.
|
||||||
|
|
||||||
[Reglas principales.]
|
La documentación vive en `/docs`, usa Markdown y nombres en castellano. Debe ser clara, directa y no duplicar fuentes de verdad. Actualizar el documento autoritativo aplicable antes de crear otro equivalente.
|
||||||
|
|
||||||
## 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.]
|
|
||||||
|
|||||||
@ -2,45 +2,40 @@
|
|||||||
|
|
||||||
## Objetivo
|
## Objetivo
|
||||||
|
|
||||||
Definir las reglas de persistencia, integridad y evolución de datos.
|
Definir las reglas de persistencia, integridad y evolución de datos. MariaDB y Sequelize son tecnologías objetivo documentadas; este documento no afirma su instalación efectiva.
|
||||||
|
|
||||||
## Base de datos
|
## Límites de persistencia
|
||||||
|
|
||||||
[Motor, versión y configuración relevante.]
|
Sequelize y sus modelos permanecen en Infrastructure; no forman contratos públicos ni se acceden desde Domain o Application. Cada repositorio gestiona un agregado o responsabilidad concreta y usa un mapper bidireccional por agregado:
|
||||||
|
|
||||||
## Modelado
|
```ts
|
||||||
|
toPersistence();
|
||||||
|
toDomain();
|
||||||
|
```
|
||||||
|
|
||||||
[Convenciones para tablas, columnas, claves y relaciones.]
|
El mapper traduce representación de dominio y persistida, sin añadir lógica de negocio. Infrastructure reconstruye entidades mediante `rehydrate()`.
|
||||||
|
|
||||||
## Persistencia
|
## Transacciones e integridad
|
||||||
|
|
||||||
[ORM, repositorios y mappers.]
|
Las operaciones agregadas se ejecutan en transacción cuando deben ser atómicas. Al modificar persistencia o lógica transaccional se comprueban atomicidad, consistencia, rollback, concurrencia, aislamiento, integridad referencial y compatibilidad con datos existentes. Una escritura satisfactoria no garantiza por sí sola que haya terminado la operación funcional completa.
|
||||||
|
|
||||||
## Transacciones
|
Las invariantes críticas se refuerzan también en base de datos cuando resulte razonable. Las consultas y mutaciones preservan el aislamiento por `companyId` y `branchId` cuando corresponda y usan consultas parametrizadas o APIs seguras de Sequelize.
|
||||||
|
|
||||||
[Reglas de atomicidad.]
|
## Concurrencia e idempotencia
|
||||||
|
|
||||||
## Integridad
|
Las operaciones repetibles —comandos, peticiones reenviadas, reintentos, creaciones, integraciones, migraciones y actualizaciones— deben ser idempotentes cuando su semántica lo requiera. Una repetición accidental no produce efectos duplicados.
|
||||||
|
|
||||||
[Constraints, foreign keys, invariantes críticas.]
|
No usar `JSON.stringify` para detectar cambios de dominio; los Value Objects se comparan semánticamente mediante primitivas o métodos de igualdad apropiados.
|
||||||
|
|
||||||
## Concurrencia
|
## Migraciones e histórico
|
||||||
|
|
||||||
[Locks, versionado, idempotencia, etc.]
|
Los cambios estructurales se realizan mediante mecanismos controlados. Las migraciones preservan datos e histórico, no exigen reintroducción manual de información y son idempotentes cuando el procedimiento lo requiera. No eliminar columnas, tablas o datos legacy sin auditoría previa.
|
||||||
|
|
||||||
## Migraciones
|
Las actualizaciones no destruyen ni sobrescriben datos operativos o históricos. Antes de un cambio estructural debe existir copia de seguridad recuperable; cuando corresponda, la actualización realiza copia automática y permite restauración o rollback sin depender de conocimientos técnicos del usuario Máster. Las migraciones y actualizaciones quedan registradas. Los cambios relevantes se validan en Beta antes de Producción.
|
||||||
|
|
||||||
[Estrategia de migraciones.]
|
No se elimina físicamente información con histórico cuando proceda desactivarla, incluidos tareas y grupos funcionales. Deben preservarse usuarios, expedientes, OF, tareas, imputaciones, errores, históricos, actividad, configuraciones y trazabilidad.
|
||||||
|
|
||||||
## Índices y rendimiento
|
|
||||||
|
|
||||||
[Convenciones y criterios.]
|
|
||||||
|
|
||||||
## Datos legacy
|
|
||||||
|
|
||||||
[Reglas para compatibilidad y eliminación.]
|
|
||||||
|
|
||||||
## Referencias
|
## Referencias
|
||||||
|
|
||||||
- [ADR relacionado]
|
- [Ficha del proyecto UECKO](../Ficha%20del%20proyecto%20UECKO.md)
|
||||||
- [Documento relacionado]
|
- [Arquitectura backend](backend.md)
|
||||||
|
|||||||
@ -2,51 +2,18 @@
|
|||||||
|
|
||||||
## Objetivo
|
## Objetivo
|
||||||
|
|
||||||
Definir la estructura y las reglas generales del frontend.
|
Definir las reglas de frontend. React, TanStack Query, TanStack Table, React Hook Form, Zod, shadcn/ui y Tailwind son tecnologías objetivo documentadas; este documento no afirma su instalación efectiva.
|
||||||
|
|
||||||
## Organización
|
## Estado y datos remotos
|
||||||
|
|
||||||
[Aplicaciones, módulos, features, pages, components, hooks, etc.]
|
Las operaciones de servidor permanecen en TanStack Query. No duplicar estado remoto en estado local sin necesidad; las query keys siguen la convención existente y, tras mutaciones, la caché se invalida o actualiza explícitamente. No introducir efectos para derivar durante render estado que pueda calcularse directamente.
|
||||||
|
|
||||||
## Estado
|
## Formularios y componentes
|
||||||
|
|
||||||
### Estado remoto
|
Los formularios usan React Hook Form y Zod conforme a los patrones existentes. Los componentes evitan responsabilidad monolítica: se extraen responsabilidades cuando exista una frontera semántica clara, no para ocultar JSX trivial. Usar shadcn/ui y Tailwind según los patrones del área.
|
||||||
|
|
||||||
[Herramienta y reglas.]
|
## UI, accesibilidad e internacionalización
|
||||||
|
|
||||||
### Estado local
|
La interfaz contempla estados `disabled`, `loading`, `empty` y `error`, conserva acciones no disponibles deshabilitadas cuando la UX requiera mostrarlas y preserva comportamiento responsive y accesibilidad.
|
||||||
|
|
||||||
[Reglas.]
|
Los textos visibles se mantienen en `es` y `en` cuando el área use i18n; no se insertan directamente en ese caso. Las columnas monetarias usan `tabular-nums` cuando corresponda.
|
||||||
|
|
||||||
## 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]
|
|
||||||
|
|||||||
@ -4,52 +4,26 @@
|
|||||||
|
|
||||||
Definir qué se prueba, dónde y con qué nivel de profundidad.
|
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
|
## Criterios
|
||||||
|
|
||||||
- Validar comportamiento observable.
|
Los tests priorizan comportamiento observable, contratos, invariantes y casos límite sobre detalles accidentales de implementación. Cuando cambie comportamiento observable se añaden o actualizan pruebas; los bugs incorporan una regresión cuando sea viable.
|
||||||
- Evitar depender de detalles internos irrelevantes.
|
|
||||||
- Añadir regresión para bugs cuando sea viable.
|
|
||||||
- Mantener tests deterministas.
|
|
||||||
|
|
||||||
## Fixtures y datos de prueba
|
Cubrir según corresponda casos válidos e inválidos, límites, errores, idempotencia, autorización y concurrencia. Los tests deben ser deterministas, sin esperas arbitrarias y no se desactivan para obtener una suite verde.
|
||||||
|
|
||||||
[Convenciones.]
|
## Niveles
|
||||||
|
|
||||||
## Mocks
|
Las pruebas unitarias cubren comportamiento de unidades y reglas aisladas. Las de integración cubren la colaboración entre componentes y persistencia cuando corresponda. Las E2E cubren flujos completos relevantes. La selección es proporcional al riesgo, alcance y capas afectadas.
|
||||||
|
|
||||||
[Cuándo y cómo usarlos.]
|
|
||||||
|
|
||||||
## Validación por cambio
|
## Validación por cambio
|
||||||
|
|
||||||
|
La evidencia se obtiene primero mediante la comprobación más acotada suficiente:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
tests específicos
|
test específico → tests del módulo o paquete → typecheck del módulo → lint del módulo → integración → E2E → validación global
|
||||||
→ tests del módulo
|
|
||||||
→ typecheck
|
|
||||||
→ lint
|
|
||||||
→ integración
|
|
||||||
→ E2E
|
|
||||||
→ validación global
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
La validación global procede ante paquetes compartidos, contratos públicos, configuración transversal, varios módulos o infraestructura común. El procedimiento de cierre y el informe de resultados se definen en la [guía de cierre](../guias/cierre-de-tareas.md).
|
||||||
|
|
||||||
## Fallos preexistentes
|
## Fallos preexistentes
|
||||||
|
|
||||||
[Cómo distinguirlos y documentarlos.]
|
Distinguir fallos causados por el cambio, fallos preexistentes, fallos ajenos al área y validaciones no ejecutadas. No atribuir un fallo a una categoría sin evidencia ni ocultar errores de compilación, typecheck, lint, tests o build.
|
||||||
|
|
||||||
## Referencias
|
|
||||||
|
|
||||||
- [ADR relacionado]
|
|
||||||
- [Documento relacionado]
|
|
||||||
|
|||||||
@ -2,38 +2,40 @@
|
|||||||
|
|
||||||
## Objetivo
|
## Objetivo
|
||||||
|
|
||||||
Describir la arquitectura general del sistema y sus principales límites.
|
Definir los límites arquitectónicos transversales del sistema, sin detallar la implementación interna de cada capa.
|
||||||
|
|
||||||
## Sistema
|
## Sistema y módulos
|
||||||
|
|
||||||
[Descripción breve del producto y su propósito.]
|
La aplicación gestiona tiempos, tareas, actividad, incidencias y procesos de Oficina Comercial y Oficina Técnica. Ambos son módulos funcionales diferenciados y cada uno es propietario de los datos que genera.
|
||||||
|
|
||||||
## Principales módulos o áreas
|
Los módulos pueden consultar información ajena cuando sea necesario, pero solo colaboran mediante servicios públicos explícitos. No se comparten repositorios, modelos ORM, mappers internos, servicios internos de escritura ni detalles de Infrastructure. Un módulo no modifica datos propiedad de otro sin permiso expreso.
|
||||||
|
|
||||||
- [Módulo 1]
|
## Estilo y límites
|
||||||
- [Módulo 2]
|
|
||||||
- [Módulo 3]
|
|
||||||
|
|
||||||
## Relaciones principales
|
El backend sigue DDD pragmático, Clean Architecture y arquitectura hexagonal. Se priorizan claridad y explicitud frente a abstracción prematura; esos principios no justifican crear capas, adaptadores, factories, genéricos, eventos o contenedores de DI sin una necesidad actual.
|
||||||
|
|
||||||
[Describir dependencias y comunicación entre módulos.]
|
La dirección general de dependencias es:
|
||||||
|
|
||||||
## Límites arquitectónicos
|
```text
|
||||||
|
Domain
|
||||||
|
no conoce Application ni Infrastructure
|
||||||
|
|
||||||
- [Regla 1]
|
Application
|
||||||
- [Regla 2]
|
depende de Domain, contratos y Core
|
||||||
- [Regla 3]
|
no conoce Express, Sequelize ni modelos ORM
|
||||||
|
|
||||||
## Flujos principales
|
Infrastructure
|
||||||
|
depende de Application, Domain y Core
|
||||||
|
```
|
||||||
|
|
||||||
[Describir los flujos más importantes a alto nivel.]
|
Cada módulo mantiene su propio composition root, que construye explícitamente sus dependencias. No se permite Service Locator ni DI implícita o mágica. Antes de cambiar una frontera arquitectónica se deben identificar productores, consumidores y efectos derivados.
|
||||||
|
|
||||||
## Dependencias externas
|
## Límites transversales
|
||||||
|
|
||||||
- [Servicio / API / infraestructura]
|
La aplicación y los datos permanecen separados. Las actualizaciones y migraciones no pueden destruir, sobrescribir ni exigir reintroducir información histórica. Las reglas técnicas que materializan estos límites se definen en [datos y persistencia](datos-persistencia.md); los contratos de cada capa, en [backend](backend.md).
|
||||||
- [Servicio / API / infraestructura]
|
|
||||||
|
|
||||||
## Referencias
|
## Referencias
|
||||||
|
|
||||||
- [ADR relacionado]
|
- [Ficha del proyecto UECKO](../Ficha%20del%20proyecto%20UECKO.md)
|
||||||
- [Documento relacionado]
|
- [Arquitectura backend](backend.md)
|
||||||
|
- [Arquitectura de datos y persistencia](datos-persistencia.md)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user