consultoria-as/Autoparts-DB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: documentacion completa — README, guia de uso, instalacion, API POS

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
consultoria-as
2026-04-02 03:38:10 +00:00
parent a389228048
commit fa7015e642
4 changed files with 2222 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1432
docs/API-POS.md Normal file
View File

File diff suppressed because it is too large Load Diff

377
docs/GUIA-DE-USO.md Normal file
View File

@@ -0,0 +1,377 @@
# Guia de Uso -- Nexus Autoparts POS
Manual de usuario para el sistema de Punto de Venta Nexus Autoparts.
---
## 1. Acceso al sistema
1. Abrir el navegador e ir a `http://[IP]:5001/pos/login`
2. Se muestra la lista de empleados del tenant
3. Seleccionar tu usuario
4. Escribir tu PIN de 4 digitos
5. El sistema te lleva al dashboard o al POS segun tu rol
**Primer acceso:** El PIN del dueno se configura al crear el tenant. El dueno puede crear empleados desde Configuracion.
**Seguridad:**
- 5 intentos fallidos por minuto maximo
- 10 intentos fallidos bloquean el dispositivo por 15 minutos
- Cada sesion genera un token JWT con duracion de 8 horas
---
## 2. Navegacion
- **Sidebar izquierdo**: contiene todas las secciones del sistema
- **Toggle de tema**: icono de luna/sol en la parte superior del sidebar para cambiar entre tema Industrial (oscuro) y Moderno (claro)
- **Logout**: boton en la parte inferior del sidebar
- **Breadcrumbs**: en el catalogo, muestran la ruta de navegacion actual
Las secciones visibles dependen del rol:
| Seccion | Dueno | Admin | Cajero | Almacenista | Contador |
|---------|-------|-------|--------|-------------|----------|
| Dashboard | Si | Si | No | No | No |
| Catalogo | Si | Si | Si | Si | Si |
| POS | Si | Si | Si | No | No |
| Inventario | Si | Si | No | Si | No |
| Clientes | Si | Si | Si | No | Si |
| Facturacion | Si | Si | No | No | Si |
| Contabilidad | Si | No | No | No | Si |
| Reportes | Si | Si | No | No | Si |
| Configuracion | Si | Si | No | No | No |
---
## 3. Catalogo
El catalogo conecta con la base de datos maestra TecDoc (1.5M+ partes OEM) y muestra stock local.
### Navegacion por vehiculo
1. **Marca** -- seleccionar marca del vehiculo (Toyota, Nissan, Ford, etc.)
2. **Modelo** -- seleccionar modelo (Corolla, Sentra, F-150, etc.)
3. **Ano** -- seleccionar ano del vehiculo
4. **Motor** -- seleccionar motorizacion
5. **Categoria** -- categoria de partes (Frenos, Motor, Suspension, etc.)
6. **Subcategoria** -- grupo especifico (Pastillas, Discos, Balatas, etc.)
7. **Partes** -- lista de partes con numero OEM, precio y stock
### Busqueda inteligente
- Escribir en la barra de busqueda un **numero de parte** (ej. "04465-02220") o **texto** (ej. "pastillas corolla")
- El sistema busca en partes OEM, aftermarket y cross-references
- Resultados muestran stock local y alternativas disponibles
### Panel de detalle
Al seleccionar una parte se abre un panel lateral con:
- Numero de parte OEM y descripcion
- **Stock local**: cantidad en la sucursal actual
- **Stock en bodegas**: disponibilidad en otras sucursales
- **Alternativas**: partes aftermarket equivalentes con precios
- **Cross-references**: numeros alternos de otras marcas
### Carrito
- Hacer clic en "Agregar" para anadir partes al carrito
- El carrito muestra cantidad, precio unitario y subtotal
- Boton **"Ir a cobrar"** salta directamente al POS con las partes cargadas
### Modo offline
Cuando no hay conexion a internet:
- Solo se muestra el inventario local (partes en la sucursal)
- La navegacion TecDoc no esta disponible
- Al restaurar la conexion, se sincronizan las operaciones pendientes
---
## 4. Punto de Venta (POS)
Pantalla principal de cobro con atajos de teclado para operacion rapida.
### Operacion basica
1. **Buscar parte** (F1): escribir numero de parte o descripcion
2. **Seleccionar cliente** (F2): buscar por nombre, RFC o telefono. Si no se selecciona, se vende a "Publico General"
3. Las partes se agregan a la lista con cantidad, precio y descuento
4. **Cobrar** (F3): abrir dialogo de pago
### Metodos de pago
| Metodo | Descripcion |
|--------|-------------|
| Efectivo | Calcula cambio automaticamente |
| Transferencia | Registra referencia bancaria |
| Tarjeta | Registra numero de autorizacion |
| Mixto | Combina dos o mas metodos |
### Tipos de operacion
- **Venta directa** (F3): cobro inmediato, descuenta inventario
- **Cotizacion** (F4): guarda sin cobrar, se puede convertir a venta despues
- **Apartado**: reserva partes con pago parcial (enganche minimo configurable). El cliente hace pagos subsecuentes hasta completar
- **Credito**: venta a cuenta del cliente (requiere cliente con credito autorizado y limite suficiente)
### Atajos de teclado
| Tecla | Accion |
|-------|--------|
| F1 | Buscar parte |
| F2 | Seleccionar cliente |
| F3 | Cobrar |
| F4 | Cotizacion |
| F5 | Apartado |
| F6 | Ultimo ticket |
| + / - | Aumentar/disminuir cantidad |
| * | Editar cantidad directa |
| Enter | Confirmar |
| Delete | Eliminar linea |
| Escape | Cancelar / cerrar dialogo |
### Margen y costos
- La columna de **costo** y **margen** solo es visible para roles Dueno y Admin
- El cajero solo ve precio de venta
---
## 5. Inventario
Gestion completa de productos y stock.
### Tab Productos
- **Ver**: lista paginada con busqueda por nombre, SKU o codigo de barras
- **Crear**: nuevo producto con nombre, SKU, codigo de barras, costo, precios (mostrador/taller/mayoreo), stock minimo, stock maximo, ubicacion en almacen
- **Editar**: modificar datos del producto
### Tab Entradas (Compras)
- Registrar compra a proveedor
- Campos: proveedor, factura del proveedor, lista de productos con cantidad y costo
- El stock se incrementa automaticamente
- Se genera movimiento en el historial
### Tab Ajustes
- Ajuste manual de inventario (merma, error de conteo, dano, etc.)
- **Requiere motivo**: el sistema no permite ajustes sin explicacion
- Genera registro en auditoria con usuario, fecha y motivo
### Tab Transferencias
- Mover productos entre sucursales
- Origen y destino, lista de productos con cantidad
- Descuenta del origen y suma al destino
- Rastrea estado: pendiente, en transito, recibida
### Tab Toma Fisica
1. **Iniciar conteo**: genera documento de toma fisica
2. **Capturar conteos**: registrar cantidades fisicas por producto
3. **Comparar**: el sistema muestra diferencias vs stock teorico
4. **Aprobar**: aplica los ajustes automaticamente
### Tab Alertas
- **Stock en cero**: productos sin existencia
- **Bajo minimo**: productos por debajo del punto de reorden
- **Sobre maximo**: productos con sobreinventario
### Tab Reportes de Inventario
| Reporte | Descripcion |
|---------|-------------|
| Valorizacion | Valor total del inventario a costo y a precio de venta |
| ABC | Clasificacion de productos por volumen de venta (A=80%, B=15%, C=5%) |
| Sin movimiento | Productos sin venta en X dias |
| Stock bajo | Productos por debajo del minimo |
| Comparativo sucursales | Stock del mismo producto en todas las sucursales |
---
## 6. Clientes
### Crear cliente
Campos principales:
- Nombre / Razon social
- RFC (para facturacion)
- Regimen fiscal SAT
- Codigo postal fiscal
- Uso de CFDI (ej. G03 Gastos en general)
- Telefono, email
- Direccion
### Tiers de precio
Cada cliente pertenece a un tier que determina el precio automatico:
| Tier | Descripcion |
|------|-------------|
| Mostrador | Precio publico (default) |
| Taller | Descuento para talleres mecanicos |
| Mayoreo | Mejor precio para compradores de volumen |
### Credito
- Asignar limite de credito al cliente
- El sistema valida que el saldo no exceda el limite al crear ventas a credito
- **Estado de cuenta**: muestra compras, pagos y saldo pendiente
- **Registrar pago**: abono parcial o total a la cuenta
### Vehiculos
- Asociar vehiculos al cliente (marca, modelo, ano, motor, placas, VIN)
- Facilita la busqueda de partes en futuras visitas
### Historial
- Ver todas las compras del cliente con fecha, total y estatus
---
## 7. Facturacion CFDI
### Generar factura
1. Ir a Facturacion
2. Seleccionar una venta completada
3. Verificar datos fiscales del cliente (RFC, razon social, regimen, CP, uso CFDI)
4. Generar factura -- se crea el XML CFDI 4.0
### Tipos de comprobante
| Tipo | Uso |
|------|-----|
| Ingreso | Factura de venta normal |
| Egreso | Nota de credito (devolucion/cancelacion) |
| Pago | Complemento de pago para ventas a credito (PPD) |
### Cola de timbrado
- Las facturas se encolan para envio al PAC (Horux)
- El PAC firma el XML con el CSD del contribuyente
- Estado: pendiente, timbrada, error, cancelada
- Reintentar facturas con error
### Cancelacion
- Seleccionar factura a cancelar
- Indicar motivo SAT:
- 01: Comprobante emitido con errores con relacion
- 02: Comprobante emitido con errores sin relacion
- 03: No se llevo a cabo la operacion
- 04: Operacion nominativa relacionada en una factura global
- Si el motivo es 01, indicar el UUID de la factura sustituta
### PDF
- Descargar representacion impresa (PDF) de cualquier factura timbrada
---
## 8. Contabilidad
### Polizas automaticas
Cada venta genera automaticamente una poliza contable:
- Cargo a Caja/Bancos (por el monto cobrado)
- Abono a Ventas (por el subtotal)
- Abono a IVA Trasladado (por el impuesto)
- Cargo a Costo de Ventas / Abono a Inventario (por el costo)
### Catalogo de cuentas
- Basado en el catalogo SAT
- Estructura jerarquica: Activo, Pasivo, Capital, Ingresos, Costos, Gastos
- Cada cuenta tiene codigo SAT, nombre, tipo (deudora/acreedora), nivel
### Reportes financieros
| Reporte | Descripcion |
|---------|-------------|
| Balanza de comprobacion | Saldos iniciales + movimientos del periodo + saldos finales |
| Estado de resultados | Ingresos - Costos - Gastos = Utilidad del periodo |
| Balance general | Activo = Pasivo + Capital a una fecha |
| Antiguedad de saldos | Cuentas por cobrar agrupadas por dias de atraso (0-30, 31-60, 61-90, 90+) |
### Periodos fiscales
- Ver periodos mensuales con estado (abierto/cerrado)
- Cerrar periodo: bloquea movimientos en ese mes. Esta accion es irreversible.
---
## 9. Caja Registradora
### Flujo diario
1. **Abrir caja**: indicar numero de caja y fondo inicial en efectivo
2. **Operar**: las ventas se registran automaticamente en la caja abierta
3. **Movimientos**: registrar entradas (cobros externos, cambio) o salidas (gastos menores, compras) de efectivo con motivo
4. **Corte X**: consulta de ventas y movimientos sin cerrar la caja
5. **Corte Z**: cierre de caja con conteo final. El sistema calcula la diferencia entre lo esperado y lo contado
### Multi-caja
- Cada cajero abre su propia sesion de caja
- Un empleado solo puede tener una caja abierta a la vez
- El numero de caja identifica la caja fisica (1, 2, 3...)
### Historial
- Consultar cortes anteriores con detalle de ventas, movimientos y diferencias
### Resumen diario
- Vista consolidada de todas las cajas del dia
---
## 10. Dashboard (Dueno)
Pantalla de resumen ejecutivo disponible solo para Dueno y Admin:
- **Ventas del dia** vs meta configurada
- **Cajas activas**: cuantas cajas estan abiertas y quien las opera
- **Alertas**: productos sin stock, facturas con error, cajas sin cerrar
- **Resumen semanal**: grafico de ventas de los ultimos 7 dias
---
## 11. Configuracion
### Datos del negocio
- Nombre, RFC, regimen fiscal, direccion, logo
- Configuracion de CFDI (serie, folio, certificados)
### Sucursales
- Crear y editar sucursales
- Nombre, direccion, telefono
- Activar/desactivar sucursal
### Empleados y roles
- Crear empleados con nombre, telefono, email, PIN y rol
- Roles disponibles:
| Rol | Permisos principales |
|-----|---------------------|
| Dueno | Todo (no se puede eliminar) |
| Admin | Todo excepto configuracion de tenant |
| Cajero | POS, catalogo, clientes basico |
| Almacenista | Inventario completo, catalogo |
| Contador | Contabilidad, facturacion, reportes |
- Cada rol tiene permisos granulares que se asignan automaticamente
### Temas
- **Industrial**: tema oscuro con tonos grafito y acentos naranja
- **Moderno**: tema claro con tonos blancos y azul primario
- El toggle esta en el sidebar y se aplica inmediatamente

