labull-framework 3.0.0__tar.gz → 3.0.1__tar.gz

{labull_framework-3.0.0/labull_framework.egg-info → labull_framework-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 3.0.0
+Version: 3.0.1
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/admin.py

@@ -23,7 +23,7 @@ class UserAdmin(admin.ModelAdmin):
 
     ⚠️ `username` 装的是 Authing 的 `sub`（登录时同步进来的），所以它**只读** ——
     改它等于把这一行与那个身份切开。
-    🔴 **"是不是平台管理员" = 有没有 `labull_framework.edit_magic_block`**（`permissions.is_admin()`）——
+    🔴 **"能不能编辑块" = 有没有 `labull_framework.edit_magic_block`**（`permissions.EDIT_PERMISSION`）——
     直接给在这个人身上、或者他所在的某个权限包里都算。这里不摆 `is_staff`：
     那一列只留给 Django 自己的 `/admin`，平台不读它。
     🔴 `groups` / `user_permissions` 两栏就是全部授权入口（组是权限包，权限码才是契约）。

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/auth/bootstrap.py

@@ -4,10 +4,10 @@
    （`edit_magic_block` 所在的权限包）对一遍 —— 名单里的人加进那个组，
    **名单之外的（以及没有工号的）一律摘掉**。于是"某人离职 / 不该再当管理员"这件事只需要从 `.env`
    里删掉一个工号 + 重启，不必记得去点。
-🔴 "是不是管理员"的唯一判据是 **`has_perm('labull_framework.edit_magic_block')`**
-   （`permissions.is_admin()`）—— **不是**组名、**不是** Django 的 `is_staff`（那一列只留给
-   Django 自己的 `/admin`）。这里之所以要找一个"组"，只是因为**写**的时候要有个落点；
-   找法按**权限**找（`permissions.admin_group()`），所以项目把那个组改名也不影响这份名单。
+🔴 "算不算管理员"的唯一判据是 **有没有 `labull_framework.edit_magic_block` 权限**
+   （`EDIT_PERMISSION in permissions_of(user)`）—— **不是**组名、**不是** Django 的 `is_staff`
+   （那一列只留给 Django 自己的 `/admin`）。这里之所以要找一个"组"，只是因为**写**的时候要有个落点；
+   找法按**权限**找（`permissions.group_holding(EDIT_PERMISSION)`），所以项目把那个组改名也不影响这份名单。
 🔴 **没配 / 是空 ⇒ 把所有人的管理员权限摘掉**（"没配"的语义就是"管理员一个都没有"）。
    ⚠️ 这是刻意选的 **fail-closed**：`.env` 少写一行、部署时忘了带这个变量，后果是**一个管理员都没有**
       —— 而不是"上一个被删掉的人悄悄留着权限"。要救回来：把那一行补回去重启。
@@ -24,7 +24,7 @@ import logging
 
 from ..env import read_env
 from ..models import User
-from ..permissions import ADMIN_PERMISSION, admin_group
+from ..permissions import EDIT_PERMISSION, group_holding
 
 logger = logging.getLogger(__name__)
 
@@ -71,11 +71,11 @@ def sync_admin_work_ids() -> int:
             'BOOTSTRAP_ADMIN_WORK_IDS=<工号>[,<工号>…]。'
         )
 
-    group = admin_group()
+    group = group_holding(EDIT_PERMISSION)
     if group is None:
         # 迁移会建"平台管理员"那个权限包；走到这里说明库还没迁移（或权限行还没建出来），
         # 不在启动路径上制造第二次失败 —— 下一次启动/迁移之后它就有了。
-        logger.error('还没有装 %s 的组（权限包）：跳过管理员名单同步', ADMIN_PERMISSION)
+        logger.error('还没有装 %s 的组（权限包）：跳过管理员名单同步', EDIT_PERMISSION)
         return 0
 
     try:

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/auth/views.py

