Ana içeriğe geç

Vekalet Parametre Yönetimi#

Bu doküman, Keysis üzerinde vekalet (proxy) süreçlerine özel parametre yönetimi mimarisini geliştiricilere açık ve anlaşılır bir şekilde aktarmayı amaçlar. Role parametre altyapısında tanımlanan genel konseptin, vekalet senaryosunda nasıl uygulandığı detaylandırılmaktadır; proxy süreçleri, rol parametre mimarisinin doğal bir uzantısıdır.

1. Amaç ve Mimari Genel Bakış#

Proxy Parameter altyapısı, bir kullanıcının başka bir kullanıcıya vekalet verdiği durumlarda, vekalet alan kişinin hangi parametrik yetkileri kullanabileceğini ince taneli (fine-grained) şekilde kontrol etmeyi sağlar.

Bu yapı sayesinde: * Vekalet verilen parametreler kullanıcı tarafından seçilebilir veya çıkarılabilir. * Sistem yöneticileri tarafından belirlenmiş sabit bir parametre seti kullanılır. * Backend servisleri, aktif vekalet üzerinden parametrik yetkilendirme yapabilir.

Mimari olarak sistem iki temel bileşene dayanır: 1. Proxy'ye özel sabit rol (proxyParameterRoleCode): Vekalet sırasında seçilebilecek tüm parametreleri barındıran, özel ve sabit rol. 2. Vekalet kaydı (Proxy): Kullanıcı tarafından verilen vekalet sürecinde, bu özel roldeki parametrelerin seçili/seçilmemiş durumu vekalet kaydı ile ilişkilendirilir.

Bu tasarım ile sistem hem esnek hem de güvenli bir kontrol mekanizması oluşturur.

2. Proxy'ye Özel Sabit Rol#

Proxy süreçleri için sistemde sabit ve güncellenemez bir rol bulunmaktadır. Bu rol, proxyParameterRoleCode koduyla tanımlıdır ve editable = 0 (düzenlenemez) olacak şekilde sistem açılışında Liquibase ilklendirme scriptleri ile otomatik olarak yüklenir. Tüm proxy parametreleri bu rol altında tanımlanır ve bu rol yalnızca vekalet süreçlerinde parametrik yetkileri taşımak için kullanılır.

Bu özel rolün amacı, kullanıcıya vekalet ile verilebilecek parametrelerin merkezi bir havuzunu oluşturmak ve proxy ekranlarında kullanıcıya gösterilecek parametre setini belirlemektir. Böylece söz konusu rol, vekalet verilirken seçilebilecek tüm izinleri üzerinde barındırır ve sistem yöneticileri bu rol aracılığıyla hangi parametrelerin vekalet konusu olabileceğini önceden tanımlamış olur.

3. Parametre Tanımı ve Rol ile Eşleştirme#

Proxy süreçlerinde kullanılan parametreler, genel Rol Parametre altyapısıyla aynı şekilde tanımlanır.

Her bir parametre, kys_role_param_def tablosunda bir kayıt olarak oluşturulur. Ardından bu parametreler, sabit proxy rolü ile ilişkilendirilerek hangi rolün hangi parametrelere sahip olacağı belirlenir. Bu ilişkilendirme verileri kys_role_param_def_rel tablosunda tutulur.

Örnek Parametreler#

Varsayılan ilklendirme verilerinden örnekler şunlardır: * Yıllık İzin Onay - YILLIK_IZIN * Mazeret İzni Onay - MAZERET_IZIN * Şehir İçi Günlük Görev İzni Onay - SEHIR_ICI_GUNLUK_GOREV_IZIN

Yukarıdaki örneklerde görüldüğü gibi, her parametrenin kullanıcı dostu bir adı (ör. "Yıllık İzin Onay") ve benzersiz bir kodu (ör. YILLIK_IZIN) bulunur. Parametre tanımları oluşturulduktan sonra, sabit proxy rolü ile bu parametreler arasında ilişki kurulmalıdır. Bu sayede proxy rolü, vekalet sırasında seçilebilecek tüm parametrelerin kümesini içerir.

