CRISTAL DE LA CONSTRUCCIÓN

CRISTAL DE LA CONSTRUCCIÓN

A continuación se examinan las obras de construcción como los sistemas Uslov, Robert y Crystal. Es un modelo cómodo si queremos transformar la industria no sólo en un conjunto de procesos, sino en una arquitectura de sentido, digital e institucional gestionada.

La lógica básica del modelo

Los puntos de concentración de las funciones, los recursos, las decisiones, los datos y las responsabilidades son los puntos de concentración de las funciones, los recursos y las decisiones.

Las costillas son conexiones entre los nudos: corrientes de materiales, dinero, documentos, equipos, tecnología, personas y control.

El cristal JIU es una estructura holística en la que todos los nudos y costillas no se reúnen caóticamente, sino según las leyes de la simetría, la jerarquía, la transparencia y el desarrollo.

En otras palabras:

• Nodo = quién o lo que hace;
• costilla = cómo se relaciona;
• Cristal = cómo todo el sistema mantiene la forma y no se descompone.

La construcción como grafo

El sector de la construcción no es una sola cadena, sino un grafo de múltiples capas.

Tiene:

• Nodos de organización
• Nodos de recursos,
• Nodos de tecnología
• Nodos jurídicos,
• Nodos financieros;
• Nodos logísticos
• Nodos de funcionamiento,
• Nudos digitales.

Y las costillas entre ellas son:

• - Corrientes de materiales;
• Corrientes de personas,
• Corrientes de información;
• Corrientes de capital
• Corrientes de permisos,
• de responsabilidades;
• Corrientes de riesgo,
• Las corrientes de retroalimentación.

Esquemas de construcción

Escondites de diseño. Es el comienzo de cualquier objeto.

Nodos clave:

• La prioridad del Estado;
• El cliente;
• Inversionista;
• Demetrador;
• Una idea de desarrollo urbano;
• El terreno;
• Solicitud social;
• Plan maestro;
• Un concepto arquitectónico.

Su función es:

Responder a la pregunta: qué construir, por qué construir, para quién construir, con qué medios y en qué lógica del territorio.

Esqueletos de regulación. Sin ellos, el sistema no es legítimo.

Esto incluye:

• Órganos federales;
• Órganos regionales;
• Autoridades municipales;
• Reglas y normas;
• La evaluación;
• Sistema de permisos;
• Inventario;
• Los órganos de supervisión;
• Armonización ambiental;
• Seguridad contra incendios y seguridad industrial.

Su función es:

Garantizar la admisibilidad, la seguridad, la conformidad y el marco jurídico.

Esquemas de diseño

Son los nudos del nacimiento del uniforme.

Esto incluye:

• Oficina de Arquitectura;
• Planificador de genes;
• Diseño;
• Sección de Ingeniería;
• BIM/TIM Modelo;
• Modelo estimado;
• La dopla digital del objeto;
• La supervisión de los autores.

Su función es:

Convertir el diseño en un sistema exacto de decisiones, planos, parámetros, tamaños y limitaciones.

Recursos y suministros

Sin ellos, el objeto no se materializará.

Esto incluye:

• Los fabricantes de materiales de construcción;
• Experiencia profesional;
• Metalurgia;
• Nodos de hormigón;
• Madera;
• Equipo de ingeniería;
• Tecnología y mecanismos;
• Energía;
• Almacenes;
• Centros logísticos.

Su función es:

Construir todo lo necesario en cuanto a tamaño, duración, calidad y precio.

Unidades de trabajo

Es el centro de la creación física.

Esto incluye

• Contratista general;
• subcontratistas;
• Equipos de construcción;
• Organizaciones de instalación;
• Tecnología;
• El terreno de construcción;
• El plan civil;
• La seguridad en el trabajo;
• Control de las obras;
• Controles de construcción.

Su función es reunir un objeto en la realidad.

Servicios financieros

La construcción sin un marco financiero se está convirtiendo rápidamente en un caos.

Espejos:

• Banco;
• Tesoro del proyecto;
• Financiación de proyectos;
• Presupuesto;
• Inversión privada;
• El sistema contractual;
• Contorno de cálculo;
• Contorno fiscal;
• Seguro;
• Evaluación de riesgos y reservas.

Su función es:

Garantizar la sostenibilidad de las corrientes monetarias y la previsibilidad de la ejecución.

Unidades de explotación

En realidad, el objeto no se construye para construir, sino para vivir después de construir.

Espejos:

• La organización explotadora;
• El director de la empresa;
• Organizaciones que proporcionan recursos;
• El sistema de vigilancia de la instalación;
• Mantenimiento;
• Trabajos importantes de conservación;
• Usuario;
• Residente/alquiler/empresa;
• Sistema de retroalimentación.

Su función es:

Convertirla en un entorno operativo.

Espejos digitales. Este es el núcleo de la futura industria.

Espejos:

• Plataforma digital única;
• Registro de objetos;
• Lista de participantes;
• Pasaporte digital del objeto;
• El seguimiento digital de las decisiones;
• BIM/TIM;
• Mercado de materiales y servicios;
• Geoanalista;
• Modelo I de previsión;
• El panel de control de la industria.

Su función es hacer que el sistema sea transparente, manejable y prejuiciado.

Ruedas de construcción

Ahora lo importante es que los nodos sin costillas son solo puntos muertos.

Cosas inteligentes.

