backend/generate/api/permission.api

syntax = "v1"

// =================================================================
// Type: 權限 (Permission)
// =================================================================
type (
    // PermissionResp 權限回應
    PermissionResp {
        ID         string `json:"id"`
        ParentID   string `json:"parent_id"`
        Name       string `json:"name"`
        HTTPPath   string `json:"http_path,omitempty"`
        HTTPMethod string `json:"http_method,omitempty"`
        Status     string `json:"status"` // active, inactive
        Type       string `json:"type"`   // menu, button, api
    }

    // PermissionTreeNode 權限樹節點
    PermissionTreeNode {
        PermissionResp
        Children []PermissionTreeNode `json:"children,omitempty"`
    }

    // GetPermissionByHTTPReq 根據 HTTP 資訊查詢權限請求
    GetPermissionByHTTPReq {
        Authorization
        Path   string `json:"path" validate:"required"`   // HTTP 路徑
        Method string `json:"method" validate:"required"` // HTTP 方法
    }

    // ExpandPermissionsReq 展開權限請求
    ExpandPermissionsReq {
        Authorization
        Permissions []string `json:"permissions" validate:"required,min=1"` // 權限名稱列表
    }

    // ExpandPermissionsResp 展開權限回應
    ExpandPermissionsResp {
        Permissions []string `json:"permissions"` // 展開後的權限列表（包含父權限）
    }

    // GetUsersByPermissionReq 根據權限查詢用戶請求
    GetUsersByPermissionReq {
        Authorization
        Permissions []string `json:"permissions" validate:"required,min=1"` // 權限名稱列表
    }

    // GetUsersByPermissionResp 根據權限查詢用戶回應
    GetUsersByPermissionResp {
        UserUIDs []string `json:"user_uids"` // 擁有指定權限的用戶 UID 列表
    }

    // ListPermissionsResp 權限列表回應
    ListPermissionsResp {
        Permissions []PermissionResp `json:"permissions"`
        Total       int64            `json:"total"`
    }
)

// =================================================================
// Type: 角色 (Role)
// =================================================================
type (
    // CreateRoleReq 創建角色請求
    CreateRoleReq {
        Authorization
        ClientID    int                    `json:"client_id" validate:"required"`
        Name        string                 `json:"name" validate:"required,min=1,max=100"`
        Permissions map[string]string      `json:"permissions,optional"` // 權限映射，key 為權限名稱，value 為狀態 (open, close)
    }

    // UpdateRoleReq 更新角色請求
    UpdateRoleReq {
        Authorization
        Name        *string            `json:"name,optional" validate:"omitempty,min=1,max=100"`
        Status      *string            `json:"status,optional" validate:"omitempty,oneof=active inactive"`
        Permissions map[string]string  `json:"permissions,optional"` // 權限映射
    }

    // RoleResp 角色回應
    RoleResp {
        ID          string            `json:"id"`
        UID         string            `json:"uid"`
        ClientID    int               `json:"client_id"`
        Name        string            `json:"name"`
        Status      string            `json:"status"`      // active, inactive
        Permissions map[string]string `json:"permissions"`  // 權限映射
        CreateTime  string            `json:"create_time"`
        UpdateTime  string            `json:"update_time"`
    }

    // RoleWithUserCountResp 角色回應（含用戶數量）
    RoleWithUserCountResp {
        RoleResp
        UserCount int `json:"user_count"`
    }

    // ListRolesReq 查詢角色列表請求
    ListRolesReq {
        Authorization
        ClientID    int      `json:"client_id,optional"`
        Name        string   `json:"name,optional"`
        Status      string   `json:"status,optional" validate:"omitempty,oneof=active inactive"`
        Permissions []string  `json:"permissions,optional"` // 權限名稱列表（篩選擁有這些權限的角色）
    }

    // ListRolesResp 角色列表回應
    ListRolesResp {
        Roles []RoleWithUserCountResp `json:"roles"`
        Total int64                   `json:"total"`
    }

    // PageRolesReq 分頁查詢角色請求
    PageRolesReq {
        Authorization
        ClientID    int      `json:"client_id,optional"`
        Name        string   `json:"name,optional"`
        Status      string   `json:"status,optional" validate:"omitempty,oneof=active inactive"`
        Permissions []string  `json:"permissions,optional"`
        Page        int      `json:"page,optional" validate:"omitempty,min=1"` // 頁碼，從 1 開始
        Size        int      `json:"size,optional" validate:"omitempty,min=1,max=100"` // 每頁大小
    }

    // PageRolesResp 角色分頁回應
    PageRolesResp {
        List  []RoleWithUserCountResp `json:"list"`
        Total int64                   `json:"total"`
        Page  int                     `json:"page"`
        Size  int                     `json:"size"`
    }
)

