Метастандарты для описания систем

1. БИЗНЕС-ПРОЦЕССЫ
   └─ BPMN, BPEL, DMN, YAWL

2. АРХИТЕКТУРА ПРЕДПРИЯТИЯ
   └─ ArchiMate, TOGAF, C4 Model

3. МОДЕЛИ ДАННЫХ
   └─ UML, ERD, JSON Schema, OWL/RDF

4. БИЗНЕС-ПРАВИЛА
   └─ DMN, Drools, SBVR

5. СОСТОЯНИЯ И WORKFLOW
   └─ State Machines, Petri Nets, Statecharts

6. API И ИНТЕГРАЦИЯ
   └─ OpenAPI, AsyncAPI, GraphQL SDL, gRPC

7. НОТАЦИИ МОДЕЛИРОВАНИЯ
   └─ SysML, IDEF, EPC

┌─────────────────────────────────────────────────────┐
│              BPMN ОСНОВНЫЕ ЭЛЕМЕНТЫ                 │
├─────────────────────────────────────────────────────┤
│                                                     │
│  СОБЫТИЯ (Events):                                  │
│  ○  Start Event (начало процесса)                   │
│  ◎  End Event (конец процесса)                      │
│  ◐  Intermediate Event (промежуточное событие)      │
│                                                     │
│  ЗАДАЧИ (Tasks):                                    │
│  ┌───────┐                                          │
│  │ Task  │  Простая задача                          │
│  └───────┘                                          │
│  ┌───────┐                                          │
│  │ ⚙ Task│  Service Task (вызов сервиса)            │
│  └───────┘                                          │
│  ┌───────┐                                          │
│  │ ✉ Task│  Send Task (отправка сообщения)          │
│  └───────┘                                          │
│                                                     │
│  ШЛЮЗЫ (Gateways):                                  │
│  ◇  Exclusive Gateway (XOR - одна ветка)            │
│  ◇+ Parallel Gateway (AND - все ветки параллельно)  │
│  ◇○ Inclusive Gateway (OR - одна или несколько)     │
│                                                     │
│  ПОТОКИ (Flows):                                    │
│  →  Sequence Flow (последовательность)              │
│  ⇢  Message Flow (сообщение между участниками)      │
│                                                     │
└─────────────────────────────────────────────────────┘

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
             targetNamespace="http://cifra.platform/processes">

  <process id="OrderFulfillment" name="Обработка заказа">

    <!-- Начало процесса -->
    <startEvent id="OrderReceived" name="Заказ получен"/>

    <!-- Проверка наличия товара -->
    <serviceTask id="CheckStock" name="Проверить наличие"
                 implementation="##WebService">
      <ioSpecification>
        <dataInput id="orderId"/>
        <dataOutput id="stockAvailable"/>
      </ioSpecification>
    </serviceTask>

    <!-- Развилка: есть товар или нет -->
    <exclusiveGateway id="StockDecision" name="Товар есть?"/>

    <!-- Ветка 1: товар есть -->
    <task id="PrepareOrder" name="Подготовить заказ"/>
    <task id="ShipOrder" name="Отправить заказ"/>

    <!-- Ветка 2: товара нет -->
    <task id="NotifyCustomer" name="Уведомить клиента"/>
    <task id="OrderFromSupplier" name="Заказать у поставщика"/>

    <!-- Конец процесса -->
    <endEvent id="OrderCompleted" name="Заказ завершён"/>

    <!-- Связи (sequence flows) -->
    <sequenceFlow sourceRef="OrderReceived" targetRef="CheckStock"/>
    <sequenceFlow sourceRef="CheckStock" targetRef="StockDecision"/>

    <!-- Условные переходы -->
    <sequenceFlow sourceRef="StockDecision" targetRef="PrepareOrder">
      <conditionExpression>stockAvailable == true</conditionExpression>
    </sequenceFlow>
    <sequenceFlow sourceRef="StockDecision" targetRef="NotifyCustomer">
      <conditionExpression>stockAvailable == false</conditionExpression>
    </sequenceFlow>

    <sequenceFlow sourceRef="PrepareOrder" targetRef="ShipOrder"/>
    <sequenceFlow sourceRef="ShipOrder" targetRef="OrderCompleted"/>

    <sequenceFlow sourceRef="NotifyCustomer" targetRef="OrderFromSupplier"/>
    <sequenceFlow sourceRef="OrderFromSupplier" targetRef="OrderCompleted"/>
  </process>

</definitions>

# processes/order_fulfillment.process.yaml
process:
  id: OrderFulfillment
  name: "Обработка заказа"
  type: business_process