Conectan:

• - La necesidad de la sociedad de un programa de construcción;
• La estrategia del Estado es un proyecto específico;
• ○ función del objeto.

Esto responde a la pregunta de por qué esta construcción tiene derecho a serlo.

Rhodes legales

Conectan:

• Proyecto de norma;
• Usando el área de uso permitido;
• Contrato del contratista;
• :: El permiso de construcción;
• El resultado es la puesta en funcionamiento.

Son las costillas de la legitimidad.

Rhodes de información

Conectan:

• - El empleador del proyector;
• El diseñador del contratista;
• - Un contratista de supervisión;
• :: La plataforma digital;
• - Doble digital.

Son costillas de datos.

Costuras financieras

Conectan:

• Inversionista de un proyecto;
• Bancos sucesivos;
• El Tesoro paga;
• Estimaciones de los trabajos efectivos;
• riesgo ○ reserva.

Son costillas de valor y confianza.

Rótulas materiales

Conectan:

• Depósito del fabricante;
• Almacén del emplazamiento;
• - La técnica de la zona de trabajo;
• Suministro de material de instalación.

Son las costillas de la creación física.

Ruedas de gestión

Conectan:

• KPI
• - El plazo de la fase;
• Control de la desviación;
• - Decisión sobre la responsabilidad;
• La reacción del sistema.

Son costillas de coordinación.

Las costillas de calidad. Conectan:

• - El material del certificado;
• :: Actuación;
• - El proyecto de conformidad;
• Estación de funcionamiento;
• Un defecto de acción correctiva.

Son costillas de seguridad.

Retroalimentación

Conectan:

• El usuario es un explotador;
• Operador de diseño;
• - La revisión de la norma;
• :: Una nueva generación de proyectos.

Son costillas de la evolución.

Cristal de construcción

Ahora, ¿qué es el cristal?

El cristal no es solo una red. Se trata de un sistema armónico de múltiples capas, en el que cada uno de los nodos tiene lugar, función, grado de comunicación y responsabilidad.

En la construcción de un cristal es:

Un modelo único de la industria espacial y digital en que:

• Cada instalación tiene un pasaporte digital;
• Cada participante tiene un perfil digital;
• Cada proceso tiene una ruta y un control;
• Cada recurso tiene su origen y condición;
• Cada decisión tendrá el autor, la fecha y las consecuencias;
• Cada rublo tiene una trayectoria;
• Cada riesgo se ve de antemano;
• Cada resultado forma parte de la estructura general del país.

Geometría del cristal de la construcción

Distribuir el cristal por lo menos en 7.

La Granja 1. Significado

Lo que se construye y por qué.

La Granja 2. Espacio

¿Dónde, en qué territorio, en qué contexto?

La Granja 3. Derecho

Sobre qué base y con qué reglas.

La Granja 4. Recursos

De qué, quién y en qué se construyen.

La Granja 5. Producción

¿Cómo exactamente el objeto se reúne por etapas?

La Granja 6. Finanzas. Con qué dinero y con qué estabilidad.

La Granja 7. Ciclo de vida

Como el objeto vive después de la entrada. Añadiendo un núcleo digital, el cristal del nivel 8, donde el entorno digital conecta todas las demás líneas.

El núcleo del cristal

Cualquier sistema cristalino debe tener un núcleo.

Para la construcción, el núcleo debe ser:

Operador digital único de servicios de construcción

No sustituye a todos los participantes, sino que se convierte en:

• Coordinador de los datos,
• el integrador de procesos,
• por el árbitro digital,
• Navegador del ciclo de vida del objeto,
• por el explotador de la transparencia,
• Un entorno de interacción entre el Estado, las empresas y los ciudadanos.

Es el que convierte la industria de la selección de participantes en un único cristal de construcción.

Fórmula del cristal de construcción

Cristal de construcción = nudos de Rheebr

Donde:

• Los nodos proporcionan una estructura,
• Las costillas son interconectadas.
• Las reglas son sostenibles,
• * Los datos permiten la transparencia;
• El tiempo da una dinámica del ciclo de vida.

Estructura práctica de los nodos

Contorno A. Estado

Espejos:

• Estrategia,
• Proyectos nacionales,
• Normas,
• Control;
• Registros,
• Programas de infraestructura.

Contorno B. Desarrollo y órdenes de compra

Espejos:

• El cliente,
• Inversionista,
• Deme un mocoso.
• Banco de Tierras,
• El modelo financiero.

Contorno C. Diseño

Espejos:

• Arquitectura
• Ingeniería,
• BIM,
• El examen forense,
• Estimaciones.

Contorno D. Producción

Espejos:

• Contratistas,
• Proveedores,
• Tecnología,
• Control del diseño,
• El plan civil.

Contorno E. Explotación

Espejos:

• Propietario
• El gerente de la empresa,
• Servicio,
• Vigilancia,
• Reparaciones.

Contorno F. Plataforma digital

Espejos:

• Pasaporte digital;
• ID del objeto,
• Mercado digital,
• Analista,
• IE,
• Vigilancia,
• Calificaciones de los afiliados.

¿Cuáles son las costillas más críticas?

En términos duros, la mayoría de las veces la industria no se derrumba por falta de nudos, sino por las malas costillas.

Las costillas más problemáticas suelen ser:

