rckrdmrd/trading-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c1b5081208
trading-platform/docs/02-definicion-modulos/OQI-005-payments-stripe/historias-usuario/US-PAY-007-ver-facturas.md
rckrdmrd c1b5081208 feat(ml): Complete FASE 11 - BTCUSD update and comprehensive documentation alignment 
ML Engine Updates:
- Updated BTCUSD with Polygon API data (2024-2025): 215,699 new records
- Re-trained all ML models: Attention (R²: 0.223), Base, Metamodel (87.3% confidence)
- Backtest results: +176.71R profit with aggressive_filter strategy

Documentation Consolidation:
- Created docs/99-analisis/_MAP.md index with 13 new analysis documents
- Consolidated inventories: removed duplicates from orchestration/inventarios/
- Updated ML_INVENTORY.yml with BTCUSD metrics and training results
- Added execution reports: FASE11-BTCUSD, correction issues, alignment validation

Architecture & Integration:
- Updated all module documentation with NEXUS v3.4 frontmatter
- Fixed _MAP.md indexes across all folders
- Updated orchestration plans and traces

Files: 229 changed, 5064 insertions(+), 1872 deletions(-)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 09:31:29 -06:00

429 lines
17 KiB
Markdown
Raw Blame History

---
id: "US-PAY-007"
title: "Ver y Descargar Facturas"
type: "User Story"
status: "Done"
priority: "Media"
epic: "OQI-005"
project: "trading-platform"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
# US-PAY-007: Ver y Descargar Facturas
**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** 📋 Planificado
**Story Points:** 3
**Prioridad:** P1 (Alta)
**Épica:** [OQI-005](../_MAP.md)
---
## Historia de Usuario
**Como** usuario de Trading Platform que ha realizado pagos
**Quiero** ver y descargar mis facturas
**Para** tener comprobantes de mis transacciones y poder deducir impuestos
---
## Criterios de Aceptación
### AC-001: Acceder a Facturas
**Dado** que soy usuario logueado con historial de pagos
**Cuando** navego a "Configuración → Facturas"
**Entonces** debería ver:
- Lista de todas mis facturas ordenadas por fecha (más reciente primero)
- Para cada factura:
- Número de factura (ej: INV-2025-000042)
- Fecha de emisión
- Descripción (Suscripción Pro, Curso Trading Básico, etc.)
- Monto total
- Estado (Pagada, Pendiente, Reembolsada)
- Botón "Descargar PDF"
- Botón "Ver Detalles"
- Filtros: Por año, por tipo (suscripción/curso), por estado
- Paginación si tengo > 20 facturas
### AC-002: Ver Sin Facturas
**Dado** que soy usuario nuevo sin pagos realizados
**Cuando** navego a la sección de facturas
**Entonces** debería ver:
- Mensaje: "No tienes facturas todavía"
- Ilustración o ícono de facturas vacías
- Botón "Ver Planes" para incentivar compra
### AC-003: Descargar Factura PDF
**Dado** que tengo una factura pagada
**Cuando** hago click en "Descargar PDF"
**Entonces** debería:
- Descargar archivo PDF inmediatamente
- Nombre del archivo: `Trading Platform_Factura_INV-2025-000042.pdf`
- PDF contiene:
- Logo de Trading Platform
- Datos fiscales de empresa
- Mis datos (nombre, email, país)
- Número de factura y fecha
- Detalle de productos/servicios
- Subtotal, impuestos (si aplica), total
- Método de pago (últimos 4 dígitos)
- Footer: "Powered by Stripe"
### AC-004: Ver Detalles de Factura
**Dado** que quiero ver más información de una factura
**Cuando** hago click en "Ver Detalles"
**Entonces** debería ver modal/página con:
- Todos los datos de la factura
- Desglose de impuestos si aplica
- ID de transacción de Stripe
- Método de pago usado
- Botón "Descargar PDF"
- Botón "Enviar por Email"
### AC-005: Enviar Factura por Email
**Dado** que estoy viendo detalles de una factura
**Cuando** hago click en "Enviar por Email"
**Entonces** debería:
- Ver confirmación: "Factura enviada a juan@example.com"
- Recibir email con:
- Asunto: "Tu factura de Trading Platform - #INV-2025-000042"
- PDF adjunto
- Link de descarga (válido 24h)
### AC-006: Filtrar Facturas
**Dado** que tengo múltiples facturas
**Cuando** aplico filtros
**Entonces** debería poder filtrar por:
- **Año:** 2025, 2024, 2023, etc.
- **Tipo:** Suscripción, Curso, Recarga de Wallet
- **Estado:** Pagada, Reembolsada
- Resultados se actualizan inmediatamente
### AC-007: Buscar Factura
**Dado** que estoy en la página de facturas
**Cuando** ingreso número de factura en búsqueda (ej: "INV-2025-042")
**Entonces** debería:
- Ver solo facturas que coincidan con el criterio
- Resaltar número coincidente
- Mensaje "No se encontraron facturas" si no hay resultados
### AC-008: Factura de Suscripción Mensual
**Dado** que tengo suscripción activa
**Cuando** veo mis facturas
**Entonces** debería ver:
- Una factura por cada cobro mensual
- Número secuencial: SUB-2025-000001, SUB-2025-000002, etc.
- Descripción: "Suscripción Pro - Enero 2025"
- Período cubierto: "01/01/2025 - 31/01/2025"
### AC-009: Nota de Crédito (Reembolso)
**Dado** que recibí un reembolso
**Cuando** veo mis facturas
**Entonces** debería ver:
- Nota de crédito con número CN-2025-000001
- Estado: "Reembolsada"
- Referencia a factura original
- Monto negativo (-$29.00)
- Ambas facturas (original + nota de crédito) listadas
### AC-010: Actualizar Datos Fiscales
**Dado** que quiero facturas con datos fiscales correctos
**Cuando** navego a "Datos Fiscales" en configuración
**Entonces** debería poder agregar/editar:
- Nombre fiscal (si difiere de nombre de usuario)
- RFC/Tax ID
- Dirección fiscal completa
- Régimen fiscal (si aplica)
- Nota: "Estos datos se aplicarán a facturas futuras"
---
## Mockup
```
┌─────────────────────────────────────────────────────────────┐
│ │
│ Facturas │
│ │
├─────────────────────────────────────────────────────────────┤
│ │
│ Filtros: [2025 ▼] [Todos ▼] [Buscar: INV-2025-...] │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ INV-2025-000042 05/12/2025 Pagada │ │
│ │ Suscripción Pro - Diciembre 2025 │ │
│ │ $49.00 │ │
│ │ │ │
│ │ [Descargar PDF] [Ver Detalles] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ INV-2025-000038 28/11/2025 Pagada │ │
│ │ Curso: Trading Básico 101 │ │
│ │ $29.00 │ │
│ │ │ │
│ │ [Descargar PDF] [Ver Detalles] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SUB-2025-000015 05/11/2025 Pagada │ │
│ │ Suscripción Pro - Noviembre 2025 │ │
│ │ $49.00 │ │
│ │ │ │
│ │ [Descargar PDF] [Ver Detalles] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ CN-2025-000003 15/10/2025 Reembolsada│ │
│ │ Nota de Crédito: Curso Trading Avanzado │ │
│ │ (Ref: INV-2025-000025) -$49.00 │ │
│ │ │ │
│ │ [Descargar PDF] [Ver Detalles] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Mostrando 1-10 de 24 facturas │
│ [← Anterior] [1] [2] [3] [Siguiente →] │
│ │
└─────────────────────────────────────────────────────────────┘
───────────── Modal: Detalles de Factura ─────────────
┌─────────────────────────────────────────────────────────────┐
│ [X] │
│ Factura #INV-2025-000042 │
│ │
│ Fecha de emisión: 05/12/2025 │
│ Estado: Pagada │
│ │
│ ─────────────────────────────────────────────────── │
│ │
│ FACTURADO A: │
│ Juan Pérez │
│ juan.perez@example.com │
│ México │
│ │
│ ─────────────────────────────────────────────────── │
│ │
│ DESCRIPCIÓN PRECIO │
│ Suscripción Pro │
│ Período: 01/12/2025 - 31/12/2025 $49.00 │
│ │
│ SUBTOTAL: $49.00 │
│ IVA (16%): $7.84 │
│ ───────────────── │
│ TOTAL: $56.84 │
│ │
│ ─────────────────────────────────────────────────── │
│ │
│ MÉTODO DE PAGO: │
│ Visa •••• 4242 │
│ │
│ ID de transacción: pi_3Abc123... │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Descargar PDF │ │ Enviar por Email│ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Flujo de Usuario (Gherkin)
```gherkin
Feature: Ver y Descargar Facturas
Scenario: Ver lista de facturas
Given que soy usuario logueado "juan@example.com"
And he realizado 3 compras en el último mes
When navego a "Configuración → Facturas"
Then debería ver 3 facturas listadas
And deberían estar ordenadas por fecha descendente
And cada una debería tener botón "Descargar PDF"
Scenario: Descargar factura PDF
Given que estoy viendo mi lista de facturas
When hago click en "Descargar PDF" en factura "INV-2025-000042"
Then debería descargar archivo "Trading Platform_Factura_INV-2025-000042.pdf"
And el PDF debería contener mis datos fiscales
And el PDF debería tener logo de Trading Platform
And el PDF debería mostrar total de $56.84 (incluido IVA)
Scenario: Ver detalles de factura
Given que estoy viendo mi lista de facturas
When hago click en "Ver Detalles" en una factura
Then debería ver modal con información detallada
And debería ver desglose de impuestos
And debería ver método de pago usado
And debería ver ID de transacción de Stripe
Scenario: Enviar factura por email
Given que estoy viendo detalles de factura "INV-2025-000042"
When hago click en "Enviar por Email"
Then debería ver "Factura enviada a juan@example.com"
And debería recibir email con PDF adjunto
And email debería incluir link de descarga válido 24h
Scenario: Filtrar facturas por año
Given que tengo facturas de 2024 y 2025
When selecciono filtro "2025"
Then debería ver solo facturas de 2025
And no debería ver facturas de 2024
Scenario: Usuario sin facturas
Given que soy usuario nuevo sin pagos
When navego a "Configuración → Facturas"
Then debería ver "No tienes facturas todavía"
And debería ver botón "Ver Planes"
```
---
## Notas Técnicas
### Frontend
- Componente: `apps/frontend/src/pages/Settings/Invoices.tsx`
- Modal: `InvoiceDetailsModal.tsx`
- Fetch facturas: `GET /api/v1/payments/invoices`
- Descargar PDF: `GET /api/v1/payments/invoices/:id/pdf`
### Backend
**Endpoints:**
1. `GET /api/v1/payments/invoices`
- Query params: `?year=2025&type=subscription&status=paid`
- Response:
```json
{
"invoices": [
{
"id": "uuid",
"invoiceNumber": "INV-2025-000042",
"type": "subscription",
"status": "paid",
"amount": 49.00,
"taxAmount": 7.84,
"total": 56.84,
"currency": "USD",
"description": "Suscripción Pro - Diciembre 2025",
"issuedAt": "2025-12-05T00:00:00Z",
"pdfUrl": "https://s3.../invoices/2025/12/uuid.pdf"
}
],
"total": 24,
"page": 1,
"perPage": 10
}
```
2. `GET /api/v1/payments/invoices/:id`
- Detalles completos de factura
3. `GET /api/v1/payments/invoices/:id/pdf`
- Generar URL firmada de S3 (expiración 24h)
- Redirect a URL firmada
4. `POST /api/v1/payments/invoices/:id/email`
- Reenviar factura por email
### Database
- Query desde tabla `billing.invoices`
- JOIN con `billing.payments` para método de pago
- Filtrar por `userId` del token
### PDF Storage
- S3 Bucket: `trading-invoices`
- Path: `invoices/{year}/{month}/{invoiceId}.pdf`
- Generar URL firmada con expiración:
```typescript
const url = s3.getSignedUrl('getObject', {
Bucket: 'trading-invoices',
Key: `invoices/2025/12/${invoiceId}.pdf`,
Expires: 86400, // 24 horas
});
```
### Email Template
**Subject:** Tu factura de Trading Platform - #INV-2025-000042
```
Hola Juan,
Adjuntamos tu factura de Trading Platform.
Número de factura: INV-2025-000042
Fecha: 05/12/2025
Total: $56.84 USD
También puedes descargarla desde:
[Descargar Factura] (válido por 24 horas)
¿Necesitas ayuda? Escríbenos a billing@trading.com
Saludos,
El equipo de Trading Platform
```
---
## Dependencias
- [RF-PAY-004: Sistema de Facturación](../requerimientos/RF-PAY-004-facturacion.md)
- Sistema de generación de PDF
- AWS S3 para almacenamiento
---
## Requerimientos Relacionados
- [RF-PAY-004: Sistema de Facturación Automática](../requerimientos/RF-PAY-004-facturacion.md)
---
## Tareas Técnicas
### Frontend
- [ ] Página `Invoices.tsx` con lista
- [ ] Modal `InvoiceDetailsModal.tsx`
- [ ] Filtros (año, tipo, estado)
- [ ] Búsqueda por número de factura
- [ ] Paginación
- [ ] Descargar PDF con loading state
- [ ] Reenviar email con confirmación
### Backend
- [ ] Endpoint `GET /invoices` con filtros
- [ ] Endpoint `GET /invoices/:id`
- [ ] Endpoint `GET /invoices/:id/pdf` (URL firmada)
- [ ] Endpoint `POST /invoices/:id/email`
- [ ] Validar que usuario sea dueño de factura
- [ ] Generar URLs firmadas de S3
### Testing
- [ ] Test: Usuario ve sus facturas correctamente
- [ ] Test: Filtros funcionan
- [ ] Test: Descargar PDF genera URL firmada
- [ ] Test: No puede ver facturas de otros usuarios
- [ ] Test: Reenvío de email funciona
- [ ] Test: Usuario sin facturas ve mensaje apropiado
Reference in New Issue View Git Blame Copy Permalink