🐛 Fixes duplicates in tags listings and new priority to enforce order (ITISFoundation#6479)

Author: pcrespov

packages/postgres-database/src/simcore_postgres_database/migration/versions/8a742f3efdd9_new_tags_priority_column.py

@@ -0,0 +1,27 @@
+"""new tags priority column
+
+Revision ID: 8a742f3efdd9
+Revises: 10729e07000d
+Create Date: 2024-10-02 15:23:27.446241+00:00
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "8a742f3efdd9"
+down_revision = "10729e07000d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column("tags", sa.Column("priority", sa.Integer(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("tags", "priority")
+    # ### end Alembic commands ###

packages/postgres-database/src/simcore_postgres_database/models/services_tags.py

@@ -14,20 +14,21 @@
         "service_key",
         sa.String,
         nullable=False,
-        doc="Service Key Identifier",
+        doc="Key name identifier for the service, without specifiying its versions",
     ),
     sa.Column(
         "service_version",
         sa.String,
         nullable=False,
-        doc="Service version",
+        doc="Version of the service. Combined with 'service_key', it forms a unique identifier for this service.",
     ),
     # Tag
     sa.Column(
         "tag_id",
         sa.BigInteger,
         sa.ForeignKey(tags.c.id, onupdate="CASCADE", ondelete="CASCADE"),
         nullable=False,
+        doc="Identifier of the tag assigned to this specific service (service_key, service_version).",
     ),
     # Constraints
     sa.ForeignKeyConstraint(

packages/postgres-database/src/simcore_postgres_database/models/tags.py

@@ -2,35 +2,42 @@
 
 from .base import metadata
 
-#
-# tags: a way to mark any entity (e.g. a project, ...)
-#       this can be used to perform operations as filter, select, compare, etc
-#
 tags = sa.Table(
+    #
+    # A way to mark any entity (e.g. a project, ...)
+    # this can be used to perform operations as filter, select, compare, etc
+    #
     "tags",
     metadata,
     sa.Column(
         "id",
         sa.BigInteger(),
         nullable=False,
         primary_key=True,
+        doc="Unique identifier for each tag.",
     ),
-    sa.Column(
-        "name",
-        sa.String(),
-        nullable=False,
-        doc="display name",
-    ),
+    sa.Column("name", sa.String(), nullable=False, doc="The display name of the tag."),
     sa.Column(
         "description",
         sa.String(),
         nullable=True,
-        doc="description displayed",
+        doc="A brief description displayed for the tag.",
     ),
     sa.Column(
         "color",
         sa.String(),
         nullable=False,
-        doc="Hex color (see https://www.color-hex.com/)",
+        doc="Hexadecimal color code representing the tag (e.g., #FF5733).",
+    ),
+    sa.Column(
+        "priority",
+        sa.Integer(),
+        nullable=True,
+        doc=(
+            "Explicit ordering priority when displaying tags. "
+            "Tags with a lower value are displayed first. "
+            "If NULL, tags are considered to have the lowest priority and "
+            "are displayed after non-NULL values, ordered by their ID (reflecting creation order)."
+        ),
     ),
 )

packages/postgres-database/src/simcore_postgres_database/models/tags_access_rights.py

@@ -22,7 +22,7 @@
             name="fk_tag_to_group_tag_id",
         ),
         nullable=False,
-        doc="Tag unique ID",
+        doc="References the unique identifier of the tag that these access rights apply to.",
     ),
     sa.Column(
         "group_id",
@@ -34,30 +34,32 @@
             name="fk_tag_to_group_group_id",
         ),
         nullable=False,
-        doc="Group unique ID",
+        doc="References the unique identifier of the group that has access rights to the tag.",
     ),
     # ACCESS RIGHTS ---
     sa.Column(
         "read",
         sa.Boolean(),
         nullable=False,
         server_default=sa.sql.expression.true(),
-        doc="If true, group can *read* a tag."
-        "This column can be used to set the tag invisible",
+        doc="Indicates whether the group has permission to view the tag. "
+        "A value of 'True' allows the group to access the tag's details.",
     ),
     sa.Column(
         "write",
         sa.Boolean(),
         nullable=False,
         server_default=sa.sql.expression.false(),
-        doc="If true, group can *create* and *update* a tag",
+        doc="Indicates whether the group has permission to modify the tag. "
+        "A value of 'True' grants write access to the group.",
     ),
     sa.Column(
         "delete",
         sa.Boolean(),
         nullable=False,
         server_default=sa.sql.expression.false(),
-        doc="If true, group can *delete* the tag",
+        doc="Indicates whether the group has permission to delete the tag. "
+        "A value of 'True' allows the group to remove the tag.",
     ),
     # TIME STAMPS ----
     column_created_datetime(timezone=False),