• Proyecto de construcción;
• Costo real estimado;
• - responsabilidad;
• - Plazos para la ejecución efectiva;
• ○ Transparencia digital;
• ○ retroinformación en el nuevo diseño;
• Datos públicos - datos privados;
• - El proveedor de la calidad del material.

Así que el objetivo principal de la reforma no es simplemente crear nuevos nudos, sino reconstruir las costillas.

Cristal del ciclo de vida del objeto

Puedes imaginar un objeto como un pequeño cristal:

Iniciación. Una idea, una necesidad, un terreno, un modelo.

Diseño conceptual, cálculos, BIM, estimaciones.

Armonía. Pruebas, permisos, conexiones.

Construcción. Entrega, trabajo, control, actos.

Entrar. Comprobaciones, documentación, lanzamiento.

Vigilancia, mantenimiento, retroalimentación.

Transformación

Reconstrucción, modernización, reutilización de datos. Ese es el cristal del ciclo de vida.

En el lenguaje metaarquitectónico

Entonces puedes decir:

Los nudos son órganos del organismo de construcción. Las costillas son sus vasos, nervios y canales. El cristal JIU es su esqueleto, su forma, su genoma y la ley de la armonía interna. Sin nudos no hay función. Sin costillas no hay coordinación. Sin el cristal, no hay integridad.

Conclusión de la gestión

Para el concepto de un único operador digital de servicios de construcción, esto significa que el operador no debe construirse como un sitio web, no como un conjunto de servicios y no como un mercado en sentido estricto, sino como:

Plataforma cristalina de la industria, en la que:

• Nodos de la industria digitalizados,
• Las costillas del sector están estandarizadas,
• El cristal de la industria está visualizado y controlado.

Así que el portal debe ser capaz de mostrar:

• ¿Quién está conectado con quién?
• :: La ruptura de las comunicaciones;
• Donde el espacio es estrecho;
• Donde el riesgo de corrupción;
• Donde hay escasez de materiales;
• :: El retraso en el cumplimiento de los plazos;
• :: La sobrecarga del contratista;
• Donde el objeto cae del contorno reglamentario;
• donde el ciclo de vida pierde el control.

Textos listos para su inclusión en el concepto

Puede insertar así:

La industria de la construcción se considera un sistema de red cristalina consistente en nudos, costillas y un núcleo digital integrado. Los núcleos representan a los participantes, los recursos, las funciones y la etapa del ciclo de vida del objeto. Las costillas reflejan los vínculos materiales, financieros, de información, jurídicos y de gestión que existen entre ellas. El cristal de la industria se forma como una arquitectura holística en la que todos los elementos están interrelacionados, estandarizados, transparentes y manejados en tiempo real. Sobre esta base, se crea el Operador Digital Unificado de Servicios de Construcción como integrador de sistemas para la coordinación, la rastreabilidad y el desarrollo evolutivo del complejo de construcción.

La versión más fuerte de este modelo

Si terminamos la idea, podemos hacer 3:

• Un mapa de la construcción de Uzlam y Röbram
• El cristal de la industria de la construcción rusa
• Arquitectura técnica de la plataforma digital basada en este cristal

Esto ya no es sólo una descripción, sino una base para:

• la hoja de ruta,
• tareas técnicas,
• Atlas de la construcción,
• Arquitectura del mercado,
• La plataforma digital estatal.

Cuadro: Espejos de Röbra ○ Funciones Servicios digitales

1. Contorno: Diseño y iniciación

MVP CRISTALLA DE CONSTRUCCIÓN

Plan de desarrollo (real)

Semana 1–2

Cuadro de funcionesYu. Roles de acceso.

Campo	Tipo
id	UUID PK
code	varchar unique
name	varchar

Ejemplos:

• super_admin
• government_operator
• investor
• customer
• contractor
• supervisor
• viewer

Cuadro user_roles. Conexión de usuarios y funciones.

Cuadro de empresas. Los participantes en el mercado.

Campo	Tipo	Finalidad
id	UUID PK	ID de la empresa
name	varchar	Nombre
short_name	varchar	Nombre corto
inn	varchar	INN
ogrn	varchar	OGRN
company_type	varchar	customer / contractor / supplier / bank / regulator
rating	numeric(3,2)	Calificación
status	varchar	active / inactive
website	varchar	Sitio web
created_at	timestamp	Fecha de creación
updated_at	timestamp	Fecha de actualización

Cuadro de company_users Conectar al usuario a la empresa.

Campo	Tipo
id	UUID PK
company_id	UUID FK -> companies.id
user_id	UUID FK -> users.id
position	varchar
is_primary	boolean
created_at	timestamp

Cuadro de regiones. Guía de regiones.

Campo	Tipo
id	UUID PK
code	varchar unique
name	varchar

Cuadro locations. Dirección y coordenadas.

Campo	Tipo
id	UUID PK
region_id	UUID FK -> regions.id
address	text
lat	numeric(10,7)
lon	numeric(10,7)
cadastral_number	varchar
created_at	timestamp

Cuadro de proyectos. Tarjeta de obra.

Campo	Tipo	Finalidad
id	UUID PK	ID del objeto
code	varchar unique	Número interno
name	varchar	Título
description	text	Descripción
project_type	varchar	residential / industrial / infrastructure
lifecycle_stage	varchar	concept / design / construction / operation
status	varchar	normal / risk / problem / archived
location_id	UUID FK -> locations.id	Locaciones
customer_company_id	UUID FK -> companies.id	Empleador
start_date	date	Comienzo de planificación
end_date	date	Finalización prevista
planned_budget	numeric(18,2)	Presupuesto del plan
actual_budget	numeric(18,2)	El hecho
created_at	timestamp	Fecha de creación
updated_at	timestamp	Fecha de actualización