events:
  start:
    - id: OrderReceived
      name: "Заказ получен"
      trigger: api_call  # или: message, timer, conditional

tasks:
  - id: CheckStock
    name: "Проверить наличие"
    type: service
    implementation: api
    endpoint: /inventory/check
    input:
      - order_id: {type: string, source: process.order_id}
    output:
      - stock_available: boolean

  - id: PrepareOrder
    name: "Подготовить заказ"
    type: user
    assignee: warehouse_team
    form: prepare_order_form

  - id: ShipOrder
    name: "Отправить заказ"
    type: service
    implementation: api
    endpoint: /shipping/create

  - id: NotifyCustomer
    name: "Уведомить клиента"
    type: service
    implementation: email
    template: out_of_stock_notification

  - id: OrderFromSupplier
    name: "Заказать у поставщика"
    type: user
    assignee: purchasing_team

gateways:
  - id: StockDecision
    name: "Товар есть?"
    type: exclusive  # XOR
    branches:
      - condition: "stock_available == true"
        target: PrepareOrder
      - condition: "stock_available == false"
        target: NotifyCustomer

flows:
  - from: OrderReceived
    to: CheckStock

  - from: CheckStock
    to: StockDecision

  - from: StockDecision
    to: [PrepareOrder, NotifyCustomer]  # Через gateway

  - from: PrepareOrder
    to: ShipOrder

  - from: ShipOrder
    to: OrderCompleted

  - from: NotifyCustomer
    to: OrderFromSupplier

  - from: OrderFromSupplier
    to: OrderCompleted

events:
  end:
    - id: OrderCompleted
      name: "Заказ завершён"

<definitions xmlns="http://www.omg.org/spec/DMN/20180521/MODEL/">
  <decision id="OrderDiscount" name="Расчёт скидки">
    <decisionTable>
      <input id="customerType" label="Тип клиента">
        <inputExpression typeRef="string">
          <text>customer.type</text>
        </inputExpression>
      </input>

      <input id="orderAmount" label="Сумма заказа">
        <inputExpression typeRef="number">
          <text>order.amount</text>
        </inputExpression>
      </input>

      <output id="discount" label="Скидка %" typeRef="number"/>

      <!-- Правила -->
      <rule>
        <inputEntry><text>"VIP"</text></inputEntry>
        <inputEntry><text>&gt;= 10000</text></inputEntry>
        <outputEntry><text>15</text></outputEntry>
      </rule>

      <rule>
        <inputEntry><text>"VIP"</text></inputEntry>
        <inputEntry><text>&gt;= 5000</text></inputEntry>
        <outputEntry><text>10</text></outputEntry>
      </rule>

      <rule>
        <inputEntry><text>"Regular"</text></inputEntry>
        <inputEntry><text>&gt;= 10000</text></inputEntry>
        <outputEntry><text>5</text></outputEntry>
      </rule>

      <rule>
        <inputEntry><text>-</text></inputEntry>
        <inputEntry><text>-</text></inputEntry>
        <outputEntry><text>0</text></outputEntry>
      </rule>
    </decisionTable>
  </decision>
</definitions>

# rules/order_discount.rule.yaml
decision:
  id: OrderDiscount
  name: "Расчёт скидки"
  type: decision_table

inputs:
  - name: customer_type
    type: enum
    values: [VIP, Regular, New]
    source: customer.type

  - name: order_amount
    type: decimal
    source: order.total

output:
  name: discount_percent
  type: integer
  range: [0, 100]

rules:
  - when:
      customer_type: VIP
      order_amount: ">= 10000"
    then:
      discount_percent: 15

  - when:
      customer_type: VIP
      order_amount: ">= 5000"
    then:
      discount_percent: 10

  - when:
      customer_type: Regular
      order_amount: ">= 10000"
    then:
      discount_percent: 5

  - when: {}  # default rule
    then:
      discount_percent: 0

# YAWL поддерживает сложные паттерны
workflow:
  patterns:
    - multi_choice: "несколько задач по условию"
    - discriminator: "первая завершённая задача продолжает процесс"
    - milestone: "задача доступна только в определённом состоянии"