Liquibase İlklendirme Örneği#

Aşağıda, sabit proxy rolü ile bir parametre arasında ilişki kurulmasına dair bir Liquibase ilklendirme örneği verilmiştir:

<insert tableName="kys_role_param_def_rel">
    <column name="role_id" valueComputed="(SELECT ID FROM kys_role WHERE code='proxyParameterRoleCode')" />
    <column name="parameter_definition_id" valueComputed="(SELECT ID FROM kys_role_param_def WHERE parameter_code='YILLIK_IZIN')"/>
</insert>
````

Yukarıdaki Liquibase örneğinde, `YILLIK_IZIN` kodlu parametre, `proxyParameterRoleCode` sabit rolüyle eşleştirilmektedir. Bu ilişki, söz konusu parametrenin vekalet sürecinde seçilebilir hale gelmesini sağlar.

## 4\. Vekalet Tanımlama Akışı

Bir kullanıcı, sistem üzerindeki **Vekalet Verme** arayüzü üzerinden başka bir kullanıcıya vekalet tanımladığında aşağıdaki adımlar gerçekleşir:

1.  **Parametrelerin Listelenmesi:** Sistem, `proxyParameterRoleCode` rolündeki tüm tanımlı parametreleri ekranda listeler. Bu liste, vekalet sırasında sunulabilecek izinlerin tamamını gösterir.
2.  **Varsayılan Seçim:** Listelenen tüm parametreler varsayılan olarak seçili (selected) durumda gelir. Yani başlangıçta vekalet veren kullanıcı, tanımlı tüm izinleri vekalet vermeye hazır olarak görür.
3.  **Parametre Hariç Bırakma:** Kullanıcı, vekalet verdiği kişinin kullanmasını istemediği yetkiler varsa ilgili parametrelerin seçimini kaldırabilir (unselect). Bu adım, vekalet kapsamını daraltma imkânı tanır.
4.  **Kayıt ve İlişkilendirme:** Kullanıcı onay verdiğinde, seçili olarak bırakılan parametreler ilgili vekalet kaydı ile ilişkilendirilerek veritabanına kaydedilir. Bu bilgiler `kys_proxy_param_rel` tablosunda saklanır.

Yukarıdaki akış sonucunda, vekalet kaydında hangi parametrelerin devredildiği açıkça belirlenmiş olur. Bu sayede sistem, vekalet alan kullanıcının sadece izin verilen işlemleri yapmasını güvence altına alır.

## 5. Servis Kullanımı
Proxy parametre yapısını kullanarak bir kullanıcının hangi işlemleri yapmaya yetkili olduğunu öğrenmek için iki adet servis uç noktası sağlanmıştır:

* **Aktif Proxy Oturumu (Kullanıcı):**
  `GET /proxy-role-parameter-values/parameter-info-by-active-proxy`
  Mevcut oturumda eğer kullanıcı bir vekalet altında işlem yapıyorsa, bu servis o vekalete ait parametre setini döndürür. (Bir kullanıcı başka biri adına işlem yaparken, bu uç nokta üzerinden hangi parametrelere sahip olduğu alınabilir.)

* **Belirli Proxy Kaydı (Yönetici):**
  `GET /proxy-role-parameter-values/parameter-info-by-proxy/{uuid}`
  Belirtilen UUID değerine sahip vekalet kaydına ait tüm parametre bilgilerini döndürür. (Yönetici veya sistem servisleri, spesifik bir vekaletin kapsamındaki parametreleri bu uç noktadan sorgulayabilir.)

Her iki servis de yanıt olarak iki temel liste döndürür:

