rckrdmrd
c24f889f70
Some checks failed
Build / Build Backend (push) Has been cancelled
Build / Build Mobile (TypeScript Check) (push) Has been cancelled
Lint / Lint Backend (push) Has been cancelled
Lint / Lint Mobile (push) Has been cancelled
Test / Backend E2E Tests (push) Has been cancelled
Test / Mobile Unit Tests (push) Has been cancelled
Build / Build Docker Image (push) Has been cancelled
- Add exports module with PDF/CSV/Excel generation - Add reports module for inventory analytics - Add POS integrations module - Add database migrations for exports, movements and integrations - Add GitHub Actions CI/CD workflow with Docker support - Add mobile export and reports screens with tests - Update epic documentation with traceability - Add deployment and security guides Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
339 lines
14 KiB
Markdown
339 lines
14 KiB
Markdown
# MII-015: Administracion SaaS
|
||
|
||
---
|
||
id: MII-015
|
||
type: Epic
|
||
status: Completado
|
||
priority: P2
|
||
phase: 4
|
||
story_points: 13
|
||
created_date: 2026-01-10
|
||
updated_date: 2026-01-13
|
||
simco_version: "4.0.0"
|
||
---
|
||
|
||
## Metadata
|
||
|
||
| Campo | Valor |
|
||
|-------|-------|
|
||
| **ID** | MII-015 |
|
||
| **Nombre** | Administracion SaaS |
|
||
| **Fase** | 4 - Crecimiento |
|
||
| **Prioridad** | P2 |
|
||
| **Story Points** | 13 |
|
||
| **Estado** | Completado |
|
||
|
||
---
|
||
|
||
## 1. Descripcion
|
||
|
||
Implementar el panel de administracion para gestionar la plataforma SaaS, incluyendo configuracion de costos, paquetes, referidos, productos y metricas del negocio.
|
||
|
||
### Objetivo
|
||
|
||
Proporcionar herramientas para operar y optimizar el negocio de MiInventario.
|
||
|
||
---
|
||
|
||
## 2. Requerimientos Relacionados
|
||
|
||
| RF | Descripcion | Prioridad |
|
||
|----|-------------|-----------|
|
||
| FR-120 | Configuracion de costos (proveedores IA, costos) | P1 |
|
||
| FR-121 | Gestion de paquetes (montos, bonos, equivalencias) | P1 |
|
||
| FR-122 | Gestion de referidos (niveles, rewards, topes) | P2 |
|
||
| FR-123 | Revision de productos (moderar nuevos SKUs) | P2 |
|
||
| FR-124 | Metricas (consumo, COGS, margen, tasa error) | P1 |
|
||
|
||
---
|
||
|
||
## 3. Criterios de Aceptacion
|
||
|
||
### AC-001: Dashboard de Metricas
|
||
```gherkin
|
||
DADO que soy administrador
|
||
CUANDO accedo al dashboard
|
||
ENTONCES veo metricas clave:
|
||
- Usuarios activos
|
||
- Sesiones por dia/semana/mes
|
||
- Revenue y COGS
|
||
- Margen bruto
|
||
- Precision promedio
|
||
```
|
||
|
||
### AC-002: Configurar Proveedores IA
|
||
```gherkin
|
||
DADO que soy administrador
|
||
CUANDO configuro proveedores IA
|
||
ENTONCES puedo:
|
||
- Ver proveedores disponibles
|
||
- Configurar costos por proveedor
|
||
- Activar/desactivar proveedores
|
||
- Ver consumo por proveedor
|
||
```
|
||
|
||
### AC-003: Gestionar Paquetes
|
||
```gherkin
|
||
DADO que soy administrador
|
||
CUANDO gestiono paquetes
|
||
ENTONCES puedo:
|
||
- Ver paquetes actuales
|
||
- Modificar precios
|
||
- Activar promociones
|
||
- Ver ventas por paquete
|
||
```
|
||
|
||
### AC-004: Moderar Productos
|
||
```gherkin
|
||
DADO que hay productos pendientes de revision
|
||
CUANDO modero productos
|
||
ENTONCES puedo:
|
||
- Ver submissions pendientes
|
||
- Aprobar o rechazar
|
||
- Fusionar con productos existentes
|
||
- Editar detalles
|
||
```
|
||
|
||
### AC-005: Revisar Referidos Sospechosos
|
||
```gherkin
|
||
DADO que hay referidos en hold por fraude
|
||
CUANDO reviso los casos
|
||
ENTONCES puedo:
|
||
- Ver senales de fraude
|
||
- Aprobar o rechazar
|
||
- Bloquear usuarios
|
||
- Liberar o cancelar recompensas
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Tareas Tecnicas
|
||
|
||
| ID | Tarea | Estimacion | Estado |
|
||
|----|-------|------------|--------|
|
||
| T-001 | Crear modulo admin en NestJS | 1 SP | Completado |
|
||
| T-002 | Implementar dashboard de metricas | 3 SP | Completado |
|
||
| T-003 | Crear CRUD de proveedores IA | 2 SP | Completado |
|
||
| T-004 | Crear CRUD de paquetes y promos | 2 SP | Completado |
|
||
| T-005 | Implementar moderacion de productos | 2 SP | Completado |
|
||
| T-006 | Crear revision de referidos | 2 SP | Completado |
|
||
| T-007 | Implementar frontend admin (web) | 1 SP | Completado |
|
||
|
||
---
|
||
|
||
## 5. Roles de Administracion
|
||
|
||
| Rol | Permisos |
|
||
|-----|----------|
|
||
| SUPER_ADMIN | Todos |
|
||
| ADMIN | Metricas, paquetes, productos |
|
||
| MODERATOR | Solo productos y referidos |
|
||
| VIEWER | Solo lectura |
|
||
|
||
---
|
||
|
||
## 6. Endpoints API
|
||
|
||
| Metodo | Endpoint | Descripcion | Auth |
|
||
|--------|----------|-------------|------|
|
||
| GET | /admin/dashboard | Metricas principales | Admin |
|
||
| GET | /admin/providers | Listar proveedores IA | Admin |
|
||
| PATCH | /admin/providers/:id | Actualizar proveedor | Admin |
|
||
| GET | /admin/packages | Listar paquetes | Admin |
|
||
| POST | /admin/packages | Crear paquete | Admin |
|
||
| PATCH | /admin/packages/:id | Actualizar paquete | Admin |
|
||
| GET | /admin/promotions | Listar promociones | Admin |
|
||
| POST | /admin/promotions | Crear promocion | Admin |
|
||
| GET | /admin/products/pending | Productos pendientes | Mod |
|
||
| POST | /admin/products/:id/approve | Aprobar producto | Mod |
|
||
| POST | /admin/products/:id/reject | Rechazar producto | Mod |
|
||
| GET | /admin/referrals/fraud-holds | Referidos en hold | Mod |
|
||
| POST | /admin/referrals/:id/approve | Aprobar referido | Mod |
|
||
| POST | /admin/referrals/:id/reject | Rechazar referido | Mod |
|
||
|
||
---
|
||
|
||
## 7. Metricas del Dashboard
|
||
|
||
### KPIs Principales
|
||
|
||
| Metrica | Descripcion | Periodo |
|
||
|---------|-------------|---------|
|
||
| MAU | Monthly Active Users | Mes |
|
||
| DAU | Daily Active Users | Dia |
|
||
| Sessions | Sesiones de inventario | Dia/Semana/Mes |
|
||
| Revenue | Ingresos MXN | Dia/Semana/Mes |
|
||
| COGS | Costo de IA | Dia/Semana/Mes |
|
||
| Gross Margin | Revenue - COGS | % |
|
||
| Avg Precision | Precision promedio | Semana |
|
||
| Error Rate | Tasa de errores | Semana |
|
||
|
||
### Graficas
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ DASHBOARD ADMIN │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 1,234 │ │ 45,678 │ │ $123,456 │ │ 52% │ │
|
||
│ │ MAU │ │ Sessions │ │ Revenue │ │ Margin │ │
|
||
│ │ +12% │ │ +8% │ │ +15% │ │ +2% │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
│ │
|
||
│ REVENUE VS COGS │
|
||
│ ──────────────── │
|
||
│ $│ ╱──────── │
|
||
│ │ ╱─────╱ │
|
||
│ │ ╱─────╱ │
|
||
│ │ ╱─────╱ │
|
||
│ │╱────╱ │
|
||
│ └──────────────────────────────────────────▶ │
|
||
│ Ene Feb Mar Abr May Jun │
|
||
│ │
|
||
│ ── Revenue -- COGS │
|
||
│ │
|
||
│ TAREAS PENDIENTES │
|
||
│ ───────────────── │
|
||
│ ⚠️ 12 productos pendientes de revision │
|
||
│ ⚠️ 5 referidos en fraud hold │
|
||
│ ℹ️ Promocion "Enero" expira en 3 dias │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Gestion de Proveedores IA
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ CONFIGURACION DE PROVEEDORES IA │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ OpenAI Vision [ON] │ │
|
||
│ │ ────────────────────────────────────────────────────── │ │
|
||
│ │ Costo por frame: $0.002 USD │ │
|
||
│ │ Costo por token: $0.00001 USD │ │
|
||
│ │ Uso este mes: 45,000 frames ($90 USD) │ │
|
||
│ │ [Editar] │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ Claude Vision [OFF] │ │
|
||
│ │ ────────────────────────────────────────────────────── │ │
|
||
│ │ Costo por frame: $0.003 USD │ │
|
||
│ │ Costo por token: $0.000015 USD │ │
|
||
│ │ Uso este mes: 0 frames │ │
|
||
│ │ [Editar] │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Proveedor activo: OpenAI Vision │
|
||
│ Tipo de cambio USD/MXN: 17.50 (actualizado hace 1h) │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Moderacion de Productos
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ PRODUCTOS PENDIENTES (12) │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ [IMG] Nuevo producto │ │
|
||
│ │ ────────────── │ │
|
||
│ │ Nombre: Coca-Cola Zero 600ml │ │
|
||
│ │ Marca: Coca-Cola │ │
|
||
│ │ Categoria: Bebidas │ │
|
||
│ │ Enviado por: user@email.com │ │
|
||
│ │ Fecha: 10 Ene 2026 │ │
|
||
│ │ │ │
|
||
│ │ Productos similares: │ │
|
||
│ │ • Coca-Cola Zero 500ml (85% similar) │ │
|
||
│ │ • Coca-Cola Light 600ml (75% similar) │ │
|
||
│ │ │ │
|
||
│ │ [✓ Aprobar] [↗ Fusionar con...] [✗ Rechazar] │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Frontend Admin
|
||
|
||
**Opcion 1: React Admin (Recomendado)**
|
||
- Libreria especializada para dashboards
|
||
- Componentes listos para CRUD
|
||
- Integracion con REST/GraphQL
|
||
|
||
**Opcion 2: Dentro de la App Mobile**
|
||
- Seccion oculta para admins
|
||
- Mismo codebase
|
||
- Limitado en funcionalidad
|
||
|
||
**Opcion 3: Web Separada**
|
||
- Next.js o similar
|
||
- Mas flexible
|
||
- Mas mantenimiento
|
||
|
||
---
|
||
|
||
## 11. Dependencias
|
||
|
||
### Entrada (Requiere)
|
||
- Todos los modulos anteriores
|
||
- MII-005: Datos de IA para metricas
|
||
- MII-009: Datos de creditos
|
||
- MII-014: Datos de referidos
|
||
|
||
### Salida (Bloquea)
|
||
- Ninguna (ultimo modulo)
|
||
|
||
---
|
||
|
||
## 12. Seguridad Admin
|
||
|
||
| Control | Implementacion |
|
||
|---------|----------------|
|
||
| Autenticacion | JWT con rol ADMIN |
|
||
| 2FA | TOTP obligatorio |
|
||
| Audit Log | Toda accion registrada |
|
||
| IP Whitelist | Opcional |
|
||
| Session timeout | 1 hora |
|
||
|
||
---
|
||
|
||
## 13. Riesgos
|
||
|
||
| Riesgo | Probabilidad | Impacto | Mitigacion |
|
||
|--------|--------------|---------|------------|
|
||
| Acceso no autorizado | Baja | Alto | 2FA, audit, whitelist |
|
||
| Error de config | Media | Alto | Preview, rollback |
|
||
| Datos sensibles | Media | Alto | Encriptacion, logs |
|
||
|
||
---
|
||
|
||
## 14. Notas de Implementacion
|
||
|
||
- Empezar con dashboard simple, iterar
|
||
- Priorizar metricas de negocio
|
||
- Considerar usar herramientas existentes (Metabase, Grafana)
|
||
- Implementar audit log desde el inicio
|
||
|
||
---
|
||
|
||
## 15. Referencias
|
||
|
||
- [REQUERIMIENTOS-FUNCIONALES.md](../00-vision-general/REQUERIMIENTOS-FUNCIONALES.md) - Seccion 5.13
|
||
- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)
|
||
|
||
---
|
||
|
||
**Ultima Actualizacion:** 2026-01-10
|