labull-framework 0.1.0__py3-none-any.whl

labull_framework/magic_block/health.py

@@ -0,0 +1,220 @@
+"""
+体检：把库里**存着的块代码**还算不算数算出来，不合格的**整批停用**，理由落库给管理员看。
+
+🔴 判据**完全复用保存那一道**（`validate.check_block`）：一行校验逻辑都不另写 ——
+   保存说合法、体检说非法（或者反过来）是最难查的一类事故。
+🔴 `enabled` / `disabled_reason` / `health_issues` / `health_checked_at` 四列**只有这里写**
+   （没有"手动启用"按钮）。幂等：改好代码再体检一次就自动恢复；**永不抛**：一个块失败不拖累别的。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from django.db.models.signals import post_migrate
+from django.utils import timezone
+
+from . import validate
+
+logger = logging.getLogger('labull_framework.magic_block')
+
+#: 一句话原因的最大长度（逐条原文在 `health_issues` 里）。
+REASON_MAX = 200
+
+#: 一条 issue 的 `kind`：`syntax` = 语法 / 结构错，`usage` = 用法 / 引用问题。两者都算不通过。
+_KINDS: dict[str, str] = {
+    'files': 'usage',
+    'backend': 'usage',
+    'syntax': 'syntax',
+}
+
+
+# ──────────────────────────── 算结论（纯函数式，不碰数据库） ────────────────────────────
+
+
+def evaluate(name: str, files: dict[str, str]) -> dict:
+    """算一个块的体检结论：`{'enabled', 'disabled_reason', 'issues'}`。
+
+    🔴 判据**完全复用保存那一道**（`validate.check_block`）—— 体检不另写一套。
+    """
+    issues: list[dict] = []
+    if name and not validate.NAME_PATTERN.match(str(name)):
+        issues.append(
+            {
+                'stage': 'files',
+                'kind': 'usage',
+                'message': f'name 不合法（{name!r}）：不能超过 {validate.NAME_MAX} 个字符、不能含控制字符',
+            }
+        )
+    try:
+        for stage, message in validate.check_block(files or {}):
+            issues.append({'stage': stage, 'kind': _KINDS.get(stage, 'usage'), 'message': message})
+    except Exception as exc:  # noqa: BLE001 —— 判据自己炸了也只算"这个块不通过"
+        issues.append(
+            {
+                'stage': 'backend',
+                'kind': 'usage',
+                'message': f'判据本身失败（不是这个块的问题）：{type(exc).__name__}: {exc}',
+            }
+        )
+    if not issues:
+        return {'enabled': True, 'disabled_reason': None, 'issues': []}
+    return {'enabled': False, 'disabled_reason': reason_of(issues), 'issues': issues}
+
+
+def reason_of(issues: list[dict]) -> str:
+    """一句话原因：第一条问题 + 还有几条（截 `REASON_MAX` 个字符）。"""
+    if not issues:
+        return '体检不通过'
+    head = str(issues[0].get('message') or '')
+    head = f'{head[:REASON_MAX]}…' if len(head) > REASON_MAX else head
+    return f'{head}（还有 {len(issues) - 1} 条，见明细）' if len(issues) > 1 else head
+
+
+# ──────────────────────────── 唯一的写库入口 ────────────────────────────
+
+
+def write_verdict(block_id: str, verdict: dict) -> None:
+    """把一个结论写进那四列（一个块一次 `UPDATE`，只更这四列）。
+
+    🔴 用 `.update()` 而不是 `row.save()`：`save()` 会把整行写回去（`files` 那一包可能很大），
+       并发保存时还会把别人刚写的那一版覆盖掉。
+    🔴 它**不碰 `updated_at`**（那是 `auto_now`）：体检改的是"能不能用"，不是"作者改了代码" ——
+       动了它会让编译缓存失效、控制台显示成"刚被人改过"。
+    """
+    from ..models import MagicBlock
+
+    MagicBlock.objects.filter(id=block_id).update(
+        enabled=bool(verdict.get('enabled')),
+        disabled_reason=verdict.get('disabled_reason'),
+        health_issues=verdict.get('issues') or [],
+        health_checked_at=timezone.now(),
+    )
+
+
+def check_all_blocks(ids: list[str] | None = None) -> dict:
+    """全量（或点名的几个）体检并把结论写库，返回一份汇总。
+
+    :param ids: 只体检这几个 uuid；省略 / 空 = **全量**。
+
+    🔴 **没有"浏览器那一半"这个输入**：块前端的代码不由我们校验（作者在前端自己负责），
+       所以体检的输入只有库里存着的包。
+    """
+    from ..models import MagicBlock
+
+    rows = list(MagicBlock.objects.all())
+    if ids:
+        wanted = {str(item) for item in ids}
+        rows = [row for row in rows if row.id in wanted]
+
+    results: list[dict] = []
+    disabled = 0
+    for row in rows:
+        was_enabled = row.enabled is not False
+        try:
+            verdict = evaluate(row.name or '', row.files or {})
+            if verdict['issues']:
+                verdict['enabled'] = False
+                verdict['disabled_reason'] = reason_of(verdict['issues'])
+        except Exception as exc:  # noqa: BLE001 —— 连算结论都炸了也只算这一个块不通过
+            verdict = {
+                'enabled': False,
+                'disabled_reason': f'体检判据自己失败（不是这个块的问题）：{type(exc).__name__}: {exc}',
+                'issues': [],
+            }
+        try:
+            write_verdict(row.id, verdict)
+        except Exception as exc:  # noqa: BLE001 —— 写不进去也只记一条，不带走整轮
+            logger.error('块 %s 的体检结论写不进库：%s: %s', row.id, type(exc).__name__, exc)
+        if not verdict['enabled']:
+            disabled += 1
+        results.append(
+            {
+                'id': row.id,
+                'name': row.name,
+                'enabled': bool(verdict['enabled']),
+                'disabledReason': verdict['disabled_reason'],
+                'issues': verdict['issues'],
+                # 这一条**本来**是启用的吗（控制台用它报"这次新停用了哪几个"）。
+                'wasEnabled': was_enabled,
+            }
+        )
+    summary = f'体检完成：查了 {len(rows)} 个块，通过 {len(rows) - disabled}，停用 {disabled}'
+    logger.info(summary)
+    return {
+        'checked': len(rows),
+        'passed': len(rows) - disabled,
+        'disabled': disabled,
+        'empty': not rows,
+        'results': results,
+        'log': [summary],
+    }
+
+
+# ──────────────────────────── 两个触发点 ────────────────────────────
+#
+# 🔴 **两条路职责不同，不许合并**：
+#   · `install_hook()` —— 挂在 `post_migrate` 上，**只在 `manage.py migrate` 之后**发。
+#     它管"库刚被改过"：一次性数据迁移跑完了，此时必须重算结论（顺序由框架保证：迁移在前）。
+#   · `startup_once()` —— 由 `wsgi.py` 显式调一次。`post_migrate` 在 `runserver` / `gunicorn`
+#     起来时**不会发**，所以"启动体检"只有这里能做。
+
+
+def install_hook() -> None:
+    """把"迁移之后跑一遍全量体检"挂到 `post_migrate` 上（幂等）。"""
+    post_migrate.connect(
+        _on_post_migrate,
+        dispatch_uid='labull_framework.magic_block.health',
+        sender='labull_framework',
+    )
+
+
+def _on_post_migrate(sender: object, **kwargs: object) -> None:
+    """`post_migrate` 接收器：迁移之后 → 补管理员 → 全量体检。
+
+    🔴 它**不调 `startup_once()`**：那个带进程级 latch，迁移之后调它会拿到"已经跑过"、
+       这一轮体检被吞掉 —— 而这一轮恰恰是数据迁移刚改过库之后最需要的那一次。
+    🔴 `install_hook` 已经把 `sender` 限成本 app 的迁移（别的 app 迁移完跑一遍纯属浪费）。
+    """
+    del sender, kwargs
+    bootstrap_admins()
+    try:
+        check_all_blocks()
+    except Exception as exc:  # noqa: BLE001 —— 体检失败不影响迁移
+        logger.error('迁移之后的全量体检失败（不影响服务）：%s: %s', type(exc).__name__, exc)
+
+
+def startup_once() -> None:
+    """进程启动时跑一次：**补管理员 → 全量体检**。无参、永不抛、进程级 latch。
+
+    🔴 名字与签名是 `wsgi.py` 的硬契约，别改。
+    """
+    global _STARTED
+    if _STARTED:
+        return
+    _STARTED = True
+    bootstrap_admins()
+    try:
+        for line in check_all_blocks()['log']:
+            logger.info(line)
+    except Exception as exc:  # noqa: BLE001 —— 冷启动时"表还没建"很常见，必须安静地过去
+        logger.error('启动体检失败（块按库里现有的启用状态跑）：%s: %s', type(exc).__name__, exc)
+
+
+#: `startup_once()` 的进程级 latch。
+_STARTED = False
+
+
+def bootstrap_admins() -> None:
+    """按环境变量点名的人补 staff（**只增不减、永不抛**）。
+
+    ⚠️ 那个模块可能还没被装上 —— 懒引用，取不到就跳过这一件事（体检不该因此不跑）。
+    """
+    try:
+        from ..auth.bootstrap import sync_staff_work_ids
+    except Exception:  # noqa: BLE001 —— 没装那一块就不是错
+        return
+    try:
+        sync_staff_work_ids()
+    except Exception as exc:  # noqa: BLE001 —— 补管理员失败不影响体检与启动
+        logger.error('启动补管理员失败（不影响服务）：%s: %s', type(exc).__name__, exc)

labull_framework/magic_block/registry.py

@@ -0,0 +1,157 @@
+"""
+编译缓存：块后端的正文在库里（不是一个 .py 文件），所以只能 `exec(compile(src), namespace)` 加载，
+加载结果按 `updated_at` 做版本键缓存在进程内 —— **保存即生效，不重启**。
+
+🔴 编译**不做任何校验**：那一份在 `validate.py`（保存与体检都先过它）。这里只把已经通过的代码
+   变成可调用的对象；两份判据并成一份的后果是"作者看到保存通过、运行期又说不合法"。
+🔴 块**可以只有前端**（包里没有 `backend_open.py` 不是错误），那时路由表就是空的。
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable
+
+from .sdk import RouteMeta, routes_of_namespace
+
+#: 缓存的条目上限（块本来就少，这个数只是不让缓存无界增长）。
+CACHE_MAX = 64
+
+#: 编译后的一条路由：handler + 它声明的权限。
+RouteHandler = Callable[[Any, Any], Any]
+
+
+@dataclass(frozen=True)
+class CompiledRoute:
+    """一条编译好的路由。"""
+
+    handler: RouteHandler
+    #: 声明的 Django 权限 codename；空串 = 任何登录用户。
+    permission: str = ''
+
+
+@dataclass(frozen=True)
+class CompiledBackend:
+    """一个块的编译产物：`类名.方法名` → handler。
+
+    🔴 加载失败（构造函数炸了 / 顶层出错）只让**这个块没有路由**，不带崩进程 ——
+       报文进 `errors`，作者调它时拿到的是 404（列出这个块真实有的路由名，这里是空的）。
+    """
+
+    routes: dict[str, CompiledRoute] = field(default_factory=dict)
+    #: 这份表是从哪一版正文编出来的（`updated_at` 的毫秒时间戳）。
+    version: int = 0
+    #: 编译时的错误（逐条中文，只给日志）。
+    errors: tuple[str, ...] = ()
+
+    def route_names(self) -> list[str]:
+        """这个块真实有的路由名（稳定排序 —— 报文里要列给作者看）。"""
+        return sorted(self.routes)
+
+
+def to_version(value: datetime | None) -> int:
+    """`updated_at` → 版本号（毫秒时间戳）。`None` ⇒ 0（与任何真实时间戳都不等，必然重编）。"""
+    if value is None:
+        return 0
+    try:
+        return int(value.timestamp() * 1000)
+    except (AttributeError, ValueError, OSError):
+        return 0
+
+
+def compile_backend(files: dict[str, str], version: int = 0) -> CompiledBackend:
+    """把一包文件编译成路由表（**不碰数据库**）。"""
+    source = (files or {}).get('backend_open.py') or ''
+    if not source.strip():
+        return CompiledBackend(routes={}, version=version)
+    try:
+        namespace: dict[str, Any] = {'__name__': 'labull_magic_block'}
+        exec(compile(source, 'backend_open.py', 'exec'), namespace)
+        classes = {
+            name: value
+            for name, value in namespace.items()
+            if isinstance(value, type) and not name.startswith('_')
+        }
+        meta: dict[str, RouteMeta] = routes_of_namespace(classes)
+        routes: dict[str, CompiledRoute] = {}
+        for route_name, route_meta in meta.items():
+            class_name, _, method_name = route_name.partition('.')
+            # 🔴 handler 绑在**实例**上：作者在 `__init__` 里赋的常量因此可用。
+            #    没写到 `meta` 里的方法不是路由（路径从装饰器来）。
+            instance = classes[class_name]()
+            handler = getattr(instance, method_name, None)
+            if callable(handler):
+                routes[route_name] = CompiledRoute(handler=handler, permission=route_meta.permission)
+        return CompiledBackend(routes=routes, version=version)
+    except Exception as exc:  # noqa: BLE001 —— 任何异常都只让"这个块没有路由"
+        return CompiledBackend(routes={}, version=version, errors=(f'加载失败：{type(exc).__name__}: {exc}',))
+
+
+class BlockRegistry:
+    """进程内单例：块 uuid → 当前生效的路由表。
+
+    🔴 版本判据是**库里那一行的 `updated_at`**：别人保存了这个块，本进程在下一次请求就看见
+       （多 worker 部署时每个 worker 各有一份缓存，各自发现版本变了 —— 这是可以接受的）。
+    """
+
+    def __init__(self) -> None:
+        self._cache: OrderedDict[str, CompiledBackend] = OrderedDict()
+
+    def get(self, block_id: str) -> CompiledBackend:
+        """取当前生效的路由表（版本对不上就重新编译）。库里没有这个块 ⇒ `LookupError`。"""
+        from ..models import MagicBlock
+
+        row = MagicBlock.objects.filter(id=block_id).only('id', 'updated_at', 'files').first()
+        if row is None:
+            raise LookupError(f'没有这个块：{block_id}')
+        version = to_version(row.updated_at)
+        hit = self._cache.get(block_id)
+        if hit is not None and hit.version == version:
+            self._cache.move_to_end(block_id)
+            return hit
+        compiled = compile_backend(row.files or {}, version)
+        self._put(block_id, compiled)
+        return compiled
+
+    def adopt(self, block_id: str, files: dict[str, str]) -> CompiledBackend:
+        """保存 / 回滚成功之后换新（**不重启即生效**的唯一落点）。
+
+        🔴 调用方必须**先**校验通过、**再**写库、最后才调这里 —— 这样"库里那一版"与
+           "内存里跑的那一版"永远同步。版本从库里重新读（`auto_now` 的时间由 Django 打，调用方算不出）。
+        """
+        from ..models import MagicBlock
+
+        row = MagicBlock.objects.filter(id=block_id).only('id', 'updated_at').first()
+        compiled = compile_backend(files or {}, to_version(row.updated_at) if row is not None else 0)
+        self._put(block_id, compiled)
+        return compiled
+
+    def invalidate(self, block_id: str) -> None:
+        """这个块没了：把缓存丢掉（不丢的话，下一次 `get()` 之前那段时间还调得到那段代码）。"""
+        self._cache.pop(block_id, None)
+
+    def enabled(self, block_id: str) -> tuple[bool, str]:
+        """这个块现在能不能用：`(能不能, 停用原因)`。库里没有 ⇒ `(False, '')`。
+
+        🔴 `is not False` 而不是 `bool(...)`：库里可能是 `NULL`（历史行），那种行按"启用"算。
+        🔴 停用要**明确拒绝**（403 + 原因），不装成"没有这个块"—— 后者会让作者去查 uuid 写错。
+        """
+        from ..models import MagicBlock
+
+        row = MagicBlock.objects.filter(id=block_id).values('enabled', 'disabled_reason').first()
+        if row is None:
+            return False, ''
+        return row['enabled'] is not False, str(row['disabled_reason'] or '')
+
+    def _put(self, block_id: str, compiled: CompiledBackend) -> None:
+        """写缓存（超上限先丢最旧的 —— `OrderedDict` 的插入序就是 LRU 序）。"""
+        self._cache.pop(block_id, None)
+        self._cache[block_id] = compiled
+        while len(self._cache) > CACHE_MAX:
+            self._cache.popitem(last=False)
+
+
+#: 进程内单例：视图是普通函数，模块级对象就是 Django 里的"单例"。
+REGISTRY = BlockRegistry()