// =================================================================
// Type: 角色權限 (Role Permission)
// =================================================================
type (
    // GetRolePermissionsResp 角色權限回應
    GetRolePermissionsResp {
        RoleUID     string            `json:"role_uid"`
        Permissions map[string]string `json:"permissions"` // 權限映射
    }

    // GetUserPermissionsResp 用戶權限回應
    GetUserPermissionsResp {
        UserUID     string            `json:"user_uid"`
        RoleUID     string            `json:"role_uid"`
        RoleName    string            `json:"role_name"`
        Permissions map[string]string `json:"permissions"` // 權限映射
    }

    // UpdateRolePermissionsReq 更新角色權限請求
    UpdateRolePermissionsReq {
        Authorization
        Permissions map[string]string `json:"permissions" validate:"required"` // 權限映射
    }

    // CheckPermissionReq 檢查權限請求
    CheckPermissionReq {
        Authorization
        Path   string `json:"path" validate:"required"`   // HTTP 路徑
        Method string `json:"method" validate:"required"` // HTTP 方法
    }

    // CheckPermissionResp 檢查權限回應
    CheckPermissionResp {
        Allowed        bool   `json:"allowed"`         // 是否有權限
        PermissionName string `json:"permission_name,omitempty"` // 權限名稱
        PlainCode      bool   `json:"plain_code"`      // 是否有 plain_code 權限（特殊邏輯）
    }
)

// =================================================================
// Type: 用戶角色 (User Role)
// =================================================================
type (
    // AssignRoleReq 指派角色請求
    AssignRoleReq {
        Authorization
        UserUID string `json:"user_uid" validate:"required"`
        RoleUID string `json:"role_uid" validate:"required"`
        Brand   string `json:"brand,optional"` // 品牌標識
    }

    // UserRoleResp 用戶角色回應
    UserRoleResp {
        UserUID    string `json:"user_uid"`
        RoleUID    string `json:"role_uid"`
        Brand      string `json:"brand"`
        CreateTime string `json:"create_time"`
        UpdateTime string `json:"update_time"`
    }

    // ListUserRolesReq 查詢用戶角色列表請求
    ListUserRolesReq {
        Authorization
        Brand  string `json:"brand,optional"`
        RoleID string `json:"role_id,optional"`
        Status string `json:"status,optional" validate:"omitempty,oneof=active inactive"`
    }

    // ListUserRolesResp 用戶角色列表回應
    ListUserRolesResp {
        UserRoles []UserRoleResp `json:"user_roles"`
        Total     int64          `json:"total"`
    }

    // GetUsersByRoleResp 角色用戶列表回應
    GetUsersByRoleResp {
        UserRoles []UserRoleResp `json:"user_roles"`
        Total     int64          `json:"total"`
    }
)

