labull-framework 3.0.3__tar.gz → 3.0.4__tar.gz

{labull_framework-3.0.3/labull_framework.egg-info → labull_framework-3.0.4}/PKG-INFO

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

labull_framework-3.0.4/labull_framework/access.py

@@ -0,0 +1,479 @@
+"""权限码与权限包（组）的**声明 → 落库**那一半 —— 声明住在环境变量里。
+
+两个变量（格式就是契约，改它要连文档 / 示例 / 判据一起改）：
+
+    LABULL_PERMISSIONS=订单.models=approve:可以审批订单,close:可以关单;…
+                       └ 模型（app_label.Model）┘ └ codename:中文名 ┘
+
+    LABULL_GROUPS=财务=orders.approve,orders.close;出纳=orders.close
+
+🔴 **为什么 permission 的条目里要写模型**：`Permission` 的行主键是
+   `(content_type, codename)`，而 content_type 只能从一个**真实模型**拿到；
+   环境变量里只有 `app_label.codename` 的话，要么造一个伪模型（admin 里会多一行幽灵，
+   `remove_stale_contenttypes` 还会把它当垃圾清掉），要么就没有 content_type。
+   写模型名是最小的一处额外信息，换来的是 content_type 正确、与 `Meta.permissions` 同一行。
+🔴 权限码本身是 `app_label.codename`（与 `flow.py` 的 `permission:`、`has_perm()` 同一份口径）：
+   模型那一段只用来定位 content_type，**不进码**。
+🔴 同步**只增不删**：少一个组 / 少一个权限就"从库里删掉"是不做的 ——
+   删组会级联掉 `auth_user_groups` 里人的授权，那是人手动配的数据，不是派生值。
+   要删只能人自己在库里删（这是用户明确要的语义）。
+🔴 `sync()` **永不抛**：它是启动路径上的一件事（与 `auth/bootstrap.py` 同一个模式），
+   库连不上 / 表还没迁移都只该进日志与报告。
+🔴 组名只是**标签**：代码里任何判据都不许读组名（判权永远看 permission）。
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from .env import read_env
+from .permissions import PERMISSION_PATTERN
+
+logger = logging.getLogger(__name__)
+
+#: 权限声明（`app_label.Model=codename:中文名[,…]`；多个模型用 `;` 分隔）。
+PERMISSIONS_ENV = 'LABULL_PERMISSIONS'
+
+#: 权限包（组）声明（`组名=app_label.codename[,…]`；多个包用 `;` 分隔）。
+GROUPS_ENV = 'LABULL_GROUPS'
+
+#: 一个标识符（app_label / 模型名 / codename 共用这一份判据）。
+_IDENT = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
+
+#: Django `Permission.codename` / `Group.name` 的上限（照抄模型那两列，抄错就会在写库时炸）。
+CODENAME_MAX = 100
+NAME_MAX = 255
+GROUP_NAME_MAX = 150
+
+
+class AccessError(ValueError):
+    """声明格式不对 —— 报文是中文原话，直接给人看（不走 `%` 模板）。"""
+
+
+@dataclass(frozen=True)
+class PermissionSpec:
+    """一条权限声明：`app_label.Model=codename:中文名`。"""
+
+    app_label: str
+    model: str
+    codename: str
+    name: str
+
+    @property
+    def code(self) -> str:
+        """它对外暴露的那个码（`app_label.codename`）—— 与 `Meta.permissions` / `flow` 同一份。"""
+        return f'{self.app_label}.{self.codename}'
+
+
+@dataclass(frozen=True)
+class GroupSpec:
+    """一个权限包：组名（只是标签）+ 它打包的那几个权限码。"""
+
+    name: str
+    permissions: tuple[str, ...] = ()
+
+
+@dataclass
+class Report:
+    """一次同步的结论（命令打印它、启动日志挑着打；**空报告 = 什么都没发生**）。"""
+
+    errors: list[str] = field(default_factory=list)
+    created_permissions: list[str] = field(default_factory=list)
+    permission_name_differs: list[str] = field(default_factory=list)
+    missing_models: list[str] = field(default_factory=list)
+    created_groups: list[str] = field(default_factory=list)
+    added: list[str] = field(default_factory=list)
+    missing: list[str] = field(default_factory=list)
+    dry_run: bool = False
+
+    def changed(self) -> bool:
+        return bool(
+            self.created_permissions or self.created_groups or self.added or self.missing
+            or self.missing_models or self.permission_name_differs or self.errors
+        )
+
+    def lines(self, *, verbose: bool = False) -> list[str]:
+        """报告 → 中文逐行（命令与启动日志共用这一份，别在调用点各拼一套）。
+
+        :param verbose: 连"名字不一致"这种**每次启动都会出现**的偏差也打（只给命令用；
+            启动日志打它等于每次开机刷一行，久了就没人看了）。
+        """
+        prefix = '（dry-run，没有写库）' if self.dry_run else ''
+        out: list[str] = []
+        for error in self.errors:
+            out.append(f'✗ {error}')
+        for code in self.created_permissions:
+            out.append(f'{prefix}新建权限 {code}')
+        if verbose:
+            for code in self.permission_name_differs:
+                out.append(f'{prefix}权限 {code} 已有行但中文名与声明不一致（**不改**：删改只能人来）')
+        for code in self.missing_models:
+            out.append(f'{prefix}✗ 声明里的模型不存在：{code}（权限行建不了）')
+        for name in self.created_groups:
+            out.append(f'{prefix}新建权限包 {name}')
+        for item in self.added:
+            out.append(f'{prefix}把 {item} 放进权限包')
+        for item in self.missing:
+            out.append(f'{prefix}✗ 权限包要的码不存在：{item}（先在模型 Meta.permissions / '
+                       f'{PERMISSIONS_ENV} 里声明，再 migrate）')
+        return out
+
+
+def _split(raw: str) -> list[str]:
+    """按 `;` 切条目（空条目忽略 —— 结尾多一个 `;` 是手滑，不是错误）。"""
+    return [item.strip() for item in str(raw or '').split(';') if item.strip()]
+
+
+def _split_codes(raw: str) -> list[str]:
+    """按 `,` 切权限码（空段**报错**：`a,,b` 多半是手滑，跳过会让一个码悄悄没进包）。"""
+    items = [item.strip() for item in str(raw or '').split(',')]
+    if any(not item for item in items):
+        raise AccessError(f'权限码列表里有空段（{raw!r}）—— 用逗号分隔，别留空项')
+    return items
+
+
+def parse_permissions(raw: str) -> tuple[PermissionSpec, ...]:
+    """`LABULL_PERMISSIONS` 的值 → 声明（格式不对抛 `AccessError`，中文原话）。"""
+    specs: list[PermissionSpec] = []
+    seen: set[str] = set()
+    for entry in _split(raw):
+        if '=' not in entry:
+            raise AccessError(
+                f'`{PERMISSIONS_ENV}` 的条目 {entry!r} 不是 `app_label.Model=codename:中文名`'
+                f'（少了那个 `=`）'
+            )
+        target, codes = entry.split('=', 1)
+        target = target.strip()
+        model_parts = target.split('.')
+        if len(model_parts) != 2 or not all(_IDENT.match(part) for part in model_parts):
+            raise AccessError(
+                f'`{PERMISSIONS_ENV}` 里的 {target!r} 不是 `app_label.Model` 的形状 —— '
+                f'要写**真实的模型**（权限行必须挂在一个 content_type 上），例如 '
+                f'`canvasdemo.Reimbursement`'
+            )
+        app_label, model = model_parts
+        for item in _split_codes(codes):
+            if ':' not in item:
+                raise AccessError(
+                    f'`{PERMISSIONS_ENV}` 里 {target} 的 {item!r} 少了中文名 —— '
+                    f'写法是 `codename:中文名`（管理员在组里看到的就是它）'
+                )
+            codename, name = item.split(':', 1)
+            codename, name = codename.strip(), name.strip()
+            if not _IDENT.match(codename) or len(codename) > CODENAME_MAX:
+                raise AccessError(
+                    f'`{PERMISSIONS_ENV}` 里的 codename {codename!r} 不是标识符'
+                    f'（字母/数字/下划线，≤{CODENAME_MAX}）'
+                )
+            if not name or len(name) > NAME_MAX:
+                raise AccessError(
+                    f'`{PERMISSIONS_ENV}` 里 {target}.{codename} 的中文名要写、且 ≤{NAME_MAX} 字'
+                )
+            code = f'{app_label}.{codename}'
+            if code in seen:
+                raise AccessError(
+                    f'`{PERMISSIONS_ENV}` 里权限码 {code} 声明了两次（同一个码只能出现一次）'
+                )
+            seen.add(code)
+            specs.append(PermissionSpec(app_label=app_label, model=model, codename=codename, name=name))
+    return tuple(specs)
+
+
+def parse_groups(raw: str) -> tuple[GroupSpec, ...]:
+    """`LABULL_GROUPS` 的值 → 声明（格式不对抛 `AccessError`，中文原话）。"""
+    specs: list[GroupSpec] = []
+    seen: set[str] = set()
+    for entry in _split(raw):
+        if '=' not in entry:
+            raise AccessError(
+                f'`{GROUPS_ENV}` 的条目 {entry!r} 不是 `组名=app_label.codename[,…]`（少了那个 `=`）'
+            )
+        name, codes = entry.split('=', 1)
+        name = name.strip()
+        if not name or len(name) > GROUP_NAME_MAX:
+            raise AccessError(
+                f'`{GROUPS_ENV}` 里的组名 {name!r} 要写、且 ≤{GROUP_NAME_MAX} 字'
+                f'（Django `Group.name` 的上限）'
+            )
+        if name in seen:
+            raise AccessError(
+                f'`{GROUPS_ENV}` 里权限包「{name}」声明了两次 —— 一个包的所有码写在同一个条目里'
+            )
+        seen.add(name)
+        codes = codes.strip()
+        if codes:
+            items = _split_codes(codes)
+            for code in items:
+                if not PERMISSION_PATTERN.match(code):
+                    raise AccessError(
+                        f'`{GROUPS_ENV}` 里「{name}」的 {code!r} 不是 `app_label.codename` 的形状 —— '
+                        f'环境变量里没有"当前 app"这个概念，要写全（例如 canvasdemo.review_reimbursement）'
+                    )
+            specs.append(GroupSpec(name=name, permissions=tuple(items)))
+        else:
+            # 空包是合法的（先建组、权限后补）；只是它一个码都不带。
+            specs.append(GroupSpec(name=name, permissions=()))
+    return tuple(specs)
+
+
+def declared_permissions() -> tuple[PermissionSpec, ...]:
+    """环境里声明的权限（格式错抛 `AccessError`；没配就是空）。"""
+    return parse_permissions(read_env(PERMISSIONS_ENV))
+
+
+def declared_groups() -> tuple[GroupSpec, ...]:
+    """环境里声明的权限包（格式错抛 `AccessError`；没配就是空）。"""
+    return parse_groups(read_env(GROUPS_ENV))
+
+
+def declared_permission_codes() -> set[str]:
+    """声明的权限码（**不碰数据库**；格式坏掉就当空 —— 判据那一层另有地方报它）。"""
+    try:
+        return {spec.code for spec in declared_permissions()}
+    except AccessError:
+        return set()
+
+
+def declaration_errors() -> list[str]:
+    """两个变量各自的格式问题（**不碰数据库**：系统检查用，`migrate` / `runserver` 就能看见）。"""
+    errors: list[str] = []
+    for env_name, parser in ((PERMISSIONS_ENV, parse_permissions), (GROUPS_ENV, parse_groups)):
+        raw = read_env(env_name)
+        if not raw:
+            continue
+        try:
+            parser(raw)
+        except AccessError as exc:
+            errors.append(str(exc))
+    return errors
+
+
+def known_group_names() -> set[str] | None:
+    """项目里"有哪些组"（声明的 ∪ 库里现有的）；取不到任何一处 ⇒ `None`（调用方跳过判据）。
+
+    🔴 为什么要并上库里的：组是**只增不删**的 —— 没在 `LABULL_GROUPS` 里声明的组
+       （管理员手建的）照样合法；把"没声明"当成"不存在"会把它误判掉。
+    """
+    names: set[str] = set()
+    known = False
+    if read_env(GROUPS_ENV).strip():
+        try:
+            names.update(spec.name for spec in declared_groups())
+            known = True
+        except AccessError:
+            pass
+    try:
+        from django.contrib.auth.models import Group
+
+        names.update(Group.objects.values_list('name', flat=True))
+        known = True
+    except Exception:  # noqa: BLE001 —— 没装 Django / 还没 migrate 都是正常情况
+        pass
+    return names if known else None
+
+
+def permissions_catalog() -> list[dict[str, str]]:
+    """项目里**声明过的业务权限**（按码排序）：`Meta.permissions` ∪ `.env` 的 `LABULL_PERMISSIONS`。
+
+    每条：`{'code', 'app_label', 'model', 'name', 'source'}`。
+
+    🔴 Django 自动生成的 `add_/change_/delete_/view_` **不在里面**：那是模型级 CRUD，
+       不是业务权限（拿它当业务权限目录是越界，见 `devkit` 的硬规矩第 1 条）。
+    🔴 不读数据库（导出不该依赖"这台机器上库迁移到哪一步了"）：真源是代码与环境变量。
+    """
+    rows: dict[str, dict[str, str]] = {}
+    try:
+        from django.apps import apps
+
+        for model in apps.get_models():
+            meta = model._meta
+            for codename, name in meta.permissions:
+                code = f'{meta.app_label}.{codename}'
+                rows.setdefault(code, {
+                    'code': code,
+                    'app_label': meta.app_label,
+                    'model': str(meta.object_name or meta.model_name),
+                    'name': str(name),
+                    'source': 'Meta.permissions',
+                })
+    except Exception:  # noqa: BLE001 —— 没有 Django 时就只剩环境变量那一半
+        pass
+    try:
+        for spec in declared_permissions():
+            # 环境变量那一份**覆盖**同名码的展示信息（它是显式声明的，人写的那一份为准）。
+            rows[spec.code] = {
+                'code': spec.code,
+                'app_label': spec.app_label,
+                'model': spec.model,
+                'name': spec.name,
+                'source': PERMISSIONS_ENV,
+            }
+    except AccessError:
+        pass
+    return [rows[code] for code in sorted(rows)]
+
+
+def groups_catalog() -> list[dict[str, Any]]:
+    """环境里声明的权限包：`[{'name': 组名, 'permissions': [码, …]}, …]`（没配就是空）。
+
+    🔴 只读**声明**、不读库：导出那一刻铺给块作者的是"这个项目声明了哪些包"；
+       库里手建的组不进来（它们是操作动作，不是契约）。
+    """
+    try:
+        return [
+            {'name': spec.name, 'permissions': list(spec.permissions)}
+            for spec in declared_groups()
+        ]
+    except AccessError:
+        return []
+
+
+def _model_class(app_label: str, model: str) -> Any:
+    """声明里那个模型（拿不到就 `None`）。"""
+    try:
+        from django.apps import apps
+
+        return apps.get_model(app_label, model)
+    except Exception:  # noqa: BLE001 —— 见调用处：报进 `missing_models`，不抛
+        return None
+
+
+def sync(*, dry_run: bool = False) -> Report:
+    """把声明同步进库（**只增不删、幂等、永不抛**）。回一份 `Report`。
+
+    🔴 顺序是契约：**先权限行、后组**（组要拿权限行去塞 M2M）。
+    🔴 库还没迁移 / 连不上 ⇒ 结论进 `errors`，不抛：这是启动路径上的一件事。
+    """
+    report = Report(dry_run=dry_run)
+    try:
+        permission_specs = declared_permissions()
+        group_specs = declared_groups()
+    except AccessError as exc:
+        report.errors.append(str(exc))
+        return report
+    if not permission_specs and not group_specs:
+        return report
+    try:
+        from django.contrib.auth.models import Group, Permission
+        from django.contrib.contenttypes.models import ContentType
+    except Exception as exc:  # noqa: BLE001 —— 没装 Django 时调用方本来就不该调它
+        report.errors.append(f'同步权限声明失败（{type(exc).__name__}: {exc}）')
+        return report
+
+    try:
+        # ── ① 权限行：先建出来（组要拿它去塞 M2M） ──
+        rows: dict[str, Any] = {}
+        #: dry-run 下"这一次会建出来"的那些码：组那一段要把它们当成"可用"，
+        #: 否则一次全新环境的 dry-run 会把每个码都报成 missing（那是假错）。
+        planned: set[str] = set()
+        for spec in permission_specs:
+            existing = Permission.objects.filter(
+                content_type__app_label=spec.app_label, codename=spec.codename,
+            ).first()
+            if existing is not None:
+                rows[spec.code] = existing
+                if existing.name != spec.name:
+                    report.permission_name_differs.append(spec.code)
+                continue
+            model_cls = _model_class(spec.app_label, spec.model)
+            if model_cls is None:
+                report.missing_models.append(f'{spec.app_label}.{spec.model}')
+                continue
+            if dry_run:
+                report.created_permissions.append(spec.code)
+                planned.add(spec.code)
+                continue
+            content_type = ContentType.objects.get_for_model(model_cls)
+            permission, _created = Permission.objects.get_or_create(
+                content_type=content_type, codename=spec.codename, defaults={'name': spec.name},
+            )
+            rows[spec.code] = permission
+            if _created:
+                report.created_permissions.append(spec.code)
+            elif permission.name != spec.name:
+                report.permission_name_differs.append(spec.code)
+
+        # ── ② 组：缺就建；权限只 add 缺的那些 ──
+        for spec in group_specs:
+            group = Group.objects.filter(name=spec.name).first()
+            if group is None:
+                if dry_run:
+                    report.created_groups.append(spec.name)
+                else:
+                    group, created = Group.objects.get_or_create(name=spec.name)
+                    if created:
+                        report.created_groups.append(spec.name)
+            held = set() if group is None else set(group.permissions.values_list('id', flat=True))
+            for code in spec.permissions:
+                permission = rows.get(code)
+                if permission is None and code in planned:
+                    # dry-run：这个码这一次会被建出来，组那一边的计划里就该有它。
+                    report.added.append(f'{spec.name} ← {code}')
+                    continue
+                if permission is None:
+                    app_label, _, codename = code.partition('.')
+                    permission = Permission.objects.filter(
+                        content_type__app_label=app_label, codename=codename,
+                    ).first()
+                if permission is None:
+                    report.missing.append(f'{spec.name} ← {code}')
+                    continue
+                if permission.id in held:
+                    continue
+                report.added.append(f'{spec.name} ← {code}')
+                if not dry_run and group is not None:
+                    group.permissions.add(permission)
+                    held.add(permission.id)
+    except Exception as exc:  # noqa: BLE001 —— 启动路径：失败只进报告与日志
+        report.errors.append(f'同步权限声明失败（{type(exc).__name__}: {exc}）')
+    return report
+
+
+def log_report(report: Report) -> None:
+    """把一份报告写进日志（启动路径用；空报告**一行都不打**）。"""
+    for line in report.lines():
+        logger.info(line)
+
+
+# ──────────────────────────── 两个触发点（与 `magic_block/health.py` 同一个模式） ────────────────────────────
+#
+# 🔴 `startup_once()`（wsgi.py 那一行）是**保证点**：部署总是先 `migrate` 再起服务，
+#    所以第一个请求进来之前组一定已经对过账。
+# 🔴 `post_migrate` 那一条**不是保证**，它是"`migrate` 之后顺手补一次"：
+#    `post_migrate` 按每个 AppConfig 各发一次，而接收器按**连接顺序**被调 ——
+#    `labull_framework` 若排在 `INSTALLED_APPS` 前面，它的接收器就比
+#    `django.contrib.auth` 的 `create_permissions` **先连上**，同一次发信号里先被调
+#    （全新库第一次发信号时 `auth_permission` 还是空表）。所以这里**不按 sender 过滤**：
+#    每次发信号都试一次，成功（没有缺码 / 没有格式错）就上进程内 latch。
+
+#: 那个接收器的 `dispatch_uid`（幂等：`ready()` 可能被跑两次）。
+_HOOK_ID = 'labull_framework.access'
+
+#: `post_migrate` 这一路"已经成功对过账"的进程内 latch。
+_SYNCED = False
+
+
+def install_hook() -> None:
+    """把"迁移之后对一次账"挂到 `post_migrate` 上（幂等；**不写 `sender=`**，理由见上）。"""
+    from django.db.models.signals import post_migrate
+
+    post_migrate.connect(_on_post_migrate, dispatch_uid=_HOOK_ID)
+
+
+def _on_post_migrate(sender: object, **kwargs: object) -> None:
+    """`post_migrate` 接收器：能对账就对上，对不上（权限行还没建）就等下一次发信号。"""
+    global _SYNCED
+    if _SYNCED:
+        return
+    try:
+        report = sync()
+        log_report(report)
+        if report.errors or report.missing_models or report.missing:
+            return
+    except Exception as exc:  # noqa: BLE001 —— 迁移路径上的失败不该带崩 `migrate`
+        logger.error('迁移之后同步权限声明失败（不影响迁移）：%s: %s', type(exc).__name__, exc)
+        return
+    _SYNCED = True

{labull_framework-3.0.3 → labull_framework-3.0.4}/labull_framework/apps.py

@@ -30,6 +30,11 @@ class LabullConfig(AppConfig):
     def ready(self) -> None:
         # 延迟 import：此刻 app 注册表已经就绪，但避免模块级 import 造成加载顺序问题。
         # 钩子是"库自己正常工作"的一部分（体检库里存着的块），**不是**对使用者项目的检查。
+        from . import access, checks  # noqa: F401 —— `checks` 的副作用是注册系统检查
         from .magic_block import health
 
         health.install_hook()
+        # 授权声明（LABULL_PERMISSIONS / LABULL_GROUPS）的"迁移之后对一次账"：
+        # 与体检那个钩子同一个模式（`post_migrate` + 进程内 latch），但**不按 sender 过滤**
+        # （理由见 access.py 顶上那一段"两个触发点"）。
+        access.install_hook()

labull_framework-3.0.4/labull_framework/checks.py

@@ -0,0 +1,25 @@
+"""平台自己的**系统检查**（`manage.py check` / `migrate` / `runserver` 都会跑它）。
+
+现在只有一条：`LABULL_PERMISSIONS` / `LABULL_GROUPS` 的**格式**。
+
+🔴 为什么要有它：那两个变量的格式是契约（`组名=app_label.codename` 之类），写错了
+   `access.sync()` 只会把一句错误放进日志 —— 而启动日志没人看。做成系统检查之后，
+   `migrate` / `runserver` 的输出里就会带一行 Warning，照它改就行。
+🔴 它**只判格式、不碰数据库**（系统检查跑在 `migrate` 之前，那时表还不存在）：
+   "声明了但库里没有这个码"那件事归 `manage.py labull_access --check`。
+"""
+
+from __future__ import annotations
+
+from django.core.checks import Warning, register
+
+
+@register()
+def access_declarations(app_configs=None, **kwargs) -> list[Warning]:
+    """`LABULL_PERMISSIONS` / `LABULL_GROUPS` 格式不对 ⇒ 各报一条 Warning（中文原话）。"""
+    from . import access
+
+    return [
+        Warning(text, id='labull.W001')
+        for text in access.declaration_errors()
+    ]

{labull_framework-3.0.3 → labull_framework-3.0.4}/labull_framework/env.py

@@ -158,7 +158,8 @@ ENV_ITEMS: tuple[EnvItem, ...] = (
     # ── 平台开关 ──
     EnvItem(
         name='BOOTSTRAP_ADMIN_WORK_IDS',
-        brief='管理员名单：启动时把这些人加进「平台管理员」权限包（`edit_magic_block` 所在的那个组），名单之外的一律摘掉（逗号分隔，上限 200；没配就是没有管理员）',
+        brief='管理员名单：启动时把这些人置为 **Django 的 `is_staff`**（"能不能编辑魔法块"就看这一列），'
+              '名单之外的一律摘掉（逗号分隔，上限 200；没配就是没有管理员）',
         hint='BOOTSTRAP_ADMIN_WORK_IDS=1001',
         group='平台开关',
     ),
@@ -223,6 +224,24 @@ ENV_ITEMS: tuple[EnvItem, ...] = (
         hint='LABULL_BLOCK_WORKERS=2',
         group='平台开关',
     ),
+    # ── 授权（权限码 / 权限包）：**声明在这里，落库由框架同步** ──
+    # 🔴 为什么是环境变量而不是迁移：迁移里的 `RunPython` 跑在 `create_permissions` **之前**，
+    #    要拿权限行去塞组就得自己再建一遍权限行（那是第二份真源）。这里只在启动时对一次账。
+    # 🔴 同步**只增不删**：要删组 / 删权限，只能人自己在库里删（删组会级联掉人的授权）。
+    EnvItem(
+        name='LABULL_PERMISSIONS',
+        brief='权限声明：`app_label.Model=codename:中文名[,codename:中文名…]`，多个模型用 `;` 分隔'
+              '（模型那一段只用来定位 content_type，对外暴露的码仍是 `app_label.codename`）',
+        hint='LABULL_PERMISSIONS=canvasdemo.Reimbursement=review_reimbursement:可以审批报销单',
+        group='授权（权限码 / 权限包）',
+    ),
+    EnvItem(
+        name='LABULL_GROUPS',
+        brief='权限包（组）声明：`组名=app_label.codename[,app_label.codename…]`，多个包用 `;` 分隔'
+              '（组名只是标签；启动时把组与它的权限同步进库，只增不删）',
+        hint='LABULL_GROUPS=财务=canvasdemo.review_reimbursement,canvasdemo.pay_reimbursement',
+        group='授权（权限码 / 权限包）',
+    ),
     # ── 块的配置面 ──
     EnvItem(
         name=f'{BLOCK_CONFIG_PREFIX}*',

{labull_framework-3.0.3 → labull_framework-3.0.4}/labull_framework/flow.py

@@ -23,7 +23,13 @@ from dataclasses import dataclass, field
 from typing import Any, Callable, Iterable, Mapping
 
 from .magic_block.sdk import MagicBackendHTTPError
-from .permissions import PERMISSION_PATTERN, permissions_of, split_permission
+from .permissions import (
+    PERMISSION_PATTERN,
+    permission_list_text,
+    permissions_of,
+    project_permissions,
+    split_permission,
+)
 
 # ──────────────────────────── 平台认的那些常量（唯一真源） ────────────────────────────
 
@@ -613,27 +619,16 @@ class Flow:
 def _permission_table() -> set[str] | None:
     """项目的 permission 清单（`app_label.codename`）；**读不到就回 `None`**。
 
