1c847fbe04
- Rename _archivo to _archive (standard convention) - Move analisis/, planes/ to _archive/ - Archive extra root files - Update _MAP.md with standardized structure Standard: SIMCO-ESTANDAR-ORCHESTRATION v1.0.0 Level: PROVIDER (L1A) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
270 lines
5.4 KiB
Markdown
270 lines
5.4 KiB
Markdown
# PLAN SPRINT 4 - Documentation ADRs
|
|
|
|
**Proyecto:** template-saas
|
|
**Sprint:** 4
|
|
**Objetivo:** Crear Architecture Decision Records y documentación técnica
|
|
**Fecha Inicio:** 2026-01-10
|
|
**SP Total:** 5
|
|
|
|
---
|
|
|
|
## RESUMEN EJECUTIVO
|
|
|
|
### Estado Actual
|
|
- **Documentación existente:** PROJECT-STATUS.md, inventarios YAML
|
|
- **ADRs:** 0 - No existen
|
|
- **API Docs:** Parcial (Swagger básico)
|
|
|
|
### Gap a Cerrar
|
|
Crear documentación arquitectónica formal:
|
|
1. ADR-001: Multi-tenancy con RLS
|
|
2. ADR-002: Autenticación JWT + OAuth
|
|
3. ADR-003: Billing con Stripe
|
|
4. ADR-004: Notificaciones Real-time
|
|
5. ADR-005: Feature Flags System
|
|
|
|
---
|
|
|
|
## TAREAS DEL SPRINT
|
|
|
|
### DOC-001: ADR Multi-tenancy
|
|
|
|
**Agente:** Docs-Agent
|
|
**SP:** 1
|
|
**Dependencia:** Ninguna
|
|
|
|
#### Entregables
|
|
```yaml
|
|
entregables:
|
|
- docs/architecture/adr/ADR-001-multi-tenancy-rls.md
|
|
```
|
|
|
|
#### Contenido
|
|
- Contexto y problema
|
|
- Opciones consideradas (schema per tenant, RLS, app-level)
|
|
- Decisión: PostgreSQL RLS
|
|
- Consecuencias positivas y negativas
|
|
- Implementación actual
|
|
|
|
---
|
|
|
|
### DOC-002: ADR Autenticación
|
|
|
|
**Agente:** Docs-Agent
|
|
**SP:** 1
|
|
**Dependencia:** Ninguna
|
|
**Paralelo con:** DOC-001
|
|
|
|
#### Entregables
|
|
```yaml
|
|
entregables:
|
|
- docs/architecture/adr/ADR-002-authentication-jwt-oauth.md
|
|
```
|
|
|
|
#### Contenido
|
|
- JWT vs Session-based
|
|
- Refresh token strategy
|
|
- OAuth 2.0 providers
|
|
- MFA implementation
|
|
- Token storage (httpOnly cookies vs localStorage)
|
|
|
|
---
|
|
|
|
### DOC-003: ADR Billing
|
|
|
|
**Agente:** Docs-Agent
|
|
**SP:** 1
|
|
**Dependencia:** Ninguna
|
|
**Paralelo con:** DOC-001, DOC-002
|
|
|
|
#### Entregables
|
|
```yaml
|
|
entregables:
|
|
- docs/architecture/adr/ADR-003-billing-stripe.md
|
|
```
|
|
|
|
#### Contenido
|
|
- Stripe vs otros providers
|
|
- Webhook handling strategy
|
|
- Subscription lifecycle
|
|
- Plan limits enforcement
|
|
- Metered billing approach
|
|
|
|
---
|
|
|
|
### DOC-004: ADR Notificaciones
|
|
|
|
**Agente:** Docs-Agent
|
|
**SP:** 1
|
|
**Dependencia:** Ninguna
|
|
|
|
#### Entregables
|
|
```yaml
|
|
entregables:
|
|
- docs/architecture/adr/ADR-004-notifications-realtime.md
|
|
```
|
|
|
|
#### Contenido
|
|
- WebSocket vs SSE vs Polling
|
|
- Push notifications (VAPID)
|
|
- Queue processing (BullMQ)
|
|
- Multi-channel strategy
|
|
- Delivery guarantees
|
|
|
|
---
|
|
|
|
### DOC-005: ADR Feature Flags
|
|
|
|
**Agente:** Docs-Agent
|
|
**SP:** 1
|
|
**Dependencia:** Ninguna
|
|
|
|
#### Entregables
|
|
```yaml
|
|
entregables:
|
|
- docs/architecture/adr/ADR-005-feature-flags.md
|
|
```
|
|
|
|
#### Contenido
|
|
- Build vs Runtime flags
|
|
- Tenant vs User level
|
|
- Gradual rollout strategy
|
|
- A/B testing support
|
|
- Flag evaluation caching
|
|
|
|
---
|
|
|
|
## TEMPLATE ADR
|
|
|
|
```markdown
|
|
# ADR-XXX: [Título]
|
|
|
|
## Estado
|
|
[Propuesto | Aceptado | Deprecado | Reemplazado]
|
|
|
|
## Contexto
|
|
[Descripción del problema o necesidad]
|
|
|
|
## Decisión
|
|
[La decisión tomada]
|
|
|
|
## Opciones Consideradas
|
|
1. [Opción 1] - Pros/Cons
|
|
2. [Opción 2] - Pros/Cons
|
|
3. [Opción 3] - Pros/Cons
|
|
|
|
## Consecuencias
|
|
|
|
### Positivas
|
|
- [Beneficio 1]
|
|
- [Beneficio 2]
|
|
|
|
### Negativas
|
|
- [Trade-off 1]
|
|
- [Trade-off 2]
|
|
|
|
## Referencias
|
|
- [Link 1]
|
|
- [Link 2]
|
|
```
|
|
|
|
---
|
|
|
|
## EJECUCIÓN DEL SPRINT
|
|
|
|
### Orden de Ejecución
|
|
|
|
```
|
|
Todos en paralelo:
|
|
├── DOC-001 (Multi-tenancy)
|
|
├── DOC-002 (Auth)
|
|
├── DOC-003 (Billing)
|
|
├── DOC-004 (Notifications)
|
|
└── DOC-005 (Feature Flags)
|
|
```
|
|
|
|
### Métricas de Éxito
|
|
|
|
| Métrica | Objetivo |
|
|
|---------|----------|
|
|
| ADRs creados | 5 |
|
|
| Decisiones documentadas | 5 |
|
|
| Referencias cruzadas | Completas |
|
|
|
|
---
|
|
|
|
## ESTRUCTURA DE ARCHIVOS
|
|
|
|
```
|
|
docs/
|
|
├── architecture/
|
|
│ ├── adr/
|
|
│ │ ├── ADR-001-multi-tenancy-rls.md
|
|
│ │ ├── ADR-002-authentication-jwt-oauth.md
|
|
│ │ ├── ADR-003-billing-stripe.md
|
|
│ │ ├── ADR-004-notifications-realtime.md
|
|
│ │ └── ADR-005-feature-flags.md
|
|
│ └── README.md (índice)
|
|
```
|
|
|
|
---
|
|
|
|
**Creado:** 2026-01-10
|
|
**Sprint:** 4 de 5
|
|
**Estado:** COMPLETADO
|
|
|
|
---
|
|
|
|
## REPORTE DE EJECUCIÓN
|
|
|
|
**Fecha Completado:** 2026-01-10
|
|
|
|
### Entregables Generados
|
|
|
|
| ADR | Archivo | Estado |
|
|
|-----|---------|--------|
|
|
| ADR-001 | docs/architecture/adr/ADR-001-multi-tenancy-rls.md | ✅ Creado |
|
|
| ADR-002 | docs/architecture/adr/ADR-002-authentication-jwt-oauth.md | ✅ Creado |
|
|
| ADR-003 | docs/architecture/adr/ADR-003-billing-stripe.md | ✅ Creado |
|
|
| ADR-004 | docs/architecture/adr/ADR-004-notifications-realtime.md | ✅ Creado |
|
|
| ADR-005 | docs/architecture/adr/ADR-005-feature-flags.md | ✅ Creado |
|
|
|
|
### Contenido de ADRs
|
|
|
|
1. **ADR-001 Multi-tenancy RLS**
|
|
- Opciones: DB per tenant, Schema per tenant, RLS
|
|
- Decisión: PostgreSQL Row-Level Security
|
|
- Implementación con `app.current_tenant_id`
|
|
|
|
2. **ADR-002 Autenticación JWT**
|
|
- Opciones: Session-based, JWT+Refresh, OAuth-only
|
|
- Decisión: JWT con Refresh Tokens + OAuth opcional
|
|
- Access Token 15min, Refresh Token 7 días
|
|
- MFA con TOTP
|
|
|
|
3. **ADR-003 Billing Stripe**
|
|
- Opciones: Custom, Stripe, Paddle/Lemonsqueezy
|
|
- Decisión: Stripe Billing
|
|
- Webhooks críticos documentados
|
|
- Customer Portal integrado
|
|
|
|
4. **ADR-004 Notificaciones Real-time**
|
|
- Opciones: Polling, SSE, WebSocket+BullMQ
|
|
- Decisión: Socket.io + BullMQ
|
|
- Canales: Email, Push, In-app, SMS (futuro), WhatsApp
|
|
- VAPID para push notifications
|
|
|
|
5. **ADR-005 Feature Flags**
|
|
- Opciones: Hardcoded, LaunchDarkly, Sistema propio
|
|
- Decisión: Sistema propio con PostgreSQL
|
|
- Override por tenant/usuario
|
|
- Rollout gradual soportado
|
|
|
|
### Métricas Finales
|
|
|
|
| Métrica | Objetivo | Resultado |
|
|
|---------|----------|-----------|
|
|
| ADRs creados | 5 | 5 ✅ |
|
|
| SP completados | 5 | 5 ✅ |
|
|
| Formato consistente | Sí | Sí ✅ |
|