diff --git a/03_MODELO_DATOS/hst-contract-cct.md b/03_MODELO_DATOS/hst-contract-cct.md new file mode 100644 index 0000000..b7d0005 --- /dev/null +++ b/03_MODELO_DATOS/hst-contract-cct.md @@ -0,0 +1,588 @@ +# 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*