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

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

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

labull_framework-3.0.5/labull_framework/access.py

@@ -0,0 +1,561 @@
+"""权限码与权限包（组）的**声明 → 落库**那一半 —— 声明住在项目里的一份 YAML 文件。
+
+默认位置：`<BASE_DIR>/labull-access.yaml`（可以用 `LABULL_ACCESS_FILE` 指到别的路径）。
+文件长这样（一份普通 YAML，**不是**环境变量里那种一行塞完的串）：
+
+```yaml
+# 权限（可选；模型 Meta.permissions 里已经声明过的不必重复）
+permissions:
+  canvasdemo.Reimbursement:
+    review_reimbursement: 可以审批报销单
+    pay_reimbursement: 可以对报销单付款
+
+# 权限包（组）：组名 → 权限码
+groups:
+  财务:
+    - canvasdemo.review_reimbursement
+    - canvasdemo.pay_reimbursement
+  出纳:
+    - canvasdemo.pay_reimbursement
+```
+
+🔴 **为什么 permissions 里要写模型**：`Permission` 的行主键是 `(content_type, codename)`，
+   而 content_type 只能从一个**真实模型**拿到。写模型名换来的是 content_type 正确、
+   与 `Meta.permissions` 指向同一行；对外暴露的码仍是 `app_label.codename`。
+🔴 **不引 PyYAML**：这个仓库不引第三方运行时依赖，所以这里只认上面这一种子集
+   （`键:` / `键: 值` / 缩进两格的映射或 `- 项` 列表），不认识的写法**当场报错**。
+🔴 同步**只增不删**：少一个组 / 少一个权限**不会**从库里删掉 —— 删组会级联掉
+   `auth_user_groups` 里人的授权，那是人手动配的数据。要删只能人自己在库里删。
+🔴 `sync()` **永不抛**：它是启动路径上的一件事（与 `auth/bootstrap.py` 同一个模式）。
+🔴 组名只是**标签**：代码里任何判据都不许读组名（判权永远看 permission）。
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .env import read_env
+from .permissions import PERMISSION_PATTERN
+
+logger = logging.getLogger(__name__)
+
+#: 声明文件的名字（默认落在项目的 `BASE_DIR` 下）。
+ACCESS_FILE_NAME = 'labull-access.yaml'
+
+#: 把声明文件指到别处（路径；相对路径按 `BASE_DIR` 解析）。
+ACCESS_FILE_ENV = 'LABULL_ACCESS_FILE'
+
+#: 一个标识符（app_label / 模型名 / codename 共用这一份判据）。
+_IDENT = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
+
+#: Django `Permission.codename` / `Permission.name` / `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(frozen=True)
+class Declaration:
+    """一份声明文件的全部内容（`permissions:` / `groups:` 都可以整块不写）。"""
+
+    permissions: tuple[PermissionSpec, ...] = ()
+    groups: tuple[GroupSpec, ...] = ()
+
+
+@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'{ACCESS_FILE_NAME} 的 permissions 里声明，再 migrate）')
+        return out
+
+
+# ──────────────────────────── 读那一份 YAML（只认这一种子集） ────────────────────────────
+
+
+def _strip_comment(line: str) -> str:
+    """去掉行尾注释（`#` 在引号里不算注释 —— 中文名里带 `#` 是合法的）。"""
+    quote = ''
+    for index, char in enumerate(line):
+        if quote:
+            if char == quote:
+                quote = ''
+        elif char in ('"', "'"):
+            quote = char
+        elif char == '#':
+            return line[:index]
+    return line
+
+
+def _value(text: str) -> str:
+    """一个标量值（去掉一对引号；`''` / `""` 是合法的空串）。"""
+    value = text.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+        return value[1:-1]
+    return value
+
+
+def _error(line_no: int, message: str) -> AccessError:
+    return AccessError(f'{ACCESS_FILE_NAME} 第 {line_no} 行：{message}')
+
+
+def parse_access(text: str) -> Declaration:
+    """把声明文件的正文读成 `Declaration`（格式不对抛 `AccessError`，带行号）。
+
+    只认这一种子集（**不引 YAML 库**）：
+
+    ```yaml
+    permissions:
+      app.Model:
+        codename: 中文名
+    groups:
+      组名:
+        - app_label.codename
+    ```
+    """
+    permissions: list[PermissionSpec] = []
+    groups: list[GroupSpec] = []
+    seen_codes: set[str] = set()
+    seen_groups: set[str] = set()
+    section = ''
+    model: tuple[str, str] | None = None       # (app_label, model)
+    group: str = ''                            # 当前正在收权限码的组名
+
+    for index, raw in enumerate(str(text or '').splitlines(), start=1):
+        line = _strip_comment(raw).rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip())
+        content = line.strip()
+
+        if indent == 0:
+            if not content.endswith(':'):
+                raise _error(index, f'顶层只许写 `permissions:` 或 `groups:`（读到 {content!r}）')
+            key = content[:-1].strip()
+            if key not in ('permissions', 'groups'):
+                raise _error(index, f'顶层不认识的键 `{key}`：只有 permissions / groups 两块')
+            section = key
+            model = None
+            group = ''
+            continue
+
+        if not section:
+            raise _error(index, '这一行缩进了，但上面还没有 `permissions:` / `groups:` 那一行')
+
+        if section == 'permissions':
+            if indent == 2:
+                target = content[:-1].strip() if content.endswith(':') else ''
+                parts = target.split('.')
+                if len(parts) != 2 or not all(_IDENT.match(part) for part in parts):
+                    raise _error(
+                        index,
+                        f'{content!r} 不是 `app_label.Model:` 的形状 —— 要写**真实的模型**'
+                        f'（权限行必须挂在一个 content_type 上），例如 `canvasdemo.Reimbursement:`',
+                    )
+                model = (parts[0], parts[1])
+                continue
+            if indent == 4:
+                if model is None:
+                    raise _error(index, '这一行上面少了 `app_label.Model:` 那一行')
+                if ':' not in content:
+                    raise _error(index, f'`{content}` 少了中文名（写法是 `codename: 中文名`）')
+                codename, name = content.split(':', 1)
+                codename, name = codename.strip(), _value(name)
+                if not _IDENT.match(codename) or len(codename) > CODENAME_MAX:
+                    raise _error(
+                        index,
+                        f'codename `{codename}` 不是标识符（字母/数字/下划线，≤{CODENAME_MAX}）',
+                    )
+                if not name or len(name) > NAME_MAX:
+                    raise _error(index, f'`{codename}` 的中文名要写、且 ≤{NAME_MAX} 字')
+                code = f'{model[0]}.{codename}'
+                if code in seen_codes:
+                    raise _error(index, f'权限码 `{code}` 写了两次（同一个码只能出现一次）')
+                seen_codes.add(code)
+                permissions.append(PermissionSpec(
+                    app_label=model[0], model=model[1], codename=codename, name=name,
+                ))
+                continue
+            raise _error(index, f'缩进不对（读到 {indent} 格）：permissions 下只许两格 / 四格')
+
+        # section == 'groups'
+        if indent == 2:
+            if not content.endswith(':'):
+                raise _error(index, f'{content!r} 不是 `组名:` 的形状（组名后面要冒号、值缩进在下面）')
+            name = content[:-1].strip()
+            if not name or len(name) > GROUP_NAME_MAX:
+                raise _error(index, f'组名要写、且 ≤{GROUP_NAME_MAX} 字（Django `Group.name` 的上限）')
+            if name in seen_groups:
+                raise _error(index, f'权限包「{name}」写了两次')
+            seen_groups.add(name)
+            group = name
+            groups.append(GroupSpec(name=name, permissions=()))
+            continue
+        if indent == 4:
+            if not group:
+                raise _error(index, '这一行上面少了 `组名:` 那一行')
+            if not content.startswith('- '):
+                raise _error(index, f'{content!r} 要写成 `- app_label.codename`（列表项）')
+            code = content[2:].strip()
+            if not PERMISSION_PATTERN.match(code):
+                raise _error(
+                    index,
+                    f'`{code}` 不是 `app_label.codename` 的形状 —— 要写全'
+                    f'（例如 canvasdemo.review_reimbursement）',
+                )
+            current = groups[-1]
+            groups[-1] = GroupSpec(name=current.name, permissions=(*current.permissions, code))
+            continue
+        raise _error(index, f'缩进不对（读到 {indent} 格）：groups 下只许两格 / 四格')
+
+    return Declaration(permissions=tuple(permissions), groups=tuple(groups))
+
+
+# ──────────────────────────── 文件在哪 ────────────────────────────
+
+
+def _base_dir() -> Path | None:
+    """项目的 `BASE_DIR`（没设就退回当前工作目录 —— `manage.py` 通常就在项目根跑）。"""
+    try:
+        from django.conf import settings
+
+        base = getattr(settings, 'BASE_DIR', None)
+        if base:
+            return Path(base)
+    except Exception:  # noqa: BLE001 —— 没配 Django 时退回 cwd
+        pass
+    try:
+        return Path.cwd()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def access_file() -> tuple[Path | None, bool]:
+    """声明文件在哪：`(路径, 是不是显式配的)`。
+
+    `LABULL_ACCESS_FILE` 配了就用它（相对路径按 `BASE_DIR` 解析）；没配就用
+    `<BASE_DIR>/labull-access.yaml`。取不到任何基准目录 ⇒ `(None, False)`。
+    """
+    raw = read_env(ACCESS_FILE_ENV).strip()
+    base = _base_dir()
+    if raw:
+        path = Path(raw)
+        if not path.is_absolute() and base is not None:
+            path = base / path
+        return path, True
+    if base is not None:
+        return base / ACCESS_FILE_NAME, False
+    return None, False
+
+
+def load() -> tuple[Declaration, list[str]]:
+    """读声明文件：`(声明, 错误清单)`。文件不在 ⇒ 空声明（默认位置）或一条错误（显式配的）。"""
+    path, explicit = access_file()
+    if path is None:
+        return Declaration(), []
+    if not path.is_file():
+        if explicit:
+            return Declaration(), [
+                f'{ACCESS_FILE_ENV} 指向 `{path}`，但那个文件不存在 —— 改对路径、或把这一项删掉'
+            ]
+        return Declaration(), []
+    try:
+        return parse_access(path.read_text(encoding='utf-8-sig')), []
+    except AccessError as exc:
+        return Declaration(), [str(exc)]
+    except Exception as exc:  # noqa: BLE001 —— 读文件失败也只进错误清单（启动路径不抛）
+        return Declaration(), [f'读不了 `{path}`：{type(exc).__name__}: {exc}']
+
+
+def declaration_errors() -> list[str]:
+    """声明文件的**格式**问题（不碰数据库：系统检查用，`migrate` / `runserver` 就能看见）。"""
+    return load()[1]
+
+
+def declared_permission_codes() -> set[str]:
+    """声明文件里的权限码（**不碰数据库**；读不出来就当空 —— 判据那一层另有地方报它）。"""
+    return {spec.code for spec in load()[0].permissions}
+
+
+def known_group_names() -> set[str] | None:
+    """项目里"有哪些组"（声明文件里的 ∪ 库里现有的）；取不到任何一处 ⇒ `None`（调用方跳过判据）。
+
+    🔴 为什么要并上库里的：组是**只增不删**的 —— 没在文件里声明的组（管理员手建的）照样合法；
+       把"没声明"当成"不存在"会把它误判掉。
+    """
+    declaration, errors = load()
+    names = {spec.name for spec in declaration.groups}
+    known = bool(names) or not errors
+    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` ∪ 声明文件的 `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
+    for spec in load()[0].permissions:
+        # 声明文件那一份**覆盖**同名码的展示信息（它是显式声明的，人写的那一份为准）。
+        rows[spec.code] = {
+            'code': spec.code,
+            'app_label': spec.app_label,
+            'model': spec.model,
+            'name': spec.name,
+            'source': ACCESS_FILE_NAME,
+        }
+    return [rows[code] for code in sorted(rows)]
+
+
+def groups_catalog() -> list[dict[str, Any]]:
+    """声明文件里的权限包：`[{'name': 组名, 'permissions': [码, …]}, …]`（没配就是空）。
+
+    🔴 只读**声明**、不读库：导出那一刻铺给块作者的是"这个项目声明了哪些包"；
+       库里手建的组不进来（它们是操作动作，不是契约）。
+    """
+    return [
+        {'name': spec.name, 'permissions': list(spec.permissions)}
+        for spec in load()[0].groups
+    ]
+
+
+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)
+    declaration, errors = load()
+    report.errors.extend(errors)
+    if errors:
+        return report
+    if not declaration.permissions and not declaration.groups:
+        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 declaration.permissions:
+            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 declaration.groups:
+            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.5}/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.5/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.5}/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,19 @@ ENV_ITEMS: tuple[EnvItem, ...] = (
         hint='LABULL_BLOCK_WORKERS=2',
         group='平台开关',
     ),
+    # ── 授权（权限码 / 权限包）：**声明在项目里的一份 YAML 文件**，落库由框架同步 ──
+    # 🔴 为什么不是迁移：迁移里的 `RunPython` 跑在 `create_permissions` **之前**，
+    #    要拿权限行去塞组就得自己再建一遍权限行（那是第二份真源）。这里只在启动时对一次账。
+    # 🔴 为什么不是环境变量：`group → 权限码` 是一张映射，塞进一行环境变量既难读、又容易写错
+    #    （见 `labull-access.yaml` 的写法）。
+    # 🔴 同步**只增不删**：要删组 / 删权限，只能人自己在库里删（删组会级联掉人的授权）。
+    EnvItem(
+        name='LABULL_ACCESS_FILE',
+        brief='授权声明文件的路径（默认就是 `BASE_DIR/labull-access.yaml`；相对路径按 `BASE_DIR` 解析）。'
+              '文件里写 `permissions:`（权限码 + 中文名）与 `groups:`（组名 → 权限码）',
+        hint='LABULL_ACCESS_FILE=config/labull-access.yaml',
+        group='授权（权限码 / 权限包）',
+    ),
     # ── 块的配置面 ──
     EnvItem(
         name=f'{BLOCK_CONFIG_PREFIX}*',