Files
system-docs/03_MODELO_DATOS/hst-contract-cct.md

589 lines
18 KiB
Markdown

# Estandar HST Contract (CCT)
**Version:** 1.0
**Estado:** Especificacion
**Fecha:** 2026-01-01
---
## Vision General
El estandar HST Contract (CCT) es un modelo de datos semantico para la gestion integral de contratos. Sigue la arquitectura de 6 capas (L1-L6) compatible con el estandar INV, proporcionando un marco completo para la gestion del ciclo de vida contractual.
### Caracteristicas Principales
- **~280 campos totales** distribuidos en 6 capas
- **18 tipos de contrato** para cubrir escenarios empresariales
- **22 roles de partes** para identificar participantes
- **14 estados de ciclo de vida** para trazabilidad completa
- **37 tipos de clausulas** estandarizadas
- **Compatibilidad eIDAS** para firmas electronicas europeas
- **Soporte Smart Contracts** para blockchain
- **Auditoria completa** con hash inmutables
---
## Arquitectura de 6 Capas (L1-L6)
### L1 - Identificacion Base
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| h_contract | VARCHAR(64) | Hash SHA-256 unico del contrato |
| contract_id | UUID | Identificador interno |
| external_ref | VARCHAR(100) | Referencia externa del cliente |
| contract_number | VARCHAR(50) | Numero de contrato |
| version | INTEGER | Version del contrato |
| parent_contract | UUID | Contrato padre (para enmiendas) |
| created_at | TIMESTAMPTZ | Fecha de creacion |
| created_by | UUID | Usuario creador |
### L2 - Clasificacion
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| contract_type | ENUM | Tipo de contrato (ver catalogo) |
| contract_subtype | VARCHAR(50) | Subtipo especifico |
| category | VARCHAR(50) | Categoria de negocio |
| department | VARCHAR(100) | Departamento responsable |
| cost_center | VARCHAR(50) | Centro de coste |
| business_unit | VARCHAR(100) | Unidad de negocio |
| project_code | VARCHAR(50) | Codigo de proyecto asociado |
| h_maestro_tags | JSONB | Tags HST asociados |
### L3 - Partes y Roles
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| parties | JSONB | Array de partes involucradas |
| party_id | UUID | Identificador de la parte |
| party_role | ENUM | Rol de la parte (ver catalogo) |
| party_type | ENUM | Tipo: person, company, government |
| legal_name | VARCHAR(255) | Nombre legal completo |
| tax_id | VARCHAR(50) | NIF/CIF/VAT |
| address | JSONB | Direccion estructurada |
| contact_person | VARCHAR(255) | Persona de contacto |
| contact_email | VARCHAR(255) | Email de contacto |
| signatory | BOOLEAN | Es firmante autorizado |
| signatory_power | TEXT | Poder de representacion |
### L4 - Terminos Contractuales
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| effective_date | DATE | Fecha de inicio de vigencia |
| expiration_date | DATE | Fecha de finalizacion |
| duration_months | INTEGER | Duracion en meses |
| auto_renewal | BOOLEAN | Renovacion automatica |
| renewal_period | INTERVAL | Periodo de renovacion |
| notice_period_days | INTEGER | Dias de preaviso |
| termination_terms | TEXT | Condiciones de terminacion |
| governing_law | VARCHAR(100) | Ley aplicable |
| jurisdiction | VARCHAR(100) | Jurisdiccion |
| dispute_resolution | ENUM | Metodo de resolucion |
| arbitration_rules | VARCHAR(100) | Reglas de arbitraje |
| language | VARCHAR(10) | Idioma del contrato |
| currency | VARCHAR(3) | Moneda principal |
### L5 - Condiciones Economicas
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| total_value | NUMERIC(18,4) | Valor total del contrato |
| annual_value | NUMERIC(18,4) | Valor anualizado |
| payment_terms | JSONB | Terminos de pago |
| payment_schedule | JSONB | Calendario de pagos |
| penalty_clauses | JSONB | Clausulas de penalizacion |
| price_adjustment | JSONB | Mecanismos de ajuste de precio |
| tax_treatment | JSONB | Tratamiento fiscal |
| billing_address | JSONB | Direccion de facturacion |
| bank_details | JSONB | Datos bancarios (encriptados) |
| insurance_requirements | JSONB | Requisitos de seguro |
| performance_bond | JSONB | Garantias de cumplimiento |
### L6 - Metadatos y Auditoria
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| status | ENUM | Estado del ciclo de vida |
| workflow_stage | VARCHAR(50) | Etapa del workflow |
| approval_chain | JSONB | Cadena de aprobacion |
| signatures | JSONB | Firmas (eIDAS compatible) |
| documents | JSONB | Documentos adjuntos |
| amendments | JSONB | Historial de enmiendas |
| notes | JSONB | Notas internas |
| tags | JSONB | Etiquetas adicionales |
| metadata | JSONB | Metadatos extensibles |
| blockchain_ref | VARCHAR(100) | Referencia blockchain |
| smart_contract_address | VARCHAR(100) | Direccion smart contract |
| audit_log | JSONB | Log de auditoria |
| h_entrada | VARCHAR(64) | Hash de entrada |
| h_instancia | VARCHAR(64) | Hash de instancia |
| last_modified_at | TIMESTAMPTZ | Ultima modificacion |
| last_modified_by | UUID | Usuario que modifico |
---
## Catalogo de Tipos de Contrato (18)
| Codigo | Nombre | Descripcion |
|--------|--------|-------------|
| COM | Commercial | Contrato de compraventa comercial |
| SVC | Service | Prestacion de servicios |
| EMP | Employment | Contrato laboral |
| LIC | License | Licencia de software/IP |
| NDA | Non-Disclosure | Acuerdo de confidencialidad |
| JVA | Joint Venture | Empresa conjunta |
| LEA | Lease | Arrendamiento/alquiler |
| LOA | Loan | Prestamo |
| INS | Insurance | Seguro |
| CON | Consulting | Consultoria |
| AGY | Agency | Agencia/representacion |
| FRA | Franchise | Franquicia |
| SLA | Service Level | Acuerdo de nivel de servicio |
| MNT | Maintenance | Mantenimiento |
| SUB | Subscription | Suscripcion |
| PAR | Partnership | Sociedad/colaboracion |
| SET | Settlement | Acuerdo transaccional |
| AMD | Amendment | Enmienda/modificacion |
---
## Catalogo de Roles de Partes (22)
| Codigo | Rol | Descripcion |
|--------|-----|-------------|
| BUYER | Comprador | Parte que adquiere |
| SELLER | Vendedor | Parte que provee |
| LICENSOR | Licenciante | Otorga la licencia |
| LICENSEE | Licenciatario | Recibe la licencia |
| LESSOR | Arrendador | Propietario del bien |
| LESSEE | Arrendatario | Usuario del bien |
| EMPLOYER | Empleador | Contratante laboral |
| EMPLOYEE | Empleado | Trabajador |
| LENDER | Prestamista | Otorga el prestamo |
| BORROWER | Prestatario | Recibe el prestamo |
| INSURER | Asegurador | Compania de seguros |
| INSURED | Asegurado | Beneficiario del seguro |
| FRANCHISOR | Franquiciador | Dueno de la marca |
| FRANCHISEE | Franquiciado | Operador local |
| PRINCIPAL | Principal | Representado |
| AGENT | Agente | Representante |
| GUARANTOR | Garante | Proporciona garantia |
| BENEFICIARY | Beneficiario | Recibe el beneficio |
| CONSULTANT | Consultor | Proveedor de asesoria |
| CLIENT | Cliente | Receptor de asesoria |
| PARTNER | Socio | Miembro de sociedad |
| WITNESS | Testigo | Testigo de la firma |
---
## Estados del Ciclo de Vida (14)
| Codigo | Estado | Descripcion | Transiciones Validas |
|--------|--------|-------------|---------------------|
| DRAFT | Borrador | En redaccion | REVIEW, CANCELLED |
| REVIEW | En Revision | Pendiente de revision | DRAFT, NEGOTIATION, CANCELLED |
| NEGOTIATION | Negociacion | En proceso de negociacion | REVIEW, PENDING_APPROVAL, CANCELLED |
| PENDING_APPROVAL | Pendiente Aprobacion | Esperando aprobacion | NEGOTIATION, APPROVED, REJECTED |
| APPROVED | Aprobado | Aprobado internamente | PENDING_SIGNATURE |
| REJECTED | Rechazado | Rechazado (final) | DRAFT |
| PENDING_SIGNATURE | Pendiente Firma | Esperando firmas | APPROVED, SIGNED, CANCELLED |
| SIGNED | Firmado | Todas las firmas completadas | ACTIVE |
| ACTIVE | Activo | En vigor | SUSPENDED, TERMINATED, EXPIRED, RENEWED |
| SUSPENDED | Suspendido | Temporalmente inactivo | ACTIVE, TERMINATED |
| TERMINATED | Terminado | Terminacion anticipada | - |
| EXPIRED | Expirado | Vencido naturalmente | RENEWED |
| RENEWED | Renovado | Renovado (nuevo periodo) | ACTIVE |
| CANCELLED | Cancelado | Cancelado antes de firma | - |
---
## Catalogo de Clausulas (37)
### Clausulas Generales
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| DEF | Definiciones | Terminos y definiciones |
| OBJ | Objeto | Proposito del contrato |
| SCO | Alcance | Ambito de aplicacion |
| DUR | Duracion | Vigencia temporal |
| PRI | Precio | Condiciones economicas |
| PAY | Pago | Terminos de pago |
| DEL | Entrega | Condiciones de entrega |
| WAR | Garantia | Garantias ofrecidas |
### Clausulas de Responsabilidad
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| LIM | Limitacion Responsabilidad | Limites de responsabilidad |
| IND | Indemnizacion | Obligaciones de indemnizar |
| INS | Seguro | Requisitos de seguro |
| FOR | Fuerza Mayor | Eventos extraordinarios |
### Clausulas de Propiedad Intelectual
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| IPR | Propiedad Intelectual | Derechos de PI |
| LIC | Licencia | Terminos de licencia |
| CON | Confidencialidad | Obligaciones de secreto |
| NDA | No Divulgacion | Restricciones de divulgacion |
| NCA | No Competencia | Restricciones de competencia |
### Clausulas de Terminacion
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| TER | Terminacion | Causas de terminacion |
| NOT | Notificacion | Requisitos de preaviso |
| PEN | Penalizacion | Penalizaciones por incumplimiento |
| TRA | Transicion | Obligaciones de transicion |
### Clausulas de Cumplimiento
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| COM | Cumplimiento | Obligaciones de compliance |
| AUD | Auditoria | Derechos de auditoria |
| REP | Reportes | Obligaciones de informar |
| REC | Registros | Mantenimiento de registros |
### Clausulas de Datos
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| DPA | Procesamiento Datos | Acuerdo de procesamiento |
| GDP | RGPD | Cumplimiento RGPD |
| SEC | Seguridad | Medidas de seguridad |
| BRE | Brecha | Notificacion de brechas |
| RET | Retencion | Periodo de retencion |
| DEL | Eliminacion | Destruccion de datos |
### Clausulas de Resolucion
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| GOV | Ley Aplicable | Jurisdiccion legal |
| JUR | Jurisdiccion | Tribunales competentes |
| ARB | Arbitraje | Clausula arbitral |
| MED | Mediacion | Procedimiento de mediacion |
### Clausulas Especiales
| Codigo | Clausula | Descripcion |
|--------|----------|-------------|
| ASS | Cesion | Transferencia de derechos |
| SUB | Subcontratacion | Autorizacion de subcontratistas |
| ENT | Integracion | Acuerdo completo |
| MOD | Modificacion | Procedimiento de enmienda |
| WAI | Renuncia | No renuncia de derechos |
---
## Compatibilidad eIDAS
El estandar CCT es compatible con el Reglamento eIDAS (910/2014) para firmas electronicas.
### Niveles de Firma Soportados
| Nivel | Tipo | Valor Legal |
|-------|------|-------------|
| SES | Simple Electronic Signature | Basico |
| AES | Advanced Electronic Signature | Presuncion de validez |
| QES | Qualified Electronic Signature | Equivalente a firma manuscrita |
### Estructura de Firma eIDAS
```json
{
"signature_id": "uuid",
"signer_id": "uuid",
"signature_level": "QES",
"timestamp": "2026-01-01T12:00:00Z",
"certificate": {
"issuer": "Qualified Trust Service Provider",
"serial": "...",
"validity": {...}
},
"signature_value": "base64...",
"document_hash": "sha256:...",
"seal": {
"timestamp_authority": "...",
"timestamp_token": "..."
}
}
```
### Proveedores QES Soportados
- **Espana:** FNMT, Camerfirma, AC Firmaprofesional
- **Alemania:** D-Trust, Bundesdruckerei
- **Francia:** Certinomis, ChamberSign
- **Italia:** Aruba PEC, InfoCert
---
## Integracion Blockchain / Smart Contracts
### Casos de Uso
| Caso | Descripcion | Beneficio |
|------|-------------|----------|
| Notarizacion | Hash del contrato en blockchain | Prueba de existencia |
| Pagos automaticos | Smart contract para milestones | Automatizacion |
| Escrow | Fondos en custodia automatica | Seguridad |
| Vesting | Liberacion programada de activos | Transparencia |
| Multi-firma | Aprobacion descentralizada | Gobernanza |
### Estructura Smart Contract
```json
{
"blockchain_network": "ethereum|polygon|arbitrum",
"contract_address": "0x...",
"deployment_tx": "0x...",
"abi_hash": "sha256:...",
"state_hash": "sha256:...",
"last_update_block": 12345678,
"oracle_sources": [],
"events": []
}
```
### Redes Soportadas
| Red | Tipo | Uso Recomendado |
|-----|------|-----------------|
| Ethereum | Mainnet | Contratos de alto valor |
| Polygon | L2 | Operaciones frecuentes |
| Arbitrum | L2 | DeFi integrado |
| Hyperledger | Permissioned | Enterprise privado |
---
## Hashes e Inmutabilidad
### Cadena de Hashes
```
h_contract = SHA-256(contract_core_data)
|
+-- h_entrada = SHA-256(modification_data)
| |
| +-- h_instancia = SHA-256(snapshot_data)
|
+-- h_bloque = SHA-256(consolidated_block)
```
### Formula de Hash
```python
h_contract = sha256(
contract_type + "|" +
parties_hash + "|" +
effective_date + "|" +
total_value + "|" +
created_at
)
```
### Verificacion de Integridad
```sql
SELECT
contract_id,
h_contract,
sha256(
contract_type || \x27|\x27 ||
parties_hash || \x27|\x27 ||
effective_date || \x27|\x27 ||
total_value || \x27|\x27 ||
created_at
) as computed_hash,
CASE
WHEN h_contract = computed_hash THEN \x27VALID\x27
ELSE \x27TAMPERED\x27
END as integrity_status
FROM contracts;
```
---
## Relaciones con Otras Entidades
### Diagrama de Relaciones
```
CONTRACT (CCT)
|
+---> HST (h_maestro tags)
| - Etiquetas semanticas del contrato
| - Clasificacion automatica
|
+---> PLY (Players/Partes)
| - Identificacion de partes
| - Roles y capacidades
|
+---> LOC (Locations)
| - Lugar de ejecucion
| - Direcciones de las partes
|
+---> FLG (Flags/Normativas)
| - Ley aplicable
| - Jurisdiccion
| - Compliance requerido
|
+---> DOC (Documentos)
| - Anexos
| - Versiones
|
+---> WFL (Workflows)
- Proceso de aprobacion
- Notificaciones
```
### Integracion con Feldman
Los contratos CCT se consolidan en Feldman como parte del registro consolidado:
```json
{
"entity_type": "CONTRACT",
"entity_id": "h_contract",
"consolidated_data": {...},
"validation_status": "VERIFIED",
"blockchain_proof": "0x..."
}
```
---
## Ejemplos de Uso
### Ejemplo 1: Contrato de Servicios (SVC)
```json
{
"h_contract": "sha256:a1b2c3...",
"contract_type": "SVC",
"parties": [
{
"party_role": "CLIENT",
"legal_name": "Empresa ABC S.L.",
"tax_id": "B12345678"
},
{
"party_role": "SELLER",
"legal_name": "Consultora XYZ S.A.",
"tax_id": "A87654321"
}
],
"effective_date": "2026-01-15",
"expiration_date": "2027-01-14",
"total_value": 120000.00,
"currency": "EUR",
"status": "ACTIVE",
"clauses": ["DEF", "OBJ", "SCO", "PRI", "PAY", "CON", "TER", "GOV"]
}
```
### Ejemplo 2: NDA (NDA)
```json
{
"h_contract": "sha256:d4e5f6...",
"contract_type": "NDA",
"parties": [
{
"party_role": "PRINCIPAL",
"legal_name": "Tech Corp"
},
{
"party_role": "AGENT",
"legal_name": "Partner Inc"
}
],
"effective_date": "2026-01-01",
"duration_months": 24,
"clauses": ["DEF", "OBJ", "CON", "NDA", "TER", "PEN", "GOV", "ARB"]
}
```
---
## Validaciones y Reglas de Negocio
### Validaciones Obligatorias
| Regla | Descripcion |
|-------|-------------|
| V001 | contract_type debe ser uno de los 18 valores validos |
| V002 | Al menos 2 partes deben estar definidas |
| V003 | effective_date no puede ser futuro si status = ACTIVE |
| V004 | expiration_date > effective_date |
| V005 | total_value >= 0 |
| V006 | Todas las firmas requeridas antes de SIGNED |
| V007 | governing_law obligatorio para contratos internacionales |
### Reglas de Transicion de Estado
```
DRAFT -> [REVIEW, CANCELLED]
REVIEW -> [DRAFT, NEGOTIATION, CANCELLED]
NEGOTIATION -> [REVIEW, PENDING_APPROVAL, CANCELLED]
PENDING_APPROVAL -> [NEGOTIATION, APPROVED, REJECTED]
APPROVED -> [PENDING_SIGNATURE]
REJECTED -> [DRAFT]
PENDING_SIGNATURE -> [APPROVED, SIGNED, CANCELLED]
SIGNED -> [ACTIVE]
ACTIVE -> [SUSPENDED, TERMINATED, EXPIRED, RENEWED]
SUSPENDED -> [ACTIVE, TERMINATED]
EXPIRED -> [RENEWED]
RENEWED -> [ACTIVE]
```
---
## APIs Recomendadas
### Endpoints REST
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /contracts | Crear contrato |
| GET | /contracts/{id} | Obtener contrato |
| PUT | /contracts/{id} | Actualizar contrato |
| DELETE | /contracts/{id} | Eliminar borrador |
| POST | /contracts/{id}/sign | Firmar contrato |
| POST | /contracts/{id}/approve | Aprobar contrato |
| GET | /contracts/{id}/history | Historial de cambios |
| POST | /contracts/{id}/verify | Verificar integridad |
### Webhooks
| Evento | Descripcion |
|--------|-------------|
| contract.created | Nuevo contrato creado |
| contract.updated | Contrato modificado |
| contract.signed | Firma completada |
| contract.activated | Contrato en vigor |
| contract.expiring | Proximo a vencer (30 dias) |
| contract.expired | Contrato vencido |
| contract.terminated | Contrato terminado |
---
## Referencias
- [Entidades Base](entidades.md) - Definicion de HST, ITM, PLY, LOC, FLG
- [Hashes](hashes.md) - Sistema de hashes del sistema
- [Flujos](flujos.md) - Flujos de trabajo estandar
- [Reglamento eIDAS](https://eur-lex.europa.eu/legal-content/ES/TXT/?uri=CELEX%3A32014R0910) - Regulacion europea de firmas electronicas
---
*Documento generado como parte del sistema TZZR - HST Contract Standard*