@@ -133,19 +133,16 @@ def user_to_dict(user) -> dict:
        而模型是 `snake_case` ⇒ 两种形状之间的转换只该有**这一处**。
     ⚠️ `work_id` 可空就原样回 `None`，不兜成空串（空串会被当成"有个空工号"）。
     ⚠️ 时间只有一处实现（`jsonio.iso_utc`）：别再写第二份 `isoformat().replace(…)`。
-    🔴 `isAdmin` = **有没有 `labull_framework.edit_magic_block`**（`permissions.is_admin()`）——
-       不是 Django 的 `is_staff`、也不是某个组名。
-    🔴 `groups` / `permissions` 是 Django 原生的那一套：**权限是契约**（`app_label.codename`），
-       组只是权限包（`groups` 只给人看/排查，前端不要拿组名做判断）。
+    🔴 **没有 `isAdmin` 这类派生位**：能做什么只看 `permissions`（`app_label.codename`，
+       直接给的 + 经组给的）。前端要判"能不能编辑块"就查
+       `permissions.includes('labull_framework.edit_magic_block')`。
+    🔴 `groups` 只是权限包的名字（只给人看/排查），**不要**拿组名做判断。
     """
-    from ..permissions import is_admin
-
     return {
         'id': user.pk,
         'username': user.get_username(),
         'name': user.name,
         'workId': user.work_id,
-        'isAdmin': is_admin(user),
         'isSuperuser': user.is_superuser,
         'isActive': user.is_active,
         'groups': [group.name for group in user.groups.all()],

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/flow.py

@@ -24,9 +24,8 @@ from typing import Any, Callable, Iterable, Mapping
 
 from .magic_block.sdk import MagicBackendHTTPError
 from .permissions import (
-    ADMIN_PERMISSION,
+    EDIT_PERMISSION,
     PERMISSION_PATTERN,
-    is_admin,
     permissions_of,
     split_permission,
 )
@@ -615,8 +614,9 @@ class Flow:
 
 # ──────────────────────────── 规则串（语法与求值只有一处） ────────────────────────────
 #
-# 认人只认 **permission**（`app_label.codename`）：`is_admin()` / `permissions_of()` /
-# `ADMIN_PERMISSION` 都在 `labull_framework/permissions.py`（那一份是"谁能做什么"的唯一真源）。
+# 认人只认 **permission**（`app_label.codename`）：`permissions_of()` / `EDIT_PERMISSION` /
+# `split_permission()` 都在 `labull_framework/permissions.py`（那一份是"谁能做什么"的唯一真源）。
+# 🔴 没有 `is_admin()` / `has_perm()` 那类包装：判断一律写成 `<权限码> in permissions_of(user)`。
 
 
 def _permission_table() -> set[str] | None:
@@ -757,7 +757,7 @@ class Candidates:
     def allows(self, user: Any) -> bool:
         """这个人能不能办（`ctx.user` 或 Django 的 User 实例都行）。"""
         if self.admin_only:
-            return is_admin(user)
+            return EDIT_PERMISSION in permissions_of(user)
         if _user_id(user) in self.ids:
             return True
         return bool(permissions_of(user) & set(self.permissions))
@@ -932,10 +932,14 @@ def _visible_moves(flow: Flow, step: Step, row: Any) -> tuple[Move, ...]:
 def _is_admin_bypass(flow: Flow, user: Any) -> bool:
     """管理员旁路（`Flow.admin_bypass`）：只放行**候选人闸门**，不放行 `confirm_permissions`。
 