┌─────────────────────────────────────────────────────┐
│                  ARCHIMATE LAYERS                   │
├─────────────────────────────────────────────────────┤
│                                                     │
│  MOTIVATION LAYER (Мотивация)                       │
│  ├─ Stakeholder (заинтересованное лицо)             │
│  ├─ Goal (цель)                                     │
│  ├─ Requirement (требование)                        │
│  └─ Constraint (ограничение)                        │
│                                                     │
│  STRATEGY LAYER (Стратегия)                         │
│  ├─ Resource (ресурс)                               │
│  ├─ Capability (способность)                        │
│  └─ Value Stream (поток ценности)                   │
│                                                     │
│  BUSINESS LAYER (Бизнес)                            │
│  ├─ Business Actor (актёр)                          │
│  ├─ Business Role (роль)                            │
│  ├─ Business Process (процесс)                      │
│  ├─ Business Service (услуга)                       │
│  └─ Business Object (объект)                        │
│                                                     │
│  APPLICATION LAYER (Приложения)                     │
│  ├─ Application Component (компонент)               │
│  ├─ Application Service (сервис)                    │
│  ├─ Application Interface (интерфейс)               │
│  └─ Data Object (объект данных)                     │
│                                                     │
│  TECHNOLOGY LAYER (Технологии)                      │
│  ├─ Node (узел)                                     │
│  ├─ Device (устройство)                             │
│  ├─ System Software (системное ПО)                  │
│  └─ Technology Service (технологический сервис)     │
│                                                     │
│  PHYSICAL LAYER (Физический)                        │
│  ├─ Equipment (оборудование)                        │
│  ├─ Facility (объект)                               │
│  └─ Material (материал)                             │
│                                                     │
└─────────────────────────────────────────────────────┘

<archimate:model>
  <!-- Бизнес-слой -->
  <element xsi:type="archimate:BusinessProcess"
           name="Управление клиентами" id="bp_customer_mgmt"/>

  <element xsi:type="archimate:BusinessRole"
           name="Менеджер по продажам" id="role_sales_manager"/>

  <element xsi:type="archimate:BusinessService"
           name="Обслуживание клиентов" id="service_customer"/>

  <!-- Слой приложений -->
  <element xsi:type="archimate:ApplicationComponent"
           name="CRM System" id="app_crm"/>

  <element xsi:type="archimate:DataObject"
           name="Customer Data" id="data_customer"/>

  <!-- Технологический слой -->
  <element xsi:type="archimate:Node"
           name="Web Server" id="node_web_server"/>

  <element xsi:type="archimate:Node"
           name="Database Server" id="node_db_server"/>

  <!-- Связи -->
  <relationship xsi:type="archimate:RealizationRelationship"
                source="app_crm" target="service_customer"/>

  <relationship xsi:type="archimate:ServingRelationship"
                source="app_crm" target="bp_customer_mgmt"/>
</archimate:model>

# architecture/crm_system.arch.yaml
architecture:
  name: "CRM System Architecture"
  framework: archimate

layers:
  business:
    processes:
      - id: customer_mgmt
        name: "Управление клиентами"
        type: business_process

    roles:
      - id: sales_manager
        name: "Менеджер по продажам"
        type: business_role
        responsibilities:
          - customer_mgmt

    services:
      - id: customer_service
        name: "Обслуживание клиентов"
        type: business_service

  application:
    components:
      - id: crm_app
        name: "CRM System"
        type: application_component
        realizes: customer_service
        serves: customer_mgmt

    data:
      - id: customer_data
        name: "Customer Data"
        type: data_object
        stored_in: database

  technology:
    nodes:
      - id: web_server
        name: "Web Server"
        type: node
        technology: nginx
        hosts: [crm_app]

      - id: db_server
        name: "Database Server"
        type: node
        technology: postgresql
        hosts: [customer_data]

relationships:
  - from: crm_app
    to: customer_service
    type: realization

  - from: crm_app
    to: customer_mgmt
    type: serving

  - from: web_server
    to: crm_app
    type: assignment

┌──────────────────────────────────────────┐
│        TOGAF ADM CYCLE                   │
├──────────────────────────────────────────┤
│                                          │
│         Preliminary Phase                │
│                ↓                         │
│         A. Architecture Vision           │
│                ↓                         │
│         B. Business Architecture         │
│                ↓                         │
│         C. Information Systems           │
│            - Data Architecture           │
│            - Application Architecture    │
│                ↓                         │
│         D. Technology Architecture       │
│                ↓                         │
│         E. Opportunities & Solutions     │
│                ↓                         │
│         F. Migration Planning            │
│                ↓                         │
│         G. Implementation Governance     │
│                ↓                         │
│         H. Architecture Change Mgmt      │
│                ↑                         │
│                └─────────────┐           │
│         Requirements Management          │
│                                          │
└──────────────────────────────────────────┘

