Refactor roles management to use role code as primary key

- Updated the roles table schema to use role code as the primary key, enhancing readability in junction tables.
- Modified related tables (user_roles, product_role_visibility) to reference role code instead of role ID.
- Adjusted seeding logic and utility functions to accommodate the new primary key structure, ensuring consistent role management across the application.
- Added a migration script to facilitate the database schema changes.

server/database/migrations/0002_refactor_roles_primary_key.sql

@@ -0,0 +1,58 @@
+-- Migration: Refactor roles table to use code as primary key
+-- This migration drops and recreates the role-related tables with the new schema
+
+-- Drop existing tables (CASCADE removes dependent foreign keys)
+DROP TABLE IF EXISTS "product_role_visibility" CASCADE;--> statement-breakpoint
+DROP TABLE IF EXISTS "user_roles" CASCADE;--> statement-breakpoint
+DROP TABLE IF EXISTS "roles" CASCADE;--> statement-breakpoint
+
+-- Recreate roles table with code as primary key
+CREATE TABLE "roles" (
+	"code" "role_code" PRIMARY KEY NOT NULL,
+	"display_name" text NOT NULL,
+	"description" text NOT NULL,
+	"requires_approval" boolean DEFAULT false NOT NULL,
+	"sort_order" integer DEFAULT 0 NOT NULL,
+	"active" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+
+-- Recreate user_roles table with roleCode instead of roleId
+CREATE TABLE "user_roles" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"role_code" "role_code" NOT NULL,
+	"status" "role_request_status" DEFAULT 'pending' NOT NULL,
+	"organization_name" text,
+	"admin_notes" text,
+	"status_history" jsonb DEFAULT '[]' NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+
+-- Recreate product_role_visibility table with roleCode instead of roleId
+CREATE TABLE "product_role_visibility" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"product_id" uuid NOT NULL,
+	"role_code" "role_code" NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+
+-- Add foreign key constraints
+ALTER TABLE "user_roles" ADD CONSTRAINT "user_roles_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "user_roles" ADD CONSTRAINT "user_roles_role_code_roles_code_fk" FOREIGN KEY ("role_code") REFERENCES "public"."roles"("code") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "product_role_visibility" ADD CONSTRAINT "product_role_visibility_product_id_products_id_fk" FOREIGN KEY ("product_id") REFERENCES "public"."products"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "product_role_visibility" ADD CONSTRAINT "product_role_visibility_role_code_roles_code_fk" FOREIGN KEY ("role_code") REFERENCES "public"."roles"("code") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+
+-- Create indexes
+CREATE INDEX "user_roles_user_id_role_code_unique" ON "user_roles" USING btree ("user_id","role_code");--> statement-breakpoint
+CREATE INDEX "user_roles_user_id_idx" ON "user_roles" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "user_roles_role_code_idx" ON "user_roles" USING btree ("role_code");--> statement-breakpoint
+CREATE INDEX "user_roles_status_idx" ON "user_roles" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "product_role_visibility_product_id_role_code_unique" ON "product_role_visibility" USING btree ("product_id","role_code");--> statement-breakpoint
+CREATE INDEX "product_role_visibility_product_id_idx" ON "product_role_visibility" USING btree ("product_id");--> statement-breakpoint
+CREATE INDEX "product_role_visibility_role_code_idx" ON "product_role_visibility" USING btree ("role_code");

server/database/migrations/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1762074397305,
       "tag": "0001_clammy_bulldozer",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1762157410000,
+      "tag": "0002_refactor_roles_primary_key",
+      "breakpoints": true
     }
   ]
 }

server/database/schema.ts