-    🔴 "管理员" = `has_perm('labull_framework.edit_magic_block')`（`permissions.is_admin()`），
+    🔴 "能旁路的人" = **有 `labull_framework.edit_magic_block` 权限的人**（`EDIT_PERMISSION`），
        不是 Django 的 `is_staff`、也不是某个组名。
     """
-    return bool(flow.admin_bypass and user is not None and is_admin(user))
+    return bool(
+        flow.admin_bypass
+        and user is not None
+        and EDIT_PERMISSION in permissions_of(user)
+    )
 
 
 def _is_confirm_permission(flow: Flow, move: Move, user: Any) -> bool:
@@ -1057,7 +1061,7 @@ def _ids_of(found: Candidates) -> list[str]:
     users = get_user_model().objects.all()
     wanted = set(found.permissions)
     if found.admin_only:
-        wanted.add(ADMIN_PERMISSION)
+        wanted.add(EDIT_PERMISSION)
     if wanted:
         query = Q()
         for permission in sorted(wanted):

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/magic_block/devkit.py

@@ -1565,7 +1565,7 @@ MagicSteps.renderBar(document.getElementById('steps'), payload)   // 步骤条
 
 ### 3. "权限"这个词在这个项目里指哪两类
 
-1. **平台级能力**：`ctx.user.is_admin`（平台管理员 = 有 `labull_framework.edit_magic_block`）、`ctx.user.permissions`（Django 的 `app_label.codename`，**这才是判据**）；`ctx.user.groups` 只是权限包的名字（只给人看）；后端路由可以声明 `@MagicBackendAPI(permission='app_label.codename')`。
+1. **平台级能力**：`ctx.user.permissions`（Django 的 `app_label.codename` —— **判据只有它**；要问"能不能编辑魔法块"就是 `'labull_framework.edit_magic_block' in ctx.user.permissions`，没有 `is_admin` 这种派生位）；`ctx.user.groups` 只是权限包的名字（只给人看）；后端路由可以声明 `@MagicBackendAPI(permission='app_label.codename')`。
 2. **Django 模型级 CRUD**（`auth_permission` 里那几组 `add_/change_/delete_/view_`）：**通常不是**需求说的那个"权限"。拿它当业务权限目录 = **越界**（见规矩 1）。
 
 ### 4. 开工前先读四样（**3 分钟，省几小时**）

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/magic_block/dispatch.py

@@ -134,15 +134,12 @@ def user_of(user: Any) -> BlockUser:
     🔴 匿名用户也映射得出来：块里的判据不用先判空。
     """
     if user is None or not getattr(user, 'is_authenticated', False):
-        return BlockUser(id='', username='', work_id='', name='', is_admin=False)
-    from ..permissions import is_admin
-
+        return BlockUser(id='', username='', work_id='', name='')
     return BlockUser(
         id=str(user.pk or ''),
         username=str(getattr(user, 'get_username', lambda: '')() or ''),
         work_id=str(getattr(user, 'work_id', '') or ''),
         name=str(getattr(user, 'name', '') or ''),
-        is_admin=is_admin(user),
         groups=_names(user.groups.values_list('name', flat=True)),
         permissions=_names(sorted(user.get_all_permissions())),
     )

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/magic_block/sdk.py

@@ -309,7 +309,8 @@ class BlockUser:
     🔴 `groups` / `permissions` 给的是**名字**（组名 / 权限 `app_label.codename`），不是 Django 对象：
        块里判权限用 `'app.codename' in ctx.user.permissions` 就够，不必碰 ORM。
     🔴 **权限才是契约，组只是权限包**：判"能不能做"永远看 `permissions`，**不要**看 `groups`
-       里的组名（组名只是标签，项目随时可能改名）。
+       里的组名（组名只是标签，项目随时可能改名）。要问"这个人能不能编辑块"就是
+       `'labull_framework.edit_magic_block' in ctx.user.permissions` —— 没有 `is_admin` 这种派生位。
     """
 
     #: 本地用户主键（Django 的 `pk`）。
@@ -320,10 +321,6 @@ class BlockUser:
     work_id: str
     #: 显示名（拿不到就是空串 —— 不编造）。
     name: str
-    #: **平台管理员** = `has_perm('labull_framework.edit_magic_block')`（直接给的 / 经组给的都算）。
-    #: 🔴 它**不是** Django 的 `is_staff`（那一列只留给 Django 自己的 `/admin`），
-    #:    也**不是**某个组名（组只是权限包）。
-    is_admin: bool
     #: 所在组的名字（只给人看 / 排查；**不要**拿组名当判据）。
     groups: tuple[str, ...] = ()
     #: 直接权限 + 组权限的 codename（`app_label.codename` 形式）。

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/magic_block/views.py

@@ -1,8 +1,9 @@
 """
 `/magic-blocks/*` 与 `/bx/*` 的全部视图（路由由 `urls.py` 按函数名指过来）。
 