# architecture/c4_crm.yaml
c4_model:
  # Level 1: System Context
  context:
    system: CRM System
    actors:
      - name: Sales Manager
        uses: CRM System
      - name: Customer
        receives_emails_from: CRM System
    external_systems:
      - name: Email Service
        used_by: CRM System

  # Level 2: Containers
  containers:
    - name: Web Application
      technology: React + TypeScript
      description: "Пользовательский интерфейс"

    - name: API Application
      technology: FastAPI + Python
      description: "REST API backend"

    - name: Database
      technology: PostgreSQL
      description: "Хранение данных"

  # Level 3: Components (внутри API Application)
  components:
    - name: Contact Manager
      technology: Python Module
      description: "Управление контактами"

    - name: Deal Manager
      technology: Python Module
      description: "Управление сделками"

  # Level 4: Code (классы и функции)
  # Обычно не документируется в C4, берётся из кода

СТРУКТУРНЫЕ ДИАГРАММЫ:
├─ Class Diagram (классы и отношения)
├─ Object Diagram (экземпляры объектов)
├─ Component Diagram (компоненты)
├─ Deployment Diagram (развёртывание)
├─ Package Diagram (пакеты)
└─ Composite Structure Diagram

ПОВЕДЕНЧЕСКИЕ ДИАГРАММЫ:
├─ Use Case Diagram (варианты использования)
├─ Activity Diagram (действия/процессы)
├─ State Machine Diagram (состояния)
├─ Sequence Diagram (последовательность)
├─ Communication Diagram (коммуникация)
└─ Timing Diagram (время)

@startuml CRM_Classes

class Contact {
  - id: UUID
  - first_name: string
  - last_name: string
  - email: string
  - phone: string
  ---
  + send_email(subject, body)
  + full_name(): string
}

class Company {
  - id: UUID
  - name: string
  - industry: enum
  - website: string
  ---
  + add_contact(contact)
  + total_deals(): decimal
}

class Deal {
  - id: UUID
  - title: string
  - amount: decimal
  - stage: enum
  - probability: integer
  ---
  + mark_as_won()
  + mark_as_lost(reason)
  + expected_revenue(): decimal
}

Contact "0..*" -- "0..1" Company : works_for
Contact "1" -- "0..*" Deal : owns
Company "0..1" -- "0..*" Deal : has

@enduml

# models/crm_classes.model.yaml
model:
  type: class_diagram
  name: "CRM Domain Model"

classes:
  Contact:
    attributes:
      - id: {type: UUID, visibility: private}
      - first_name: {type: string, visibility: private}
      - last_name: {type: string, visibility: private}
      - email: {type: string, visibility: private}
      - phone: {type: string, visibility: private}

    methods:
      - send_email:
          params: [subject: string, body: string]
          returns: void
          visibility: public

      - full_name:
          params: []
          returns: string
          visibility: public

  Company:
    attributes:
      - id: {type: UUID, visibility: private}
      - name: {type: string, visibility: private}
      - industry: {type: enum, visibility: private}
      - website: {type: string, visibility: private}

    methods:
      - add_contact:
          params: [contact: Contact]
          returns: void

      - total_deals:
          params: []
          returns: decimal

  Deal:
    attributes:
      - id: {type: UUID, visibility: private}
      - title: {type: string, visibility: private}
      - amount: {type: decimal, visibility: private}
      - stage: {type: enum, visibility: private}
      - probability: {type: integer, visibility: private}

    methods:
      - mark_as_won: {params: [], returns: void}
      - mark_as_lost: {params: [reason: string], returns: void}
      - expected_revenue: {params: [], returns: decimal}

relationships:
  - from: Contact
    to: Company
    type: association
    multiplicity: [0..*, 0..1]
    label: "works_for"

  - from: Contact
    to: Deal
    type: association
    multiplicity: [1, 0..*]
    label: "owns"

  - from: Company
    to: Deal
    type: association
    multiplicity: [0..1, 0..*]
    label: "has"

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│   Contact    │       │   Company    │       │     Deal     │
├──────────────┤       ├──────────────┤       ├──────────────┤
│ id (PK)      │──┐    │ id (PK)      │       │ id (PK)      │
│ first_name   │  │    │ name         │       │ title        │
│ last_name    │  │    │ industry     │    ┌──│ contact_id   │
│ email        │  │    │ website      │    │  │ company_id   │
│ phone        │  │    └──────────────┘    │  │ amount       │
│ company_id   │──┘           │            │  │ stage        │
└──────────────┘               │            │  │ probability  │
       │                       │            │  └──────────────┘
       │                       │            │          │
       │ 0..*           0..1   │            └──────────┘
       └───────────────────────┘                 1

