# DSL Language Specification

This document describes the DSL (Domain Specific Language) used to specify fullstack CRUD applications. The DSL has four layers: Domain, DTO, API, and UI.

---

# DSL Grammar Concepts

## entity

An **entity** is a domain object that becomes a database table and a first-class resource in the backend and frontend.

```
entity Equipment {
  attribute id { type uuid; key primary; }
  attribute name { type string; is required; }
}
```

- **Domain:** Defines the canonical model; one entity = one Prisma model, one NestJS module, one React Admin resource.
- **Naming:** PascalCase (e.g. `Equipment`, `EquipmentType`, `RepairOrder`).

---

## attribute

An **attribute** is a field of an entity. It has a type and optional modifiers.

```
attribute name {
  description "Наименование";
  type string;
  is required;
  is unique;
}
```

**Modifiers:**

- `type` — required; one of: `string`, `uuid`, `integer`, `decimal`, `date`, `text`, or an enum name.
- `key primary` — this attribute is the primary key.
- `key foreign { relates Entity.field }` — foreign key to another entity's field.
- `is required` — non-nullable.
- `is unique` — unique constraint.
- `default Value` — default value (for enums or literals).
- `description "..."` — human-readable description.

---

## enum

An **enum** defines a fixed set of values. Used for attributes that can only take one of these values.

```
enum EquipmentStatus {
  value Active { label "В эксплуатации"; }
  value Repair { label "В ремонте"; }
}
```

- **value** — identifier used in data and code.
- **label** — optional display label for UI.

---

## primary key

Exactly one attribute per entity must be marked as primary key.

```
attribute id {
  type uuid;
  key primary;
}
```

Or for a natural key:

```
attribute code {
  type string;
  key primary;
  is required;
  is unique;
}
```

---

## foreign key

A **foreign key** links to another entity's primary key. The attribute type must match the referenced primary key type.

```
attribute equipmentTypeCode {
  type string;
  key foreign {
    relates EquipmentType.code;
  }
  is required;
}
```

- `relates Entity.attribute` — references `Entity`'s `attribute` (must be primary key).
- FK type must equal referenced PK type (e.g. `string` → `EquipmentType.code`, `uuid` → `Equipment.id`).

---

## required

- **is required** — attribute is non-nullable in domain and (unless overridden) in DTOs.
- Absence of `is required` means the attribute is optional (nullable).

---

## default

- **default Value** — applied when no value is provided (e.g. enum defaults like `default Active`).
- Value must exist in the enum when the attribute type is an enum.

---

## map

Used in **DTO** and **UI** layers to bind a DTO/UI field to a domain entity attribute.

**In DTO:**

```
attribute name {
  type string;
  map Equipment.name;
}
```

- Ensures DTO attribute corresponds to an existing `Entity.attribute` and that types align.

**In UI:**

```
attribute Наименование {
  map Equipment.name;
}
```

- UI label (e.g. "Наименование") maps to domain field `Equipment.name` for correct data binding and generation.

---

# DSL → System Component Mapping

## DSL → Prisma

| DSL Concept  | Prisma Result               |
| ------------ | --------------------------- |
| entity       | model                       |
| attribute    | field                       |
| enum         | enum                        |
| key primary  | @id or @id @default(uuid()) |
| key foreign  | relation + references       |
| type string  | String                      |
| type uuid    | String @id @default(uuid()) |
| type integer | Int                         |
| type decimal | Decimal                     |
| type date    | DateTime                    |
| type text    | String                      |

---

## DSL → NestJS

| DSL Concept    | NestJS Result                         |
| -------------- | ------------------------------------- |
| entity         | One module (e.g. equipment.module.ts) |
| entity         | Controller with CRUD endpoints        |
| entity         | Service with Prisma CRUD              |
| DTO (Create)   | create-{entity}.dto.ts                |
| DTO (Update)   | update-{entity}.dto.ts                |
| DTO (Response) | Used for GET response shape           |

API paths are derived from entity name: PascalCase → kebab-case, pluralized (e.g. `Equipment` → `/equipment`, `RepairOrder` → `/repair-orders`).

---

## DSL → React Admin

| DSL Concept           | React Admin Result                  |
| --------------------- | ----------------------------------- |
| entity                | Resource (name = kebab-case plural) |
| attribute             | Form field / column                 |
| type string           | TextInput, TextField                |
| type integer/decimal  | NumberInput, NumberField            |
| type date             | DateInput, DateField                |
| enum                  | SelectInput with choices            |
| foreign key           | ReferenceInput, ReferenceField      |
| UI attribute with map | Field with correct source           |

---

# DTO Mapping

- **map Entity.attribute** — DTO attribute corresponds to domain attribute; types must match.
- **Create DTO** — must not include generated primary keys (e.g. no `id` for uuid PK).
- **Update DTO** — all fields optional (nullable) for partial updates.
- **List response DTO** — must expose `data` (array) and `total` (integer) for React Admin compatibility.

---

# UI Mapping

- Each UI attribute should have **map Entity.attribute** so it binds to a real domain field.
- UI attribute name is the label (e.g. "Наименование"); **source** in generated components is the domain attribute name (e.g. `name`).
- Enums → SelectInput; foreign keys → ReferenceInput/ReferenceField.