🏗️ 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               INT   PK IDENTITY(1,1)
  email            TEXT  UNIQUE NOT NULL
  email_validado   BOOL  DEFAULT false       ← TODOS validan con OTP
  nombre           TEXT  NOT NULL
  password_hash    TEXT  NULL                ← internos; inversionista NULL
  created_at       TIMESTAMPTZ DEFAULT now()

── Proyectos ──
proyectos
  id               INT   PK IDENTITY(1,1)
  admin_id         INT   FK usuarios.id
  nombre           TEXT  NOT NULL
  descripcion      TEXT
  ubicacion        TEXT
  estatus          TEXT  CHECK (estatus IN ('activo','inactivo','cerrado'))
  codigo_invitacion TEXT UNIQUE NOT NULL      ← fijo, para asesores
  imagen_representativa TEXT NULL
  logo_url          TEXT NULL
  imagen_notificacion TEXT NULL

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

── Códigos de asesor (promoción) ──
codigos_asesor
  id               INT   PK IDENTITY(1,1)
  proyecto_id      INT   FK proyectos.id
  asesor_id        INT   FK usuarios.id
  codigo           TEXT  UNIQUE NOT NULL       ← NO expira, asigna comisión

── Etapas ──
etapas
  id               INT   PK IDENTITY(1,1)
  proyecto_id      INT   FK proyectos.id
  nombre           TEXT  NOT NULL
  fecha_entrega    DATE
  orden            INT
  en_venta         BOOL  DEFAULT false
  estatus          TEXT  DEFAULT 'abierta'     ← abierta / cerrada
  tiempo_apartado  INT   DEFAULT 72            ← horas para subir comprobante
  imagen_lotificacion TEXT NULL
  imagen_cuenta     TEXT NULL
  banco             TEXT NULL
  numero_cuenta     TEXT NULL
  beneficiario      TEXT NULL
  concepto_pago     TEXT NULL
  ── Solo modalidad 'tickets' ──
  total_tickets     INT   NULL                 ← cuántos tickets
  precio_ticket     NUMERIC(12,2) NULL         ← precio unitario
  created_at       TIMESTAMPTZ DEFAULT now()

── Promociones (descuentos por unidad) ──
promociones
  id               INT   PK IDENTITY(1,1)
  etapa_id         INT   FK etapas.id
  cantidad_min     INT   NOT NULL             ← mínimo de unidades para la tarifa (ej. 1, 3)
  descuento_unidad NUMERIC(12,2) NOT NULL     ← descuento POR UNIDAD (ej. 10000, 15000)

── Lotes ──
lotes
  id               INT   PK IDENTITY(1,1)
  etapa_id         INT   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'))
  coordenadas_mapa TEXT  NULL                  ← MapCoordinates de Terry
  created_at       TIMESTAMPTZ DEFAULT now()

── Apartados ──
apartados
  id               INT   PK IDENTITY(1,1)
  lote_id          INT   FK lotes.id  NULL     ← tickets: NULL
  etapa_id         INT   FK etapas.id          ← pool de tickets
  cantidad         INT   DEFAULT 1             ← tickets: cuántos
  inversionista_id INT   FK usuarios.id
  apartado_por     INT   FK usuarios.id NULL
  codigo_asesor    TEXT  FK codigos_asesor
  estatus          TEXT  DEFAULT 'apartado'
  expira_en        TIMESTAMPTZ
  comprobante_url  TEXT  NULL
  solicita_cancelacion BOOL DEFAULT false
  cancel_aprobado_por INT   FK usuarios.id NULL
  cancel_ejecutado_por INT   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