Легенда:
─── : one to many
──< : many (crow's foot)
─○─ : zero or one
─●─ : exactly one

# models/crm_erd.model.yaml
model:
  type: entity_relationship_diagram
  name: "CRM Database Schema"

entities:
  Contact:
    primary_key: id
    attributes:
      - id: {type: UUID, required: true}
      - first_name: {type: VARCHAR(100), required: true}
      - last_name: {type: VARCHAR(100), required: true}
      - email: {type: VARCHAR(255), required: true, unique: true}
      - phone: {type: VARCHAR(20)}
      - company_id: {type: UUID, foreign_key: Company.id}

  Company:
    primary_key: id
    attributes:
      - id: {type: UUID, required: true}
      - name: {type: VARCHAR(300), required: true, unique: true}
      - industry: {type: VARCHAR(50)}
      - website: {type: VARCHAR(500)}

  Deal:
    primary_key: id
    attributes:
      - id: {type: UUID, required: true}
      - title: {type: VARCHAR(300), required: true}
      - contact_id: {type: UUID, required: true, foreign_key: Contact.id}
      - company_id: {type: UUID, foreign_key: Company.id}
      - amount: {type: DECIMAL(15,2), required: true}
      - stage: {type: VARCHAR(50), required: true}
      - probability: {type: INTEGER, default: 50}

relationships:
  - from: Contact
    to: Company
    type: many_to_one
    cardinality: "0..* : 0..1"
    foreign_key: company_id

  - from: Deal
    to: Contact
    type: many_to_one
    cardinality: "0..* : 1"
    foreign_key: contact_id

  - from: Deal
    to: Company
    type: many_to_one
    cardinality: "0..* : 0..1"
    foreign_key: company_id

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cifra.platform/schemas/contact.json",
  "title": "Contact",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "first_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "last_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "company": {
      "$ref": "#/$defs/Company"
    }
  },
  "required": ["id", "first_name", "last_name", "email"],
  "$defs": {
    "Company": {
      "type": "object",
      "properties": {
        "id": {"type": "string", "format": "uuid"},
        "name": {"type": "string"}
      }
    }
  }
}

@prefix crm: <http://cifra.platform/ontology/crm#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .

# Классы
crm:Contact a owl:Class ;
    rdfs:label "Contact" ;
    rdfs:comment "Person or organization contact" .

crm:Company a owl:Class ;
    rdfs:label "Company" ;
    rdfs:comment "Business organization" .

# Свойства
crm:worksFor a owl:ObjectProperty ;
    rdfs:domain crm:Contact ;
    rdfs:range crm:Company ;
    rdfs:label "works for" .

# Экземпляры
crm:contact_001 a crm:Contact ;
    crm:firstName "Иван" ;
    crm:lastName "Петров" ;
    crm:email "ivan@example.com" ;
    crm:worksFor crm:company_001 .

crm:company_001 a crm:Company ;
    crm:name "ООО Рога и Копыта" ;
    crm:industry "retail" .

@startuml Deal_States

[*] --> Lead

Lead --> Qualification : qualify
Lead --> Lost : disqualify

Qualification --> Proposal : create_proposal
Qualification --> Lost : disqualify

Proposal --> Negotiation : start_negotiation
Proposal --> Lost : reject

Negotiation --> Won : accept
Negotiation --> Lost : reject
Negotiation --> Proposal : request_changes

Won --> [*]
Lost --> [*]

@enduml

# workflows/deal_states.workflow.yaml
state_machine:
  entity: Deal
  initial_state: Lead

states:
  Lead:
    description: "Первичный контакт"
    allowed_actions: [qualify, disqualify, edit]

  Qualification:
    description: "Квалификация лида"
    allowed_actions: [create_proposal, disqualify, edit]

  Proposal:
    description: "Коммерческое предложение"
    allowed_actions: [start_negotiation, reject, edit]

  Negotiation:
    description: "Переговоры"
    allowed_actions: [accept, reject, request_changes, edit]

  Won:
    description: "Сделка выиграна"
    final: true
    allowed_actions: [view]

  Lost:
    description: "Сделка проиграна"
    final: true
    allowed_actions: [view, reopen]