Cuadro de proyectos_stages. Etapas del proyecto.

Campo	Tipo
id	UUID PK
project_id	UUID FK -> projects.id
stage_code	varchar
stage_name	varchar
planned_start	date
planned_end	date
actual_start	date
actual_end	date
status	varchar
created_at	timestamp

Cuadro de contratos. Contratos dentro del sistema.

Campo	Tipo
id	UUID PK
project_id	UUID FK -> projects.id
contract_number	varchar
contract_type	varchar
customer_company_id	UUID FK -> companies.id
contractor_company_id	UUID FK -> companies.id
amount	numeric(18,2)
currency	varchar
date_start	date
date_end	date
status	varchar
created_at	timestamp
updated_at	timestamp

Cuadro de documentos. Documentos del proyecto.

Campo	Tipo
id	UUID PK
project_id	UUID FK -> projects.id
company_id	UUID FK -> companies.id null
contract_id	UUID FK -> contracts.id null
doc_type	varchar
title	varchar
file_url	text
version	integer
issued_at	date
status	varchar
created_by	UUID FK -> users.id
created_at	timestamp

La tabla de riesgo del objeto.

Campo	Tipo
id	UUID PK
project_id	UUID FK -> projects.id
related_company_id	UUID FK -> companies.id null
related_stage_id	UUID FK -> project_stages.id null
risk_type	varchar
severity	varchar
probability	varchar
description	text
status	varchar
detected_at	timestamp
resolved_at	timestamp null

Cuadro events. La lista de eventos.

Campo	Tipo
id	UUID PK
project_id	UUID FK -> projects.id null
company_id	UUID FK -> companies.id null
user_id	UUID FK -> users.id null
event_type	varchar
event_payload	jsonb
created_at	timestamp

Cuadro del proyecto_metrics. Metrics del proyecto.

Campo	Tipo
id	UUID PK
project_id	UUID FK -> projects.id
metric_date	date
progress_percent	numeric(5,2)
cost_variance	numeric(18,2)
schedule_variance_days	integer
open_risks_count	integer
created_at	timestamp

Índices PostgreSQL

Es lo mínimo necesario:

• projects(code)
• projects(status, lifecycle_stage)
• projects(customer_company_id)
• contracts(project_id)
• contracts(customer_company_id, contractor_company_id)
• documents(project_id, doc_type)
• risks(project_id, status, severity)
• events(project_id, created_at desc)
• locations(region_id)
• GIN Índice por events.event_payload

Neo4j: modelo del grafo

En la columna, guardamos la esencia como nudos y relaciones como costillas.

Los nudos. Lápices principales:

• Project
• Company
• User
• Contract
• Document
• Stage
• Location
• Risk

Propiedades obligatorias de un nodo. Para uniformidad:

• id — UUID de PostgreSQL
• Tipo de criatura
• name
• status
• createdAt
• updatedAt

Las costillas de Neo4j. Relaciones básicas

• [:LOCATED_AT]
  Project -> Location
• [:OWNED_BY]
  Project -> Company
• [:PARTICIPATES_IN]
  Company -> Project
• [:HAS_STAGE]
  Project -> Stage
• [:HAS_CONTRACT]
  Project -> Contract
• [:CUSTOMER_IN]
  Company -> Contract
• [:CONTRACTOR_IN]
  Company -> Contract
• [:HAS_DOCUMENT]
  Project -> Document
• [:ISSUED_BY]
  Document -> Company
• [:HAS_RISK]
  Project -> Risk
• [:RELATED_TO]
  Risk - < Company or Risk -> Stage
• [:EMPLOYED_BY]
  User -> Company

Propiedades de las costillas

Por ejemplo PARTICIPATES_IN:

• role
• startDate
• endDate
• status

HAS_CONTRACT:

• contractNumber
• amount
• currency
• status

HAS_RISK:

• severity
• detectedAt

Ejemplo de grafo

(Company: Customer) -[:PARTICIPATES_IN {role:"customer"}]-> (Project)

(Company: GeneralContractor) -[:PARTICIPATES_IN {role:"general_contractor"}]-> (Project)

(Project) -[:HAS_CONTRACT]-> (Contract)

(Company: Customer) -[:CUSTOMER_IN]-> (Contract)

(Company: GeneralContractor) -[:CONTRACTOR_IN]-> (Contract)

(Project) -[:HAS_STAGE]-> (Stage: Construction)

(Project) -[:HAS_RISK {severity:"high"}]-> (Risk)

(Project) -[:LOCATED_AT]-> (Location)

Arquitectura API

Para MVP, será suficiente con REST API v1. Más adelante, podrá agregar GraphQL para pantallas complejas de la barra.

Regla general API

Prefijo básico

/api/v1

Formato

{

  "data": {},

  "meta": {},

  "error": null

}

Error

