# 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*