From 00430467421524ca0b6acb0691d17a8b32f0d9da Mon Sep 17 00:00:00 2001 From: Egor Berezovskiy Date: Wed, 27 Aug 2025 11:06:12 +0200 Subject: [PATCH 1/3] docs: sub category Signed-off-by: Egor Berezovskiy --- .../design-docs/subcategory/index.en.md | 71 +++++++++++++++++++ .../design-docs/subcategory/index.fr.md | 8 +++ 2 files changed, 79 insertions(+) create mode 100644 content/docs/reference/design-docs/subcategory/index.en.md create mode 100644 content/docs/reference/design-docs/subcategory/index.fr.md 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 0000000000..4417535852 --- /dev/null +++ b/content/docs/reference/design-docs/subcategory/index.en.md @@ -0,0 +1,71 @@ +--- +title: "Sub category" +linkTitle: "Sub category" +weight: 60 +description: "Describes the sub-category model and its relation to train schedules and paced trains." +--- + +## Introduction + +Sub categories are created via a dedicated API. Each sub category has a name and a unique code, as well as visual properties like **color**, **hovered_color**, and **background_color**. +Each sub category is associated with a parent main category. +Both **TrainSchedules** and **PacedTrains** can specify either a **main_category** or a user-defined **sub_category_code**. + +### SubCategory model + +```yml +name: "RER" +code: "RER" +main_category: "COMMUTER_TRAIN" +color: "#FF0000" +hovered_color: "#FFA500" +background_color: "#FFD700" +``` + +### 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" +``` + +Only one of the two can be defined at a time, or both can be absent. + +If a referenced sub category is deleted, the affected train schedules or paced trains will automatically fall back to the sub category’s associated **main_category**. + +## 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 0000000000..3b616f2384 --- /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._ From 3afbff21664e061551f927881e49254f6586ad56 Mon Sep 17 00:00:00 2001 From: Egor Berezovskiy Date: Wed, 3 Sep 2025 11:30:56 +0200 Subject: [PATCH 2/3] fixup! doc: add missing pages to at least translate table of contents Signed-off-by: Egor Berezovskiy --- .../design-docs/subcategory/index.en.md | 31 +++++++++++++++---- 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/content/docs/reference/design-docs/subcategory/index.en.md b/content/docs/reference/design-docs/subcategory/index.en.md index 4417535852..e58dba0bba 100644 --- a/content/docs/reference/design-docs/subcategory/index.en.md +++ b/content/docs/reference/design-docs/subcategory/index.en.md @@ -2,14 +2,16 @@ title: "Sub category" linkTitle: "Sub category" weight: 60 -description: "Describes the sub-category model and its relation to train schedules and paced trains." +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 has a name and a unique code, as well as visual properties like **color**, **hovered_color**, and **background_color**. -Each sub category is associated with a parent main category. -Both **TrainSchedules** and **PacedTrains** can specify either a **main_category** or a user-defined **sub_category_code**. +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 @@ -22,6 +24,23 @@ 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: @@ -38,9 +57,9 @@ category: sub_category_code: "RER" ``` -Only one of the two can be defined at a time, or both can be absent. +Both **TrainSchedules** and **PacedTrains** can specify either a **main category** or a user-defined **sub category**. -If a referenced sub category is deleted, the affected train schedules or paced trains will automatically fall back to the sub category’s associated **main_category**. +When a subcategory is deleted, any train schedules and paced trains using it will automatically fall back to its associated parent category. ## Sub categories Api From 1922f15d0e903e890c8fbc174083303759b3dbee Mon Sep 17 00:00:00 2001 From: Egor Berezovskiy Date: Wed, 3 Sep 2025 11:52:37 +0200 Subject: [PATCH 3/3] fixup! docs: sub category Signed-off-by: Egor Berezovskiy --- content/docs/reference/design-docs/subcategory/index.en.md | 2 ++ .../docs/reference/design-docs/subcategory/sub_category.svg | 3 +++ 2 files changed, 5 insertions(+) create mode 100644 content/docs/reference/design-docs/subcategory/sub_category.svg diff --git a/content/docs/reference/design-docs/subcategory/index.en.md b/content/docs/reference/design-docs/subcategory/index.en.md index e58dba0bba..1470384e4a 100644 --- a/content/docs/reference/design-docs/subcategory/index.en.md +++ b/content/docs/reference/design-docs/subcategory/index.en.md @@ -61,6 +61,8 @@ Both **TrainSchedules** and **PacedTrains** can specify either a **main 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 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 0000000000..6975923074 --- /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