175 lines
8.6 KiB
Markdown
175 lines
8.6 KiB
Markdown
---
|
|
name: mcd-mld-designer
|
|
description: >-
|
|
Design, document, and maintain database Conceptual Models (MCD) and Logical Models (MLD)
|
|
following strict Merise rules, naming conventions (<DB_TRIGRAM>_<TABLE> and <TBL_TRIGRAM>_<COLUMN>),
|
|
and native Mermaid diagrams rendered in Antigravity and VS Code. Enforces tracking in db/mcd.md
|
|
and db/mld.md, and must be used before any database modification.
|
|
---
|
|
|
|
# MCD & MLD Database Designer
|
|
|
|
This skill guides the creation, update, and maintenance of relational database architectures using the **Merise methodology** (MCD to MLD) with graphical **Mermaid.js** diagrams that render natively inside Antigravity artifacts and Visual Studio Code Markdown viewers.
|
|
|
|
---
|
|
|
|
## ⚠️ Mandatory Pre-Modification Rule
|
|
|
|
> [!IMPORTANT]
|
|
> **No database change may be made without this skill.**
|
|
> Before creating tables, adding columns, modifying relationships, writing ORM models, or running database migrations:
|
|
> 1. Read and inspect existing schemas in `db/mcd.md` and `db/mld.md`.
|
|
> 2. Apply all conceptual (MCD) and logical (MLD) modifications according to this skill.
|
|
> 3. Update and persist changes directly in `db/mcd.md` and `db/mld.md`.
|
|
> 4. Ensure `AGENT.md` (or `GEMINI.md`) in the project enforces this rule (see [AGENT.md Rule Template](./references/agent-rule-template.md)).
|
|
|
|
---
|
|
|
|
## 1. Strict Naming Conventions
|
|
|
|
All identifiers and data types must be in **UPPERCASE**.
|
|
|
|
### 1.1 Database Trigram (`<DB_TRIGRAM>`)
|
|
- Derived from the database or project name: **first 3 alphanumeric characters**, uppercase, stripped of accents/special characters (or an explicit 3-letter trigram requested by the user).
|
|
- *Examples*:
|
|
- Database `ECOMMERCE` ➔ `ECO`
|
|
- Database `INVENTORY` ➔ `INV`
|
|
- Database `HEALTHCARE` ➔ `HEA`
|
|
|
|
### 1.2 Table Names (`<DB_TRIGRAM>_<NAME_OF_TABLE>`)
|
|
- Every table is prefixed with `<DB_TRIGRAM>_` followed by the functional entity name in UPPERCASE.
|
|
- *Examples*:
|
|
- `ECO_CUSTOMER`
|
|
- `ECO_ORDER`
|
|
- `ECO_PRODUCT`
|
|
|
|
### 1.3 Table Trigram (`<TBL_TRIGRAM>`)
|
|
- Derived from the functional table name (without the DB prefix): **first 3 characters** of the table name.
|
|
- *Examples*:
|
|
- `CUSTOMER` ➔ `CUS`
|
|
- `ORDER` ➔ `ORD`
|
|
- `PRODUCT` ➔ `PRO`
|
|
- `CATEGORY` ➔ `CAT`
|
|
|
|
### 1.4 Column Names (`<TBL_TRIGRAM>_<NAME_OF_COLUMN>`)
|
|
- Every column is prefixed with its table's 3-letter abbreviation.
|
|
- *Examples for `ECO_CUSTOMER` (`CUS`)*:
|
|
- `CUS_ID` (Primary Key)
|
|
- `CUS_FIRST_NAME`
|
|
- `CUS_LAST_NAME`
|
|
- `CUS_EMAIL`
|
|
- `CUS_CREATED_AT`
|
|
|
|
### 1.5 Foreign Keys (`<HOST_TBL_TRIGRAM>_<TARGET_TBL_TRIGRAM>_<COLUMN_NAME>`)
|
|
- When Table A references Table B, the foreign key column in Table A is prefixed with `HOST_TBL_TRIGRAM_TARGET_TBL_TRIGRAM_`:
|
|
- *Examples*:
|
|
- Table `ECO_ORDER` (`ORD`) referencing `ECO_CUSTOMER` (`CUS`):
|
|
➔ Foreign Key column: `ORD_CUS_ID`
|
|
- Table `ECO_PRODUCT` (`PRO`) referencing `ECO_CATEGORY` (`CAT`):
|
|
➔ Foreign Key column: `PRO_CAT_ID`
|
|
|
|
### 1.6 Associative / Junction Tables (N:M Relationships)
|
|
- Use meaningful functional names whenever applicable (e.g. `ECO_ORDER_ITEM`), or concatenation of entities (e.g. `ECO_ORDER_PRODUCT`).
|
|
- Table trigram follows the functional name:
|
|
- `ECO_ORDER_ITEM` ➔ Trigram `ITE`
|
|
- Columns: `ITE_ORD_ID` (FK referencing `ECO_ORDER`), `ITE_PRO_ID` (FK referencing `ECO_PRODUCT`), `ITE_QUANTITY`, `ITE_UNIT_PRICE`.
|
|
- Primary Key is composite: `(ITE_ORD_ID, ITE_PRO_ID)`.
|
|
|
|
---
|
|
|
|
## 2. File-Based Tracking Architecture
|
|
|
|
All database artifacts **must** be stored and maintained under the project's `db/` folder:
|
|
|
|
```text
|
|
<project_root>/
|
|
├── db/
|
|
│ ├── mcd.md # Conceptual Data Model (Data Dictionary + Mermaid Flowchart MCD)
|
|
│ └── mld.md # Logical Data Model (Relational schema text + Mermaid erDiagram MLD)
|
|
├── AGENT.md # Contains the mandatory rule requiring this skill before DB edits
|
|
```
|
|
|
|
### Protocol for Any Database Edit:
|
|
1. **Never edit code or SQL migrations directly** without first updating `db/mcd.md` and `db/mld.md`.
|
|
2. **Review `db/mcd.md`**: Update the Data Dictionary, add/modify entities, associations, and cardinalities in the MCD Mermaid flowchart.
|
|
3. **Review `db/mld.md`**: Translate MCD updates into relational tables, foreign keys, constraints, and update the MLD Mermaid `erDiagram`.
|
|
4. **Synchronize & Document**: Add a changelog entry at the bottom of both `db/mcd.md` and `db/mld.md` detailing the version, date, and changes made.
|
|
|
|
---
|
|
|
|
## 3. End-to-End Modeling Workflow
|
|
|
|
Follow this 4-step sequence whenever modeling or extending a database:
|
|
|
|
### Step 1: Requirements & Data Dictionary
|
|
Extract all entities and properties from user requirements or business domain.
|
|
Construct the Data Dictionary table:
|
|
|
|
| Code Propriété | Libellé / Description | Type | Contraintes | Entité Source |
|
|
| :--- | :--- | :--- | :--- | :--- |
|
|
| `CUS_ID` | Identifiant client | INT | PK, AUTO_INCREMENT | CUSTOMER |
|
|
| `CUS_EMAIL` | Adresse e-mail | VARCHAR(150) | UNIQUE, NOT NULL | CUSTOMER |
|
|
| `ORD_ID` | Numéro de commande | INT | PK, AUTO_INCREMENT | ORDER |
|
|
|
|
*(In English contexts, use English column headers: Property Code, Description, Type, Constraints, Source Entity)*
|
|
|
|
### Step 2: Conceptual Data Model (MCD)
|
|
- Identify **Entities** (Entités) and **Associations** (Relations).
|
|
- Define **Merise Cardinalities**:
|
|
- `0,1`: Optional single link (zero or one)
|
|
- `1,1`: Mandatory single link (exactly one)
|
|
- `0,N`: Optional multiple link (zero to many)
|
|
- `1,N`: Mandatory multiple link (at least one)
|
|
- Render the MCD using a **Mermaid Flowchart** (`flowchart LR` or `flowchart TD`) compatible with Antigravity and VS Code:
|
|
- Entities as rectangular nodes with attributes.
|
|
- Associations as rounded/oval nodes `((Association))`.
|
|
- Links annotated with cardinalities: `ENTITE_A ---|"1,N"| ASSOC ---|"1,1"| ENTITE_B`.
|
|
- Save in `db/mcd.md`.
|
|
|
|
### Step 3: Logical Data Model (MLD)
|
|
Apply the standard Merise transformation rules (see [Merise Rules Reference](./references/merise-rules.md)):
|
|
1. **One-to-Many (`1,N` - `1,1` or `0,1`)**:
|
|
- The primary key of the `(0,N)` or `(1,N)` entity migrates into the `(1,1)` or `(0,1)` entity as a foreign key.
|
|
- Named: `<HOST_TRIGRAM>_<TARGET_TRIGRAM>_<COL>` (e.g. `ORD_CUS_ID`).
|
|
2. **Many-to-Many (`0,N`/`1,N` - `0,N`/`1,N`)**:
|
|
- The association becomes a junction table `<DB_TRIGRAM>_<NAME>`.
|
|
- Its primary key is composite, formed by foreign keys to both participating entities.
|
|
- Any attributes of the association become columns in this junction table.
|
|
3. **Write Relational Schema Text**:
|
|
- Primary Keys are underlined (or indicated with `(PK)`).
|
|
- Foreign Keys are marked with `#` (or `(FK)`).
|
|
- Example:
|
|
```text
|
|
ECO_CUSTOMER (CUS_ID, CUS_FIRST_NAME, CUS_LAST_NAME, CUS_EMAIL)
|
|
ECO_ORDER (ORD_ID, ORD_DATE, ORD_TOTAL_AMOUNT, #ORD_CUS_ID)
|
|
ECO_ORDER_ITEM (#ITE_ORD_ID, #ITE_PRO_ID, ITE_QUANTITY, ITE_UNIT_PRICE)
|
|
```
|
|
4. **Render Mermaid `erDiagram`**:
|
|
- Use standard Mermaid ER syntax with exact table names and typed columns.
|
|
- Save in `db/mld.md`.
|
|
|
|
### Step 4: Normalization Verification (3NF)
|
|
Verify all schemas comply with the 3 Normal Forms:
|
|
- **1NF**: All attributes are atomic (no repeating groups or comma-separated lists).
|
|
- **2NF**: In 1NF and all non-key attributes are fully functionally dependent on the entire primary key (no partial dependency on part of a composite key).
|
|
- **3NF**: In 2NF and no transitive functional dependencies (no non-key attribute depends on another non-key attribute).
|
|
|
|
---
|
|
|
|
## 4. Bilingual Support (French / English)
|
|
|
|
Adapt the vocabulary and documentation language automatically to the language used by the user:
|
|
- **French**: Modèle Conceptuel de Données (MCD), Modèle Logique de Données (MLD), Entités, Associations, Cardinalités, Dictionnaire des Données, Clé Primaire (PK), Clé Étrangère (FK).
|
|
- **English**: Conceptual Data Model (CDM / MCD), Logical Data Model (LDM / MLD), Entities, Relationships, Cardinalities, Data Dictionary, Primary Key (PK), Foreign Key (FK).
|
|
|
|
The strict naming conventions (`<DB>_<TABLE>` and `<TBL>_<COLUMN>`) and Mermaid diagram syntax remain strictly enforced regardless of language.
|
|
|
|
---
|
|
|
|
## 5. References & Examples
|
|
|
|
- **[AGENT.md Rule Template](./references/agent-rule-template.md)**: Setup instructions to enforce this skill in `AGENT.md` / `GEMINI.md`.
|
|
- **[Merise Transformation Rules](./references/merise-rules.md)**: Detailed formal rules for translating MCD associations to MLD relations.
|
|
- **[Mermaid Diagram Syntax](./references/diagram-syntax.md)**: Formatting rules and templates for Antigravity & VS Code compatibility.
|
|
- **[Complete E-Commerce Example](./examples/ecommerce-sample.md)**: Fully worked example with `db/mcd.md` and `db/mld.md` templates.
|