-🔴 权限用**平台管理员**（`permissions.is_admin(user)` = `has_perm('labull_framework.edit_magic_block')`；
-   **不是** Django 的 `is_staff`、也不是某个组名）：写口与管理员读口要管理员（**自己写 `admin_only`**：
+🔴 权限用**权限码**（`permissions.EDIT_PERMISSION` = `labull_framework.edit_magic_block`，
+   **写死在框架里**；**不是** Django 的 `is_staff`、也不是某个组名）：写口与管理员读口都要求
+   `EDIT_PERMISSION in permissions_of(user)`（**自己写 `edit_only`**：
    `@staff_member_required` 对未登录用户会 302 到 admin 登录页，而这里要的是 401 + JSON）；
    `status` 那条口已经没了：任何登录用户能读的**只有 `render` 一条**，而且**永远不许**改成回整行 / 回全量 `files`。
 🔴 所有回话一律走 `jsonio`（一处出口：编码政策与错误形状都在那里）。
@@ -33,24 +34,25 @@ from .service import (
 )
 
 
-def admin_only(view: Callable[..., HttpResponse]) -> Callable[..., HttpResponse]:
-    """管理员守卫：没登录 ⇒ **401 + JSON**；登录了但不是管理员 ⇒ **403 + JSON**。
+def edit_only(view: Callable[..., HttpResponse]) -> Callable[..., HttpResponse]:
+    """编辑守卫（抽屉 / 控制台那几口）：没登录 ⇒ **401 + JSON**；登录了但没有编辑权限 ⇒ **403 + JSON**。
 
-    🔴 "管理员" = **有没有 `labull_framework.edit_magic_block`**（直接给的 / 经权限包给的都算）——
-       不是 Django 的 `is_staff`、也不是某个组名。
+    🔴 判据就一句：**`labull_framework.edit_magic_block in permissions_of(user)`**
+       （直接给的 / 经权限包给的都算）—— 这个码**写死在框架里**（`permissions.EDIT_PERMISSION`），
+       它就是"能不能编辑魔法块"那一档；不是 Django 的 `is_staff`、也不是某个组名。
     🔴 两条判据分开报：一个是"你是谁"，一个是"你能不能" —— 合成一条会让前端不知道该去登录还是找管理员。
     🔴 **不返回 302**：这几条是接口，前端要看状态码分支（302 会被 `fetch` 当成功跟着跳，最后拿到一页 HTML）。
     """
     from ..jsonio import no_identity
-    from ..permissions import is_admin
+    from ..permissions import EDIT_PERMISSION, permissions_of
 
     @wraps(view)
     def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
         user = getattr(request, 'user', None)
         if user is None or not getattr(user, 'is_authenticated', False):
             return no_identity()
-        if not is_admin(user):
-            return problem('这条接口只给管理员（需要 labull_framework.edit_magic_block 权限）', 403)
+        if EDIT_PERMISSION not in permissions_of(user):
+            return problem('这条接口只给能编辑魔法块的人（需要 labull_framework.edit_magic_block 权限）', 403)
         return view(request, *args, **kwargs)
 
     return wrapper
@@ -164,7 +166,7 @@ def _row_view(row: Any) -> dict:
 # ──────────────────────────── 管理员读口 ────────────────────────────
 
 
-@admin_only
+@edit_only
 def index_view(request: HttpRequest) -> HttpResponse:
     """`GET /magic-blocks/index` —— 控制台用的块索引（**不带文件正文**）。
 
@@ -186,7 +188,7 @@ def index_view(request: HttpRequest) -> HttpResponse:
     })
 
 