| Alan | Açıklama |
| :--- | :--- |
| **allAvailableParameters** | Proxy rolünde tanımlı tüm parametreler (vekalet sırasında seçilebilecek tüm izinlerin listesi). |
| **proxyAssignedParameters** | İlgili vekalet için seçilmiş parametreler (sadece vekalet veren kullanıcının izin verdiği izinlerin listesi). |

Geri dönen JSON yapısı içinde ayrıca vekalet kaydının detayları (proxy nesnesi) bulunur. Örnek bir yanıt yapısı şöyledir:

```json
{
  "body": {
    "proxy": {
      "id": 1000,
      "deleted": false,
      "uuid": "127851cc-adc5-43c2-bdfe-0de0cef3686f",
      "sourceProfileId": 21,
      "sourceProfileUserUsername": "hvltest1",
      "sourceUserName": "Hvl",
      "sourceUserSurname": "Test1",
      "sourceProfileName": "Admin Profil",
      "targetUserId": 11,
      "targetUserUsername": "hvltest2",
      "targetUserName": "Hvl",
      "targetUserSurname": "Test2",
      "startDate": "2025-11-19T08:11:08+03:00",
      "endDate": "2025-11-26T08:09:10+03:00",
      "name": "Örnek Vekalet",
      "description": "Yıllık izin onayı için vekalet"
    },
    "allAvailableParameters": [
      {
        "parameterName": "Yıllık İzin Onay",
        "parameterCode": "YILLIK_IZIN",
        "parameterValueType": "STRING",
        "parameterType": "VEKALET"
      },
      {
        "parameterName": "Mazeret İzni Onay",
        "parameterCode": "MAZERET_IZIN",
        "parameterValueType": "STRING",
        "parameterType": "VEKALET"
        }
      // ... diğer tüm tanımlı vekalet parametreleri
    ],
    "proxyAssignedParameters": [
      {
        "parameterName": "Yıllık İzin Onay",
        "parameterCode": "YILLIK_IZIN",
        "parameterValueType": "STRING",
        "parameterType": "VEKALET"
      }
      // ... kullanıcı tarafından seçilmiş diğer parametreler (eğer varsa)
    ]
  }
}

Yukarıdaki örnekte, sistemde tanımlı iki vekalet parametresi bulunmakta ve kullanıcı bunlardan sadece Yıllık İzin Onay parametresini vekalet kapsamında bırakmıştır.

  • Servis cevabında allAvailableParameters listesi rolün tüm parametrelerini içerir.
  • proxyAssignedParameters listesi yalnızca vekaletin kapsadığı parametreleri göstermektedir.

Önemli Not: Geliştirici uygulamalarında, erişim kontrolü için sadece proxyAssignedParameters listesindeki parametrelerin dikkate alınması önerilir. Bu, whitelist yaklaşımıyla, yalnızca vekalet verenin onayladığı aksiyonların gerçekleştirilmesini garanti altına alır. (Alternatif olarak, tüm liste ile atanan liste farkını alarak bir blacklist yaklaşımı da uygulanabilir, ancak en güvenli yaklaşım whitelist yöntemidir.)

6. Backend Kullanımı#

Backend tarafında, bir kullanıcının belirli bir işlemi yapmaya yetkili olup olmadığını kontrol etmek için proxy parametreleri kullanılabilir. Vekalet kapsamında gelen parametre kodları sayesinde, kod içerisinde koşullu kontroller yapılabilir.

Örneğin, yıllık izin onaylama yetkisinin verilip verilmediğini anlamak için aşağıdaki kontrol uygulanabilir:

boolean canApproveLeave = proxyParams.contains("YILLIK_IZIN");

Yukarıdaki örnekte, aktif kullanıcıya vekalet veren kişi "YILLIK_IZIN" parametresini devrettiyse canApproveLeave true olacaktır; böylece kullanıcı yalnızca vekalet kapsamında kendisine verilmiş yetkiler için işlemi gerçekleştirebilir. Bu yaklaşım, sistemde dinamik ve güvenli bir yetki kontrolü sağlar.

7. İlklendirme Scriptleri#

Proxy parametre altyapısının sorunsuz çalışabilmesi için gerekli rol ve parametre tanımları, sistem ilk kurulumunda Liquibase aracılığıyla yüklenir. Bu sayede uygulama ilk çalıştığında, sabit proxy rolü ve ilgili parametreler hazır olarak gelir.

Aşağıda, Liquibase scriptlerine dair örnekler sunulmuştur:

Rol Tanımı (Liquibase)#

Proxy'ye özel rolün oluşturulması

Rol Tanımı (Liquibase)#

Örnek bir vekalet parametresinin oluşturulması öncesinde, bu parametreleri taşıyacak rolün tanımlanması gerekir.

<insert tableName="kys_role">
    <column name="code" value="proxyParameterRoleCode" />
    <column name="name" value="Vekalet Parametre İşlemleri"/>
    <column name="editable" valueNumeric="0"/>
    <column name="proxyable" valueNumeric="1"/>
</insert>

Açıklama: Yukarıda, kod değeri proxyParameterRoleCode olan "Vekalet Parametre İşlemleri" adında bir rol tanımlanmaktadır.

  • editable alanı 0 (false) yapılarak rolün değiştirilemez olduğu belirtilmiştir.
  • proxyable alanı 1 yapılarak vekalet işlemlerinde kullanılabilir olduğu işaretlenmiştir.

Parametre Tanımları (Liquibase)#

Örnek bir vekalet parametresinin (Yıllık İzin Onay) oluşturulması:

<insert tableName="kys_role_param_def">
    <column name="parameter_name" value="Yıllık İzin Onay"/>
    <column name="parameter_code" value="YILLIK_IZIN" />
    <column name="parameter_type" value="VEKALET"/>
    <column name="parameter_value_type" value="STRING"/>
</insert>

Açıklama: Yukarıdaki Liquibase kodu, "Yıllık İzin Onay" isminde ve YILLIK_IZIN kodunda bir parametre tanımı eklemektedir. parameter_type alanı "VEKALET" olarak belirtilerek bu parametrenin vekalet süreçlerine ait olduğu vurgulanmıştır.

Not: Farklı parametreler için benzer şekilde ek insert blokları tanımlanacaktır (ör. Mazeret İzni Onay, Şehir İçi Görev İzni Onay vb., her biri kendine özgü parameter_code değeriyle).

Rol-Parametre İlişkisi (Liquibase)#

Parametrelerin proxy rolü ile eşleştirilmesi:

<insert tableName="kys_role_param_def_rel">
    <column name="role_id" valueComputed="(SELECT ID FROM kys_role WHERE code='proxyParameterRoleCode')"/>
    <column name="parameter_definition_id" valueComputed="(SELECT ID FROM kys_role_param_def WHERE parameter_code='YILLIK_IZIN')"/>
</insert>

Açıklama: Son olarak, yukarıdaki örnek kod parçası, YILLIK_IZIN kodlu parametrenin sabit proxy rolüyle ilişkilendirildiğini göstermektedir. Bu insert işlemi sayesinde sistem, ilgili rolün hangi parametreleri içerdiğini belirler.

İlgili Liquibase scriptlerinde, tanımlanan her parametre için benzer ilişkilendirmeler yapılmalıdır (örneğin, MAZERET_IZIN, SEHIR_ICI_GUNLUK_GOREV_IZIN kodlu parametreler de aynı rol ile ilişkilendirilecektir).

Sonuç#

Bu ilklendirme adımları tamamlandığında, Keysis uygulaması ilk çalıştığı andan itibaren proxy parametre rolü ve parametreleri kullanıma hazır hale gelir. Geliştiriciler ve sistem yöneticileri, bu altyapıyı kullanarak vekalet işlemlerinde ince taneli yetki kısıtlamalarını güvenle uygulayabilirler.