{

  "data": null,

  "meta": {},

  "error": {

    "code": "PROJECT_NOT_FOUND",

    "message": "Project not found"

  }

Authorization: Bearer <token>

Auth API. POST /auth/login. Entra.

Request

{

  "email": "user@example.com",

  "password": "secret"

}

Response

{

  "data": {

    "accessToken": "jwt",

    "refreshToken": "jwt",

    "user": {

      "id": "uuid",

      "fullName": "Ivan Petrov,"

      "email": "user@example.com",

      "roles": ["customer"]

    }

  },

  "meta": {},

  "error": null

}

POST /auth/refresh. Una actualización de la token.

GET /auth/me. Perfil del usuario actual.

API

GET /companies. Lista de empresas. Parámetros:

• search
• companyType
• status
• page
• limit

POST /companies. Crear una empresa.

Request

{

  "Name": "OOO Stroy Grad,"

  "shortName": "Strey Grad,"

  "inn": "1234567890",

  "ogrn": "1234567890123",

  "companyType": "contractor",

  "website": "https://example.com"

}

GET /companies/{id}. Tarjeta de la compañía.

PATCH /companies/{id}. Reiniciar la compañía.

GET /companies/{id}/projects. Proyectos de la empresa.

GET /companies/{id}/relations. Los contactos de la compañía están en la línea.

Response

{

  "data": {

    "nodes": [

      { "id": "c1," "type": "company," "name": "OSG Stroy Grad"},

      { "id": "p1," "type": "project," "name": "HC North" }

    ],

    "edges": [

      {

        "from": "c1",

        "to": "p1",

        "type": "PARTICIPATES_IN",

        "role": "contractor",

        "status": "active"

      }

    ]

  },

  "meta": {},

  "error": null

}

API proyectos

GET /projects. Lista de proyectos. Filtradores:

• status
• lifecycleStage
• regionId
• customerCompanyId
• search
• page
• limit

POST /projects. Crear un proyecto.

Request

{

  "Name": "HK Norte,"

  "description": "Un complejo de viviendas multifuncionales"

  "projectType": "residential",

  "lifecycleStage": "design",

  "status": "normal",

  "location": {

    "regionId": "uuid",

    "address": "San Petersburgo,"

    "lat": 59.93,

    "lon": 30.31,

    "cadastralNumber": "78:00:0000000:1234"

  },

  "customerCompanyId": "uuid",

  "startDate": "2026-04-01",

  "endDate": "2028-10-31",

  "plannedBudget": 2500000000

}

GET /projects/{id} Mapa del proyecto.

PATCH /projects/{id}. Renovar el proyecto.

GET /projects/{id}/graph. Endpoint principal MVP. Devuelve los nudos y las costillas del objeto.

Response

{

  "data": {

    "project": {

      "id": "uuid",

      "Name": "HK Norte,"

      "status": "risk",

      "lifecycleStage": "construction"

    },

    "nodes": [

      { "id": "p1," "type": "project," "name": "CG North," "status": "risk"},

      { "id": "c1," "type": "company," "name": "El Empleador del Desarrollo," "estatus": "active"},

      { "id": "c2," "type": "company," "name": "Gensord 1," "status": "active"},

      { "id": "r1," "type": "risk," "name": "salto de tiempo," "status": "open" }

    ],

    "edges": [

      { "from": "c1", "to": "p1", "type": "PARTICIPATES_IN", "role": "customer", "status": "active" },

      { "from": "c2", "to": "p1", "type": "PARTICIPATES_IN", "role": "general_contractor", "status": "active" },

      { "from": "p1", "to": "r1", "type": "HAS_RISK", "severity": "high" }

    ]

  },

  "meta": {},

  "error": null

}

GET /projects/{id}/timeline. La lista de cambios y acontecimientos.

GET /projects/{id}/metrics. Metrics del proyecto.

GET /projects/{id}/risks. Lista de riesgos.

POST /projects/{id}/risks. Crear riesgos.

GET /projects/{id}/documents. Documentos del proyecto.

POST /projects/{id}/documents. Carga el documento.

GET /projects/{id}/companies. Los participantes en el proyecto.

POST /projects/{id}/companies. Añadir un participante al proyecto.

Request

{

  "companyId": "uuid",

  "role": "supplier",

  "startDate": "2026-05-01",

  "status": "active"

}

API etapas del proyecto

GET /projects/{id}/stages. Lista de pasos.

POST /projects/{id}/stages. Crear fase.

PATCH /projects/{id}/stages/{stageId}. Actualiza la fase.

API contratos

GET /contracts. Lista de contratos. Filtradores:

• projectId
• customerCompanyId
• contractorCompanyId
• status

POST /contracts. Crear un contrato.

Request

{

  "projectId": "uuid",

  "contractNumber": "C-2026-001",

  "contractType": "general_contract",

  "customerCompanyId": "uuid",

  "contractorCompanyId": "uuid",

  "amount": 1500000000,

  "currency": "RUB",

  "dateStart": "2026-04-10",

  "dateEnd": "2027-12-20",

  "status": "active"

}

GET /contracts/{id}. Tarjeta de contrato.

PATCH /contracts/{id}. Renovar el contrato.

API riesgos

GET / risks. Lista común de riesgos. Filtradores:

• projectId
• severity
• status
• relatedCompanyId

POST / risks. Crear riesgos.

PATCH /risks/{id}. Cambiar el riesgo.

POST / risks/{id}/rolve. Cierra el riesgo.

API

GET /documents/{id}. Metadatos del documento.

GET /documents/{id}/download descargar archivo.

API del grafo. Es un servicio independiente porque constituye el corazón del sistema.

GET /graph/projects/{id}

Grafo del proyecto.

GET /graph/companies/{id}

Grafo de la empresa.

POST /graph/query

Solicitud de búsqueda o análisis de la columna. Para MVP, es mejor limitar las consultas a las solicitudes de plantilla en lugar de dar un Cypher arbitrario.

Request

{

  "queryType": "project_neighbors",

  "entityId": "uuid",

  "depth": 2

}

GET /graph/search. Encontrar elementos esenciales en la columna:

• q
• type

API analistas

GET /analytics/dashboard

Resumen:

• Número de proyectos
• Número de proyectos problemáticos
• Número de riesgos abiertos
• Número de empresas activas

GET /analytics/projects/status-summary

Resumen de la situación de los proyectos.

GET /analytics/companies/top-contractors

Un montón de contratistas por número de proyectos.

GET /analytics/risks/hotspots

Donde hay más riesgos.

API

GET /events

El registro de eventos. Filtradores:

• projectId
• companyId
• eventType
• from
• to

Dividir en servicios. Para MVP es suficiente con 5 servicios.

auth-service

• login
• refresh
• me
• users
• roles

directory-service

• companies
• regions
• locations

project-service

• projects
• stages
• contracts
• documents
• risks
• metrics
• events

graph-service

• graph endpoints
• sync from PostgreSQL to Neo4j
• graph queries

analytics-service

• dashboards
• summaries
• alerts

Sincronización PostgreSQL y Neo4j

Este es un momento importante, la fuente de la verdad para las tarjetas de Comment PostgreSQL, la fuente de la verdad para las conexiones y los pases de Neo4j.

Enfoque. Después de crear/actualizar la esencia en PostgreSQL:

• Escribamos en events
• Publicando el evento
• graph-service actualiza el grafo

Ejemplos de acontecimientos:

• project.created
• project.updated
• company.added_to_project
• contract.created
• risk.created

Mínima DTO

CreateProjectDto

{

  "name": "string",

  "description": "string",

  "projectType": "residential",

  "lifecycleStage": "design",

  "status": "normal",

  "customerCompanyId": "uuid",

  "startDate": "2026-04-01",

  "endDate": "2027-12-31",

  "plannedBudget": 1000000

}

AddCompanyToProjectDto

{

  "companyId": "uuid",

  "role": "contractor",

  "startDate": "2026-04-01",

  "endDate": null,

  "status": "active"

}

CreateRiskDto

{

  "projectId": "uuid",

  "relatedCompanyId": "uuid",

  "riskType": "deadline_delay",

  "severity": "high",

  "probability": "medium",

  "description": 21 días retrasados"

}

¿Qué hay que hacer en la primera versión?

Sin eso, MVP estará vacío:

Lo haré.

• projects
• companies
• contracts
• risks
• events
• GET /projects/{id}/graph
• GET /companies/{id}/relations

Se puede posponer.

• documentos complejos
• Analista ampliado
• IoT
• BIM Depósito
• Marketplace

Aparato de vidrio directo recomendado bajo este esquema

Backend

• NestJS
• PostgreSQL
• Prisma o TypeORM
• Neo4j
• Redis para caché y colas
• Swagger/OpenAPI para documentación

Frontend

• Next.js
• React Query
• Cytoscape.js para el grafo
• Tailwind CSS ó MUI

Infra

• Docker
• Docker Compose para MVP
• Nginx
• Depósito combinado de documentos S3

Estructura del emplazamiento

/crystal-construction

  /apps

    /api-gateway

    /auth-service

    /directory-service

    /project-service

    /graph-service

    /analytics-service

    /web-client

  /packages

    /shared-types

    /shared-utils

    /ui

  /infra

    /docker

    /nginx

    /db

  /docs

    openapi.yaml

    database-schema.md

    graph-model.md

El procedimiento de montaje más apropiado

• Subir auth-service
• Subir directory-service
• Hacer un proyecto-service
• Hacer graph-service
• Conectar UI a GET /projects/{id}/graph
• Añadir riesgos y eventos
• Añadir dashboard

MVP debe responder a 4:

• ¿Qué es ese objeto?
• ¿Quién está conectado con él?
• ¿Dónde está el riesgo?
• ¿Qué está pasando ahora?

Si API y el BD lo dan, ya tienes el núcleo de trabajo de Crystal de la Construcción.

1. OpenAPI-Terminal

Por debajo del marco de especificaciones de OpenAPI 3.1 para MVP.

openapi: 3.1.0

info:

  title: Crystal Construction API

  version: 1.0.0

  description: API MVP

servers:

  - url: https://api.crystal-construction.local/api/v1

tags:

  - name: Auth

  - name: Companies

  - name: Projects

  - name: Contracts

  - name: Risks

  - name: Graph

  - name: Analytics

paths:

  /auth/login:

    post:

      tags: [Auth]

      summary: Entrada del usuario

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/LoginRequest'

      responses:

        '200':

          description: Entrar con éxito

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/AuthResponse'

  /auth/me:

    get:

      tags: [Auth]

      summary: Perfil del usuario actual

      security:

        - bearerAuth: []

      responses:

        '200':

          description: Perfil de usuario

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/UserProfileResponse'

  /companies:

    get:

      tags: [Companies]

      Resumen: Lista de empresas

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: search

          schema: { type: string }

        - in: query

          name: companyType

          schema: { type: string }

        - in: query

          name: status

          schema: { type: string }

        - in: query

          name: page

          schema: { type: integer, minimum: 1, default: 1 }

        - in: query

          name: limit

          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }

      responses:

        '200':

          description: Lista de empresas

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyListResponse'

    post:

      tags: [Companies]

      summary: Crear una empresa

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateCompanyRequest'

      responses:

        '201':

          description: Compañía creada

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyResponse'

  /companies/{id}:

    get:

      tags: [Companies]

      Resumen: Tarjeta de la empresa

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      responses:

        '200':

          description: Datos de la empresa

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyResponse'

    patch:

      tags: [Companies]

      Summary: Actualizar la empresa

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/UpdateCompanyRequest'

      responses:

        '200':

          description: La empresa está actualizada

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyResponse'

  /companies/{id}/relations:

    get:

      tags: [Graph]

      summary: Grafo de conexiones de la empresa

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

        - in: query

          name: depth

          schema: { type: integer, minimum: 1, maximum: 3, default: 1 }

      responses:

        '200':

          description: Grafo de la empresa

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/GraphResponse'

  /projects:

    get:

      tags: [Projects]

      summary: List of projects

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: status

          schema: { type: string }

        - in: query

          name: lifecycleStage

          schema: { type: string }

        - in: query

          name: regionId

          schema: { type: string, format: uuid }

        - in: query

          name: customerCompanyId

          schema: { type: string, format: uuid }

        - in: query

          name: search

          schema: { type: string }

        - in: query

          name: page

          schema: { type: integer, default: 1 }

        - in: query

          name: limit

          schema: { type: integer, default: 20 }

      responses:

        '200':

          description: Lista de proyectos

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectListResponse'

    post:

      tags: [Projects]

      summary: Crear proyecto

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateProjectRequest'

      responses:

        '201':

          description: Proyecto creado

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectResponse'

  /projects/{id}:

    get:

      tags: [Projects]

      Resumen: Mapa del proyecto

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      responses:

        '200':

          description: Datos del proyecto

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectResponse'

    patch:

      tags: [Projects]

      summary: Actualizar el proyecto

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/UpdateProjectRequest'

      responses:

        '200':

          description: Proyecto actualizado

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectResponse'

  /projects/{id}/graph:

    get:

      tags: [Graph]

      summary: Grafo del proyecto

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

        - in: query

          name: depth

          schema: { type: integer, minimum: 1, maximum: 3, default: 2 }

      responses:

        '200':

          description: Contador del proyecto

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectGraphResponse'

  /projects/{id}/companies:

    post:

      tags: [Projects]

      summary: Añadir un participante al proyecto

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/AddCompanyToProjectRequest'

      responses:

        '201':

          description: Participante añadido

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/OperationResponse'

  /contracts:

    get:

      tags: [Contracts]

      summary: Lista de contratos

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: projectId

          schema: { type: string, format: uuid }

        - in: query

          name: customerCompanyId

          schema: { type: string, format: uuid }

        - in: query

          name: contractorCompanyId

          schema: { type: string, format: uuid }

        - in: query

          name: status

          schema: { type: string }

      responses:

        '200':

          description: Lista de contratos

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ContractListResponse'

    post:

      tags: [Contracts]

      summary: Crear un contrato

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateContractRequest'

      responses:

        '201':

          description: Contrato creado

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ContractResponse'

  /risks:

    get:

      tags: [Risks]

      summary: List of risks

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: projectId

          schema: { type: string, format: uuid }

        - in: query

          name: severity

          schema: { type: string }

        - in: query

          name: status

          schema: { type: string }

      responses:

        '200':

          description: Lista de riesgos

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/RiskListResponse'

    post:

      tags: [Risks]

      summary: Crear riesgo

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateRiskRequest'

      responses:

        '201':

          description: Riesgo creado

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/RiskResponse'

  /risks/{id}/resolve:

    post:

      tags: [Risks]

      summary: Cerrar el riesgo

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      responses:

        '200':

          description: Riesgo cerrado

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/RiskResponse'

  /analytics/dashboard:

    get:

      tags: [Analytics]

      summary: Dashbord MVP

      security:

        - bearerAuth: []

      responses:

        '200':

          description: Analista integrador

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/DashboardResponse'