-@admin_only
+@edit_only
 def list_view(request: HttpRequest) -> HttpResponse:
     """`/magic-blocks` —— **GET 列全部块**（带正文，管理员控制台用）；**POST 保存一个块**。
 
@@ -224,7 +226,7 @@ def list_view(request: HttpRequest) -> HttpResponse:
     return _json([_row_view(row) for row in rows])
 
 
-@admin_only
+@edit_only
 def tags_view(request: HttpRequest, block_id: str) -> HttpResponse:
     """`/magic-blocks/<id>/tags` —— **只改标签**（`PUT`/`POST`），别的一律不碰。
 
@@ -248,7 +250,7 @@ def tags_view(request: HttpRequest, block_id: str) -> HttpResponse:
     return _json(_row_view(row))
 
 
-@admin_only
+@edit_only
 def detail_field_view(request: HttpRequest, block_id: str) -> HttpResponse:
     """`/magic-blocks/<id>/detail` —— **只改详情介绍**（`PUT`/`POST`），别的一律不碰。
 
@@ -275,7 +277,7 @@ def detail_field_view(request: HttpRequest, block_id: str) -> HttpResponse:
     return _json(_row_view(row))
 
 
-@admin_only
+@edit_only
 def versions_view(request: HttpRequest, block_id: str, number: str | None = None) -> HttpResponse:
     """`/magic-blocks/<id>/versions[/<number>]` —— 版本史的读、切、删、下。
 
@@ -372,7 +374,7 @@ def _zip_response(block_id: str, number: int, files: dict[str, str]) -> HttpResp
     return response
 
 
-@admin_only
+@edit_only
 def detail_view(request: HttpRequest, block_id: str) -> HttpResponse:
     """`GET /magic-blocks/<id>` —— 一行（没有就是 `null`，不是 404）。
 
@@ -433,7 +435,7 @@ def render_view(request: HttpRequest) -> HttpResponse:
 # ──────────────────────────── 写口 ────────────────────────────
 
 
-@admin_only
+@edit_only
 def rules_view(request: HttpRequest) -> HttpResponse:
     """`GET /magic-blocks/rules` —— **读回改动时要照的扫描规则**（认哪些扩展名 / 跳过哪些目录 / 几层到顶）。
 
@@ -450,7 +452,7 @@ def rules_view(request: HttpRequest) -> HttpResponse:
     return _json({'rules': scan_rules()})
 
 
-@admin_only
+@edit_only
 def export_view(request: HttpRequest) -> HttpResponse:
     """`POST /magic-blocks/export` —— **magic block export**：把库里的块算成**一整个开发包**。
 
@@ -492,7 +494,7 @@ def export_view(request: HttpRequest) -> HttpResponse:
     return _json(export_package(blocks, framework_only=body.get('framework') is True))
 
 
-@admin_only
+@edit_only
 def import_view(request: HttpRequest) -> HttpResponse:
     """`POST /magic-blocks/import` —— 把改好的目录**读回库**（一个块失败只报它自己）。
 
@@ -518,7 +520,7 @@ def import_view(request: HttpRequest) -> HttpResponse:
     return _json(write_dir(items, actor=str(body.get('updatedBy') or '')))
 
 
-@admin_only
+@edit_only
 def read_view(request: HttpRequest) -> HttpResponse:
     """`POST /magic-blocks/read` —— 读一个目录，与库里的块逐块对比（**只读，不写库**）。
 
@@ -634,7 +636,7 @@ def _read_stream(body: dict) -> HttpResponse:
     return response
 
 
-@admin_only
+@edit_only
 def check_view(request: HttpRequest) -> HttpResponse:
     """`POST /magic-blocks/check` —— 重新体检（默认全量，也可以点名几块），然后**统一写库**。
 

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/models.py

@@ -15,10 +15,11 @@ class User(AbstractUser):
     `AbstractUser` 自带 `username` 的 unique 约束，所以"同一身份两行"在库这一层就不可能发生。
     ⚠️ 没有本地口令：登录只走 OIDC，口令列由 `set_unusable_password()` 堵死。
 
