@nocobase/plugin-acl 2.1.0-beta.15 → 2.1.0-beta.17

package/dist/swagger/index.js

@@ -32,23 +32,23 @@ module.exports = __toCommonJS(swagger_exports);
 var swagger_default = {
   openapi: "3.0.2",
   info: {
-    title: "NocoBase API - ACL plugin"
+    title: "NocoBase API - ACL plugin",
+    version: "1.0.0"
   },
   paths: {
     "/roles:list": {
       get: {
         tags: ["roles"],
-        description: "",
-        parameters: [],
+        summary: "List roles",
         responses: {
           200: {
-            description: "ok",
+            description: "OK",
             content: {
               "application/json": {
                 schema: {
                   type: "array",
                   items: {
-                    $ref: "#/components/schemas/role"
+                    $ref: "#/components/schemas/Role"
                   }
                 }
               }
@@ -60,25 +60,15 @@ var swagger_default = {
     "/roles:get": {
       get: {
         tags: ["roles"],
-        description: "",
-        parameters: [
-          {
-            name: "filterByTk",
-            in: "query",
-            description: "role name",
-            required: true,
-            schema: {
-              type: "string"
-            }
-          }
-        ],
+        summary: "Get a role",
+        parameters: [{ $ref: "#/components/parameters/RoleNameQuery" }],
         responses: {
           200: {
-            description: "ok",
+            description: "OK",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/role"
+                  $ref: "#/components/schemas/Role"
                 }
               }
             }
@@ -89,23 +79,25 @@ var swagger_default = {
     "/roles:create": {
       post: {
         tags: ["roles"],
-        description: "",
+        summary: "Create a role",
+        description: "Create a role. Request body uses direct role values.",
         requestBody: {
+          required: true,
           content: {
             "application/json": {
               schema: {
-                $ref: "#/components/schemas/role"
+                $ref: "#/components/schemas/RoleWrite"
               }
             }
           }
         },
         responses: {
-          "200": {
+          200: {
             description: "OK",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/role"
+                  $ref: "#/components/schemas/Role"
                 }
               }
             }
@@ -116,34 +108,26 @@ var swagger_default = {
     "/roles:update": {
       post: {
         tags: ["roles"],
-        description: "",
-        parameters: [
-          {
-            name: "filterByTk",
-            in: "query",
-            description: "role name",
-            required: true,
-            schema: {
-              type: "string"
-            }
-          }
-        ],
+        summary: "Update a role",
+        description: "Update a role by role name (`filterByTk`). Commonly used for role metadata and system permission snippets.",
+        parameters: [{ $ref: "#/components/parameters/RoleNameQuery" }],
         requestBody: {
+          required: true,
           content: {
             "application/json": {
               schema: {
-                $ref: "#/components/schemas/role"
+                $ref: "#/components/schemas/RoleWrite"
               }
             }
           }
         },
         responses: {
           200: {
-            description: "ok",
+            description: "OK",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/role"
+                  $ref: "#/components/schemas/Role"
                 }
               }
             }
@@ -154,20 +138,10 @@ var swagger_default = {
     "/roles:destroy": {
       post: {
         tags: ["roles"],
-        description: "",
-        parameters: [
-          {
-            name: "filterByTk",
-            in: "query",
-            description: "role name",
-            required: true,
-            schema: {
-              type: "string"
-            }
-          }
-        ],
+        summary: "Destroy a role",
+        parameters: [{ $ref: "#/components/parameters/RoleNameQuery" }],
         responses: {
-          "200": {
+          200: {
             description: "OK"
           }
         }
@@ -176,14 +150,15 @@ var swagger_default = {
     "/roles:check": {
       get: {
         tags: ["roles"],
-        description: "return current user role",
+        summary: "Check current role context",
+        description: "Return the current effective role context, including role mode and resolved ACL action map for the current user.",
         responses: {
           200: {
-            description: "ok",
+            description: "OK",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/role"
+                  $ref: "#/components/schemas/RoleCheck"
                 }
               }
             }
@@ -194,82 +169,478 @@ var swagger_default = {
     "/roles:setDefaultRole": {
       post: {
         tags: ["roles"],
-        description: "set default role for new user",
+        summary: "Set default role for new users",
         requestBody: {
+          required: true,
           content: {
             "application/json": {
               schema: {
                 type: "object",
                 properties: {
-                  roleName: {
-                    type: "string"
+                  roleName: { type: "string" }
+                },
+                required: ["roleName"]
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK"
+          }
+        }
+      }
+    },
+    "/roles:setSystemRoleMode": {
+      post: {
+        tags: ["roles"],
+        summary: "Set system role mode",
+        description: "Set the system role mode. Valid values are `default`, `allow-use-union`, and `only-use-union`.",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/RoleModeWrite"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK"
+          }
+        }
+      }
+    },
+    "/roles:applyDataPermissions": {
+      post: {
+        tags: ["roles"],
+        summary: "Apply collection-level independent ACL permissions in batch for a role",
+        description: "Apply one or more collection-level independent ACL permission configs for a role in one request. Supports action scope binding by `scopeId` or `scopeKey`.",
+        parameters: [{ $ref: "#/components/parameters/RoleNameQuery" }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/RoleDataPermissionsApplyWrite"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleDataPermissionsApplyResult"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/roles/{roleName}/users:list": {
+      get: {
+        tags: ["roles.users"],
+        summary: "List users bound to a role",
+        parameters: [
+          { $ref: "#/components/parameters/RoleNamePath" },
+          { $ref: "#/components/parameters/PageQuery" },
+          { $ref: "#/components/parameters/PageSizeQuery" },
+          { $ref: "#/components/parameters/SortQuery" },
+          { $ref: "#/components/parameters/AppendsQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  additionalProperties: true,
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        additionalProperties: true
+                      }
+                    },
+                    meta: {
+                      type: "object",
+                      additionalProperties: true
+                    }
                   }
                 }
               }
             }
           }
-        },
+        }
+      }
+    },
+    "/roles/{roleName}/users:add": {
+      post: {
+        tags: ["roles.users"],
+        summary: "Bind one or more users to a role",
+        parameters: [
+          { $ref: "#/components/parameters/RoleNamePath" },
+          { $ref: "#/components/parameters/MembershipUserFilterByTkQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK"
+          }
+        }
+      }
+    },
+    "/roles/{roleName}/users:remove": {
+      post: {
+        tags: ["roles.users"],
+        summary: "Unbind one or more users from a role",
+        parameters: [
+          { $ref: "#/components/parameters/RoleNamePath" },
+          { $ref: "#/components/parameters/MembershipUserFilterByTkQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK"
+          }
+        }
+      }
+    },
+    "/users/{userId}/roles:list": {
+      get: {
+        tags: ["users.roles"],
+        summary: "List roles bound to a user",
+        parameters: [
+          { $ref: "#/components/parameters/UserIdPath" },
+          { $ref: "#/components/parameters/PageQuery" },
+          { $ref: "#/components/parameters/PageSizeQuery" },
+          { $ref: "#/components/parameters/SortQuery" },
+          { $ref: "#/components/parameters/AppendsQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  additionalProperties: true,
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        additionalProperties: true
+                      }
+                    },
+                    meta: {
+                      type: "object",
+                      additionalProperties: true
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/{userId}/roles:add": {
+      post: {
+        tags: ["users.roles"],
+        summary: "Bind one or more roles to a user",
+        parameters: [
+          { $ref: "#/components/parameters/UserIdPath" },
+          { $ref: "#/components/parameters/MembershipRoleFilterByTkQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK"
+          }
+        }
+      }
+    },
+    "/users/{userId}/roles:remove": {
+      post: {
+        tags: ["users.roles"],
+        summary: "Unbind one or more roles from a user",
+        parameters: [
+          { $ref: "#/components/parameters/UserIdPath" },
+          { $ref: "#/components/parameters/MembershipRoleFilterByTkQuery" }
+        ],
         responses: {
-          "200": {
+          200: {
             description: "OK"
           }
         }
       }
     },
-    "/roles/{roleName}/collections:list": {
+    "/dataSources/{dataSourceKey}/roles:update": {
+      post: {
+        tags: ["dataSources.roles"],
+        summary: "Update global ACL strategy for a role in a data source",
+        description: "Configure global table permissions for a role inside a data source. Request body typically includes `roleName`, `dataSourceKey`, and `strategy.actions`.",
+        parameters: [
+          { $ref: "#/components/parameters/DataSourceKeyPath" },
+          { $ref: "#/components/parameters/RoleNameQuery" }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/DataSourceRole"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/DataSourceRole"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/dataSources/{dataSourceKey}/roles:get": {
+      get: {
+        tags: ["dataSources.roles"],
+        summary: "Get global ACL strategy for a role in a data source",
+        parameters: [
+          { $ref: "#/components/parameters/DataSourceKeyPath" },
+          { $ref: "#/components/parameters/RoleNameQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/DataSourceRole"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/roles/{roleName}/dataSourcesCollections:list": {
+      get: {
+        tags: ["roles.dataSourcesCollections"],
+        summary: "List data-source collections in role permission configuration",
+        description: "List collections in the target data source for the given role and indicate whether they use global permissions or collection-level independent permissions. You can pass `dataSourceKey` directly, or through `filter.dataSourceKey` for compatibility.",
+        parameters: [
+          { $ref: "#/components/parameters/RoleNamePath" },
+          { $ref: "#/components/parameters/DataSourceKeyQuery" },
+          { $ref: "#/components/parameters/PageQuery" },
+          { $ref: "#/components/parameters/PageSizeQuery" },
+          { $ref: "#/components/parameters/SortQuery" },
+          { $ref: "#/components/parameters/AppendsQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    count: { type: "integer" },
+                    rows: {
+                      type: "array",
+                      items: { $ref: "#/components/schemas/RoleCollectionPermissionRow" }
+                    },
+                    page: { type: "integer" },
+                    pageSize: { type: "integer" },
+                    totalPage: { type: "integer" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/roles/{roleName}/dataSourceResources:create": {
+      post: {
+        tags: ["roles.dataSourceResources"],
+        summary: "Create collection-level independent ACL permissions for a role",
+        description: [
+          "Create collection-level independent permission config for a role in a data source.",
+          "Request body usually includes `name`, `dataSourceKey`, `usingActionsConfig`, and `actions`.",
+          "The server uses the role path parameter plus request-body `name` and `dataSourceKey` to create the record."
+        ].join("\n"),
+        parameters: [{ $ref: "#/components/parameters/RoleNamePath" }, { $ref: "#/components/parameters/FilterQuery" }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/RoleDataSourceResourceWrite"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleDataSourceResource"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/roles/{roleName}/dataSourceResources:get": {
       get: {
-        tags: ["roles.collections"],
-        description: "list permissions of collections for role by roleName",
+        tags: ["roles.dataSourceResources"],
+        summary: "Get one collection-level independent ACL permission for a role",
+        description: "Get one collection-level independent permission config. You can target it by `filterByTk`, or by `name` + `dataSourceKey`. `filter` with `{ name, dataSourceKey }` is still supported for compatibility.",
+        parameters: [
+          { $ref: "#/components/parameters/RoleNamePath" },
+          { $ref: "#/components/parameters/ResourcePermissionTkQuery" },
+          { $ref: "#/components/parameters/DataSourceKeyQuery" },
+          { $ref: "#/components/parameters/DataSourceResourceNameQuery" },
+          { $ref: "#/components/parameters/FilterQuery" },
+          { $ref: "#/components/parameters/AppendsQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleDataSourceResource"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/roles/{roleName}/dataSourceResources:update": {
+      post: {
+        tags: ["roles.dataSourceResources"],
+        summary: "Update collection-level independent ACL permissions for a role",
+        description: "Update one collection-level independent permission config. You can target it by `filterByTk`, or by `name` + `dataSourceKey`. `filter` with `{ name, dataSourceKey }` is still supported for compatibility.",
         parameters: [
-          {
-            name: "filterByTk",
-            in: "query",
-            description: "role name",
-            required: true,
-            schema: {
-              type: "string"
+          { $ref: "#/components/parameters/RoleNamePath" },
+          { $ref: "#/components/parameters/ResourcePermissionTkQuery" },
+          { $ref: "#/components/parameters/DataSourceKeyQuery" },
+          { $ref: "#/components/parameters/DataSourceResourceNameQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/RoleDataSourceResourceWrite"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleDataSourceResource"
+                }
+              }
             }
           }
+        }
+      }
+    },
+    "/rolesResourcesScopes:list": {
+      get: {
+        tags: ["rolesResourcesScopes"],
+        summary: "List reusable ACL scopes",
+        parameters: [
+          { $ref: "#/components/parameters/PageQuery" },
+          { $ref: "#/components/parameters/PageSizeQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
         ],
         responses: {
-          "200": {
+          200: {
             description: "OK",
             content: {
               "application/json": {
                 schema: {
                   type: "array",
-                  items: {
-                    type: "object",
-                    properties: {
-                      type: {
-                        type: "string",
-                        description: "collection"
-                      },
-                      name: {
-                        type: "string",
-                        description: "collection name"
-                      },
-                      collectionName: {
-                        type: "string",
-                        description: "collection name"
-                      },
-                      title: {
-                        type: "string",
-                        description: "collection title"
-                      },
-                      roleName: {
-                        type: "string",
-                        description: "role name"
-                      },
-                      usingConfig: {
-                        type: "string",
-                        enum: ["resourceAction", "strategy"],
-                        description: "resourceAction: \u5355\u72EC\u914D\u7F6E, strategy: \u5168\u5C40\u7B56\u7565"
-                      },
-                      exists: {
-                        type: "boolean",
-                        description: "\u662F\u5426\u5B58\u5728\u5355\u72EC\u914D\u7F6E\u7684\u6743\u9650"
-                      }
+                  items: { $ref: "#/components/schemas/RoleResourceScope" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/rolesResourcesScopes:get": {
+      get: {
+        tags: ["rolesResourcesScopes"],
+        summary: "Get a reusable ACL scope",
+        parameters: [{ $ref: "#/components/parameters/ScopePkQuery" }, { $ref: "#/components/parameters/FilterQuery" }],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleResourceScope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/dataSources/{dataSourceKey}/rolesResourcesScopes:list": {
+      get: {
+        tags: ["dataSources.rolesResourcesScopes"],
+        summary: "List reusable ACL scopes in a data source",
+        parameters: [
+          { $ref: "#/components/parameters/DataSourceKeyPath" },
+          { $ref: "#/components/parameters/PageQuery" },
+          { $ref: "#/components/parameters/PageSizeQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: { $ref: "#/components/schemas/RoleResourceScope" }
+                    },
+                    meta: {
+                      type: "object",
+                      additionalProperties: true
                     }
                   }
                 }
@@ -279,50 +650,121 @@ var swagger_default = {
         }
       }
     },
+    "/dataSources/{dataSourceKey}/rolesResourcesScopes:get": {
+      get: {
+        tags: ["dataSources.rolesResourcesScopes"],
+        summary: "Get a reusable ACL scope in a data source",
+        parameters: [
+          { $ref: "#/components/parameters/DataSourceKeyPath" },
+          { $ref: "#/components/parameters/ScopePkQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleResourceScope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/dataSources/{dataSourceKey}/rolesResourcesScopes:create": {
+      post: {
+        tags: ["dataSources.rolesResourcesScopes"],
+        summary: "Create a reusable ACL scope in a data source",
+        description: "Create a reusable scope definition under the target data source.",
+        parameters: [{ $ref: "#/components/parameters/DataSourceKeyPath" }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/RoleResourceScopeWrite"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleResourceScope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/dataSources/{dataSourceKey}/rolesResourcesScopes:update": {
+      post: {
+        tags: ["dataSources.rolesResourcesScopes"],
+        summary: "Update a reusable ACL scope in a data source",
+        parameters: [
+          { $ref: "#/components/parameters/DataSourceKeyPath" },
+          { $ref: "#/components/parameters/ScopePkQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/RoleResourceScopeWrite"
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: "OK",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RoleResourceScope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/dataSources/{dataSourceKey}/rolesResourcesScopes:destroy": {
+      post: {
+        tags: ["dataSources.rolesResourcesScopes"],
+        summary: "Destroy a reusable ACL scope in a data source",
+        parameters: [
+          { $ref: "#/components/parameters/DataSourceKeyPath" },
+          { $ref: "#/components/parameters/ScopePkQuery" },
+          { $ref: "#/components/parameters/FilterQuery" }
+        ],
+        responses: {
+          200: {
+            description: "OK"
+          }
+        }
+      }
+    },
     "/availableActions:list": {
       get: {
         tags: ["availableActions"],
-        description: "available actions of resource in current system",
-        parameters: [],
+        summary: "List configurable ACL actions",
+        description: "List ACL actions available in the current system. Use this before configuring resource-level action or field permissions.",
         responses: {
-          "200": {
+          200: {
             description: "OK",
             content: {
               "application/json": {
                 schema: {
                   type: "array",
-                  items: {
-                    type: "object",
-                    properties: {
-                      name: {
-                        type: "string",
-                        description: "Action\u540D\u79F0"
-                      },
-                      displayName: {
-                        type: "string",
-                        description: "Action\u663E\u793A\u540D\u79F0"
-                      },
-                      allowConfigureFields: {
-                        type: "boolean",
-                        description: "\u662F\u5426\u5141\u8BB8\u914D\u7F6E\u5B57\u6BB5"
-                      },
-                      onNewRecord: {
-                        type: "string",
-                        description: "\u662F\u5426\u662F\u65B0\u8BB0\u5F55\u7684Action"
-                      },
-                      type: {
-                        type: "string",
-                        description: "new-data \u6216\u8005 old-data"
-                      },
-                      aliases: {
-                        type: "array",
-                        items: {
-                          type: "string"
-                        },
-                        description: "\u522B\u540D"
-                      }
-                    }
-                  }
+                  items: { $ref: "#/components/schemas/AvailableAction" }
                 }
               }
             }
@@ -332,72 +774,436 @@ var swagger_default = {
     }
   },
   components: {
+    parameters: {
+      RoleNameQuery: {
+        name: "filterByTk",
+        in: "query",
+        description: "Role name.",
+        required: true,
+        schema: { type: "string" }
+      },
+      RoleNamePath: {
+        name: "roleName",
+        in: "path",
+        description: "Role name.",
+        required: true,
+        schema: { type: "string" }
+      },
+      UserIdPath: {
+        name: "userId",
+        in: "path",
+        description: "User primary key.",
+        required: true,
+        schema: {
+          anyOf: [{ type: "string" }, { type: "integer" }]
+        }
+      },
+      DataSourceKeyPath: {
+        name: "dataSourceKey",
+        in: "path",
+        description: "Data source key, for example `main`.",
+        required: true,
+        schema: { type: "string" }
+      },
+      DataSourceKeyQuery: {
+        name: "dataSourceKey",
+        in: "query",
+        description: "Data source key, for example `main`.",
+        schema: { type: "string" }
+      },
+      MembershipUserFilterByTkQuery: {
+        name: "filterByTk",
+        in: "query",
+        description: "User primary key, or a list of user primary keys.",
+        required: true,
+        schema: {
+          anyOf: [
+            { type: "string" },
+            { type: "integer" },
+            {
+              type: "array",
+              items: {
+                anyOf: [{ type: "string" }, { type: "integer" }]
+              }
+            }
+          ]
+        }
+      },
+      MembershipRoleFilterByTkQuery: {
+        name: "filterByTk",
+        in: "query",
+        description: "Role name, or a list of role names.",
+        required: true,
+        schema: {
+          anyOf: [
+            { type: "string" },
+            {
+              type: "array",
+              items: {
+                type: "string"
+              }
+            }
+          ]
+        }
+      },
+      ResourceNameQuery: {
+        name: "filterByTk",
+        in: "query",
+        description: "Resource name, typically the collection name.",
+        required: true,
+        schema: { type: "string" }
+      },
+      DataSourceResourceNameQuery: {
+        name: "name",
+        in: "query",
+        description: "Resource name, typically the collection name.",
+        schema: { type: "string" }
+      },
+      ScopePkQuery: {
+        name: "filterByTk",
+        in: "query",
+        description: "Scope primary key.",
+        schema: { type: "integer" }
+      },
+      ResourcePermissionTkQuery: {
+        name: "filterByTk",
+        in: "query",
+        description: "Resource permission record primary key.",
+        schema: { type: "integer" }
+      },
+      PageQuery: {
+        name: "page",
+        in: "query",
+        schema: { type: "integer" }
+      },
+      PageSizeQuery: {
+        name: "pageSize",
+        in: "query",
+        schema: { type: "integer" }
+      },
+      FilterQuery: {
+        name: "filter",
+        in: "query",
+        schema: {
+          type: "object",
+          additionalProperties: true
+        }
+      },
+      AppendsQuery: {
+        name: "appends",
+        in: "query",
+        schema: {
+          type: "array",
+          items: { type: "string" }
+        }
+      }
+    },
     schemas: {
-      role: {
+      RoleStrategy: {
+        type: "object",
+        description: "Global action strategy for a role.",
+        properties: {
+          actions: {
+            type: "array",
+            items: { type: "string" },
+            description: "Action names such as `create`, `view`, `update`, `destroy`, or scoped variants like `view:own`."
+          }
+        },
+        additionalProperties: true
+      },
+      RoleWrite: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Role title." },
+          name: { type: "string", description: "Role identifier." },
+          description: { type: "string", description: "Role description." },
+          hidden: { type: "boolean", description: "Whether the role is hidden." },
+          default: { type: "boolean", description: "Whether the role is default for new users." },
+          allowConfigure: { type: "boolean", description: "Whether the role can be configured." },
+          allowNewMenu: { type: "boolean", description: "Whether the role can create menus." },
+          snippets: {
+            type: "array",
+            items: { type: "string" },
+            description: "System permission snippets, for example `ui.*`, `!pm`, or `!app`."
+          },
+          strategy: {
+            allOf: [{ $ref: "#/components/schemas/RoleStrategy" }],
+            description: "Role-level ACL strategy."
+          }
+        },
+        additionalProperties: true
+      },
+      Role: {
+        allOf: [{ $ref: "#/components/schemas/RoleWrite" }],
+        properties: {
+          createdAt: { type: "string", format: "date-time" },
+          updatedAt: { type: "string", format: "date-time" }
+        }
+      },
+      RoleCheck: {
         type: "object",
         properties: {
-          title: {
+          role: { type: "string", description: "Current effective role name." },
+          roleMode: {
             type: "string",
-            description: "\u89D2\u8272\u540D\u79F0"
+            enum: ["default", "allow-use-union", "only-use-union"],
+            description: "System role mode."
           },
+          availableActions: {
+            type: "array",
+            items: { type: "string" }
+          },
+          actions: {
+            type: "object",
+            additionalProperties: true,
+            description: "Resolved ACL action map for the current role context."
+          }
+        },
+        additionalProperties: true
+      },
+      RoleModeWrite: {
+        type: "object",
+        properties: {
+          roleMode: {
+            type: "string",
+            enum: ["default", "allow-use-union", "only-use-union"]
+          }
+        },
+        required: ["roleMode"]
+      },
+      RoleDataPermissionActionWrite: {
+        type: "object",
+        properties: {
           name: {
             type: "string",
-            description: "\u89D2\u8272\u6807\u8BC6"
+            description: "ACL action name, such as `view`, `create`, `update`, or `destroy`."
           },
-          description: {
-            type: "string",
-            description: "\u89D2\u8272\u63CF\u8FF0"
+          fields: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional allowed field list for field-configurable actions."
           },
-          hidden: {
-            type: "boolean",
-            description: "\u662F\u5426\u9690\u85CF"
+          scopeId: {
+            type: "integer",
+            nullable: true,
+            description: "Optional scope id. Use `null` to clear the scope binding."
           },
-          default: {
-            type: "boolean",
-            description: "\u662F\u5426\u9ED8\u8BA4"
+          scopeKey: {
+            type: "string",
+            description: "Optional built-in/custom scope key. When provided, server resolves it to `scopeId`."
           },
-          allowConfigure: {
-            type: "boolean",
-            description: "\u662F\u5426\u5141\u8BB8\u914D\u7F6E"
+          scope: {
+            type: "object",
+            properties: {
+              id: { type: "integer" },
+              key: { type: "string" }
+            },
+            additionalProperties: true,
+            description: "Optional compatibility payload from existing role-resource readback."
+          }
+        },
+        required: ["name"],
+        additionalProperties: true
+      },
+      RoleDataPermissionResourceWrite: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Collection name."
           },
-          allowNewMenu: {
+          usingActionsConfig: {
             type: "boolean",
-            description: "\u662F\u5426\u5141\u8BB8\u65B0\u5EFA\u83DC\u5355"
+            description: "Whether the collection uses independent action config."
           },
-          snippets: {
+          actions: {
             type: "array",
-            items: {
-              type: "string"
-            },
-            description: "\u63A5\u53E3\u6743\u9650"
+            items: { $ref: "#/components/schemas/RoleDataPermissionActionWrite" },
+            description: "Independent action config list for the collection."
+          }
+        },
+        required: ["name"],
+        additionalProperties: true
+      },
+      RoleDataPermissionsApplyWrite: {
+        type: "object",
+        properties: {
+          dataSourceKey: {
+            type: "string",
+            description: "Data source key, default is `main` when omitted."
           },
-          strategy: {
+          resources: {
             type: "array",
-            description: "\u6570\u636E\u8868\u6743\u9650\u7B56\u7565",
-            items: {
-              type: "object",
-              properties: {
-                actions: {
-                  type: "array",
-                  items: {
-                    type: "string"
-                  },
-                  description: "\u64CD\u4F5C"
-                }
-              }
-            }
+            items: { $ref: "#/components/schemas/RoleDataPermissionResourceWrite" },
+            description: "Collection-level independent permission payloads to apply in batch."
+          }
+        },
+        required: ["resources"],
+        additionalProperties: true
+      },
+      RoleDataPermissionsApplyResult: {
+        type: "object",
+        properties: {
+          roleName: { type: "string" },
+          dataSourceKey: { type: "string" },
+          count: { type: "integer" },
+          resources: {
+            type: "array",
+            items: { $ref: "#/components/schemas/RoleDataSourceResource" }
+          }
+        },
+        additionalProperties: true
+      },
+      DataSourceRole: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Optional existing role-data-source permission record id." },
+          roleName: { type: "string", description: "Role name." },
+          dataSourceKey: { type: "string", description: "Data source key, usually `main`." },
+          strategy: {
+            allOf: [{ $ref: "#/components/schemas/RoleStrategy" }],
+            description: "Global table actions for this role in the data source."
+          }
+        },
+        additionalProperties: true
+      },
+      RoleCollectionPermissionRow: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "Resource type, usually `collection`." },
+          name: { type: "string", description: "Collection name." },
+          collectionName: { type: "string", description: "Collection name." },
+          title: { type: "string", description: "Collection title." },
+          roleName: { type: "string", description: "Role name." },
+          usingConfig: {
+            type: "string",
+            enum: ["resourceAction", "strategy"],
+            description: "`strategy` means the collection uses global permissions. `resourceAction` means it has collection-level independent permissions."
           },
-          createdAt: {
+          exists: { type: "boolean", description: "Whether a dedicated resource config exists." }
+        }
+      },
+      RoleResourceScope: {
+        type: "object",
+        properties: {
+          id: { type: "integer", description: "Scope primary key." },
+          key: { type: "string", description: "Scope key such as `all` or `own`." },
+          dataSourceKey: {
             type: "string",
-            format: "date-time",
-            description: "\u521B\u5EFA\u65F6\u95F4"
+            nullable: true,
+            description: "Optional data source key, for example `main`."
+          },
+          name: { type: "string", description: "Scope display name." },
+          resourceName: { type: "string", nullable: true, description: "Optional resource binding." },
+          scope: {
+            type: "object",
+            additionalProperties: true,
+            description: "JSON filter object used as the ACL scope condition."
+          }
+        },
+        additionalProperties: true
+      },
+      RoleResourceScopeWrite: {
+        type: "object",
+        properties: {
+          id: { type: "integer", description: "Optional scope primary key, commonly present in update payloads." },
+          dataSourceKey: { type: "string", nullable: true, description: "Optional data source key." },
+          resourceName: { type: "string", nullable: true, description: "Optional bound resource name." },
+          name: { type: "string", description: "Scope display name." },
+          scope: {
+            type: "object",
+            additionalProperties: true,
+            description: "Row filter JSON."
+          }
+        },
+        required: ["name", "scope"],
+        additionalProperties: true
+      },
+      RoleResourceAction: {
+        type: "object",
+        properties: {
+          id: {
+            type: "integer",
+            description: "Optional action record id, commonly present in update payloads."
           },
-          updatedAt: {
+          name: {
             type: "string",
-            format: "date-time",
-            description: "\u66F4\u65B0\u65F6\u95F4"
+            description: "ACL action name, for example `view`, `create`, `update`, `destroy`, or a scoped variant."
+          },
+          fields: {
+            type: "array",
+            items: { type: "string" },
+            description: "Allowed field names for this action when field-level configuration is supported."
+          },
+          scopeId: {
+            type: "integer",
+            nullable: true,
+            description: "Optional bound scope id. Use `null` to clear the scope."
+          },
+          scope: {
+            allOf: [{ $ref: "#/components/schemas/RoleResourceScope" }],
+            nullable: true,
+            description: "Optional row-permission scope for this action."
+          }
+        },
+        required: ["name"],
+        additionalProperties: true
+      },
+      RoleDataSourceResourceWrite: {
+        type: "object",
+        description: "Collection-level independent permission config inside a data source.",
+        properties: {
+          id: {
+            type: "integer",
+            description: "Optional resource permission record id, commonly present in update payloads."
+          },
+          name: { type: "string", description: "Resource name, typically the collection name." },
+          dataSourceKey: { type: "string", description: "Data source key, usually `main`." },
+          roleName: { type: "string", description: "Optional role name echoed by the client in update payloads." },
+          usingActionsConfig: {
+            type: "boolean",
+            description: "Whether this collection uses independent actions instead of only the global strategy."
+          },
+          actions: {
+            type: "array",
+            items: { $ref: "#/components/schemas/RoleResourceAction" },
+            description: "Independent action configs for this collection."
           }
+        },
+        required: ["name", "dataSourceKey"],
+        additionalProperties: true
+      },
+      RoleDataSourceResource: {
+        allOf: [{ $ref: "#/components/schemas/RoleDataSourceResourceWrite" }],
+        properties: {
+          id: { type: "integer" },
+          roleName: { type: "string" }
         }
+      },
+      AvailableAction: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Action name." },
+          displayName: { type: "string", description: "Localized display name." },
+          allowConfigureFields: {
+            type: "boolean",
+            description: "Whether field-level permission config is supported for this action."
+          },
+          onNewRecord: {
+            type: "boolean",
+            description: "Whether the action applies to new records instead of existing records."
+          },
+          type: {
+            type: "string",
+            description: "Action category such as `new-data` or `old-data`."
+          },
+          aliases: {
+            type: "array",
+            items: { type: "string" },
+            description: "Action aliases resolved by ACL."
+          }
+        },
+        additionalProperties: true
       }
     }
   }