Clientes
RN-CLI-01 — La identidad del cliente es un UUID, no su documento
Sección titulada «RN-CLI-01 — La identidad del cliente es un UUID, no su documento»Estado: ✅ Confirmada
Cada cliente tiene un UUID generado por el sistema como identificador interno. El número de documento es un atributo de búsqueda, no la clave.
| UUID | Documento | |
|---|---|---|
| Rol | Identidad interna | Dato de negocio |
| Lo genera | El sistema | Lo trae el cliente |
| ¿Puede faltar? | Nunca | Sí |
| ¿Puede cambiar? | Nunca | Sí (corrección de carga) |
Por qué: en venta a hogares muchas veces no hay documento a mano. Si el
documento fuera la clave, no podrías registrar al cliente hasta conseguirlo —
y el seller en la calle necesita registrar la venta ahora.
El saldo de deuda y el de botellones se acumulan por cliente: duplicar el cliente parte el saldo en dos y ninguno de los dos es real.
RN-CLI-08 — El documento es único: dos clientes nunca lo comparten
Sección titulada «RN-CLI-08 — El documento es único: dos clientes nunca lo comparten»Estado: ✅ Confirmada — obligatorio y único.
Un número de documento pertenece a una sola persona. El documento es obligatorio: no se registra un cliente sin él. Y el sistema impide registrar dos clientes con el mismo.
La restricción va sobre (tipo_documento, numero), no sobre el número suelto
— ver RN-CLI-09.
Por qué: es la defensa contra el duplicado. Sin esta restricción, el mismo cliente cargado dos veces parte su deuda y su saldo de botellones en dos, y ninguno de los dos es real.
RN-CLI-09 — El tipo de documento es explícito; el dígito de verificación se calcula
Sección titulada «RN-CLI-09 — El tipo de documento es explícito; el dígito de verificación se calcula»Estado: 🟡 Supuesto — propuesta de diseño sobre datos confirmados.
En Colombia conviven dos identificadores:
| Tipo | Quién | Número base | Formato |
|---|---|---|---|
| CC | Persona natural | Cédula | 79123456 |
| NIT | Contribuyente | Cédula (natural) o asignado por DIAN (empresa) | 900123456-8 |
El guion del NIT no separa dos datos: separa el número de su dígito de verificación (DV), que DIAN calcula con un algoritmo módulo 11 de pesos fijos sobre el número base.
Cómo se calcula el DV
Sección titulada «Cómo se calcula el DV»El algoritmo está definido en la Orden Administrativa 4 de 1989 de la DIAN. No es una convención nuestra ni una elección de diseño: es norma.
El DV es una función del número base — mismo número, mismo dígito, siempre. Por eso no hace falta pedirlo.
-
Se toman los 9 dígitos del NIT, completando con ceros a la izquierda si hace falta.
-
Se multiplica cada dígito por su peso, de izquierda a derecha:
41, 37, 29, 23, 19, 17, 13, 7, 3 -
Se suman los productos.
-
resto = suma mod 11. -
Si el resto es 0 o 1, el DV es el resto. Si es 2 o más,
DV = 11 − resto.
NIT base 900123456
dígito peso producto 9 41 369 0 37 0 0 29 0 1 23 23 2 19 38 3 17 51 4 13 52 5 7 35 6 3 18 ──── suma 586
586 mod 11 = 3 → DV = 11 − 3 = 8 → 900123456-8| NIT base | Suma | Resto | DV |
|---|---|---|---|
123456789 |
665 | 5 | 6 |
900123456 |
586 | 3 | 8 |
79123456 |
737 | 0 | 0 |
(La última fila muestra el caso resto = 0: ahí el DV es cero, no 11 − 0.)
Para qué sirve realmente: el DV no es seguridad, es detección de errores de transcripción. La secuencia de pesos son números primos justamente para eso: cambiar un dígito, o intercambiar dos vecinos, casi siempre produce un DV distinto.
Eso es lo que lo convierte en una validación: si alguien dicta un NIT completo y el dígito no coincide con el calculado, hay un número mal tomado — y se detecta en el momento, no cuando la factura electrónica rebota.
El modelo
Sección titulada «El modelo»tipo_documento CC | NIT ← explícito, elegido por el usuarionumero string ← sin DVdv derivado ← calculado, nunca capturadoEl DV no se almacena como dato de entrada. Se calcula. Si el usuario tiene el NIT completo a mano y escribe el dígito, se usa para validar — si no coincide con el calculado, hubo un error de tipeo y se avisa en el momento.
RN-CLI-10 — El documento tiene estado de verificación
Sección titulada «RN-CLI-10 — El documento tiene estado de verificación»Estado: ✅ Confirmada
Registrar el número y comprobar que sea cierto son dos cosas distintas. El sistema las separa:
| Estado | Cómo se llega | Qué significa |
|---|---|---|
🟡 PENDIENTE |
El cliente dictó el número | Nadie vio el documento físico |
✅ VERIFICADO |
Quien registró marcó que cotejó contra el documento físico | Alguien puso su nombre detrás del dato |
El estado por defecto es PENDIENTE. Pasar a VERIFICADO es una acción
deliberada del seller o del pos, y queda registrada con quién y cuándo.
Por qué: obliga a elegir entre frenar la venta y creerle a cualquiera. El
seller registra y vende ahora; el sistema sabe que ese dato todavía no está
comprobado y puede tratarlo distinto.
RN-CLI-11 — La copia local alcanza; el choque al sincronizar solo se registra
Sección titulada «RN-CLI-11 — La copia local alcanza; el choque al sincronizar solo se registra»Estado: ✅ Confirmada — alcance definido por Aquazaku.
El seller valida contra la copia local de documentos que trae de su última
sincronización. La lista es liviana —solo números— así que la app la lleva
completa y valida al instante, sin señal.
Eso alcanza. El seller sincroniza en su casa antes de salir y al mediodía;
la ventana en que su copia queda vieja es de pocas horas. Y con el volumen actual
de clientes, que dos seller registren la misma cédula el mismo día es
suficientemente improbable como para no construir nada alrededor.
Pero el rechazo hay que atenderlo igual
Sección titulada «Pero el rechazo hay que atenderlo igual»Esto no es una funcionalidad: es qué hace el sync cuando la base le dice que no. Y va a decir que no, porque RN-CLI-08 pone una restricción de unicidad que se aplica lo hayamos previsto o no.
El sync intenta crear el cliente → la base: "ese documento ya existe" → NO se crea un cliente nuevo → la venta se asocia al cliente que YA estaba → la discrepancia queda en el logEl documento es la clave natural para reconciliar, así que la venta encuentra sola a su dueño. Sin pantallas, sin decisiones manuales.
Por qué: es la primera consecuencia concreta del modo offline. El comportamiento ante rechazo va en el ADR de sincronización, junto con las otras tres decisiones (RN-RUT-05).
RN-CLI-02 — Un cliente no se borra, se desactiva
Sección titulada «RN-CLI-02 — Un cliente no se borra, se desactiva»Estado: 🟡 Supuesto
Un cliente con historial nunca se elimina. Se marca como inactivo y deja de aparecer en las operaciones nuevas.
Por qué: borrarlo rompe el historial de ventas y deja envases sin dueño.
RN-CLI-03 — El saldo del cliente es derivado, no editable
Sección titulada «RN-CLI-03 — El saldo del cliente es derivado, no editable»Estado: 🟡 Supuesto
saldo de deuda = ventas a crédito − cobros registradosNo existe “editar el saldo”. Se corrige con un documento: un cobro, una anulación o un ajuste con motivo.
Por qué: un saldo editable a mano hace que la cobranza deje de ser auditable. Es el mismo principio que RN-STK-02.
RN-CLI-04 — El crédito es una habilitación explícita con límite
Sección titulada «RN-CLI-04 — El crédito es una habilitación explícita con límite»Estado: 🟡 Supuesto
Un cliente no tiene crédito por defecto. Se le habilita, con un límite, y alguien queda registrado como responsable de esa habilitación.
Por qué: sin límite explícito la deuda crece hasta que alguien la nota, y para entonces ya es incobrable. Ver RN-VEN-05.
RN-CLI-05 — La ruta se asigna a la dirección, no al cliente
Sección titulada «RN-CLI-05 — La ruta se asigna a la dirección, no al cliente»Estado: ✅ Confirmada — modelo objetivo definido por Aquazaku.
Lo que pertenece a una ruta es la dirección. Un cliente con locales en zonas distintas puede tener cada uno en una ruta diferente.
Cliente "Panadería del Centro"├── Sucursal Norte → Ruta A├── Sucursal Sur → Ruta B└── Depósito → sin ruta (compra en mostrador)Por qué: el seller visita lugares, no razones sociales. Si la ruta colgara
del cliente, un cliente con tres locales en tres zonas obligaría a partirlo en
tres registros — y ahí se parten también su deuda y su saldo de botellones.
RN-CLI-06 — Un cliente tiene tres saldos distintos
Sección titulada «RN-CLI-06 — Un cliente tiene tres saldos distintos»Estado: ✅ Confirmada — granularidades verificadas con Aquazaku.
La ficha del cliente lleva tres cuentas que no se mezclan:
| Saldo | Unidad | Granularidad |
|---|---|---|
| Deuda | Dinero | Cliente |
| Botellones en su poder | Cantidad | Cliente |
| Bases prestadas | Lista de IDs | Dirección |
Por qué: son tres deudas distintas. Un cliente puede estar al día con la plata, deberte quince botellones y tener dos bases sin devolver. Un solo campo “estado de cuenta” no dice nada útil.
Ver Botellones y bases.
RN-CLI-07 — La dirección es una entidad, no un campo de texto
Sección titulada «RN-CLI-07 — La dirección es una entidad, no un campo de texto»Estado: ✅ Confirmada — se deriva de RN-BAS-03.
Un cliente tiene una o varias direcciones. Cada base prestada se asigna a una dirección concreta, no al cliente.
Cliente├── Dirección A → base #A-0412├── Dirección B → base #A-0913└── Dirección C → base #B-0027Por qué: si la dirección fuera un campo de texto en la ficha del cliente, no podrías responder “¿a cuál de sus tres locales voy a buscar la base #A-0913?”. El préstamo deja de ser reclamable.
Preguntas abiertas
Sección titulada «Preguntas abiertas»- ¿El número de documento es único? Sabemos que se filtra por él, no que identifique. Ver la recomendación en RN-CLI-01.
- ¿Se distinguen tipos de cliente (hogar vs. comercio) con precios distintos?
- ¿Qué pasa cuando un cliente supera su límite de crédito en plena ruta?
¿El
sellerpuede vender igual, o el sistema lo bloquea? - ¿Se cobra depósito o garantía por la base prestada?
- ¿Puede una dirección quedar sin ruta asignada? (Hoy sí: compra en mostrador.)