@@ -160,10 +160,10 @@ export const products = pgTable(
  * Roles Table
  * Defines available user roles (private, educator, company)
  * Phase 2/3: Educator and Company roles require approval workflow
+ * Note: Using role code as primary key for better readability in junction tables
  */
 export const roles = pgTable('roles', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  code: roleCodeEnum('code').unique().notNull(), // 'private', 'educator', 'company'
+  code: roleCodeEnum('code').primaryKey(), // 'private', 'educator', 'company' - Primary Key
   displayName: text('display_name').notNull(), // "Privatperson", "Pädagoge", "Unternehmen"
   description: text('description').notNull(), // Role description
   requiresApproval: boolean('requires_approval').notNull().default(false), // false for 'private', true for 'educator'/'company'
@@ -186,9 +186,9 @@ export const userRoles = pgTable(
     userId: uuid('user_id')
       .notNull()
       .references(() => users.id, { onDelete: 'cascade' }),
-    roleId: uuid('role_id')
+    roleCode: roleCodeEnum('role_code')
       .notNull()
-      .references(() => roles.id, { onDelete: 'cascade' }),
+      .references(() => roles.code, { onDelete: 'cascade' }),
 
     // Role request status (Phase 2/3 feature - prepared in MVP)
     status: roleRequestStatusEnum('status').notNull().default('pending'),
@@ -206,8 +206,9 @@ export const userRoles = pgTable(
   },
   (table) => [
     // Unique constraint: User can only have one entry per role
-    index('user_roles_user_id_role_id_unique').on(table.userId, table.roleId),
+    index('user_roles_user_id_role_code_unique').on(table.userId, table.roleCode),
     index('user_roles_user_id_idx').on(table.userId),
+    index('user_roles_role_code_idx').on(table.roleCode),
     index('user_roles_status_idx').on(table.status),
   ]
 )
@@ -225,15 +226,16 @@ export const productRoleVisibility = pgTable(
     productId: uuid('product_id')
       .notNull()
       .references(() => products.id, { onDelete: 'cascade' }),
-    roleId: uuid('role_id')
+    roleCode: roleCodeEnum('role_code')
       .notNull()
-      .references(() => roles.id, { onDelete: 'cascade' }),
+      .references(() => roles.code, { onDelete: 'cascade' }),
     createdAt: timestamp('created_at').defaultNow().notNull(),
   },
   (table) => [
     // Unique constraint: Product-Role pair can only exist once
-    index('product_role_visibility_product_id_role_id_unique').on(table.productId, table.roleId),
+    index('product_role_visibility_product_id_role_code_unique').on(table.productId, table.roleCode),
     index('product_role_visibility_product_id_idx').on(table.productId),
+    index('product_role_visibility_role_code_idx').on(table.roleCode),
   ]
 )
 
@@ -381,8 +383,8 @@ export const userRolesRelations = relations(userRoles, ({ one }) => ({
     references: [users.id],
   }),
   role: one(roles, {
-    fields: [userRoles.roleId],
-    references: [roles.id],
+    fields: [userRoles.roleCode],
+    references: [roles.code],
   }),
 }))
 
@@ -392,7 +394,7 @@ export const productRoleVisibilityRelations = relations(productRoleVisibility, (
     references: [products.id],
   }),
   role: one(roles, {
-    fields: [productRoleVisibility.roleId],
-    references: [roles.id],
+    fields: [productRoleVisibility.roleCode],
+    references: [roles.code],
   }),
 }))

server/database/seed.ts

@@ -173,7 +173,7 @@ async function seed() {
       const roleCodes = productData.roles || []
 
       for (const roleCode of roleCodes) {
-        // Find role by code
+        // Find role display name for logging
         const role = insertedRoles.find((r) => r.code === roleCode)
         if (!role) {
           console.warn(`   ⚠️  Role '${roleCode}' not found for product ${product.name}`)
@@ -184,14 +184,14 @@ async function seed() {
         const existing = await db.query.productRoleVisibility.findFirst({
           where: and(
             eq(productRoleVisibility.productId, product.id),
-            eq(productRoleVisibility.roleId, role.id)
+            eq(productRoleVisibility.roleCode, roleCode)
           ),
         })
 
         if (!existing) {
           await db.insert(productRoleVisibility).values({
             productId: product.id,
-            roleId: role.id,
+            roleCode, // Direct reference to roles.code (PK)
           })
           assignmentCount++
           console.log(`   - ${product.name} → ${role.displayName}`)