272
docs/INSTALACION.md Normal file
View File

@@ -0,0 +1,272 @@
# Guia de Instalacion -- Nexus Autoparts
Instrucciones para instalar y poner en marcha el sistema Nexus Autoparts POS.
---
## Requisitos del sistema
| Componente | Minimo | Recomendado |
|------------|--------|-------------|
| OS | Linux (Debian 12 / Ubuntu 22.04 / Raspberry Pi OS) | Debian 13 o Ubuntu 24.04 |
| Python | 3.11+ | 3.12+ |
| PostgreSQL | 15+ | 16+ |
| RAM | 2 GB | 4 GB |
| Disco | 20 GB (SSD recomendado) | 50 GB SSD |
| Red | LAN | LAN + acceso a internet para TecDoc y timbrado CFDI |
---
## Instalacion paso a paso
### 1. Instalar dependencias del sistema
```bash
sudo apt update && sudo apt install -y \
python3 python3-pip python3-venv \
postgresql postgresql-client \
git
```
### 2. Configurar PostgreSQL
```bash
# Crear usuario y base de datos maestra (catalogo TecDoc)
sudo -u postgres createuser nexus -P
# Cuando pida password: nexus_autoparts_2026
sudo -u postgres createdb nexus_autoparts -O nexus
sudo -u postgres psql -c "ALTER ROLE nexus CREATEDB;"
```
El permiso `CREATEDB` es necesario porque el sistema crea una base de datos separada por cada tenant (cliente).
### 3. Clonar el repositorio
```bash
git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git /home/Autopartes
```
### 4. Instalar dependencias Python
```bash
pip install -r /home/Autopartes/pos/requirements.txt --break-system-packages
```
O con un entorno virtual:
```bash
python3 -m venv /home/Autopartes/venv
source /home/Autopartes/venv/bin/activate
pip install -r /home/Autopartes/pos/requirements.txt
```
### 5. Cargar schema de la base maestra (catalogo)
```bash
sudo -u postgres psql nexus_autoparts < /home/Autopartes/vehicle_database/sql/schema.sql
```
### 6. Crear el primer tenant
```bash
cd /home/Autopartes/pos
python3 -c "
from services.tenant_manager import provision_tenant
result = provision_tenant(
'Mi Refaccionaria',
rfc='RFC000000AAA',
owner_name='Admin',
owner_pin='1234'
)
print(result)
"
```
Esto crea:
- Una entrada en la tabla maestra de tenants
- Una base de datos `tenant_mi_refaccionaria` con todas las tablas del POS
- Un empleado "Admin" con rol "owner" y PIN 1234
### 7. Aplicar migraciones
```bash
cd /home/Autopartes/pos
python3 -c "
from tenant_db import get_tenant_conn_by_dbname
conn = get_tenant_conn_by_dbname('tenant_mi_refaccionaria')
cur = conn.cursor()
with open('migrations/v1.1_pos_tables.sql') as f:
cur.execute(f.read())
conn.commit()
print('Migraciones aplicadas correctamente')
"
```
### 8. Iniciar el POS
```bash
cd /home/Autopartes/pos
python3 app.py
```
Acceder desde el navegador:
```
http://[IP-del-servidor]:5001/pos/login
PIN: 1234
```
### 9. (Opcional) Iniciar la web publica
```bash
cd /home/Autopartes/dashboard
python3 server.py
```
Acceder: `http://[IP-del-servidor]:5000`
---
## Importar datos TecDoc
Para tener el catalogo de partes OEM y aftermarket:
```bash
cd /home/Autopartes
# Fase 1: descargar datos de TecDoc API a archivos JSON
python3 scripts/import_tecdoc.py download
# Fase 2: importar JSON a PostgreSQL
python3 scripts/import_tecdoc.py import
# Ver progreso
python3 scripts/import_tecdoc.py status
```
El script es **resumible**: si se interrumpe, al volver a ejecutar salta los archivos ya descargados.
---
## Instalacion como servicio (systemd)
### POS (puerto 5001)
Crear el archivo `/etc/systemd/system/nexus-pos.service`:
```ini
[Unit]
Description=Nexus Autoparts POS
After=postgresql.service
Wants=postgresql.service
[Service]
Type=simple
WorkingDirectory=/home/Autopartes/pos
ExecStart=/usr/bin/python3 app.py
Restart=always
RestartSec=5
User=root
Environment=PYTHONUNBUFFERED=1
[Install]
WantedBy=multi-user.target
```
### Web publica (puerto 5000)
Crear el archivo `/etc/systemd/system/nexus-web.service`:
```ini
[Unit]
Description=Nexus Autoparts Web Publica
After=postgresql.service
Wants=postgresql.service
[Service]
Type=simple
WorkingDirectory=/home/Autopartes/dashboard
ExecStart=/usr/bin/python3 server.py
Restart=always
RestartSec=5
User=root
Environment=PYTHONUNBUFFERED=1
[Install]
WantedBy=multi-user.target
```
### Activar los servicios
```bash
sudo systemctl daemon-reload
sudo systemctl enable nexus-pos nexus-web
sudo systemctl start nexus-pos nexus-web
# Verificar estado
sudo systemctl status nexus-pos
sudo systemctl status nexus-web
```
---
## Instalacion en Raspberry Pi 5
El POS esta optimizado para correr en Raspberry Pi 5.
### Hardware recomendado
| Componente | Especificacion | Precio aprox. |
|------------|---------------|---------------|
| Raspberry Pi 5 | 8 GB RAM | $80 USD |
| SSD NVMe | 256 GB (via HAT M.2) | $30 USD |
| Case con ventilador | Oficial o Argon | $15 USD |
| Fuente USB-C | 5V 5A oficial | $12 USD |
| MicroSD | 32 GB (solo para boot) | $5 USD |
| **Total** | | **~$142 USD** |
### Pasos adicionales para RPi 5
1. Instalar Raspberry Pi OS (64-bit, Debian Bookworm)
2. Configurar boot desde SSD NVMe (no usar MicroSD como disco principal)
3. Seguir los mismos pasos de instalacion de arriba
4. Para acceso desde tablets/celulares en la misma red LAN, usar la IP local del RPi
### Rendimiento esperado
- Consultas de catalogo: < 200ms
- Busqueda de partes: < 500ms
- Transacciones POS: < 100ms
- Soporte simultaneo: 3-5 terminales sin degradacion
---
## Verificacion post-instalacion
```bash
# Verificar que PostgreSQL esta corriendo
sudo systemctl status postgresql
# Verificar que el POS responde
curl http://localhost:5001/pos/health
# Debe responder: {"status":"ok"}
# Verificar la base maestra
sudo -u postgres psql nexus_autoparts -c "SELECT count(*) FROM parts;"
# Verificar tenant
sudo -u postgres psql tenant_mi_refaccionaria -c "SELECT name, role FROM employees;"
```
---
## Troubleshooting
| Problema | Solucion |
|----------|----------|
| `psycopg2` no instala | `sudo apt install libpq-dev python3-dev` y reinstalar |
| Puerto 5001 ocupado | `sudo lsof -i :5001` para ver que proceso lo usa |
| "Tenant not found" | Verificar que `provision_tenant` se ejecuto correctamente |
| PIN bloqueado | Esperar 15 minutos o reiniciar el servicio POS |
| Base de datos no conecta | Verificar credenciales en `pos/config.py` |