labull_framework/magic_block/sdk.py

@@ -0,0 +1,245 @@
+"""
+块作者看到的**契约本体**：`backend_open.py` 怎么写、`ctx` 有几个键、`errors` 怎么抛，
+全部以本文件为准。块包校验（`validate.py`）与执行（`registry.py` / `dispatch.py`）
+读的是同一批常量与同一份元数据 —— 三处各写一份必然走偏。
+
+🔴 `ctx` **只有 4 个键**（`CTX_KEYS`）：`user` / `config` / `request` / `block`。
+   一个都不许加 —— 加一个键就是给块代码多一样能力，而契约、文档、校验三边都要跟着改。
+   ⚠️ **业务模型不经过 `ctx`**：块后端是普通的 Python，`from modules.orders.models import Order`
+   就是 Django 的写法（`ctx` 里再放一份"表名 → 模型"的映射，等于同一件事两个来源）。
+🔴 `errors` 必须是**同一个对象**（不是每次 new）：块里写 `except errors.NotFound` 要抓得住。
+🔴 这里的装饰器**只挂标记**：签名对不对、名字许不许，是 `validate.py` 的静态判据，不是运行期的事。
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import date, datetime, time
+from decimal import Decimal
+from typing import Any, Callable
+from uuid import UUID
+
+#: 块包入口（必备件）：宿主在不透明源 iframe 里渲染的就是它。
+BLOCK_ENTRY = 'index.open.html'
+
+#: 块包清单（必备件）：`id` / `module` / `name` / `brief` 四个键全部必填。
+#: 🔴 认块**只认它里面的 `id`**（与页面里写死的那个 uuid 逐字一致）。
+BLOCK_MANIFEST = 'magic-block.open.yaml'
+
+#: 块自己的后端（**可选**）：包里有别的名字的文件都不是后端，不会被校验、也不会挂路由。
+BLOCK_BACKEND_FILE = 'backend_open.py'
+
+#: 块作者唯一许写的那条 import 的模块路径（逐字）。块模块被塞进 `sys.modules` 的就是这个键。
+LIB_SDK = 'labull_framework.magic_block.sdk'
+
+#: 块配置的前缀：环境变量 `BLOCK_OCR_KEY` ⇒ `ctx.config['OCR_KEY']`。
+BLOCK_CONFIG_PREFIX = 'BLOCK_'
+
+#: 单次 `/bx/…` 调用的软超时（秒）：超时回 504，但那个方法**还在后台跑**（见 `dispatch.py`）。
+ROUTE_TIMEOUT_SECONDS = 15
+
+#: 请求正文的字节上限（24 MiB）。分块读、边读边数，不靠 `Content-Length`。
+MAX_BODY_BYTES = 24 * 1024 * 1024
+
+#: `ctx` 的键（4 个，一个都不许加）。🔴 顺序也是契约：文档与类型照它排。
+CTX_KEYS: tuple[str, ...] = ('user', 'config', 'request', 'block')
+
+#: 路由元数据挂在方法对象上的属性名。
+#: 🔴 用属性而不是"另建一张注册表"：装饰器写在方法定义上面，那时类还不存在，没有任何地方可登记。
+ROUTE_META = '__labull_magic_route__'
+
+
+# ──────────────────────────── 路由声明 ────────────────────────────
+
+
+@dataclass(frozen=True)
+class RouteMeta:
+    """一条路由的声明：`@MagicBackendAPI(permission=…)` 挂在方法上的那份元数据。"""
+
+    #: 调这条路由要的 Django 权限 codename；空串 = **任何登录用户**都能调。
+    #:
+    #: 🔴 省略 `permission` 是刻意的 fail-open：该拦在 handler 里判（"这一行是不是他的"），
+    #:    不是靠装饰器一个默认值。要收紧就写 `permission='app.codename'`（Django 的 has_perm）。
+    permission: str = ''
+
+
+@dataclass(frozen=True)
+class _RouteDecorator:
+    """装饰器返回的东西：既是装饰器，也是元数据载体。"""
+
+    permission: str
+
+    def __call__(self, method: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(method, ROUTE_META, RouteMeta(permission=self.permission))
+        return method
+
+
+def MagicBackendAPI(permission: str | None = None) -> _RouteDecorator:
+    """路由声明装饰器：**只是往方法上挂一份元数据**，本身零安全价值。
+
+    🔴 没挂它的方法**不是路由**（路径从装饰器来，不是从"是 public 方法"来）——
+       少写一行装饰器的表现是"前端调它回 404（报文里列出真实有的路由名）"，不是"谁都能调"。
+    🔴 传进来的东西不是字符串就当场 `TypeError`：它发生在**保存试加载**（模块级装饰器求值）时，
+       静默当"任何登录用户"会让一个权限口子无声地开着。
+    """
+    if permission is None:
+        return _RouteDecorator('')
+    if not isinstance(permission, str):
+        raise TypeError(
+            '@MagicBackendAPI(permission=…) 要么省略（任何登录用户），要么给一个 Django 权限 codename 字符串'
+        )
+    return _RouteDecorator(permission.strip())
+
+
+def route_meta_of(method: object) -> RouteMeta | None:
+    """读一个方法上的路由元数据（没挂装饰器 ⇒ `None`，也就是"这方法不是路由"）。"""
+    meta = getattr(method, ROUTE_META, None)
+    return meta if isinstance(meta, RouteMeta) else None
+
+
+def routes_of_namespace(classes: dict[str, type]) -> dict[str, RouteMeta]:
+    """从**已加载的类**里读出 `类名.方法名` → 声明（顺序 = 类与方法的书写顺序）。
+
+    ⚠️ 与 `validate.routes_of()` 是两件事、不是两份判据：那一份从源码文本（`ast`）读，
+       管保存校验与接口声明；这一份从已加载的对象读，管运行期真拿得到的 handler。
+       两者都只认这个装饰器挂上的元数据，所以结论一致。
+    """
+    out: dict[str, RouteMeta] = {}
+    for class_name, cls in classes.items():
+        for method_name, method in vars(cls).items():
+            if method_name.startswith('_'):
+                continue
+            meta = route_meta_of(method)
+            if meta is not None:
+                out[f'{class_name}.{method_name}'] = meta
+    return out
+
+
+# ──────────────────────────── 块作者能抛的错误 ────────────────────────────
+
+
+class MagicBackendHTTPError(Exception):
+    """块后端能抛的 HTTP 语义错误：分发器按 `status` 映射状态码，别的异常一律 500。
+
+    🔴 状态码口径与 HTTP 一致（400 / 401 / 403 / 404 / 409 / 500），否则"块里抛 403"
+       会变成 500，人看到的是"服务器错误"而不是"你没权限"。
+    """
+
+    status: int = 500
+
+    def __init__(self, message: str = '') -> None:
+        super().__init__(message)
+        self.message = str(message)
+
+
+def _error_class(name: str, status: int) -> type[MagicBackendHTTPError]:
+    """造一个带状态码的错误类（六个名字共用这一处，省得六段一模一样的类体）。"""
+    return type(name, (MagicBackendHTTPError,), {'status': status})
+
+
+class _Errors:
+    """`errors` —— 块作者抛的那六个（每个都是"状态码 + 报文"的一种语义）。
+
+    🔴 六个成员是**同一个对象上的类属性**：块代码里 `except errors.NotFound` 因此成立。
+    """
+
+    BadRequest = _error_class('BadRequest', 400)
+    Unauthorized = _error_class('Unauthorized', 401)
+    Forbidden = _error_class('Forbidden', 403)
+    NotFound = _error_class('NotFound', 404)
+    Conflict = _error_class('Conflict', 409)
+    Internal = _error_class('Internal', 500)
+
+
+#: 见到 `errors` 就是这一份（块包里 import 的也是它）。
+errors = _Errors()
+
+
+# ──────────────────────────── ctx 的形状 ────────────────────────────
+
+
+@dataclass(frozen=True)
+class BlockUser:
+    """`ctx.user` —— handler 里认人的唯一口径。
+
+    🔴 来源只有 `request.user`（Django 的会话），**绝不从 body 取**：
+       body 是调用方说了算的，拿它认人等于没有身份。
+    🔴 `groups` / `permissions` 给的是**名字**（组名 / 权限 codename），不是 Django 对象：
+       块里判权限用 `'app.codename' in ctx.user.permissions` 就够，不必碰 ORM。
+    """
+
+    #: 本地用户主键（Django 的 `pk`）。
+    id: str
+    #: 登录用户名（OIDC 的 `sub` 落在这一列）。
+    username: str
+    #: 工号（登录时由 `username` 映射而来；没有就是空串）。
+    work_id: str
+    #: 显示名（拿不到就是空串 —— 不编造）。
+    name: str
+    #: Django 自带的 staff 位（"是不是管理员"的唯一判据）。
+    is_staff: bool
+    #: 所在组的名字。
+    groups: tuple[str, ...] = ()
+    #: 直接权限 + 组权限的 codename（`app_label.codename` 形式）。
+    permissions: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class BlockCtx:
+    """handler 第二个参数里的 `ctx` —— **块里能拿到的全部能力**（就这 4 个键）。
+
+    🔴 这一段**没有查询操作符**（`eq` / `and` / `desc` …）：Django 原生 `Q` / `F` /
+       `filter` / `order_by` 就够了，多一层自己的 DSL 是净负担。
+    🔴 **也没有"业务表清单"**：块后端直接 import 自己的模型（`from modules.orders.models import Order`）——
+       那是 Django 的写法，而 `ctx` 里再放一份映射就是同一件事两个来源。
+    """
+
+    #: 认人的唯一口径。
+    user: BlockUser
+    #: 配置面：环境里 `BLOCK_` 前缀的那些（前缀剥掉当键；没配的键**不存在**）。
+    config: dict[str, str]
+    #: HTTP 请求原样给的（读 header / 原始字节用）。⚠️ **不该拿它判身份** —— 那只有 `ctx.user`。
+    request: Any
+    #: 当前块的身份（`id` / `module` / `name` / `brief`），只读。
+    block: dict[str, Any]
+
+
+# ──────────────────────────── 返回值只能是 JSON ────────────────────────────
+
+
+class _BlockJSONEncoder(json.JSONEncoder):
+    """块 handler 返回值的编码器：日期 / 金额 / uuid / 集合要能序列化。
+
+    🔴 每一样都转成**字符串**：JSON 的 number 是双精度，`Decimal` 走它有**静默丢精度**的风险
+       （金额上那是事故）；`datetime` 本来就没有 JSON 原生表示。字符串是唯一不撒谎的表示。
+    🔴 原始字节**明确报错**，不偷偷 base64 —— 那会让作者以为前端拿到的是那段字节。
+    """
+
+    def default(self, o: Any) -> Any:
+        if isinstance(o, Decimal):
+            return str(o)
+        if isinstance(o, (datetime, date, time)):
+            return o.isoformat()
+        if isinstance(o, UUID):
+            return str(o)
+        if isinstance(o, (bytes, bytearray, memoryview)):
+            raise TypeError('返回值里有原始字节：JSON 里没有字节类型，请自己 base64 成字符串')
+        if isinstance(o, (set, frozenset)):
+            # 不排序：set 的顺序本来就是实现细节，排了反而像它有语义。
+            return list(o)
+        if type(o).__module__.startswith('django') and hasattr(o, '__str__'):
+            # Django 的惰性对象（翻译串那类）：取它的字符串形式。
+            return str(o)
+        return super().default(o)
+
+
+def block_json(value: Any) -> str:
+    """把 handler 的返回值编成 JSON 文本（`None` ⇒ `'null'`）。
+
+    🔴 编不出来就**报出来**，绝不回半个对象 —— 半个 JSON 比一条错误难查得多。
+    """
+    try:
+        return json.dumps(value, cls=_BlockJSONEncoder, ensure_ascii=False)
+    except (TypeError, ValueError) as exc:
+        raise errors.Internal(f'返回值不能序列化成 JSON：{exc}') from exc