docs: update API, architecture, installation guides and README
- API-POS.md: added sections 11-15 (BNPL, ERP, WhatsApp Cloud, Supplier Portal, Dashboard Stats) - ARCHITECTURE.md: added infra/monitoring section with systemd, Prometheus/Grafana, PWA, and integration stubs - INSTALACION.md: added systemd setup, monitoring docker compose, PWA install notes, and Playwright test commands - README.md: updated endpoint count, tech stack, infrastructure table
This commit is contained in:
23
README.md
23
README.md
@@ -27,7 +27,7 @@ Sistema integral que combina un catalogo publico de autopartes con un Punto de V
|
||||
- **Multi-tenant**: base de datos aislada por cliente
|
||||
- **PWA**: instalable en tablets/celulares, modo offline
|
||||
- **10 pantallas**: Login, Catalogo, Inventario, POS, Clientes, Facturacion, Contabilidad, Dashboard, Reportes, Configuracion
|
||||
- **81+ endpoints API** organizados en 9 blueprints
|
||||
- **100+ endpoints API** organizados en 15+ blueprints
|
||||
- **2 temas**: Industrial oscuro + Moderno claro (toggle en sidebar)
|
||||
- **Auth por PIN** con JWT + rate limiting + bloqueo por dispositivo
|
||||
- **5 roles**: Dueno, Admin, Cajero, Almacenista, Contador
|
||||
@@ -43,7 +43,7 @@ Sistema integral que combina un catalogo publico de autopartes con un Punto de V
|
||||
| Facturacion | CFDI 4.0 (Ingreso, Egreso, Pago), cola de timbrado, cancelacion SAT |
|
||||
| Contabilidad | Polizas automaticas, catalogo SAT, balanza, estado de resultados, balance general, antiguedad |
|
||||
| Caja Registradora | Apertura, movimientos, corte X, corte Z, multi-caja |
|
||||
| Dashboard | Ventas del dia vs meta, cajas activas, alertas |
|
||||
| Dashboard | Ventas del dia vs meta, cajas activas, alertas, graficos en tiempo real |
|
||||
| Reportes | Financieros y operativos |
|
||||
| Configuracion | Negocio, sucursales, empleados, roles, temas |
|
||||
|
||||
@@ -60,8 +60,13 @@ Sistema integral que combina un catalogo publico de autopartes con un Punto de V
|
||||
| CFDI | lxml (XML builder CFDI 4.0) |
|
||||
| Frontend | HTML/CSS/JS vanilla (sin framework) |
|
||||
| Estilos | CSS custom properties (design tokens) |
|
||||
| PWA | Service Worker + manifest |
|
||||
| PWA | Service Worker + manifest + install prompt |
|
||||
| Data import | TecDoc via Apify, NHTSA VIN API |
|
||||
| Monitoreo | Prometheus + Grafana (Docker) |
|
||||
| Tests E2E | Playwright |
|
||||
| BNPL | APLAZO / Kueski / Clip (stub) |
|
||||
| ERP Sync | Aspel / CONTPAQi / SAP / Odoo (stub) |
|
||||
| WhatsApp | Baileys webhook + Meta Cloud API (stub) |
|
||||
|
||||
---
|
||||
|
||||
@@ -77,6 +82,18 @@ Sistema integral que combina un catalogo publico de autopartes con un Punto de V
|
||||
|
||||
---
|
||||
|
||||
## Infraestructura Desplegada
|
||||
|
||||
| Servicio | Puerto | Estado |
|
||||
|----------|--------|--------|
|
||||
| POS (Gunicorn) | 5001 | Production |
|
||||
| Dashboard (Flask) | 5000 | Production |
|
||||
| Quart Async Catalog | 5002 | Production |
|
||||
| Prometheus | 9090 | Docker |
|
||||
| Grafana | 3001 | Docker |
|
||||
| Meilisearch | 7700 | Docker |
|
||||
| Metabase | 3000 | Docker |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Requisitos
|
||||
|
||||
150
docs/API-POS.md
150
docs/API-POS.md
@@ -1430,3 +1430,153 @@ Todos los errores retornan:
|
||||
```json
|
||||
{"error": "Descripcion del error"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. BNPL (Buy Now Pay Later) — Stub
|
||||
|
||||
Prefix: `/pos/api/bnpl`
|
||||
|
||||
Stubs ready for APLAZO, Kueski, Clip integration.
|
||||
|
||||
### GET /providers
|
||||
|
||||
List configured BNPL providers.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"providers": [
|
||||
{"id": "ap lazo", "name": "APLAZO", "enabled": false, "config_needed": ["api_key", "merchant_id"]},
|
||||
{"id": "kueski", "name": "Kueski Pay", "enabled": false, "config_needed": ["api_key", "secret"]},
|
||||
{"id": "clip", "name": "Clip Pagos", "enabled": false, "config_needed": ["api_key"]}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /applications
|
||||
|
||||
Create a BNPL application for a sale.
|
||||
|
||||
**Request body:**
|
||||
```json
|
||||
{
|
||||
"sale_id": 123,
|
||||
"amount": 1500.00,
|
||||
"provider": "ap lazo",
|
||||
"customer": {"name": "Juan Perez", "phone": "5512345678"}
|
||||
}
|
||||
```
|
||||
|
||||
### GET /applications/:id
|
||||
|
||||
Get application status.
|
||||
|
||||
### POST /webhook/:provider
|
||||
|
||||
Receive provider webhooks.
|
||||
|
||||
---
|
||||
|
||||
## 12. ERP Sync — Stub
|
||||
|
||||
Prefix: `/pos/api/erp`
|
||||
|
||||
Stubs ready for Aspel SAE, CONTPAQi, SAP B1, Odoo.
|
||||
|
||||
### GET /providers
|
||||
|
||||
List supported ERP systems.
|
||||
|
||||
### POST /sync
|
||||
|
||||
Start a sync job.
|
||||
|
||||
**Request body:**
|
||||
```json
|
||||
{
|
||||
"provider": "aspel_sae",
|
||||
"sync_type": "sales"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /sync/:job_id
|
||||
|
||||
Get sync job status.
|
||||
|
||||
### POST /sync/:job_id/run
|
||||
|
||||
Mock execute sync job.
|
||||
|
||||
---
|
||||
|
||||
## 13. WhatsApp Business API (Meta Cloud) — Stub
|
||||
|
||||
Prefix: `/pos/api/whatsapp-cloud`
|
||||
|
||||
### GET/POST /webhook
|
||||
|
||||
Meta Cloud API webhook verification and message reception.
|
||||
|
||||
### GET /status
|
||||
|
||||
Check Meta Cloud API connection status.
|
||||
|
||||
### GET /templates
|
||||
|
||||
List approved message templates.
|
||||
|
||||
### POST /messages
|
||||
|
||||
Send a message.
|
||||
|
||||
**Request body:**
|
||||
```json
|
||||
{
|
||||
"to": "5215512345678",
|
||||
"body": "Su orden esta lista",
|
||||
"template": "order_ready"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Supplier Portal
|
||||
|
||||
Prefix: `/pos/api/supplier-portal`
|
||||
|
||||
### GET /demand
|
||||
|
||||
Aggregated demand by zone, part group, and time range.
|
||||
|
||||
**Query params:** `days` (default 30), `group_id`, `branch_id`
|
||||
|
||||
### GET /top-parts
|
||||
|
||||
Top 50 moving parts with current stock.
|
||||
|
||||
**Query params:** `days` (default 30)
|
||||
|
||||
---
|
||||
|
||||
## 15. Dashboard Stats
|
||||
|
||||
Prefix: `/pos/api/dashboard`
|
||||
|
||||
### GET /stats
|
||||
|
||||
Summary stats for today and this month.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"today": {"sales_count": 42, "sales_total": 12500.00},
|
||||
"month": {"sales_count": 1200, "sales_total": 450000.00},
|
||||
"top_products": [...],
|
||||
"hourly_sales": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### GET /stats/employees
|
||||
|
||||
Sales per employee today.
|
||||
|
||||
@@ -447,3 +447,42 @@ const data = await res.json();
|
||||
### Nota sobre NUMERIC de PostgreSQL
|
||||
|
||||
PostgreSQL retorna valores `NUMERIC` como strings. Todas las funciones de formato en JS usan `parseFloat()` para convertir antes de mostrar.
|
||||
|
||||
---
|
||||
|
||||
## Infraestructura y Monitoreo (2026-04)
|
||||
|
||||
### Servicios Systemd
|
||||
|
||||
| Servicio | Descripcion | Puerto |
|
||||
|----------|-------------|--------|
|
||||
| `nexus-pos.service` | Gunicorn POS (Flask) | 5001 |
|
||||
| `nexus.service` | Dashboard (Flask) | 5000 |
|
||||
| `nexus-quart.service` | Hypercorn async catalog | 5002 |
|
||||
| `nexus-celery.service` | Celery workers | — |
|
||||
| `nexus-mv-refresh.timer` | Refresh MV diario 03:00 UTC | — |
|
||||
| `nexus-cache-warm.timer` | Cache warming diario 04:00 UTC | — |
|
||||
|
||||
### Monitoreo (Prometheus + Grafana)
|
||||
|
||||
- **Prometheus** :9090 — métricas de sistema, PostgreSQL, Redis
|
||||
- **Grafana** :3001 — dashboards visuales (login admin/nexus2026)
|
||||
- Exporters: node-exporter, postgres-exporter, redis-exporter
|
||||
|
||||
### Stubs de Integraciones de Negocio
|
||||
|
||||
- **BNPL** (`bnpl_bp.py`): APLAZO, Kueski, Clip
|
||||
- **ERP Sync** (`erp_bp.py`): Aspel SAE, CONTPAQi, SAP B1, Odoo
|
||||
- **WhatsApp Meta Cloud** (`whatsapp_cloud_bp.py`): reemplazo escalable de Baileys
|
||||
- **Supplier Portal** (`supplier_portal_bp.py`): demanda por zona y top partes
|
||||
|
||||
### PWA
|
||||
|
||||
- Service Worker (`pos/static/pwa/sw.js`) con cache-first para assets
|
||||
- Install prompt (`pos/static/js/pwa-install.js`) captura `beforeinstallprompt`
|
||||
- Manifest registrado en 14 templates POS
|
||||
|
||||
### Tests E2E
|
||||
|
||||
- Playwright + Chromium
|
||||
- Primer smoke test: login page loads and rejects invalid credentials
|
||||
|
||||
@@ -280,3 +280,39 @@ sudo -u postgres psql tenant_mi_refaccionaria -c "SELECT name, role FROM employe
|
||||
| "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` |
|
||||
|
||||
---
|
||||
|
||||
## Servicios Systemd (Produccion)
|
||||
|
||||
Despues de la instalacion, copiar los servicios y habilitarlos:
|
||||
|
||||
```bash
|
||||
sudo cp systemd/*.service systemd/*.timer /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now nexus-pos.service nexus.service nexus-celery.service nexus-quart.service
|
||||
sudo systemctl enable --now nexus-mv-refresh.timer nexus-cache-warm.timer
|
||||
```
|
||||
|
||||
## Monitoreo (Opcional)
|
||||
|
||||
Levantar Prometheus + Grafana:
|
||||
|
||||
```bash
|
||||
cd docker
|
||||
docker compose -f docker-compose.monitoring.yml up -d
|
||||
```
|
||||
|
||||
- Grafana: http://servidor:3001 (admin / nexus2026)
|
||||
- Prometheus: http://servidor:9090
|
||||
|
||||
## PWA (Instalable)
|
||||
|
||||
El POS ya incluye Service Worker y manifest. Al abrir cualquier pagina del POS en Chrome/Edge, aparecera un banner para instalar la app. Requiere HTTPS en produccion para el prompt automatico.
|
||||
|
||||
## Tests E2E (Playwright)
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user