-    🔴 **"能做什么"只看 `Permission`**（`app_label.codename`）：`has_perm(...)` / `get_all_permissions()`。
+    🔴 **"能做什么"只看 `Permission`**（`app_label.codename`）：`permissions_of(user)` 是唯一读法，
+    判断写成 `'app.codename' in permissions_of(user)`（**没有** `is_admin()` / `has_perm()` 这类包装）。
     授权只走 Django 原生的 `groups` / `user_permissions`（它们继承自 `PermissionsMixin`），
     `Group` 只是把一组权限**打包**（组名是标签，代码不按组名判断任何事）。
-    "是不是平台管理员" = 有没有 `labull_framework.edit_magic_block`（见 `permissions.is_admin()`）——
+    "能不能编辑块" = 有没有 `labull_framework.edit_magic_block`（`permissions.EDIT_PERMISSION`，写死在框架里）——
     平台**不读也不写** Django 的 `is_staff`（那一列只留给 Django 自己的 `/admin`）。
     🔴 新用户**不自动进任何组**：那是项目的数据/策略（框架不装 `post_save`）。
     """

{labull_framework-3.0.0 → labull_framework-3.0.1}/labull_framework/permissions.py

@@ -1,13 +1,17 @@
 """平台权限的唯一真源：**`Permission`（`app_label.codename`）** —— 组只是权限包。
 
 🔴 3.0.0 起**没有**"项目角色表"了（`LabullRole` / `User.roles` / `roles.py` 全删）：
-   能做什么只看 `user.has_perm('app_label.codename')`（直接给的 + 经组给的，Django 已经算好了）。
-   `Group` 只把一组权限**打包**（方便加人）；**组名是标签**，代码里不许按组名判断身份 ——
-   "是不是管理员"也一样（判据是 `edit_magic_block` 这个权限，见 `is_admin()`）。
+   能做什么只看**这个人有哪些权限**（`permissions_of()`，直接给的 + 经组给的，Django 已经算好了）。
+   `Group` 只把一组权限**打包**（方便加人）；**组名是标签**，代码里不许按组名判断身份。
+🔴 **没有 `is_admin()` / `has_perm()` 这类"判断方法"**：框架里所有授权判断都写成
+   `<权限码> in permissions_of(user)` —— 一条判据、一个写法。你要问"这个人能不能编辑块"，
+   就是问"他有没有 `labull_framework.edit_magic_block`"。
+🔴 **`edit_magic_block` 这个码写死在框架里**（`EDIT_PERMISSION`）：它就是"能不能打开抽屉 /
+   控制台去编辑魔法块"的那一档（写口、管理台、`Flow.admin_bypass`、示例块的守卫都按它判）。
+   它是平台自己的契约，不改名、不配环境变量。
 🔴 框架**不装任何 `post_save` / `user_logged_in` 来给新用户加组**：新用户默认进哪个组是
    项目的数据/策略（示例项目给了一份可复制的实现：`backend/example/canvasdemo/signals.py`）。