transitions:
  - from: Lead
    to: Qualification
    trigger: qualify
    guard: "deal.amount > 0 AND deal.contact IS NOT NULL"
    action: |
      deal.qualified_at = datetime.now()
      deal.save()

  - from: Qualification
    to: Proposal
    trigger: create_proposal
    action: |
      proposal = Proposal.create_for_deal(deal)
      deal.proposal = proposal
      deal.save()

  - from: Proposal
    to: Negotiation
    trigger: start_negotiation
    guard: "deal.proposal.status == 'sent'"

  - from: Negotiation
    to: Won
    trigger: accept
    action: |
      deal.won_at = datetime.now()
      deal.probability = 100
      deal.save()
      # Создать invoice
      Invoice.create_from_deal(deal)

  - from: Negotiation
    to: Lost
    trigger: reject
    action: |
      deal.lost_at = datetime.now()
      deal.probability = 0
      deal.save()

  - from: [Lead, Qualification, Proposal, Negotiation]
    to: Lost
    trigger: disqualify

# workflows/parallel_approval.petri.yaml
petri_net:
  name: "Параллельное согласование"

places:
  - id: p_submitted
    name: "Заявка подана"
    initial_tokens: 1

  - id: p_finance_review
    name: "Проверка финансами"
    initial_tokens: 0

  - id: p_legal_review
    name: "Проверка юристами"
    initial_tokens: 0

  - id: p_finance_approved
    name: "Финансы одобрили"
    initial_tokens: 0

  - id: p_legal_approved
    name: "Юристы одобрили"
    initial_tokens: 0

  - id: p_approved
    name: "Одобрено"
    initial_tokens: 0

transitions:
  - id: t_split
    name: "Разделить на проверки"
    input: [p_submitted]
    output: [p_finance_review, p_legal_review]

  - id: t_finance_approve
    name: "Финансы одобряют"
    input: [p_finance_review]
    output: [p_finance_approved]

  - id: t_legal_approve
    name: "Юристы одобряют"
    input: [p_legal_review]
    output: [p_legal_approved]

  - id: t_join
    name: "Объединить результаты"
    input: [p_finance_approved, p_legal_approved]
    output: [p_approved]

# api/crm_api.openapi.yaml
openapi: 3.1.0
info:
  title: CRM API
  version: 1.0.0
  description: API для управления контактами и сделками

servers:
  - url: https://api.example.com/v1

paths:
  /contacts:
    get:
      summary: Список контактов
      operationId: listContacts
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'

    post:
      summary: Создать контакт
      operationId: createContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '201':
          description: Контакт создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'

  /contacts/{contactId}:
    get:
      summary: Получить контакт
      parameters:
        - name: contactId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          description: Не найдено

components:
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        company:
          $ref: '#/components/schemas/Company'
      required: [id, first_name, last_name, email]

    ContactCreate:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
      required: [first_name, last_name, email]

    Company:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

# api/crm_events.asyncapi.yaml
asyncapi: 2.6.0
info:
  title: CRM Events API
  version: 1.0.0
  description: Event-driven architecture для CRM

servers:
  production:
    url: kafka.example.com:9092
    protocol: kafka
    description: Production Kafka cluster

channels:
  crm/contacts/created:
    description: Событие создания контакта
    publish:
      message:
        $ref: '#/components/messages/ContactCreated'

  crm/deals/won:
    description: Событие выигрыша сделки
    publish:
      message:
        $ref: '#/components/messages/DealWon'

components:
  messages:
    ContactCreated:
      name: ContactCreated
      title: Contact Created Event
      payload:
        type: object
        properties:
          event_id:
            type: string
            format: uuid
          timestamp:
            type: string
            format: date-time
          contact:
            $ref: '#/components/schemas/Contact'

    DealWon:
      name: DealWon
      title: Deal Won Event
      payload:
        type: object
        properties:
          event_id:
            type: string
          timestamp:
            type: string
            format: date-time
          deal:
            $ref: '#/components/schemas/Deal'

  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string

# api/crm_graphql.schema.graphql

type Contact {
  id: ID!
  firstName: String!
  lastName: String!
  email: String!
  phone: String
  company: Company
  deals: [Deal!]!
}

type Company {
  id: ID!
  name: String!
  industry: Industry
  website: String
  contacts: [Contact!]!
  deals: [Deal!]!
}

type Deal {
  id: ID!
  title: String!
  amount: Float!
  stage: DealStage!
  probability: Int!
  contact: Contact!
  company: Company
}

enum Industry {
  TECH
  FINANCE
  RETAIL
  MANUFACTURING
  OTHER
}

enum DealStage {
  LEAD
  QUALIFICATION
  PROPOSAL
  NEGOTIATION
  WON
  LOST
}

type Query {
  contact(id: ID!): Contact
  contacts(limit: Int, offset: Int): [Contact!]!

  company(id: ID!): Company
  companies(limit: Int, offset: Int): [Company!]!

  deal(id: ID!): Deal
  deals(stage: DealStage, limit: Int, offset: Int): [Deal!]!
}