components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

  parameters:

    IdPath:

      in: path

      name: id

      required: true

      schema:

        type: string

        format: uuid

  schemas:

    ApiError:

      type: object

      properties:

        code: { type: string }

        message: { type: string }

      required: [code, message]

    LoginRequest:

      type: object

      properties:

        email: { type: string, format: email }

        password: { type: string }

      required: [email, password]

    AuthUser:

      type: object

      properties:

        id: { type: string, format: uuid }

        fullName: { type: string }

        email: { type: string, format: email }

        roles:

          type: array

          items: { type: string }

      required: [id, fullName, email, roles]

    AuthResponse:

      type: object

      properties:

        data:

          type: object

          properties:

            accessToken: { type: string }

            refreshToken: { type: string }

            user:

              $ref: '#/components/schemas/AuthUser'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    UserProfileResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/AuthUser'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    Company:

      type: object

      properties:

        id: { type: string, format: uuid }

        name: { type: string }

        shortName: { type: string }

        inn: { type: string }

        ogrn: { type: string }

        companyType: { type: string }

        rating: { type: number }

        status: { type: string }

        website: { type: string, nullable: true }

      required: [id, name, companyType, status]

    CreateCompanyRequest:

      type: object

      properties:

        name: { type: string }

        shortName: { type: string }

        inn: { type: string }

        ogrn: { type: string }

        companyType: { type: string }

        website: { type: string }

      required: [name, inn, ogrn, companyType]

    UpdateCompanyRequest:

      type: object

      properties:

        name: { type: string }

        shortName: { type: string }

        companyType: { type: string }

        rating: { type: number }

        status: { type: string }

        website: { type: string }

    CompanyResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/Company'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    CompanyListResponse:

      type: object

      properties:

        data:

          type: array

          items:

            $ref: '#/components/schemas/Company'

        meta:

          type: object

          properties:

            page: { type: integer }

            limit: { type: integer }

            total: { type: integer }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    LocationInput:

      type: object

      properties:

        regionId: { type: string, format: uuid }

        address: { type: string }

        lat: { type: number }

        lon: { type: number }

        cadastralNumber: { type: string }

      required: [regionId, address]

    Project:

      type: object

      properties:

        id: { type: string, format: uuid }

        code: { type: string }

        name: { type: string }

        description: { type: string, nullable: true }

        projectType: { type: string }

        lifecycleStage: { type: string }

        status: { type: string }

        customerCompanyId: { type: string, format: uuid }

        startDate: { type: string, format: date, nullable: true }

        endDate: { type: string, format: date, nullable: true }

        plannedBudget: { type: number, nullable: true }

        actualBudget: { type: number, nullable: true }

      required: [id, name, projectType, lifecycleStage, status]

    CreateProjectRequest:

      type: object

      properties:

        name: { type: string }

        description: { type: string }

        projectType: { type: string }

        lifecycleStage: { type: string }

        status: { type: string }

        location:

          $ref: '#/components/schemas/LocationInput'

        customerCompanyId: { type: string, format: uuid }

        startDate: { type: string, format: date }

        endDate: { type: string, format: date }

        plannedBudget: { type: number }

      required:

        - name

        - projectType

        - lifecycleStage

        - status

        - location

        - customerCompanyId

    UpdateProjectRequest:

      type: object

      properties:

        name: { type: string }

        description: { type: string }

        lifecycleStage: { type: string }

        status: { type: string }

        actualBudget: { type: number }

        endDate: { type: string, format: date }

    ProjectResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/Project'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    ProjectListResponse:

      type: object

      properties:

        data:

          type: array

          items:

            $ref: '#/components/schemas/Project'

        meta:

          type: object

          properties:

            page: { type: integer }

            limit: { type: integer }

            total: { type: integer }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    GraphNode:

      type: object

      properties:

        id: { type: string }

        type: { type: string }

        name: { type: string }

        status: { type: string, nullable: true }

        metadata:

          type: object

          additionalProperties: true

      required: [id, type, name]

    GraphEdge:

      type: object

      properties:

        from: { type: string }

        to: { type: string }

        type: { type: string }

        role: { type: string, nullable: true }

        status: { type: string, nullable: true }

        metadata:

          type: object

          additionalProperties: true

      required: [from, to, type]

    GraphResponse:

      type: object

      properties:

        data:

          type: object

          properties:

            nodes:

              type: array

              items: { $ref: '#/components/schemas/GraphNode' }

            edges:

              type: array

              items: { $ref: '#/components/schemas/GraphEdge' }

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    ProjectGraphResponse:

      type: object

      properties:

        data:

          type: object

          properties:

            project:

              $ref: '#/components/schemas/Project'

            nodes:

              type: array

              items: { $ref: '#/components/schemas/GraphNode' }

            edges:

              type: array

              items: { $ref: '#/components/schemas/GraphEdge' }

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    CreateContractRequest:

      type: object

      properties:

        projectId: { type: string, format: uuid }

        contractNumber: { type: string }

        contractType: { type: string }

        customerCompanyId: { type: string, format: uuid }

        contractorCompanyId: { type: string, format: uuid }

        amount: { type: number }

        currency: { type: string }

        dateStart: { type: string, format: date }

        dateEnd: { type: string, format: date }

        status: { type: string }

      required:

        - projectId

        - contractNumber

        - contractType

        - customerCompanyId

        - contractorCompanyId

        - amount

        - currency

        - status

    Contract:

      type: object

      properties:

        id: { type: string, format: uuid }

        projectId: { type: string, format: uuid }

        contractNumber: { type: string }

        contractType: { type: string }

        customerCompanyId: { type: string, format: uuid }

        contractorCompanyId: { type: string, format: uuid }

        amount: { type: number }

        currency: { type: string }

        status: { type: string }

      required: [id, projectId, contractNumber, contractType, amount, currency, status]

    ContractResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/Contract'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    ContractListResponse:

      type: object

      properties:

        data:

          type: array

          items: { $ref: '#/components/schemas/Contract' }

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    CreateRiskRequest:

      type: object

      properties:

        projectId: { type: string, format: uuid }

        relatedCompanyId: { type: string, format: uuid, nullable: true }

        riskType: { type: string }

        severity: { type: string }

        probability: { type: string }

        description: { type: string }

      required: [projectId, riskType, severity, probability, description]

    Risk:

      type: object

      properties:

        id: { type: string, format: uuid }

        projectId: { type: string, format: uuid }

        relatedCompanyId: { type: string, format