Guía para Documentar Funcionalidades

Esta guía explica cómo documentar funcionalidades del sistema Bautista. Cada funcionalidad debe tener una documentación completa que sirva tanto para entender qué hace el sistema como para definir requerimientos antes de desarrollar.

Cuándo documentar

Debes crear documentación de funcionalidades en estos casos:

1. Antes de desarrollar una nueva funcionalidad (como requerimientos)
2. Después de desarrollar para documentar lo implementado
3. Al modificar una funcionalidad existente significativamente

Tipos de documentación

1. Recursos (Resources)

Documentan entidades del sistema que tienen CRUD completo.

Archivo: {modulo}/{nombre}-resource.md

Ejemplo: tesoreria/boniret-resource.md

Contenido:

• Descripción de la entidad
• Esquema de datos (tabla, campos, tipos)
• Endpoints API (GET, POST, PUT, DELETE)
• Validaciones de negocio
• Relaciones con otras entidades
• Permisos requeridos

Ver: boniret-resource.md como ejemplo completo

2. Procesos (Processes)

Documentan flujos de negocio complejos que involucran múltiples pasos.

Archivo: {modulo}/{nombre}-process.md

Ejemplo: ventas/facturacion-masiva-process.md

Contenido:

• Descripción del proceso
• Flujo de trabajo (diagrama o pasos)
• Entidades involucradas
• Validaciones y reglas de negocio
• Frontend: vistas y acciones del usuario
• Backend: servicios y lógica

3. Vistas (Views)

Documentan interfaces de usuario específicas.

Archivo: {modulo}/{nombre}-view.md

Ejemplo: ventas/comprobantes-listado-view.md

Contenido:

• Descripción de la vista
• Componentes y elementos UI
• Interacciones disponibles
• Permisos y roles
• Datos mostrados
• Acciones disponibles

Estructura de un documento de funcionalidad

Todo documento debe seguir esta estructura básica:

# Título de la Funcionalidad

**Módulo**: {nombre del módulo}
**Tipo**: Resource | Process | View
**Estado**: Planificado | En desarrollo | Implementado

## Descripción

Descripción clara y concisa de qué hace la funcionalidad.

## Frontend

### Vistas
- Lista de vistas involucradas

### Componentes
- Componentes UI utilizados

### Interacciones
- Qué puede hacer el usuario

### Permisos
- Roles y permisos necesarios

## Backend

### Recursos/Endpoints
- Listado de endpoints API

### Modelos
- Entidades y tablas involucradas

### Servicios
- Lógica de negocio

### Relaciones
- Relaciones con otras entidades

### Validaciones
- Reglas de negocio y validaciones

## Casos de uso

Ejemplos de uso común de la funcionalidad

## Consideraciones técnicas

Aspectos técnicos importantes a tener en cuenta

Usando la plantilla

1. Copia el archivo template.md
2. Renómbralo según la convención: {modulo}/{nombre}-{tipo}.md
3. Completa todas las secciones
4. Revisa que esté completa antes de marcar como lista

Ejemplos de documentación

Documentación como requerimiento (antes de desarrollar)

# Gestión de Retenciones

**Módulo**: Tesorería
**Tipo**: Resource
**Estado**: Planificado

## Descripción

El sistema debe permitir gestionar conceptos de retenciones que se aplicarán
en los recibos. Cada concepto puede ser de tipo porcentaje o fijo.

## Frontend

### Vistas
- Listado de conceptos de retenciones con filtros
- Formulario de alta/edición de concepto
- Vista de detalle del concepto

### Interacciones
- Crear nuevo concepto
- Editar concepto existente
- Eliminar concepto (soft delete)
- Filtrar por tipo, impuesto/servicio

### Permisos
- TESORERIA_RETENCIONES_VIEW: Ver retenciones
- TESORERIA_RETENCIONES_WRITE: Crear/editar retenciones
- TESORERIA_RETENCIONES_DELETE: Eliminar retenciones

## Backend

### Recursos/Endpoints
- GET /api/tesoreria/boniret - Listar conceptos
- GET /api/tesoreria/boniret/{id} - Obtener concepto
- POST /api/tesoreria/boniret - Crear concepto
- PUT /api/tesoreria/boniret/{id} - Actualizar concepto
- DELETE /api/tesoreria/boniret/{id} - Eliminar concepto

### Modelos
- Tabla: `boniret`
- Campos:
  - id (int, PK)
  - nombre (string 15, unique)
  - cuenta (int)
  - valor (decimal, nullable)
  - tipo (char 1: P o F)
  - impser (boolean)
  - acumula (boolean)
  - deleted_at (timestamp)

### Validaciones
- nombre: requerido, máximo 15 caracteres, único
- cuenta: requerida, debe existir en plan de cuentas
- tipo: requerido, solo 'P' o 'F'
- valor:
  - Si tipo='P': entre 0 y 100
  - Si tipo='F': mayor a 0
- impser: requerido, booleano
- acumula: requerido, booleano

### Relaciones
- cuenta → tabla `cuentas` (plan de cuentas)
- Usado en: generación de recibos

## Casos de uso

1. Crear retención IIBB del 2.5%
2. Crear retención de Ganancias del 3%
3. Aplicar retenciones en generación de recibo

Checklist de completitud

Antes de considerar completa una documentación, verificar:

• [ ] Título y metadata completos
• [ ] Descripción clara de la funcionalidad
• [ ] Sección Frontend completa con vistas, interacciones y permisos
• [ ] Sección Backend completa con endpoints, modelos y validaciones
• [ ] Casos de uso definidos
• [ ] Referencias a otras funcionalidades relacionadas
• [ ] Diagramas o ejemplos cuando sea necesario

Buenas prácticas

1. Sé específico: No usar términos genéricos, ser concreto
2. Incluye ejemplos: Casos de uso reales ayudan a entender
3. Mantén actualizado: Si cambia el código, actualiza la documentación
4. Usa referencias: Enlaza a otras documentaciones relacionadas
5. Diagramas visuales: Cuando el proceso es complejo, incluye diagramas
6. Formato consistente: Sigue siempre la misma estructura

Referencias

• Plantilla base
• Ejemplo completo: Boniret Resource
• Guía de Backend
• Guía de Frontend