type Mutation {
  createContact(input: CreateContactInput!): Contact!
  updateContact(id: ID!, input: UpdateContactInput!): Contact!
  deleteContact(id: ID!): Boolean!

  createDeal(input: CreateDealInput!): Deal!
  updateDealStage(id: ID!, stage: DealStage!): Deal!
}

input CreateContactInput {
  firstName: String!
  lastName: String!
  email: String!
  phone: String
  companyId: ID
}

input UpdateContactInput {
  firstName: String
  lastName: String
  email: String
  phone: String
  companyId: ID
}

input CreateDealInput {
  title: String!
  amount: Float!
  contactId: ID!
  companyId: ID
}

type Subscription {
  dealStageChanged(dealId: ID!): Deal!
  contactCreated: Contact!
}

┌────────────────────────────────────────────────────┐
│              CIDL META-FORMAT                      │
├────────────────────────────────────────────────────┤
│                                                    │
│  Единое определение:                               │
│  - Entities (данные)                               │
│  - Processes (бизнес-процессы)                     │
│  - Rules (правила)                                 │
│  - States (состояния)                              │
│  - API (интерфейсы)                                │
│  - Architecture (архитектура)                      │
│                                                    │
└────────────────────────────────────────────────────┘
                      ↓ Генераторы
         ┌────────────┼────────────┐
         ↓            ↓            ↓
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │ BPMN    │  │ OpenAPI │  │ GraphQL │
    │ XML     │  │ YAML    │  │ SDL     │
    └─────────┘  └─────────┘  └─────────┘
         ↓            ↓            ↓
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │ UML     │  │ ERD     │  │ArchiMate│
    │PlantUML │  │ Diagram │  │ XML     │
    └─────────┘  └─────────┘  └─────────┘
         ↓            ↓            ↓
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │SQLAlchemy│ │FastAPI  │  │ React   │
    │ Models  │  │Endpoints│  │Components│
    └─────────┘  └─────────┘  └─────────┘

# crm_complete.cidl.yaml
project:
  name: CRM System
  version: 1.0.0
  type: business_application

# 1. DATA MODELS (Entity definitions)
entities:
  Contact:
    extends: [BaseEntity, TimestampMixin, OwnershipMixin]
    fields:
      first_name: {type: string, max_length: 100, required: true}
      last_name: {type: string, max_length: 100, required: true}
      email: {type: email, unique: true, required: true}
      phone: {type: phone}
      company: {type: relation, target: Company}
      deals: {type: relation, target: Deal, many: true}

  Company:
    extends: [BaseEntity, TimestampMixin]
    fields:
      name: {type: string, max_length: 300, unique: true, required: true}
      industry: {type: enum, values: [tech, finance, retail]}
      website: {type: url}

  Deal:
    extends: [BaseEntity, TimestampMixin, AuditMixin]
    fields:
      title: {type: string, max_length: 300, required: true}
      amount: {type: decimal, min_value: 0, required: true}
      stage: {type: enum, values: [lead, qualification, proposal, negotiation, won, lost]}
      probability: {type: integer, min_value: 0, max_value: 100, default: 50}
      contact: {type: relation, target: Contact, required: true}
      company: {type: relation, target: Company}

# 2. BUSINESS PROCESSES
processes:
  DealLifecycle:
    type: business_process
    events:
      start:
        - trigger: api_call
          name: "New Deal Created"

    tasks:
      - id: Qualify
        name: "Qualify Lead"
        type: user
        assignee: sales_team

      - id: CreateProposal
        name: "Create Proposal"
        type: service
        endpoint: /proposals/create

      - id: Negotiate
        name: "Negotiate Terms"
        type: user
        assignee: sales_manager

      - id: CloseDeal
        name: "Close Deal"
        type: service
        endpoint: /deals/{id}/close

    gateways:
      - id: QualifyDecision
        type: exclusive
        branches:
          - condition: "deal.qualified == true"
            target: CreateProposal
          - condition: "deal.qualified == false"
            target: EndLost

    flows:
      - from: Start
        to: Qualify
      - from: Qualify
        to: QualifyDecision
      - from: CreateProposal
        to: Negotiate
      - from: Negotiate
        to: CloseDeal

