🏗️ Terry 3.0

🎯 Objetivo

Plataforma de gestión inmobiliaria: administradores registran desarrollos (proyectos), generan enlaces de invitación para asesores, los asesores promocionan proyectos mediante códigos propios para inversionistas, y los inversionistas apartan lotes con validación por OTP. Incluye conciliación básica (cambio de estatus de lote).

Stack: Python 3.13 + FastAPI + PostgreSQL 18 + JWT + React (Vite + Tailwind).
Reconstruye Terry 1/2 (.NET 9 + Blazor + SQL Server) sobre stack validable en este servidor.

🚫 Fuera de alcance (v1)

• Pagos digitales / pasarela (Stripe/OpenPay) — la validación es manual (comprobante + conciliador)
• Reportes descargables
• Mapa interactivo SVG de lotes
• Planes de suscripción / facturación (anotado como futuro)
• Migración de datos desde Terry 1/2
• Auditoría / historial de lotes (pendiente para v2)

👤 Roles y permisos

Regla de oro: los permisos se cuelgan de la membresía (usuario × proyecto), no del usuario global. Un mismo usuario puede ser Admin de sus proyectos y Asesor en proyectos ajenos.

Roles por proyecto

Registro unificado

Una sola cuenta. Lo que determina los permisos es la acción:

Matriz de permisos

🔗 Códigos de invitación

Enlaces de ejemplo

🧠 Modelo de datos

── Usuarios ──
usuarios
  id               UUID  PK
  email            TEXT  UNIQUE NOT NULL
  email_validado   BOOL  DEFAULT false       ← inversionistas validan con OTP
  nombre           TEXT  NOT NULL
  password_hash    TEXT  NULL                ← internos (Admin/Asesor); inversionista NULL
  created_at       TIMESTAMPTZ DEFAULT now()

── Proyectos ──
proyectos
  id               UUID  PK
  admin_id         UUID  FK usuarios.id      ← dueño
  nombre           TEXT  NOT NULL
  descripcion      TEXT
  ubicacion        TEXT
  estatus          TEXT  CHECK (estatus IN ('activo','inactivo','cerrado'))
  codigo_invitacion TEXT UNIQUE NOT NULL      ← fijo, NUNCA cambia (para asesores)

── Membresías (roles por proyecto) ──
membresias
  id               UUID  PK
  proyecto_id      UUID  FK proyectos.id
  usuario_id       UUID  FK usuarios.id
  rol              TEXT  CHECK (rol IN ('asesor','conciliador'))
  activo           BOOL  DEFAULT true         ← asesor lo pone false al "dejar de promover"

── Códigos de asesor (promoción) ──
codigos_asesor
  id               UUID  PK
  proyecto_id      UUID  FK proyectos.id
  asesor_id        UUID  FK usuarios.id       ← quien promociona (Admin también)
  codigo           TEXT  UNIQUE NOT NULL       ← NO expira — permanente

── Etapas ──
etapas
  id               UUID  PK
  proyecto_id      UUID  FK proyectos.id
  nombre           TEXT  NOT NULL
  fecha_entrega    DATE
  orden            INT
  en_venta         BOOL  DEFAULT false
  tiempo_apartado  INT  DEFAULT 72            ← horas para subir comprobante

── Lotes ──
lotes
  id               UUID  PK
  etapa_id         UUID  FK etapas.id
  numero           TEXT  NOT NULL
  m2               NUMERIC(10,2)
  precio           NUMERIC(12,2) NOT NULL
  moneda           TEXT  DEFAULT 'MXN'
  estatus          TEXT  CHECK (estatus IN ('disponible','apartado','regular','mora','pagado'))

── Apartados ──
apartados
  id               UUID  PK
  lote_id          UUID  FK lotes.id  UNIQUE
  inversionista_id UUID  FK usuarios.id     ← comprador (siempre existe y validado)
  apartado_por     UUID  FK usuarios.id NULL ← quien apartó a nombre de otro
  codigo_asesor    TEXT  FK codigos_asesor   ← para asignar comisión
  estatus          TEXT  DEFAULT 'apartado'
  expira_en        TIMESTAMPTZ              ← now + etapa.tiempo_apartado
  comprobante_url  TEXT  NULL
  solicita_cancelacion BOOL DEFAULT false
  cancel_aprobado_por UUID FK usuarios.id NULL
  cancel_ejecutado_por UUID FK usuarios.id NULL

📊 Estados

Proyecto

Lote

📡 Endpoints

🔄 Flujos clave

1. Alta de Asesor

2. Flujo del Inversionista

3. Apartado con expiración

4. Cancelación

5. Conciliador por proyecto

6. Desvinculación de asesor

🔐 Seguridad

• JWT: access corto (30 min) + refresh (rotación, revocable)
• Inversionista: sin contraseña — email + OTP + flag email_validado
• Contraseñas con bcrypt
• OTP: 6 dígitos, expira 15 min
• Códigos de invitación: tokens aleatorios no secuenciales (GUID o nanoid)
• Código de proyecto: fijo y permanente (nunca cambia)
• Rate limit en login/OTP (5 intentos/IP/minuto)
• CORS para frontend en Cloudflare Pages
• Control de concurrencia en apartados: transacciones con SELECT ... FOR UPDATE en PostgreSQL
• Solo se aparta para cuentas verificadas (email existe + validado)

🌐 Dominio y Deploy

Deploy

• API: FastAPI en contenedor Docker → Dokploy. Env vars: DATABASE_URL, JWT_SECRET, SMTP_HOST, SMTP_USER, SMTP_PASS, CORS_ORIGIN
• Frontend: React + Vite + Tailwind → Cloudflare Pages
• Spec: Cloudflare Pages terry3-spec
• Migraciones: Alembic (suben con el contenedor)

✅ Decisiones cerradas

📋 Pendientes para v2

• Historial / auditoría de lotes — pendiente de definir formato
• Almacenamiento de comprobantes — se define cuando se implemente
• Lista exacta de plantillas de correo a definir en implementación

🧭 Próximos pasos

1. ✅ Spec v1.0 aprobado (estás aquí)
2. ⬜ Crear repositorio terry3 en GitHub
3. ⬜ Crear base terry3 en PostgreSQL 18 (Dokploy)
4. ⬜ API + Alembic + migraciones
5. ⬜ Lógica de auth (JWT + OTP + códigos de invitación)
6. ⬜ CRUD de proyectos, etapas, lotes
7. ⬜ Flujo de apartado con concurrencia
8. ⬜ Frontend React
9. ⬜ Registrar en _REFERENCIA.md y tarjeta en el taller
10. ⬜ Despliegue completo