-    🔴 `None` 的两种正常来源：块作者本地没有项目上下文 / 表还没迁移（`auth_permission` 还不存在）。
+    🔴 真源是 `permissions.project_permissions()`（**只有那一处**）：`LABULL_PERMISSIONS` 的声明
+       ∪ app registry 的 `Meta.permissions` ∪ `auth_permission` 现有的行。
+       也就是说：**不需要先 migrate** 就能判（`Meta.permissions` 是代码）；也算上环境变量里
+       声明、还没落库的那些码。
+    🔴 `None` 的两种正常来源：块作者本地没有项目上下文 / 三处都读不到。
        那时 D10 / D13 只判语法、不判白名单 —— 不许把"读不到"当成"一条都没有"
        （那会把一条干净的流程判成非法）。
     🔴 表在、但一条都没有 ⇒ 回**空集**（不是 `None`）：那是"项目确实还没声明任何权限"，该拒。
     """
-    try:
-        from django.contrib.auth.models import Permission
-
-        rows = Permission.objects.values_list('content_type__app_label', 'codename')
-        return {f'{app_label}.{codename}' for app_label, codename in rows}
-    except Exception:  # noqa: BLE001 —— 见 docstring：表还没迁移是正常情况
-        return None
-
-
-def _permission_list_text(table: Iterable[str], limit: int = 40) -> str:
-    """一句"当前项目有哪些 permission"（太长就截断：报文要能读，不能糊一屏）。"""
-    names = sorted(str(item) for item in table)
-    if not names:
-        return '（一条都没有）'
-    shown = ' / '.join(names[:limit])
-    return shown if len(names) <= limit else f'{shown} …（共 {len(names)} 个）'
+    return project_permissions()
 
 
 def _check_permissions(subject: str, codes: Iterable[str], table: set[str] | None) -> None:
@@ -646,12 +641,14 @@ def _check_permissions(subject: str, codes: Iterable[str], table: set[str] | Non
     if not table:
         raise FlowError(
             f'{subject} 用了 permission {" / ".join(unknown)} —— 本项目现在**一条 permission 都没有**。'
-            f'给模型的 `Meta.permissions` 里加一条（例如 (\'approve\', \'可以审批\')），migrate 之后'
-            f'就有 `<app_label>.approve` 这个码；flow.py 里只写 permission:<app_label>.approve。'
+            f'在模型的 `Meta.permissions` 里加一条（例如 (\'approve\', \'可以审批\')），'
+            f'或在 `.env` 的 LABULL_PERMISSIONS 里声明一条，之后就有 `<app_label>.approve` 这个码；'
+            f'flow.py 里只写 permission:<app_label>.approve。'
         )
     raise FlowError(
         f'{subject} 里有不认识的 permission {" / ".join(unknown)} —— 当前项目有的是 '
-        f'{_permission_list_text(table)}（在模型的 `Meta.permissions` 里声明，migrate 之后才有）'
+        f'{permission_list_text(table)}（在模型的 `Meta.permissions` 里声明，'
+        f'或在 `.env` 的 LABULL_PERMISSIONS 里声明）'
     )