-   这个模块只回答"这个人现在能做什么"。
-🔴 匿名 / 没有会话（`user is None`）一律 False：没有"没登录所以放行"这回事。
+   这个模块只回答"这个人现在有哪些权限"。
 """
 
 from __future__ import annotations
@@ -16,16 +20,12 @@ import re
 from typing import Any
 
 #: 平台自己的三个权限（与 `MagicBlock.Meta.permissions` **逐字同源**：那边是声明，这里是引用）。
-#: 🔴 只在这里写一次：`admin_only` / 启动名单 / 示例块的守卫全都引用这几个常量。
-ADMIN_PERMISSION = 'labull_framework.edit_magic_block'
+#: 🔴 只在这里写一次：`admin_only` 那个守卫 / 启动名单 / 示例块的守卫全都引用这几个常量。
+#: 🔴 `EDIT_PERMISSION` 是**写死**的：它就是"能不能编辑魔法块（抽屉 / 控制台）"那一档。
+EDIT_PERMISSION = 'labull_framework.edit_magic_block'
 MANAGE_USERS_PERMISSION = 'labull_framework.manage_users'
 VIEW_PERMISSION = 'labull_framework.view_magicblock'
 
-#: 框架迁移建的两个默认组 —— **只是标签**（代码拿它建组/写进迁移，判断永远走 permission）。
-#: 🔴 项目想改名就改：行为一个字都不变（没有任何判据读这两个名字）。
-PLATFORM_ADMIN_GROUP = '平台管理员'
-DEFAULT_GROUP = '普通用户'
-
 #: `app_label.codename` 的形状（`flow.py` 里 `permission:` 的码也用它 —— 一份判据两处用）。
 PERMISSION_PATTERN = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$')
 
@@ -43,10 +43,12 @@ def split_permission(text: Any) -> tuple[str, str]:
 
 
 def permissions_of(user: Any) -> set[str]:
-    """这个人**有效**的权限（`app_label.codename`：直接给的 ∪ 经组给的）。
+    """这个人**有效**的权限（`app_label.codename`：直接给的 ∪ 经组给的）—— 授权的唯一读法。
 
     🔴 两种"人"都认：Django 的 `User`（`get_all_permissions()`）与块里的 `ctx.user`
        （`BlockUser.permissions` 是现成的元组）—— 两处各写一份判据迟早会漂。
+    🔴 判断一律写成 `'app.codename' in permissions_of(user)`（没有 `is_admin()` / `has_perm()`
+       那种包装：多一层包装就多一处"两套解释"）。
     """
     if user is None:
         return set()
@@ -59,31 +61,14 @@ def permissions_of(user: Any) -> set[str]:
     return {str(item) for item in (getattr(user, 'permissions', None) or ())}
 
 
-def has_perm(user: Any, permission: str) -> bool:
-    """这个人有没有这个权限（`permission` 是 `app_label.codename`）。"""
-    return str(permission or '') in permissions_of(user)
-
-
-def is_admin(user: Any) -> bool:
-    """"是不是平台管理员" = 有没有 `edit_magic_block`。
-
-    🔴 **不是** Django 的 `is_staff`（那一列只留给 Django 自己的 `/admin`）、
-       **不是**某个组名（组名只是标签）。`ctx.user.is_admin` / 管理台写口 /
-       `Flow.admin_bypass` / `/auth/me.isAdmin` 全走这一处。
-    """
-    if user is None or not getattr(user, 'is_authenticated', True):
-        return False
-    return has_perm(user, ADMIN_PERMISSION)
-
-
-def admin_group() -> Any:
-    """**持有 `edit_magic_block` 的那个组**（启动时那份管理员名单加人的落点）。
+def group_holding(permission: str) -> Any:
+    """**持有这个权限的那个组**（启动时那份管理员名单加人的落点）。
 
-    🔴 按**权限**找、不按组名找：项目把"平台管理员"改名之后这份名单照样能用（组名只是标签）。
+    🔴 按**权限**找、不按组名找：项目把那个组改名之后这份名单照样能用（组名只是标签）。
     🔴 有多个组都持有它时取主键最小的那个（确定性）：名单只往**一个**组里加人。
     ⚠️ 表还没迁移 / 还没有那个组 ⇒ `None`：调用方静默跳过，别在启动路径上抛。
     """
-    app_label, codename = split_permission(ADMIN_PERMISSION)
+    app_label, codename = split_permission(permission)
     if not app_label:
         return None
     try:

{labull_framework-3.0.0 → labull_framework-3.0.1/labull_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 3.0.0
+Version: 3.0.1
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-3.0.0 → labull_framework-3.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "labull-framework"
-version = "3.0.0"
+version = "3.0.1"
 description = "Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks"
 readme = "README-pypi.md"
 requires-python = ">=3.10"