feat: append of basic skills
This commit is contained in:
Infuseting
commit
613d7ea8f6
|
|
@ -0,0 +1,165 @@
|
||||||
|
---
|
||||||
|
name: frontend-design
|
||||||
|
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
|
||||||
|
license: MIT
|
||||||
|
---
|
||||||
|
|
||||||
|
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||||
|
|
||||||
|
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||||
|
|
||||||
|
## Design Thinking
|
||||||
|
|
||||||
|
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||||
|
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||||
|
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||||
|
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||||
|
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||||
|
|
||||||
|
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||||
|
|
||||||
|
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||||
|
- Production-grade and functional
|
||||||
|
- Visually striking and memorable
|
||||||
|
- Cohesive with a clear aesthetic point-of-view
|
||||||
|
- Meticulously refined in every detail
|
||||||
|
|
||||||
|
## Frontend Aesthetics Guidelines
|
||||||
|
|
||||||
|
Focus on:
|
||||||
|
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||||
|
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||||
|
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||||
|
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||||
|
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||||
|
|
||||||
|
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||||
|
|
||||||
|
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||||
|
|
||||||
|
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||||
|
|
||||||
|
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||||
|
|
||||||
|
## Common Design Issues
|
||||||
|
|
||||||
|
### Typography Problems
|
||||||
|
**Issue**: Generic font choices (Inter, Arial, Roboto)
|
||||||
|
**Solution**: Use distinctive font pairings from Google Fonts or custom fonts. Examples: display fonts (Playfair Display, Bebas Neue, Archivo Black) paired with refined body fonts (Source Serif, Crimson Text, Work Sans).
|
||||||
|
|
||||||
|
**Issue**: Poor hierarchy and readability
|
||||||
|
**Solution**: Establish clear type scale with CSS variables. Use size, weight, and spacing to create visual hierarchy.
|
||||||
|
|
||||||
|
### Color & Theme Issues
|
||||||
|
**Issue**: Clichéd color schemes (purple gradients on white)
|
||||||
|
**Solution**: Commit to bold, contextual color choices. Use CSS variables for consistency. Consider: monochromatic with one accent, high-contrast brutalism, muted earth tones, vibrant complementary pairs.
|
||||||
|
|
||||||
|
**Issue**: Low contrast affecting accessibility
|
||||||
|
**Solution**: Verify color contrast ratios meet WCAG AA (4.5:1 for text, 3:1 for large text). Use tools like WebAIM Contrast Checker.
|
||||||
|
|
||||||
|
### Layout Issues
|
||||||
|
**Issue**: Predictable, cookie-cutter layouts
|
||||||
|
**Solution**: Experiment with asymmetry, overlapping elements, diagonal flow, grid-breaking components. Use CSS Grid and Flexbox creatively.
|
||||||
|
|
||||||
|
**Issue**: Responsive breakpoints failing
|
||||||
|
**Solution**: Test at 320px, 768px, 1024px, 1440px. Use fluid typography (clamp()) and container queries.
|
||||||
|
|
||||||
|
### Animation Issues
|
||||||
|
**Issue**: Excessive or jarring animations
|
||||||
|
**Solution**: Use subtle, purposeful animations. Respect `prefers-reduced-motion`. Focus on one well-orchestrated page load rather than scattered micro-interactions.
|
||||||
|
|
||||||
|
**Issue**: Performance problems from animations
|
||||||
|
**Solution**: Prefer CSS animations over JavaScript. Use `transform` and `opacity` (GPU-accelerated). Avoid animating `width`, `height`, `top`, `left`.
|
||||||
|
|
||||||
|
### Accessibility Violations
|
||||||
|
**Issue**: Missing keyboard navigation
|
||||||
|
**Solution**: Ensure all interactive elements are keyboard accessible. Add visible focus states.
|
||||||
|
|
||||||
|
**Issue**: Poor semantic HTML
|
||||||
|
**Solution**: Use semantic tags (`<nav>`, `<main>`, `<article>`, `<section>`). Add ARIA labels where needed.
|
||||||
|
|
||||||
|
**Issue**: Missing alt text on images
|
||||||
|
**Solution**: Add descriptive alt text for images. Use empty alt (`alt=""`) for decorative images.
|
||||||
|
|
||||||
|
## Design Validation Checklist
|
||||||
|
|
||||||
|
After creating a design, verify:
|
||||||
|
|
||||||
|
### Visual Quality
|
||||||
|
- [ ] Color contrast meets WCAG AA standards (4.5:1 for text)
|
||||||
|
- [ ] Typography is distinctive and readable
|
||||||
|
- [ ] Visual hierarchy is clear (headings, body, accents)
|
||||||
|
- [ ] Design has a clear aesthetic direction (not generic)
|
||||||
|
- [ ] Spacing and alignment are consistent
|
||||||
|
- [ ] No overused AI patterns (purple gradients, Inter font, etc.)
|
||||||
|
|
||||||
|
### Responsive Design
|
||||||
|
- [ ] Tested at mobile breakpoint (320px-480px)
|
||||||
|
- [ ] Tested at tablet breakpoint (768px-1024px)
|
||||||
|
- [ ] Tested at desktop breakpoint (1440px+)
|
||||||
|
- [ ] Text remains readable at all sizes
|
||||||
|
- [ ] Images and media scale appropriately
|
||||||
|
- [ ] No horizontal scrolling on small screens
|
||||||
|
|
||||||
|
### Accessibility
|
||||||
|
- [ ] All interactive elements keyboard accessible
|
||||||
|
- [ ] Focus states visible and clear
|
||||||
|
- [ ] Semantic HTML used throughout
|
||||||
|
- [ ] Alt text present for images
|
||||||
|
- [ ] Color is not the only indicator (for colorblind users)
|
||||||
|
- [ ] Animations respect `prefers-reduced-motion`
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
- [ ] Animations use GPU-accelerated properties (`transform`, `opacity`)
|
||||||
|
- [ ] No layout thrashing from animations
|
||||||
|
- [ ] Images optimized (WebP, proper dimensions)
|
||||||
|
- [ ] Fonts loaded efficiently (font-display: swap)
|
||||||
|
- [ ] Critical CSS inlined for faster first paint
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
- [ ] CSS variables used for theming consistency
|
||||||
|
- [ ] Clean, semantic class names
|
||||||
|
- [ ] No hardcoded magic numbers
|
||||||
|
- [ ] Comments explain complex decisions
|
||||||
|
- [ ] Works without JavaScript (progressive enhancement)
|
||||||
|
|
||||||
|
### Browser Compatibility
|
||||||
|
- [ ] Tested in Chrome/Edge (Chromium)
|
||||||
|
- [ ] Tested in Firefox
|
||||||
|
- [ ] Tested in Safari (WebKit)
|
||||||
|
- [ ] Fallbacks for modern CSS features (Grid, clamp, etc.)
|
||||||
|
|
||||||
|
## Testing Your Design
|
||||||
|
|
||||||
|
### Visual Testing
|
||||||
|
```bash
|
||||||
|
# Test responsive breakpoints
|
||||||
|
# Open browser DevTools → Toggle device toolbar
|
||||||
|
# Test at: 320px, 768px, 1024px, 1440px, 1920px
|
||||||
|
```
|
||||||
|
|
||||||
|
### Accessibility Testing
|
||||||
|
```bash
|
||||||
|
# Check color contrast
|
||||||
|
# Use WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
|
||||||
|
|
||||||
|
# Test keyboard navigation
|
||||||
|
# Tab through all interactive elements
|
||||||
|
# Verify visible focus states
|
||||||
|
# Test with screen reader (VoiceOver on Mac, NVDA on Windows)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Testing
|
||||||
|
```bash
|
||||||
|
# Open browser DevTools → Performance tab
|
||||||
|
# Record page load and interactions
|
||||||
|
# Look for layout shifts (CLS)
|
||||||
|
# Verify animations run at 60fps
|
||||||
|
# Check for memory leaks with long animations
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cross-Browser Testing
|
||||||
|
- Chrome/Edge: Primary testing
|
||||||
|
- Firefox: Verify CSS Grid/Flexbox behavior
|
||||||
|
- Safari: Test WebKit-specific issues
|
||||||
|
- Mobile browsers: Test touch interactions and viewport
|
||||||
|
|
@ -0,0 +1,174 @@
|
||||||
|
---
|
||||||
|
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.
|
||||||
|
|
@ -0,0 +1,217 @@
|
||||||
|
# End-to-End Database Design Example: E-Commerce Platform
|
||||||
|
|
||||||
|
This reference demonstrates the exact structure and content required for `db/mcd.md` and `db/mld.md` in a project named `ECOMMERCE` (Database Trigram: `ECO`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. File: `db/mcd.md` (Conceptual Data Model)
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Modèle Conceptuel de Données (MCD) - E-Commerce Platform
|
||||||
|
|
||||||
|
**Projet**: E-Commerce Platform
|
||||||
|
**Trigramme Base de Données**: `ECO`
|
||||||
|
**Dernière mise à jour**: 2026-09-12
|
||||||
|
**Version**: 1.0.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Dictionnaire des Données
|
||||||
|
|
||||||
|
| Code Propriété | Libellé / Description | Type | Contraintes | Entité Source |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
|
| `CUS_ID` | Identifiant unique du client | INT | PK, NOT NULL | CUSTOMER |
|
||||||
|
| `CUS_FIRST_NAME` | Prénom du client | VARCHAR(50) | NOT NULL | CUSTOMER |
|
||||||
|
| `CUS_LAST_NAME` | Nom de famille du client | VARCHAR(50) | NOT NULL | CUSTOMER |
|
||||||
|
| `CUS_EMAIL` | Adresse e-mail du client | VARCHAR(150) | UNIQUE, NOT NULL | CUSTOMER |
|
||||||
|
| `CUS_CREATED_AT` | Date d'inscription | TIMESTAMP | NOT NULL | CUSTOMER |
|
||||||
|
| `ORD_ID` | Identifiant unique de la commande | INT | PK, NOT NULL | ORDER |
|
||||||
|
| `ORD_DATE` | Date de la commande | TIMESTAMP | NOT NULL | ORDER |
|
||||||
|
| `ORD_TOTAL_AMOUNT` | Montant total de la commande | DECIMAL(10,2) | NOT NULL, >= 0 | ORDER |
|
||||||
|
| `ORD_STATUS` | Statut de la commande (PENDING, PAID, SHIPPED) | VARCHAR(20) | NOT NULL | ORDER |
|
||||||
|
| `PRO_ID` | Identifiant unique du produit | INT | PK, NOT NULL | PRODUCT |
|
||||||
|
| `PRO_NAME` | Nom du produit | VARCHAR(100) | NOT NULL | PRODUCT |
|
||||||
|
| `PRO_PRICE` | Prix unitaire hors taxe | DECIMAL(10,2) | NOT NULL, >= 0 | PRODUCT |
|
||||||
|
| `PRO_STOCK` | Quantité en stock | INT | NOT NULL, >= 0 | PRODUCT |
|
||||||
|
| `CAT_ID` | Identifiant de la catégorie | INT | PK, NOT NULL | CATEGORY |
|
||||||
|
| `CAT_NAME` | Nom de la catégorie | VARCHAR(50) | UNIQUE, NOT NULL | CATEGORY |
|
||||||
|
| `ITE_QUANTITY` | Quantité commandée pour un produit | INT | NOT NULL, > 0 | CONTIENT (ASSOCIATION) |
|
||||||
|
| `ITE_UNIT_PRICE` | Prix unitaire facturé au moment de l'achat | DECIMAL(10,2) | NOT NULL | CONTIENT (ASSOCIATION) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Règles de Gestion & Associations
|
||||||
|
|
||||||
|
1. **PASSER (PLACE)** :
|
||||||
|
- Un client peut passer 0 ou plusieurs commandes : `CUSTOMER (0,N)`.
|
||||||
|
- Une commande est passée par exactement un client : `ORDER (1,1)`.
|
||||||
|
2. **CONTIENT (CONTAIN)** :
|
||||||
|
- Une commande contient 1 ou plusieurs produits : `ORDER (1,N)`.
|
||||||
|
- Un produit peut figurer dans 0 ou plusieurs commandes : `PRODUCT (0,N)`.
|
||||||
|
- Propriétés de l'association : `ITE_QUANTITY`, `ITE_UNIT_PRICE`.
|
||||||
|
3. **CLASSIFIER (CLASSIFY)** :
|
||||||
|
- Une catégorie peut contenir 0 ou plusieurs produits : `CATEGORY (0,N)`.
|
||||||
|
- Un produit appartient obligatoirement à une et une seule catégorie : `PRODUCT (1,1)`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Diagramme Conceptuel (MCD)
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
%% ENTITIES
|
||||||
|
CUSTOMER["CUSTOMER<br/>-------------------<br/>+ CUS_ID<br/>- CUS_FIRST_NAME<br/>- CUS_LAST_NAME<br/>- CUS_EMAIL<br/>- CUS_CREATED_AT"]
|
||||||
|
|
||||||
|
ORDER["ORDER<br/>-------------------<br/>+ ORD_ID<br/>- ORD_DATE<br/>- ORD_TOTAL_AMOUNT<br/>- ORD_STATUS"]
|
||||||
|
|
||||||
|
PRODUCT["PRODUCT<br/>-------------------<br/>+ PRO_ID<br/>- PRO_NAME<br/>- PRO_PRICE<br/>- PRO_STOCK"]
|
||||||
|
|
||||||
|
CATEGORY["CATEGORY<br/>-------------------<br/>+ CAT_ID<br/>- CAT_NAME"]
|
||||||
|
|
||||||
|
%% ASSOCIATIONS
|
||||||
|
ASSOC_PASSER(["PASSER"])
|
||||||
|
ASSOC_CONTIENT(["CONTIENT<br/>-------------------<br/>- ITE_QUANTITY<br/>- ITE_UNIT_PRICE"])
|
||||||
|
ASSOC_CLASSIER(["CLASSIFIER"])
|
||||||
|
|
||||||
|
%% CARDINALITIES
|
||||||
|
CUSTOMER ---|"0,N"| ASSOC_PASSER
|
||||||
|
ASSOC_PASSER ---|"1,1"| ORDER
|
||||||
|
|
||||||
|
ORDER ---|"1,N"| ASSOC_CONTIENT
|
||||||
|
ASSOC_CONTIENT ---|"0,N"| PRODUCT
|
||||||
|
|
||||||
|
PRODUCT ---|"1,1"| ASSOC_CLASSIER
|
||||||
|
ASSOC_CLASSIER ---|"0,N"| CATEGORY
|
||||||
|
|
||||||
|
%% STYLING
|
||||||
|
classDef entity fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b;
|
||||||
|
classDef assoc fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100;
|
||||||
|
class CUSTOMER,ORDER,PRODUCT,CATEGORY entity;
|
||||||
|
class ASSOC_PASSER,ASSOC_CONTIENT,ASSOC_CLASSIER assoc;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Historique des Modifications (Changelog)
|
||||||
|
|
||||||
|
| Version | Date | Auteur | Description des modifications |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| 1.0.0 | 2026-09-12 | AI Assistant | Création initiale du MCD avec CUSTOMER, ORDER, PRODUCT, CATEGORY. |
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. File: `db/mld.md` (Logical Data Model)
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Modèle Logique de Données (MLD) - E-Commerce Platform
|
||||||
|
|
||||||
|
**Projet**: E-Commerce Platform
|
||||||
|
**Trigramme Base de Données**: `ECO`
|
||||||
|
**Dernière mise à jour**: 2026-09-12
|
||||||
|
**Version**: 1.0.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Schéma Relationnel Textuel
|
||||||
|
|
||||||
|
- **ECO_CUSTOMER** (<u>CUS_ID</u>, CUS_FIRST_NAME, CUS_LAST_NAME, CUS_EMAIL, CUS_CREATED_AT)
|
||||||
|
- **ECO_CATEGORY** (<u>CAT_ID</u>, CAT_NAME)
|
||||||
|
- **ECO_PRODUCT** (<u>PRO_ID</u>, PRO_NAME, PRO_PRICE, PRO_STOCK, #PRO_CAT_ID)
|
||||||
|
- **ECO_ORDER** (<u>ORD_ID</u>, ORD_DATE, ORD_TOTAL_AMOUNT, ORD_STATUS, #ORD_CUS_ID)
|
||||||
|
- **ECO_ORDER_ITEM** (<u>#ITE_ORD_ID</u>, <u>#ITE_PRO_ID</u>, ITE_QUANTITY, ITE_UNIT_PRICE)
|
||||||
|
|
||||||
|
*Note: Les clés primaires sont soulignées (<u>PK</u>) et les clés étrangères sont préfixées d'un dièse (#).*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Description des Tables & Contraintes
|
||||||
|
|
||||||
|
### 2.1 Table `ECO_CUSTOMER`
|
||||||
|
- `CUS_ID`: INT, PRIMARY KEY, AUTO_INCREMENT
|
||||||
|
- `CUS_FIRST_NAME`: VARCHAR(50), NOT NULL
|
||||||
|
- `CUS_LAST_NAME`: VARCHAR(50), NOT NULL
|
||||||
|
- `CUS_EMAIL`: VARCHAR(150), UNIQUE, NOT NULL
|
||||||
|
- `CUS_CREATED_AT`: TIMESTAMP, DEFAULT CURRENT_TIMESTAMP
|
||||||
|
|
||||||
|
### 2.2 Table `ECO_CATEGORY`
|
||||||
|
- `CAT_ID`: INT, PRIMARY KEY, AUTO_INCREMENT
|
||||||
|
- `CAT_NAME`: VARCHAR(50), UNIQUE, NOT NULL
|
||||||
|
|
||||||
|
### 2.3 Table `ECO_PRODUCT`
|
||||||
|
- `PRO_ID`: INT, PRIMARY KEY, AUTO_INCREMENT
|
||||||
|
- `PRO_NAME`: VARCHAR(100), NOT NULL
|
||||||
|
- `PRO_PRICE`: DECIMAL(10,2), NOT NULL, CHECK (PRO_PRICE >= 0)
|
||||||
|
- `PRO_STOCK`: INT, NOT NULL, DEFAULT 0, CHECK (PRO_STOCK >= 0)
|
||||||
|
- `PRO_CAT_ID`: INT, NOT NULL, FOREIGN KEY REFERENCES `ECO_CATEGORY(CAT_ID)`
|
||||||
|
|
||||||
|
### 2.4 Table `ECO_ORDER`
|
||||||
|
- `ORD_ID`: INT, PRIMARY KEY, AUTO_INCREMENT
|
||||||
|
- `ORD_DATE`: TIMESTAMP, NOT NULL, DEFAULT CURRENT_TIMESTAMP
|
||||||
|
- `ORD_TOTAL_AMOUNT`: DECIMAL(10,2), NOT NULL, CHECK (ORD_TOTAL_AMOUNT >= 0)
|
||||||
|
- `ORD_STATUS`: VARCHAR(20), NOT NULL, CHECK (ORD_STATUS IN ('PENDING', 'PAID', 'SHIPPED', 'CANCELLED'))
|
||||||
|
- `ORD_CUS_ID`: INT, NOT NULL, FOREIGN KEY REFERENCES `ECO_CUSTOMER(CUS_ID)`
|
||||||
|
|
||||||
|
### 2.5 Table `ECO_ORDER_ITEM` (Junction Table)
|
||||||
|
- `ITE_ORD_ID`: INT, NOT NULL, FOREIGN KEY REFERENCES `ECO_ORDER(ORD_ID)` ON DELETE CASCADE
|
||||||
|
- `ITE_PRO_ID`: INT, NOT NULL, FOREIGN KEY REFERENCES `ECO_PRODUCT(PRO_ID)`
|
||||||
|
- `ITE_QUANTITY`: INT, NOT NULL, CHECK (ITE_QUANTITY > 0)
|
||||||
|
- `ITE_UNIT_PRICE`: DECIMAL(10,2), NOT NULL, CHECK (ITE_UNIT_PRICE >= 0)
|
||||||
|
- **PRIMARY KEY**: `(ITE_ORD_ID, ITE_PRO_ID)`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Diagramme Logique (MLD)
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
erDiagram
|
||||||
|
ECO_CUSTOMER {
|
||||||
|
INT CUS_ID PK
|
||||||
|
VARCHAR CUS_FIRST_NAME
|
||||||
|
VARCHAR CUS_LAST_NAME
|
||||||
|
VARCHAR CUS_EMAIL
|
||||||
|
TIMESTAMP CUS_CREATED_AT
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_CATEGORY {
|
||||||
|
INT CAT_ID PK
|
||||||
|
VARCHAR CAT_NAME
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_PRODUCT {
|
||||||
|
INT PRO_ID PK
|
||||||
|
VARCHAR PRO_NAME
|
||||||
|
DECIMAL PRO_PRICE
|
||||||
|
INT PRO_STOCK
|
||||||
|
INT PRO_CAT_ID FK
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_ORDER {
|
||||||
|
INT ORD_ID PK
|
||||||
|
TIMESTAMP ORD_DATE
|
||||||
|
DECIMAL ORD_TOTAL_AMOUNT
|
||||||
|
VARCHAR ORD_STATUS
|
||||||
|
INT ORD_CUS_ID FK
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_ORDER_ITEM {
|
||||||
|
INT ITE_ORD_ID PK,FK
|
||||||
|
INT ITE_PRO_ID PK,FK
|
||||||
|
INT ITE_QUANTITY
|
||||||
|
DECIMAL ITE_UNIT_PRICE
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_CUSTOMER ||--o{ ECO_ORDER : "places"
|
||||||
|
ECO_CATEGORY ||--o{ ECO_PRODUCT : "classifies"
|
||||||
|
ECO_ORDER ||--|{ ECO_ORDER_ITEM : "contains"
|
||||||
|
ECO_PRODUCT ||--o{ ECO_ORDER_ITEM : "ordered_in"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Historique des Modifications (Changelog)
|
||||||
|
|
||||||
|
| Version | Date | Auteur | Description des modifications |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| 1.0.0 | 2026-09-12 | AI Assistant | Création initiale du MLD avec ECO_CUSTOMER, ECO_CATEGORY, ECO_PRODUCT, ECO_ORDER, ECO_ORDER_ITEM. |
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,61 @@
|
||||||
|
# AGENT.md & GEMINI.md Rule Template
|
||||||
|
|
||||||
|
To ensure that any AI assistant working on the project strictly adheres to the database design process and never modifies the database without updating the MCD/MLD, add the following section to the project's root `AGENT.md` or `GEMINI.md` file (or `.agents/rules/db-modeling.md`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Copy-Paste Section for `AGENT.md` / `GEMINI.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
<!-- ===================================================================== -->
|
||||||
|
<!-- DATABASE DESIGN & MODIFICATION POLICY -->
|
||||||
|
<!-- ===================================================================== -->
|
||||||
|
|
||||||
|
## Database Design & Modification Rules (MANDATORY)
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> **YOU CANNOT PERFORM ANY DATABASE MODIFICATIONS WITHOUT USING THE `mcd-mld-designer` SKILL.**
|
||||||
|
>
|
||||||
|
> Direct editing of database tables, columns, migrations, or ORM models without first updating the documentation is strictly forbidden.
|
||||||
|
|
||||||
|
### 1. Source of Truth Files
|
||||||
|
All database models are tracked and versioned in the following project files:
|
||||||
|
- `db/mcd.md`: Conceptual Data Model (MCD) containing the Data Dictionary, Entities, Associations, and Mermaid Flowchart.
|
||||||
|
- `db/mld.md`: Logical Data Model (MLD) containing Relational Schemas, Constraints, and Mermaid ER Diagram.
|
||||||
|
|
||||||
|
### 2. Pre-Modification Protocol
|
||||||
|
Before creating a new table, adding/renaming a column, or altering a relationship:
|
||||||
|
1. Activate the `mcd-mld-designer` skill.
|
||||||
|
2. Read and analyze the current state in `db/mcd.md` and `db/mld.md`.
|
||||||
|
3. Update `db/mcd.md` (Entities, Attributes, Associations, Cardinalities).
|
||||||
|
4. Update `db/mld.md` (Relational Schemas, Foreign Keys, Types, Constraints).
|
||||||
|
5. Document the modification in the Changelog section of both files.
|
||||||
|
6. Only after steps 1-5 are completed may code, ORM models, or migration scripts be written.
|
||||||
|
|
||||||
|
### 3. Strict Naming Conventions
|
||||||
|
- **Tables**: `<3_CHARS_DB>_<TABLE_NAME>` in UPPERCASE (e.g. `ECO_CUSTOMER`).
|
||||||
|
- **Columns**: `<3_CHARS_TABLE>_<COLUMN_NAME>` in UPPERCASE (e.g. `CUS_EMAIL`, `CUS_ID`).
|
||||||
|
- **Foreign Keys**: `<HOST_TRIGRAM>_<TARGET_TRIGRAM>_<COLUMN_NAME>` (e.g. in `ECO_ORDER`, FK referencing `ECO_CUSTOMER` is `ORD_CUS_ID`).
|
||||||
|
- **Associative Tables**: Meaningful functional name (e.g. `ECO_ORDER_ITEM` with `ITE_ORD_ID`, `ITE_PRO_ID`, `ITE_QUANTITY`) or concatenated entity names.
|
||||||
|
- **Casing**: UPPERCASE for all prefixes, table names, column names, and data types.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Alternative: Local Rule File (`.agents/rules/db-modeling.md`)
|
||||||
|
|
||||||
|
If the project uses Antigravity directory-based rules, create `.agents/rules/db-modeling.md` with frontmatter:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
description: Mandatory database design and modification rules using mcd-mld-designer
|
||||||
|
trigger: always_on
|
||||||
|
---
|
||||||
|
|
||||||
|
# Database Modification Enforcement Rule
|
||||||
|
|
||||||
|
Whenever the user's prompt or task involves database tables, schema design, migrations, or ORM models:
|
||||||
|
1. Activate and follow the `mcd-mld-designer` skill.
|
||||||
|
2. Ensure all schema definitions exist and are maintained in `db/mcd.md` and `db/mld.md`.
|
||||||
|
3. Respect all naming conventions (<DB>_<TABLE> and <TBL>_<COL>) and UPPERCASE casing.
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,109 @@
|
||||||
|
# Mermaid Diagram Syntax Guide (Antigravity & VS Code Compatible)
|
||||||
|
|
||||||
|
Both Antigravity and Visual Studio Code (via Markdown preview extensions) natively render Mermaid diagrams. To avoid syntax or parsing errors, follow these strict templates.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. MCD Diagram Template (`flowchart LR` or `flowchart TD`)
|
||||||
|
|
||||||
|
Merise MCDs represent **Entities** (rectangles) and **Associations** (rounded/ovals) connected by lines labeled with `(min,max)` cardinalities.
|
||||||
|
|
||||||
|
### Syntax Guidelines
|
||||||
|
1. Always quote edge labels containing commas: `---|"1,N"|` (unquoted commas can break Mermaid parsers).
|
||||||
|
2. Use `<br/>` for line breaks inside node labels.
|
||||||
|
3. Keep entity attributes clean with a separator (`---`).
|
||||||
|
4. Association nodes use double parentheses `((Name))` or stadium brackets `([Name])`.
|
||||||
|
|
||||||
|
### Code Example
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
%% ENTITIES
|
||||||
|
CUSTOMER["CUSTOMER<br/>-------------------<br/>+ CUS_ID (Identifiant)<br/>- CUS_FIRST_NAME<br/>- CUS_LAST_NAME<br/>- CUS_EMAIL"]
|
||||||
|
|
||||||
|
ORDER["ORDER<br/>-------------------<br/>+ ORD_ID (Identifiant)<br/>- ORD_DATE<br/>- ORD_TOTAL_AMOUNT"]
|
||||||
|
|
||||||
|
PRODUCT["PRODUCT<br/>-------------------<br/>+ PRO_ID (Identifiant)<br/>- PRO_NAME<br/>- PRO_PRICE"]
|
||||||
|
|
||||||
|
%% ASSOCIATIONS
|
||||||
|
ASSOC_PASS(["PASSER / PLACE"])
|
||||||
|
ASSOC_CONT(["CONTENIR / CONTAIN<br/>-------------------<br/>- ITE_QUANTITY<br/>- ITE_UNIT_PRICE"])
|
||||||
|
|
||||||
|
%% CARDINALITIES
|
||||||
|
CUSTOMER ---|"0,N"| ASSOC_PASS
|
||||||
|
ASSOC_PASS ---|"1,1"| ORDER
|
||||||
|
|
||||||
|
ORDER ---|"1,N"| ASSOC_CONT
|
||||||
|
ASSOC_CONT ---|"0,N"| PRODUCT
|
||||||
|
|
||||||
|
%% STYLING
|
||||||
|
classDef entity fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b;
|
||||||
|
classDef assoc fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100;
|
||||||
|
class CUSTOMER,ORDER,PRODUCT entity;
|
||||||
|
class ASSOC_PASS,ASSOC_CONT assoc;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. MLD Diagram Template (`erDiagram`)
|
||||||
|
|
||||||
|
Merise MLDs represent normalized relational tables with explicit types, primary keys (`PK`), and foreign keys (`FK`).
|
||||||
|
|
||||||
|
### Syntax Guidelines
|
||||||
|
1. In Mermaid `erDiagram`, data types must be single tokens without spaces (e.g. `VARCHAR`, `INT`, `DECIMAL`, `TIMESTAMP`, `BOOLEAN`). Do not write `VARCHAR(100)` directly in the type position if your renderer strictly checks tokens; use `VARCHAR` or `VARCHAR_100`.
|
||||||
|
2. Always assign `PK` and `FK` flags.
|
||||||
|
3. Relationship lines indicate relational cardinality (Crow's Foot notation):
|
||||||
|
- `||--o{`: Exactly one to zero or many (1 to 0..N)
|
||||||
|
- `||--|{`: Exactly one to one or many (1 to 1..N)
|
||||||
|
- `|o--o{`: Zero or one to zero or many (0..1 to 0..N)
|
||||||
|
- `||--||`: Exactly one to exactly one (1 to 1)
|
||||||
|
|
||||||
|
### Code Example
|
||||||
|
```mermaid
|
||||||
|
erDiagram
|
||||||
|
ECO_CUSTOMER {
|
||||||
|
INT CUS_ID PK
|
||||||
|
VARCHAR CUS_FIRST_NAME
|
||||||
|
VARCHAR CUS_LAST_NAME
|
||||||
|
VARCHAR CUS_EMAIL
|
||||||
|
TIMESTAMP CUS_CREATED_AT
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_ORDER {
|
||||||
|
INT ORD_ID PK
|
||||||
|
INT ORD_CUS_ID FK "References ECO_CUSTOMER"
|
||||||
|
TIMESTAMP ORD_DATE
|
||||||
|
DECIMAL ORD_TOTAL_AMOUNT
|
||||||
|
VARCHAR ORD_STATUS
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_PRODUCT {
|
||||||
|
INT PRO_ID PK
|
||||||
|
VARCHAR PRO_NAME
|
||||||
|
DECIMAL PRO_PRICE
|
||||||
|
INT PRO_STOCK_QUANTITY
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_ORDER_ITEM {
|
||||||
|
INT ITE_ORD_ID PK,FK "References ECO_ORDER"
|
||||||
|
INT ITE_PRO_ID PK,FK "References ECO_PRODUCT"
|
||||||
|
INT ITE_QUANTITY
|
||||||
|
DECIMAL ITE_UNIT_PRICE
|
||||||
|
}
|
||||||
|
|
||||||
|
ECO_CUSTOMER ||--o{ ECO_ORDER : "places"
|
||||||
|
ECO_ORDER ||--|{ ECO_ORDER_ITEM : "contains"
|
||||||
|
ECO_PRODUCT ||--o{ ECO_ORDER_ITEM : "ordered_in"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Markdown Formatting in `db/mcd.md` and `db/mld.md`
|
||||||
|
|
||||||
|
- Enclose every diagram inside triple backticks with `mermaid`:
|
||||||
|
````markdown
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
...
|
||||||
|
```
|
||||||
|
````
|
||||||
|
- Never mix raw HTML script tags; use native Markdown and Mermaid notation.
|
||||||
|
|
@ -0,0 +1,91 @@
|
||||||
|
# Merise Methodology & Transformation Reference
|
||||||
|
|
||||||
|
This reference covers the formal Merise rules for constructing Conceptual Data Models (MCD) and translating them into Logical Data Models (MLD).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Merise Concepts
|
||||||
|
|
||||||
|
### 1.1 Entité (Entity)
|
||||||
|
An object, concept, or person with an independent existence in the business domain.
|
||||||
|
- Has a unique identifier (**Identifiant** / Primary Key candidate).
|
||||||
|
- Contains atomic properties (**Propriétés** / Attributes).
|
||||||
|
- In MLD: Becomes a relational table prefixed with `<DB_TRIGRAM>_`.
|
||||||
|
|
||||||
|
### 1.2 Association (Relationship)
|
||||||
|
A semantic link between two or more entities.
|
||||||
|
- May be binary (between 2 entities), ternary (3 entities), or reflexive (an entity linked to itself).
|
||||||
|
- May carry properties (e.g. `QUANTITY` in a `CONTAINS` association).
|
||||||
|
|
||||||
|
### 1.3 Cardinalités (Cardinalities)
|
||||||
|
Defined as a pair `(min, max)` for each entity participating in an association:
|
||||||
|
- `min`: Minimum number of times an entity instance can participate in the association (`0` or `1`).
|
||||||
|
- `max`: Maximum number of times an entity instance can participate in the association (`1` or `N`).
|
||||||
|
|
||||||
|
Common combinations:
|
||||||
|
- `(0,1)`: Optional, at most one
|
||||||
|
- `(1,1)`: Mandatory, exactly one
|
||||||
|
- `(0,N)`: Optional, zero to many
|
||||||
|
- `(1,N)`: Mandatory, at least one
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. MCD to MLD Transformation Rules
|
||||||
|
|
||||||
|
### Rule 1: One-to-Many Association (`(X,1)` ↔ `(X,N)`)
|
||||||
|
When one side has a maximum cardinality of `1` and the other side has a maximum cardinality of `N`:
|
||||||
|
1. **No new table** is created for the association.
|
||||||
|
2. The primary key of the `(X,N)` entity migrates into the table of the `(X,1)` entity as a **Foreign Key (FK)**.
|
||||||
|
3. Any attributes on the association migrate into the `(X,1)` table as well.
|
||||||
|
4. **Naming convention**: In the host table (`HOST`), the foreign key referencing `TARGET` is named:
|
||||||
|
`<HOST_TRIGRAM>_<TARGET_TRIGRAM>_<COLUMN_NAME>`
|
||||||
|
*Example*: `ECO_ORDER` (`ORD`) has FK `ORD_CUS_ID` referencing `ECO_CUSTOMER` (`CUS`).
|
||||||
|
|
||||||
|
### Rule 2: Many-to-Many Association (`(X,N)` ↔ `(X,N)`)
|
||||||
|
When both sides have a maximum cardinality of `N`:
|
||||||
|
1. **A new table is created** for the association.
|
||||||
|
2. The table name uses a meaningful functional name (e.g. `ECO_ORDER_ITEM`) or a concatenation of entity names (e.g. `ECO_ORDER_PRODUCT`).
|
||||||
|
3. The **Primary Key** is composite, consisting of the foreign keys referencing both participating entities:
|
||||||
|
- `(#ITE_ORD_ID, #ITE_PRO_ID)`
|
||||||
|
4. Any attributes of the association become columns in this junction table (e.g. `ITE_QUANTITY`, `ITE_UNIT_PRICE`).
|
||||||
|
|
||||||
|
### Rule 3: One-to-One Association (`(X,1)` ↔ `(X,1)`)
|
||||||
|
When both sides have a maximum cardinality of `1`:
|
||||||
|
- **Case A: `(1,1)` ↔ `(0,1)`**:
|
||||||
|
The primary key of the `(0,1)` entity migrates into the table of the `(1,1)` entity as an FK with a `UNIQUE` constraint.
|
||||||
|
- **Case B: `(0,1)` ↔ `(0,1)`**:
|
||||||
|
The primary key migrates into either table (whichever entity is created second or is functionally secondary) with a `UNIQUE` constraint.
|
||||||
|
- **Case C: `(1,1)` ↔ `(1,1)`**:
|
||||||
|
Usually indicates the two entities should be merged into a single table, unless there is a strong architectural reason for separation.
|
||||||
|
|
||||||
|
### Rule 4: Reflexive Association (Self-Referencing)
|
||||||
|
An association between an entity and itself (e.g. Employee has a Manager who is an Employee, or Category has a Parent Category):
|
||||||
|
1. **Reflexive `(0,1)` / `(1,1)` to `(0,N)`**:
|
||||||
|
- A foreign key column is added to the same table.
|
||||||
|
- Named: `<TBL_TRIGRAM>_<TBL_TRIGRAM>_<ROLE_NAME>_<COL>`
|
||||||
|
- *Example*: In `ECO_CATEGORY` (`CAT`), parent category FK: `CAT_CAT_PARENT_ID`.
|
||||||
|
- *Example*: In `COR_EMPLOYEE` (`EMP`), manager FK: `EMP_EMP_MANAGER_ID`.
|
||||||
|
2. **Reflexive `(0,N)` to `(0,N)`** (e.g. Product is composed of other Products - Bill of Materials):
|
||||||
|
- A junction table is created (e.g. `ECO_PRODUCT_COMPONENT`).
|
||||||
|
- Trigram `COM`: `COM_PRO_PARENT_ID` and `COM_PRO_CHILD_ID` forming the composite PK.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Normalization Rules (1NF, 2NF, 3NF)
|
||||||
|
|
||||||
|
Every relational model produced by this skill must satisfy **Third Normal Form (3NF)**:
|
||||||
|
|
||||||
|
### First Normal Form (1NF)
|
||||||
|
- Every table has a primary key.
|
||||||
|
- Every column contains only atomic (indivisible) scalar values (no CSV strings, no JSON objects as substitute for relational tables).
|
||||||
|
- No repeating groups or duplicate columns (e.g. `PHONE_1`, `PHONE_2` is invalid; use a separate phone table if multiple phones are supported).
|
||||||
|
|
||||||
|
### Second Normal Form (2NF)
|
||||||
|
- Must be in 1NF.
|
||||||
|
- Every non-key column must depend on the **entire** primary key (applies to composite primary keys in junction tables).
|
||||||
|
- *Example Violation*: In junction table `ECO_ORDER_ITEM` with PK `(ITE_ORD_ID, ITE_PRO_ID)`, having `ITE_PRODUCT_NAME` is invalid because the product name depends only on `PRO_ID`, not on `ORD_ID`.
|
||||||
|
|
||||||
|
### Third Normal Form (3NF)
|
||||||
|
- Must be in 2NF.
|
||||||
|
- No non-key column may depend on another non-key column (no transitive dependency).
|
||||||
|
- *Example Violation*: In `ECO_CUSTOMER`, having `CUS_CITY_NAME` and `CUS_CITY_POSTAL_CODE` where postal code determines city name. If postal code determines city, normalize into a separate `ECO_CITY` table or ensure direct dependency on customer address.
|
||||||
|
|
@ -0,0 +1,79 @@
|
||||||
|
---
|
||||||
|
name: modern-standards-advisor
|
||||||
|
description: >-
|
||||||
|
Systematically research and advise on current, state-of-the-art engineering standards,
|
||||||
|
application security (AppSec), modern RFCs, and best practices. Use whenever the user asks how
|
||||||
|
to implement a feature according to modern industry standards (e.g. password security, user ban/revocation,
|
||||||
|
session management, API design, sensitive data handling) OR automatically when designing/implementing
|
||||||
|
sensitive architectural components (auth, crypto, access control, token invalidation, rate limiting).
|
||||||
|
---
|
||||||
|
|
||||||
|
# Modern Standards & Best Practices Advisor
|
||||||
|
|
||||||
|
Ce skill guide l'agent pour rechercher systématiquement en direct sur le web les normes industrielles récentes, les standards de sécurité applicative (AppSec) et les meilleures pratiques d'ingénierie logicielle, garantissant des implémentations fiables et conformes à l'état de l'art.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Déclencheurs d'Activation (Mode Hybride)
|
||||||
|
|
||||||
|
Ce skill est activé dans deux situations :
|
||||||
|
|
||||||
|
1. **Sur demande explicite de l'utilisateur** :
|
||||||
|
- Questions du type : *"Comment sécuriser un mot de passe selon les normes actuelles ?"*, *"Quelle est la meilleure façon de gérer le bannissement d'un utilisateur ?"*, *"Quelles sont les bonnes pratiques récentes pour concevoir une API REST ?"*, etc.
|
||||||
|
2. **Automatiquement lors de la conception / implémentation de briques sensibles** :
|
||||||
|
- Authentification et gestion de sessions (JWT, OAuth 2.1, cookies HttpOnly).
|
||||||
|
- Stockage et hachage de secrets ou mots de passe (Argon2id, PBKDF2, bcrypt).
|
||||||
|
- Cycle de vie utilisateur critique (bannissement, révocation de sessions, suspension de compte, suppression RGPD).
|
||||||
|
- Chiffrement au repos et en transit (AES-GCM, TLS 1.3, gestion de clés).
|
||||||
|
- Contrôle d'accès et autorisations (RBAC, ABAC, IDOR / BOLA prevention).
|
||||||
|
- Protection contre le déni de service et la force brute (Rate limiting, Token Bucket, Leaky Bucket).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Protocole de Recherche Web en Direct
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> **Recherche Web Systématique et Fraîcheur Obligatoire**
|
||||||
|
> Ne jamais se fier uniquement à des connaissances figées dans le temps. Pour chaque sujet abordé, l'agent doit exécuter des recherches en direct via `search_web` et consulter les pages de référence avec `read_url_content`.
|
||||||
|
|
||||||
|
### 1. Hiérarchie Stricte des Sources
|
||||||
|
- **Tier 1 (Autorité Absolue)** :
|
||||||
|
- **OWASP** (`site:cheatsheetseries.owasp.org`, `owasp.org`) : Cheat Sheets, ASVS, API Security Top 10.
|
||||||
|
- **Normes IETF / RFC** (`datatracker.ietf.org`) : RFCs officielles et en cours (ex: RFC 9106, RFC 9068, OAuth 2.1).
|
||||||
|
- **NIST** (`csrc.nist.gov`) : Notamment SP 800-63 (Digital Identity Guidelines).
|
||||||
|
- **MDN Web Docs** (`developer.mozilla.org`) : Spécifications web, en-têtes HTTP, sécurité navigateurs.
|
||||||
|
- **Docs Officielles de Frameworks / Runtimes** : Documentation officielle de la dernière version LTS/stable (ex: Spring Security, FastAPI, Django, Node.js, ASP.NET Core).
|
||||||
|
- **Tier 2 (Ingénierie de Pointe)** :
|
||||||
|
- Blogs techniques des références de la sécurité et du scale : Cloudflare, Auth0/Okta Developer, Stripe Engineering, AWS Architecture Center, GitHub Engineering.
|
||||||
|
|
||||||
|
### 2. Filtre Négatif (Sources et Anti-patterns Bannis)
|
||||||
|
- Rejeter tout article ou tutoriel antérieur à 2022 (sauf standard fondamental pérenne).
|
||||||
|
- Éviter les blogs amateurs non audités (Medium, Dev.to non sourcé) ou les réponses StackOverflow sans consensus ni avertissements de sécurité.
|
||||||
|
- Proscrire les algorithmes et méthodes obsolètes (MD5, SHA-256 sans dérivation pour les mots de passe, JWT dans `localStorage` pour des sessions bancaires, flags de bannissement statiques en base sans révocation immédiate du cache de tokens).
|
||||||
|
|
||||||
|
*Consultez le playbook complet de requêtes et d'anti-patterns dans [search-playbook.md](./references/search-playbook.md).*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Gabarit Obligatoire de Restitution (5 Volets)
|
||||||
|
|
||||||
|
Toute réponse ou recommandation produite sous l'égide de ce skill doit suivre rigoureusement cette structure en 5 sections :
|
||||||
|
|
||||||
|
### 1. 🎯 Norme Actuelle de Référence & Spécifications Officielles
|
||||||
|
- Nom de la norme / RFC / recommandation OWASP en vigueur à ce jour.
|
||||||
|
- Justification technique : pourquoi cette norme a supplanté les approches antérieures.
|
||||||
|
|
||||||
|
### 2. ✅ Bonnes Pratiques (Do's) vs ❌ Anti-patterns & Pièges à Bannir (Don'ts)
|
||||||
|
- Tableau clair opposant les pratiques actuelles recommandées aux erreurs classiques et approches obsolètes.
|
||||||
|
|
||||||
|
### 3. 📐 Architecture & Flux Étape par Étape
|
||||||
|
- Description pas-à-pas du flux de données ou de contrôle (ex: cinématique lors d'un bannissement d'utilisateur ou du login).
|
||||||
|
- Diagramme Mermaid (`sequenceDiagram` ou `flowchart`) visualisant l'interaction entre client, API, cache/éviction (Redis) et base de données.
|
||||||
|
|
||||||
|
### 4. 💻 Exemple d'Implémentation Concret
|
||||||
|
- Code complet, propre et prêt à l'emploi, ciblant le langage ou framework du projet (ou Python / TypeScript moderne si le projet est agnostique).
|
||||||
|
- Utilisation exclusive des bibliothèques de référence auditées (ex: `argon2-cffi` en Python, `@noble/hashes` ou `argon2` en Node, etc.).
|
||||||
|
|
||||||
|
### 5. 📋 Checklist de Conformité & Sources Officielles Citées
|
||||||
|
- Liste à puces de vérification rapide avant mise en production (Definition of Done sécurité/normes).
|
||||||
|
- Liens cliquables directs vers les sources officielles et documentations consultées.
|
||||||
|
|
@ -0,0 +1,63 @@
|
||||||
|
# Playbook de Recherche & Sélection des Sources - Modern Standards Advisor
|
||||||
|
|
||||||
|
Ce document détaille les stratégies de recherche web, les opérateurs ciblés et la grille d'évaluation des sources pour garantir des recommandations 100% à l'état de l'art.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Hiérarchie des Sources Autorisées
|
||||||
|
|
||||||
|
### Tier 1 : Référentiels Normatifs & Documentation Officielle (Priorité Absolue)
|
||||||
|
Toute recommandation critique d'architecture ou de sécurité doit obligatoirement s'adosser à au moins une source de ce niveau :
|
||||||
|
- **OWASP** : `owasp.org`, `cheatsheetseries.owasp.org` (ASVS, Top 10, API Security Top 10, Cheat Sheets).
|
||||||
|
- **Standards IETF / RFC** : `datatracker.ietf.org`, `rfc-editor.org` (ex: RFC 9106 pour Argon2, RFC 7519 pour JWT, RFC 6749/8252 pour OAuth 2.0 / 2.1).
|
||||||
|
- **NIST** : `csrc.nist.gov` (notamment NIST SP 800-63 Digital Identity Guidelines).
|
||||||
|
- **MDN Web Docs** : `developer.mozilla.org` (sécurité web, headers HTTP, CORS, CSP, cookies).
|
||||||
|
- **Docs officielles de runtimes / frameworks** : Docs officielles de la version **courante majeure** du langage ou framework ciblé (ex: Node.js LTS, Python 3.11+, Spring Security 6+, FastAPI, Django, etc.).
|
||||||
|
|
||||||
|
### Tier 2 : Blogs d'Ingénierie de Référence & Fournisseurs Spécialisés
|
||||||
|
Utilisés pour les détails d'implémentation opérationnelle, les retours d'expérience à l'échelle et les architectures de production :
|
||||||
|
- **Fournisseurs de sécurité & Auth** : Cloudflare Blog (`blog.cloudflare.com`), Auth0 / Okta Developer Blog (`auth0.com/blog`), Stripe Engineering (`stripe.com/blog`), 1Password Engineering.
|
||||||
|
- **Grands acteurs du Cloud & Scale** : AWS Architecture Center, Google Cloud Architecture Framework, GitHub Engineering Blog, Netflix TechBlog.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Filtre Négatif : Sources & Pratiques Baddies (Blacklist)
|
||||||
|
|
||||||
|
L'agent doit **rejeter et exclure** des recommandations :
|
||||||
|
1. **Les articles et tutoriels datant d'avant 2022** (sauf RFC fondamentale non obsolète comme RFC 2119).
|
||||||
|
2. **Les plateformes non vérifiées sans consensus** :
|
||||||
|
- Articles Medium / Dev.to amateurs sans références normatives.
|
||||||
|
- Réponses StackOverflow anciennes ou sans validation critique des failles induites.
|
||||||
|
- Tutos YouTube ou code snippets non audités.
|
||||||
|
3. **Les anti-patterns et algorithmes dépréciés** :
|
||||||
|
- *Mots de passe* : MD5, SHA-1, SHA-256/512 direct (sans fonction de dérivation mémoire-dure), salage "fait maison".
|
||||||
|
- *Gestion de session / JWT* : Tokens JWT stockés dans le `localStorage` pour des sessions sensibles, absence de mécanisme de révocation (blacklist Redis ou rotation de refresh token), tokens sans expiration courte.
|
||||||
|
- *Bannissement utilisateur* : Simple flag `is_banned = true` en base sans invalidation immédiate du cache de session / tokens en circulation.
|
||||||
|
- *Chiffrement* : DES, 3DES, RC4, modes ECB, AES-CBC sans HMAC (privilégier AES-GCM ou ChaCha20-Poly1305).
|
||||||
|
- *Base de données / Entrées* : Concaténation de requêtes SQL (toujours requêtes préparées / ORM paramétré).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Matrice des Formules de Recherche Web (Cheat Queries)
|
||||||
|
|
||||||
|
Pour obtenir directement les meilleures sources via l'outil `search_web`, employer des requêtes ciblées combinant le domaine ou l'autorité :
|
||||||
|
|
||||||
|
| Sujet / Domaine | Formule de Recherche Recommandée |
|
||||||
|
| :--- | :--- |
|
||||||
|
| **Stockage & Hash de mots de passe** | `site:cheatsheetseries.owasp.org "Password Storage" OR "Argon2id"` |
|
||||||
|
| **Révocation de Session / Bannissement** | `site:cheatsheetseries.owasp.org "Session Management" OR "Revocation"` ou `site:auth0.com/blog token revocation best practices` |
|
||||||
|
| **Authentification & JWT** | `site:cheatsheetseries.owasp.org "JSON Web Token" OR RFC 9068 OR "OAuth 2.1"` |
|
||||||
|
| **Contrôle d'accès (RBAC / ABAC)** | `site:cheatsheetseries.owasp.org "Authorization" OR "NIST RBAC"` |
|
||||||
|
| **Sécurisation des APIs** | `site:owasp.org "API Security Top 10" OR site:cheatsheetseries.owasp.org "REST Security"` |
|
||||||
|
| **Protection contre la force brute / DoS** | `site:cheatsheetseries.owasp.org "Denial of Service" OR "Rate Limiting" token bucket` |
|
||||||
|
| **Gestion des données sensibles / RGPD** | `site:cheatsheetseries.owasp.org "Cryptographic Storage" OR "Key Management"` |
|
||||||
|
| **En-têtes de sécurité HTTP** | `site:developer.mozilla.org "Content Security Policy" OR "Permissions-Policy" OR "HSTS"` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Grille d'Évaluation de la Fraîcheur et Pertinence
|
||||||
|
|
||||||
|
Avant de formuler une recommandation, vérifier :
|
||||||
|
1. **L'année de parution ou de révision** : La norme est-elle active ? Y a-t-il eu une nouvelle RFC ou une version mise à jour d'OWASP (ex: OWASP Top 10 2021+, API Top 10 2023+) ?
|
||||||
|
2. **Le consensus de la communauté AppSec** : La technique est-elle considérée comme le défaut standard de l'industrie (de facto standard) ou une alternative expérimentale ?
|
||||||
|
3. **L'impact opérationnel** : La recommandation prend-elle en compte les compromis réels (performance, latence, coût de calcul vs sécurité) ?
|
||||||
Loading…
Reference in New Issue