// =================================================================
// Service: 權限管理 API - 需要登入 (Permission Service)
// =================================================================
@server(
    group: permission
    prefix: /api/v1/permissions
    schemes: https
    timeout: 30s
    middleware: AuthMiddleware
)
service gateway {
    // ==================== 權限管理 ====================
    @doc(
        summary: "取得所有權限"
        description: "取得系統中所有啟用的權限列表"
    )
    @handler getAllPermissions
    get / (Authorization) returns (ListPermissionsResp)

    @doc(
        summary: "取得權限樹"
        description: "取得以樹狀結構組織的權限列表"
    )
    @handler getPermissionTree
    get /tree (Authorization) returns (PermissionTreeNode)

    @doc(
        summary: "根據 HTTP 資訊取得權限"
        description: "根據 HTTP 路徑和方法取得對應的權限資訊"
    )
    @handler getPermissionByHTTP
    post /by-http (GetPermissionByHTTPReq) returns (PermissionResp)

    @doc(
        summary: "展開權限"
        description: "展開權限列表，包含所有父權限"
    )
    @handler expandPermissions
    post /expand (ExpandPermissionsReq) returns (ExpandPermissionsResp)

    @doc(
        summary: "根據權限取得用戶"
        description: "取得擁有指定權限的所有用戶 UID"
    )
    @handler getUsersByPermission
    post /users (GetUsersByPermissionReq) returns (GetUsersByPermissionResp)

    // ==================== 角色管理 ====================
    @doc(
        summary: "創建角色"
        description: "創建一個新角色並設定權限"
    )
    @handler createRole
    post /roles (CreateRoleReq) returns (RoleResp)

    @doc(
        summary: "更新角色"
        description: "更新角色的名稱、狀態或權限"
    )
    @handler updateRole
    put /roles/:uid (UpdateRoleReq) returns (RoleResp)

    @doc(
        summary: "刪除角色"
        description: "刪除指定角色（軟刪除，設為 inactive）"
    )
    @handler deleteRole
    delete /roles/:uid (Authorization) returns (RespOK)

    @doc(
        summary: "取得角色"
        description: "根據 UID 取得角色的詳細資訊"
    )
    @handler getRole
    get /roles/:uid (Authorization) returns (RoleResp)

    @doc(
        summary: "查詢角色列表"
        description: "查詢角色列表，支援多種篩選條件"
    )
    @handler listRoles
    get /roles (ListRolesReq) returns (ListRolesResp)

    @doc(
        summary: "分頁查詢角色"
        description: "分頁查詢角色列表，支援多種篩選條件"
    )
    @handler pageRoles
    get /roles/page (PageRolesReq) returns (PageRolesResp)

    // ==================== 角色權限管理 ====================
    @doc(
        summary: "取得角色權限"
        description: "取得指定角色的所有權限"
    )
    @handler getRolePermissions
    get /roles/:role_uid (Authorization) returns (GetRolePermissionsResp)

    @doc(
        summary: "取得用戶權限"
        description: "取得指定用戶的所有權限（透過角色）"
    )
    @handler getUserPermissions
    get /users/:user_uid (Authorization) returns (GetUserPermissionsResp)

    @doc(
        summary: "更新角色權限"
        description: "更新指定角色的權限列表"
    )
    @handler updateRolePermissions
    put /roles/:role_uid (UpdateRolePermissionsReq) returns (GetRolePermissionsResp)

    @doc(
        summary: "檢查權限"
        description: "檢查當前用戶是否有執行指定 HTTP 操作的權限"
    )
    @handler checkPermission
    post /check (CheckPermissionReq) returns (CheckPermissionResp)

    // ==================== 用戶角色管理 ====================
    @doc(
        summary: "指派角色給用戶"
        description: "為用戶指派一個角色"
    )
    @handler assignRole
    post /users/:user_uid/roles (AssignRoleReq) returns (UserRoleResp)

    @doc(
        summary: "更新用戶角色"
        description: "更新用戶的角色（替換現有角色）"
    )
    @handler updateUserRole
    put /users/:user_uid/roles/:role_uid (Authorization) returns (UserRoleResp)

    @doc(
        summary: "移除用戶角色"
        description: "移除用戶的角色"
    )
    @handler removeUserRole
    delete /users/:user_uid/roles (Authorization) returns (RespOK)

    @doc(
        summary: "取得用戶角色"
        description: "取得指定用戶的角色資訊"
    )
    @handler getUserRole
    get /users/:user_uid/roles (Authorization) returns (UserRoleResp)

    @doc(
        summary: "取得角色的所有用戶"
        description: "取得擁有指定角色的所有用戶"
    )
    @handler getUsersByRole
    get /roles/:role_uid/users (Authorization) returns (GetUsersByRoleResp)

    @doc(
        summary: "查詢用戶角色列表"
        description: "查詢用戶角色列表，支援多種篩選條件"
    )
    @handler listUserRoles
    get /user-roles (ListUserRolesReq) returns (ListUserRolesResp)
}