diff --git a/content/docs/reference/design-docs/subcategory/index.en.md b/content/docs/reference/design-docs/subcategory/index.en.md new file mode 100644 index 000000000..1470384e4 --- /dev/null +++ b/content/docs/reference/design-docs/subcategory/index.en.md @@ -0,0 +1,92 @@ +--- +title: "Sub category" +linkTitle: "Sub category" +weight: 60 +description: "Sub categories help organize and visually distinguish train schedules and paced trains when displayed in OSRD and NGE." +--- + +## Introduction + +Sub categories are created via a dedicated API. Each sub category includes: + + - A name and a unique code, + - Visual properties like **color**, **hovered_color**, and **background_color**, + - A link to a parent main category. + +### SubCategory model + +```yml +name: "RER" +code: "RER" +main_category: "COMMUTER_TRAIN" +color: "#FF0000" +hovered_color: "#FFA500" +background_color: "#FFD700" +``` + +## Main Train Category in Rolling Stocks + +The main train category defines the general type or purpose of a train. +It is used to classify trains into broad groups such as: + - HighSpeedTrain – for long-distance high-speed services + - FreightTrain – for goods and cargo transportation + - ... + +The RollingStock model includes a primary_category field to indicate which main category it belongs to: +```yml +primary_category: "HIGH_SPEED_TRAIN" +``` + +This category helps ensure consistency between the train schedule and the rolling stock, and is also used for visual display and filtering in the UI. + +⚠️ If a train schedule or paced train specifies a main category, or a sub category whose parent category differs from the rolling stock’s primary category, a warning is displayed. + +### Train Schedule & Paced Train Category + +The category field in train schedules and paced trains can take either: + +```yml +category: + main_category: "COMMUTER_TRAIN" +``` + +Or + +```yml +category: + sub_category_code: "RER" +``` + +Both **TrainSchedules** and **PacedTrains** can specify either a **main category** or a user-defined **sub category**. + +When a subcategory is deleted, any train schedules and paced trains using it will automatically fall back to its associated parent category. + +![sub category diagram](sub_category.svg) + +## Sub categories Api + +### Create sub categories + +Creates one or more sub categories in batch. + +``` +POST /api/sub_category +``` + +Request body: array of sub category objects. + +### Retrieve sub categories + +Retrieves paginated sub categories. + +``` +GET /api/sub_category?page=1&page_size=1000 +``` + +### Delete sub categories + +Deletes a sub category using its code. + +``` +DELETE /sub_category/:code +``` diff --git a/content/docs/reference/design-docs/subcategory/index.fr.md b/content/docs/reference/design-docs/subcategory/index.fr.md new file mode 100644 index 000000000..3b616f238 --- /dev/null +++ b/content/docs/reference/design-docs/subcategory/index.fr.md @@ -0,0 +1,8 @@ +--- +title: "Sub category" +linkTitle: "Sub category" +weight: 60 +description: "Décrit le modèle de sous-catégorie et sa relation avec train schedules et paced trains." +--- + +_Non traduit : veuillez sélectionner une autre langue._ diff --git a/content/docs/reference/design-docs/subcategory/sub_category.svg b/content/docs/reference/design-docs/subcategory/sub_category.svg new file mode 100644 index 000000000..697592307 --- /dev/null +++ b/content/docs/reference/design-docs/subcategory/sub_category.svg @@ -0,0 +1,3 @@ + + +
PacedTrain
PacedTrain
category:
   sub_category_code:
category:...
TrainSchedule
TrainSchedule
category:
   sub_category_code:
category:...
SubCategory
SubCategory
code:
code:
RollingStock
RollingStock
primary_category:
primary_category: \ No newline at end of file