# 3. BUSINESS RULES
rules:
  DealDiscount:
    type: decision_table
    inputs:
      - customer_type: {type: enum, values: [VIP, Regular, New]}
      - deal_amount: {type: decimal}
    output:
      discount_percent: {type: integer, range: [0, 100]}

    rules:
      - when: {customer_type: VIP, deal_amount: ">= 100000"}
        then: {discount_percent: 15}
      - when: {customer_type: VIP, deal_amount: ">= 50000"}
        then: {discount_percent: 10}
      - when: {customer_type: Regular, deal_amount: ">= 100000"}
        then: {discount_percent: 5}
      - when: {}
        then: {discount_percent: 0}

# 4. STATE MACHINES
state_machines:
  DealStates:
    entity: Deal
    initial: lead

    states:
      lead: {description: "Первичный контакт"}
      qualification: {description: "Квалификация"}
      proposal: {description: "Коммерческое предложение"}
      negotiation: {description: "Переговоры"}
      won: {description: "Выиграна", final: true}
      lost: {description: "Проиграна", final: true}

    transitions:
      - {from: lead, to: qualification, trigger: qualify}
      - {from: qualification, to: proposal, trigger: create_proposal}
      - {from: proposal, to: negotiation, trigger: start_negotiation}
      - {from: negotiation, to: won, trigger: accept}
      - {from: negotiation, to: lost, trigger: reject}

# 5. API DEFINITION
api:
  rest:
    version: v1
    base_path: /api/v1

    endpoints:
      # Auto-generated CRUD для всех entities
      - entity: Contact
        operations: [list, create, read, update, delete]

      - entity: Company
        operations: [list, create, read, update, delete]

      - entity: Deal
        operations: [list, create, read, update, delete]
        custom:
          - path: /{id}/qualify
            method: POST
            handler: qualify_deal

          - path: /{id}/close
            method: POST
            handler: close_deal

  graphql:
    enabled: true
    playground: true

    queries:
      - contacts
      - companies
      - deals

    mutations:
      - createContact
      - updateContact
      - createDeal
      - updateDealStage

    subscriptions:
      - dealStageChanged
      - contactCreated

  events:
    broker: kafka
    topics:
      - name: crm.contacts.created
        schema: ContactCreated

      - name: crm.deals.won
        schema: DealWon

# 6. ARCHITECTURE
architecture:
  layers:
    business:
      processes: [DealLifecycle]
      roles: [SalesManager, SalesRep]

    application:
      components:
        - name: CRM Application
          type: web_app
          technology: React + TypeScript

        - name: CRM API
          type: api
          technology: FastAPI + Python

    technology:
      nodes:
        - name: Web Server
          technology: nginx

        - name: App Server
          technology: uvicorn

        - name: Database
          technology: postgresql

# 7. CONFIGURATION
config:
  database:
    type: postgresql
    migrations: alembic

  auth:
    type: jwt
    token_expiration: 3600

  deployment:
    type: docker
    orchestration: docker-compose

$ python -m cidl.cli generate crm_complete.cidl.yaml --all

🔄 Generating from CIDL...

✅ Generated data models:
   ├─ SQLAlchemy models (generated/models/)
   ├─ Pydantic schemas (generated/schemas/)
   ├─ ERD diagram (docs/erd.png)
   └─ UML class diagram (docs/classes.puml)

✅ Generated business processes:
   ├─ BPMN 2.0 XML (generated/processes/deal_lifecycle.bpmn)
   ├─ Process documentation (docs/processes/)
   └─ Camunda deployment artifacts

✅ Generated business rules:
   ├─ DMN XML (generated/rules/deal_discount.dmn)
   ├─ Python rule engine (generated/rules/deal_discount.py)
   └─ Decision table visualization (docs/rules/)

✅ Generated state machines:
   ├─ State diagram (docs/states/deal_states.png)
   └─ Python state machine (generated/states/deal_states.py)

✅ Generated API:
   ├─ OpenAPI 3.1 spec (generated/api/openapi.yaml)
   ├─ GraphQL schema (generated/api/schema.graphql)
   ├─ AsyncAPI spec (generated/api/asyncapi.yaml)
   ├─ FastAPI routers (generated/api/routers/)
   └─ API documentation (docs/api/)

✅ Generated architecture:
   ├─ ArchiMate model (generated/architecture/archimate.xml)
   ├─ C4 diagrams (docs/architecture/c4/)
   └─ Deployment diagram (docs/architecture/deployment.png)

✅ Generated deployment:
   ├─ Dockerfile
   ├─ docker-compose.yml
   ├─ kubernetes manifests (k8s/)
   └─ nginx config

✅ Generated documentation:
   ├─ README.md
   ├─ API docs (Swagger UI)
   ├─ Process docs
   └─ Architecture docs

Done! 🚀

Next steps:
1. Review generated code in generated/
2. Customize if needed
3. Run: docker-compose up