feat(role): add role_code across schema and APIs

app/api/admin_catalog.py

@@ -71,6 +71,13 @@ def _generate_unique_key(prefix: str, exists_check) -> str:
     raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"failed_generate_{prefix.lower()}_key")
 
 
+def _resolve_role_code(value: str | None, fallback_name: str) -> str:
+    candidate = (value or "").strip()
+    if candidate:
+        return candidate
+    return fallback_name.strip()
+
+
 def _company_item(company) -> CompanyItem:
     return CompanyItem(
         id=company.id,
@@ -451,6 +458,7 @@ def list_roles(
         RoleItem(
             id=row.id,
             role_key=row.role_key,
+            role_code=row.role_code,
             system_key=system_map[row.system_id].system_key,
             system_name=system_map[row.system_id].name,
             name=row.name,
@@ -481,9 +489,11 @@ def create_role(payload: RoleCreateRequest, db: Session = Depends(get_db)) -> Ro
     )
 
     role_key = _generate_unique_key("RL", lambda key: roles_repo.get_by_key(key) is not None)
+    role_code = _resolve_role_code(payload.role_code, payload.name)
     try:
         row = roles_repo.create(
             role_key=role_key,
+            role_code=role_code,
             system_id=system.id,
             name=payload.name,
             description=payload.description,
@@ -496,6 +506,7 @@ def create_role(payload: RoleCreateRequest, db: Session = Depends(get_db)) -> Ro
     return RoleItem(
         id=row.id,
         role_key=row.role_key,
+        role_code=row.role_code,
         system_key=system.system_key,
         system_name=system.name,
         name=row.name,
@@ -527,6 +538,7 @@ def update_role(role_key: str, payload: RoleUpdateRequest, db: Session = Depends
         system_id = system.id
         target_system = system
     next_provider_role_name = payload.name if payload.name is not None else role.name
+    next_role_code = _resolve_role_code(payload.role_code, next_provider_role_name)
     next_description = payload.description if payload.description is not None else role.description
 
     if target_system.id != old_system.id:
@@ -551,6 +563,7 @@ def update_role(role_key: str, payload: RoleUpdateRequest, db: Session = Depends
         role = roles_repo.update(
             role,
             system_id=system_id,
+            role_code=next_role_code,
             name=payload.name,
             description=payload.description,
             status=payload.status,
@@ -566,6 +579,7 @@ def update_role(role_key: str, payload: RoleUpdateRequest, db: Session = Depends
     return RoleItem(
         id=role.id,
         role_key=role.role_key,
+        role_code=role.role_code,
         system_key=system.system_key,
         system_name=system.name,
         name=role.name,
@@ -610,6 +624,7 @@ def list_system_roles(system_key: str, db: Session = Depends(get_db)) -> SystemR
             RoleItem(
                 id=row.id,
                 role_key=row.role_key,
+                role_code=row.role_code,
                 system_key=system.system_key,
                 system_name=system.name,
                 name=row.name,
@@ -637,6 +652,7 @@ def list_site_roles(site_key: str, db: Session = Depends(get_db)) -> SiteRolesRe
             SiteRoleItem(
                 id=site_role.id,
                 role_key=role.role_key,
+                role_code=role.role_code,
                 role_name=role.name,
                 system_key=system.system_key,
                 system_name=system.name,
@@ -972,6 +988,7 @@ def list_member_effective_roles(user_sub: str, db: Session = Depends(get_db)) ->
             system_key=system.system_key,
             system_name=system.name,
             role_key=role.role_key,
+            role_code=role.role_code,
             role_name=role.name,
         )
         for site, company, role, system in rows

app/api/internal.py

@@ -41,7 +41,7 @@ def upsert_user_by_sub(
     )
 
 
-def _build_user_role_rows(db: Session, user_sub: str) -> list[tuple[str, str, str, str, str, str, str, str]]:
+def _build_user_role_rows(db: Session, user_sub: str) -> list[tuple[str, str, str, str, str, str, str, str, str]]:
     users_repo = UsersRepository(db)
     user_sites_repo = UserSitesRepository(db)
 
@@ -59,6 +59,7 @@ def _build_user_role_rows(db: Session, user_sub: str) -> list[tuple[str, str, st
             system.system_key,
             system.name,
             role.role_key,
+            role.role_code,
             role.name,
         )
         for site, company, role, system in rows
@@ -84,6 +85,7 @@ def get_user_roles(user_sub: str, db: Session = Depends(get_db)) -> InternalUser
                 system_key=system_key,
                 system_name=system_name,
                 role_key=role_key,
+                role_code=role_code,
                 role_name=role_name,
             )
             for (
@@ -94,6 +96,7 @@ def get_user_roles(user_sub: str, db: Session = Depends(get_db)) -> InternalUser
                 system_key,
                 system_name,
                 role_key,
+                role_code,
                 role_name,
             ) in rows
         ],

app/api/internal_catalog.py

@@ -68,6 +68,7 @@ def internal_list_roles(
         InternalRoleItem(
             id=i.id,
             role_key=i.role_key,
+            role_code=i.role_code,
             system_key=system_map[i.system_id].system_key,
             system_name=system_map[i.system_id].name,
             name=i.name,

app/api/me.py

@@ -77,6 +77,7 @@ def get_my_permission_snapshot(
                 system.system_key,
                 system.name,
                 role.role_key,
+                role.role_code,
                 role.name,
             )
             for site, company, role, system in rows