labull-framework 0.1.0__py3-none-any.whl

labull_framework/magic_block/views.py

@@ -0,0 +1,407 @@
+"""
+`/magic-blocks/*` 与 `/bx/*` 的全部视图（路由由 `urls.py` 按函数名指过来）。
+
+🔴 权限用 Django 原生的 `is_staff`：写口与管理员读口要 staff（**自己写 `staff_only`**：
+   `@staff_member_required` 对未登录用户会 302 到 admin 登录页，而这里要的是 401 + JSON）；
+   `status` / `render` 只要求登录，而且**永远不许**改成回整行 / 回全量 `files`。
+🔴 所有回话一律走 `jsonio`（一处出口：编码政策与错误形状都在那里）。
+"""
+
+from __future__ import annotations
+
+import json
+from functools import wraps
+from typing import Any, Callable
+
+from django.http import HttpRequest, HttpResponse
+
+from ..jsonio import problem
+from .dispatch import block_dispatch_view as block_dispatch_view
+from .health import check_all_blocks
+from .sdk import BLOCK_BACKEND_FILE, BLOCK_ENTRY
+from .service import (
+    PAGE_IDS_MAX,
+    BlockNotFound,
+    MagicBlockService,
+    SaveRejected,
+    api_dts,
+    health_issues,
+    iso,
+    sorted_files,
+    unique_ids,
+)
+
+__all__ = [
+    'index_view',
+    'status_view',
+    'render_view',
+    'rules_view',
+    'export_view',
+    'import_view',
+    'read_view',
+    'check_view',
+    'list_view',
+    'detail_view',
+    'rollback_view',
+    'delete_view',
+    'block_dispatch_view',
+    'staff_only',
+    'ids_of',
+]
+
+
+def staff_only(view: Callable[..., HttpResponse]) -> Callable[..., HttpResponse]:
+    """管理员守卫：没登录 ⇒ **401 + JSON**；登录了但 `is_staff=False` ⇒ **403 + JSON**。
+
+    🔴 两条判据分开报：一个是"你是谁"，一个是"你能不能" —— 合成一条会让前端不知道该去登录还是找管理员。
+    🔴 **不返回 302**：这几条是接口，前端要看状态码分支（302 会被 `fetch` 当成功跟着跳，最后拿到一页 HTML）。
+    """
+    from ..jsonio import no_identity
+
+    @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 getattr(user, 'is_staff', False):
+            return problem('这条接口只给管理员（Django 的 is_staff）', 403)
+        return view(request, *args, **kwargs)
+
+    return wrapper
+
+
+def login_only(view: Callable[..., HttpResponse]) -> Callable[..., HttpResponse]:
+    """只要求登录的守卫（`status` / `render` 两条读口用）。同样回 401 而不是 302。"""
+    from ..jsonio import no_identity
+
+    @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()
+        return view(request, *args, **kwargs)
+
+    return wrapper
+
+
+# ──────────────────────────── 小件 ────────────────────────────
+
+
+def _json(payload: Any, status: int = 200) -> HttpResponse:
+    """回一份 JSON（编码政策不在这里 —— 一律走 `jsonio` 那个出口）。"""
+    from ..jsonio import json_response
+
+    return json_response(payload, status=status)
+
+
+def _body(request: HttpRequest) -> dict:
+    """读 JSON 正文（读不出来当空对象：GET 那几条没有正文，写口漏了字段由各自的判据报）。"""
+    raw = request.body or b''
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw.decode('utf-8', errors='replace'))
+    except ValueError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _method(request: HttpRequest, want: str) -> HttpResponse | None:
+    """动词不对 ⇒ 405（路径是对的，只是动词不对 —— 报文要说清这一点）。"""
+    if request.method == want:
+        return None
+    return problem(f'这条接口只认 {want}', 405)
+
+
+def ids_of(query: str | None) -> list[str]:
+    """解析 `?ids=`：切分 → 去空白 → 去重 → 校验上限。
+
+    🔴 缺了 / 一个都没有 ⇒ **400 并说清怎么写**：回空数组会把"参数写错了"装成"这些块都没有"。
+    🔴 上限按**去重之后**的个数算（重复的 uuid 本来就是同一次查询）。
+    """
+    wanted = unique_ids([piece.strip() for piece in str(query or '').split(',')])
+    if not wanted:
+        raise SaveRejected(
+            'ids 不能为空：请用 ?ids=<uuid>[,<uuid>…] 一次问一个或多个块（未开发的块回 draft，不是 404）'
+        )
+    if len(wanted) > PAGE_IDS_MAX:
+        raise SaveRejected(f'一次最多问 {PAGE_IDS_MAX} 个块，这次给了 {len(wanted)} 个：请拆成几次')
+    return wanted
+
+
+def _reject(exc: SaveRejected) -> HttpResponse:
+    """保存 / 参数被拦下 ⇒ 400 + 逐条 issues（报文形态与别的错一致，多一个 `issues` 列）。"""
+    from ..jsonio import json_response
+
+    payload: dict[str, Any] = {
+        'statusCode': getattr(exc, 'status', 400) or 400,
+        'message': exc.message,
+    }
+    if exc.issues:
+        payload['issues'] = list(exc.issues)
+    return json_response(payload, status=payload['statusCode'])
+
+
+def _row_view(row: Any) -> dict:
+    """一行 → 管理员读口的下发形状（含文件包、体检结论与**接口名单**）。
+
+    🔴 接口名单只在这几条口上（列表 / 单条 / 保存 / 回滚）：它和块代码是同一侧的信息。
+    """
+    service = MagicBlockService()
+    routes, dts = service.api_manifest(row.id)
+    return {
+        'id': row.id,
+        'module': row.module,
+        'name': row.name,
+        'brief': row.brief,
+        'enabled': row.enabled is not False,
+        'disabledReason': row.disabled_reason or '',
+        'issues': health_issues(row),
+        'files': dict(row.files or {}),
+        'fileNames': sorted_files(row.files or {}),
+        'apiRoutes': routes,
+        'apiDts': dts,
+        'prevFiles': dict(row.prev_files or {}),
+        'prevUpdatedAt': iso(row.prev_updated_at),
+        'updatedBy': row.updated_by or '',
+        'updatedAt': iso(row.updated_at),
+    }
+
+
+# ──────────────────────────── 管理员读口 ────────────────────────────
+
+
+@staff_only
+def index_view(request: HttpRequest) -> HttpResponse:
+    """`GET /magic-blocks/index` —— 控制台用的块索引（**不带文件正文**）。
+
+    🔴 回话里**没有**"业务表清单"那种东西：块后端要模型就直接 import 它自己那一个
+       （Django 的写法），控制台也不需要知道项目的表结构。
+    """
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    service = MagicBlockService()
+    return _json({'blocks': service.index(request.GET.get('module') or None)})
+
+
+@staff_only
+def list_view(request: HttpRequest) -> HttpResponse:
+    """`/magic-blocks` —— **GET 列全部块**（带正文，管理员控制台用）；**POST 保存一个块**。
+
+    🔴 两个动词**同一个视图**：URLconf 是按路径匹配的，同一个路径写两条 `path()` 时
+       第二条永远匹配不到 —— `POST /magic-blocks` 会先撞上那条只认 GET 的，回一个 405。
+    """
+    if request.method == 'POST':
+        body = _body(request)
+        files = body.get('files')
+        try:
+            row = MagicBlockService().save(
+                block_id=str(body.get('id') or ''),
+                module=str(body.get('module') or ''),
+                name=str(body.get('name') or ''),
+                brief=str(body.get('brief') or ''),
+                files=files if isinstance(files, dict) else {},
+                # 审计字段拿不到就留空，**不许拿它挡住写入**。
+                actor=str(body.get('updatedBy') or ''),
+            )
+        except SaveRejected as exc:
+            return _reject(exc)
+        return _json(_row_view(row))
+
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    rows = MagicBlockService().list(request.GET.get('module') or None)
+    return _json([_row_view(row) for row in rows])
+
+
+@staff_only
+def detail_view(request: HttpRequest, block_id: str) -> HttpResponse:
+    """`GET /magic-blocks/<id>` —— 一行（没有就是 `null`，不是 404）。"""
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    row = MagicBlockService().get(block_id)
+    return _json(_row_view(row) if row is not None else None)
+
+
+# ──────────────────────────── 任何登录用户都能读的两条 ────────────────────────────
+
+
+@login_only
+def status_view(request: HttpRequest) -> HttpResponse:
+    """`GET /magic-blocks/status?ids=` —— 页面拿它决定三态。
+
+    🔴 回话里**一个字节的块代码都没有**：这条口任何登录用户都能读。
+    """
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    try:
+        wanted = ids_of(request.GET.get('ids'))
+    except SaveRejected as exc:
+        return _reject(exc)
+    return _json(MagicBlockService().statuses(wanted))
+
+
+@login_only
+def render_view(request: HttpRequest) -> HttpResponse:
+    """`GET /magic-blocks/render?ids=` —— `ok` 的块连**前端**文件一起给。
+
+    🔴 两条边界都在 `service.render()` 里：`.py` 一律不出门，且只有 `ok` 才带 `files` 键。
+    """
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    try:
+        wanted = ids_of(request.GET.get('ids'))
+    except SaveRejected as exc:
+        return _reject(exc)
+    return _json(MagicBlockService().render(wanted))
+
+
+# ──────────────────────────── 写口 ────────────────────────────
+
+
+@staff_only
+def rules_view(request: HttpRequest) -> HttpResponse:
+    """`GET /magic-blocks/rules` —— **读回改动时要照的扫描规则**（认哪些扩展名 / 跳过哪些目录 / 几层到顶）。
+
+    🔴 为什么要单独一条口：规则是一份**平台契约**，不是导出产物。原来只随 `POST /magic-blocks/export`
+       的回话给，于是"刷新页面之后想读回改动"就变成"必须再导出一次" —— 而导出会覆盖用户刚改的目录
+       （真踩过：用户点「读回改动」被要求先导出，合理反应是"这不合理"）。
+    🔴 判据只有 `export.scan_rules()` 那一处：这条口只是把它发出去，浏览器一条都不许抄。
+    """
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    from .export import scan_rules
+
+    return _json({'rules': scan_rules()})
+
+
+@staff_only
+def export_view(request: HttpRequest) -> HttpResponse:
+    """`POST /magic-blocks/export` —— **magic block export**：把库里的块算成**一整个开发包**。
+
+    请求体：`{}`（**没有参数**：开发目录由浏览器选，页面名单位于前端自己写的那份 `pages.lock.ts`）。
+    回话：`{'files': {'workspace/<可读名>-<uuid>/index.open.html': '<正文>', …}, 'blocks': N, 'rules': {…}}`
+
+    🔴 它**一个字节都不写盘**：写盘在用户自己机器上（浏览器 File System Access API），后端只算内容 ——
+       "铺到服务器某个目录"那条路没了（那会把开发目录放在离用户编辑器最远的地方）。
+    🔴 `rules` 是"读回改动"时浏览器要照的扫描规则（哪些扩展名 / 跳过哪些目录 / 几层到顶）：
+       判据只有 `export.scan_rules()` 一处，浏览器一条都不抄。
+    """
+    refused = _method(request, 'POST')
+    if refused is not None:
+        return refused
+    from .export import export_package
+
+    return _json(export_package())
+
+
+@staff_only
+def import_view(request: HttpRequest) -> HttpResponse:
+    """`POST /magic-blocks/import` —— 把改好的目录**读回库**（一个块失败只报它自己）。
+
+    请求体：`{'path': '<服务器上的目录>', 'includeMissing'?, 'blocks'?}`
+    🔴 走的是**保存那一条路**（`service.save`）：校验、体检、编译缓存失效全在那一处。
+    """
+    refused = _method(request, 'POST')
+    if refused is not None:
+        return refused
+    from .export import read_dir, write_dir
+
+    body = _body(request)
+    blocks = body.get('blocks')
+    items = [item for item in (blocks if isinstance(blocks, list) else []) if isinstance(item, dict)]
+    if not items and body.get('path'):
+        # 只给了目录：按读回来的结果取能存的那几条（与前端勾选全部同一件事）。
+        scanned = read_dir(str(body['path']))
+        items = [item for item in scanned['blocks'] if item.get('canApply')]
+        if not items:
+            # 🔴 逐条失败也要带出去：只说一句"没有能保存的块"，用户不知道是目录选错了还是块本身不合格。
+            detail = '；'.join(str(item.get('reason') or '') for item in scanned['failures'][:3])
+            return problem(f'这个目录里没有能保存的块。{detail}'.strip(), 400)
+    return _json(write_dir(items, actor=str(body.get('updatedBy') or '')))
+
+
+@staff_only
+def read_view(request: HttpRequest) -> HttpResponse:
+    """`POST /magic-blocks/read` —— 读一个目录，与库里的块逐块对比（**只读，不写库**）。
+
+    请求体两种（**两种入口、同一套判据**，见 `export._judge()`）：
+      · `{'root', 'folders': [{'where', 'files'}], 'failures'?, 'truncated'?}` —— **浏览器扫的**。
+        开发目录在用户自己机器上（导出就铺在那里），后端读不到它：由浏览器照导出报文里的
+        `rules` 扫一遍，把"我扫到了什么"递上来（形状见 `frontend/magic-block/src/localfs.ts`）。
+      · `{'path': '<服务器上的绝对路径>'}` —— 后端自己读那个目录（源码本来就在服务器上时用）。
+    """
+    refused = _method(request, 'POST')
+    if refused is not None:
+        return refused
+    from .export import read_dir, scan_folders
+
+    body = _body(request)
+    if isinstance(body.get('folders'), list):
+        return _json(scan_folders(body, include_missing=body.get('includeMissing') is True))
+    return _json(read_dir(str(body.get('path') or ''), include_missing=body.get('includeMissing') is True))
+
+
+@staff_only
+def check_view(request: HttpRequest) -> HttpResponse:
+    """`POST /magic-blocks/check` —— 重新体检（默认全量，也可以点名几块），然后**统一写库**。
+
+    请求体：`{'blocks': [uuid…]?}`（省略 = 全量）
+    🔴 点名库里没有的块 ⇒ **整条 404**（不许静默丢掉用户看到的失败）。
+    🔴 **没有"浏览器那一半"**：块前端不由我们校验。
+    """
+    refused = _method(request, 'POST')
+    if refused is not None:
+        return refused
+    body = _body(request)
+    blocks = body.get('blocks')
+    wanted = [str(item) for item in blocks] if isinstance(blocks, list) and blocks else None
+    if wanted:
+        from ..models import MagicBlock
+
+        known = set(MagicBlock.objects.filter(id__in=wanted).values_list('id', flat=True))
+        missing = [item for item in wanted if item not in known]
+        if missing:
+            return problem(f'这些块在库里找不到：{" / ".join(missing)}', 404)
+    result = check_all_blocks(wanted)
+    result.pop('log', None)
+    return _json(result)
+
+
+@staff_only
+def rollback_view(request: HttpRequest, block_id: str) -> HttpResponse:
+    """`POST /magic-blocks/<id>/rollback` —— 回滚到上一版（**双向兑换**：再点一次就回去）。"""
+    refused = _method(request, 'POST')
+    if refused is not None:
+        return refused
+    try:
+        row = MagicBlockService().rollback(block_id)
+    except BlockNotFound as exc:
+        return problem(exc.message, 404)
+    except SaveRejected as exc:
+        return _reject(exc)
+    return _json(_row_view(row))
+
+
+@staff_only
+def delete_view(request: HttpRequest, block_id: str) -> HttpResponse:
+    """`DELETE /magic-blocks/<id>` —— 删一个块（一行，`files` 跟着走）。"""
+    refused = _method(request, 'DELETE')
+    if refused is not None:
+        return refused
+    try:
+        MagicBlockService().delete(block_id)
+    except BlockNotFound as exc:
+        return problem(exc.message, 404)
+    return _json({'ok': True})
+
+
+# ──────────────────────────── 块后端那条口 ────────────────────────────
+# 🔴 它的定义在 `dispatch.py`（那里才是机制说明），这里只做**显式转发**，
+#    好让"这份文件就是全部入口"这句话成立（`urls.py` 按名字指过来）。

labull_framework/management/commands/labull_contract.py

@@ -0,0 +1,52 @@
+"""`manage.py labull_contract [--out PATH]`：把当前的模型形状导成一份 JSON。
+
+它是一个**可选出口**，不是任何东西的输入：这一页页面自己读的是进程内的模型元数据。
+导出它的两个理由：① 让别的语言的工具 / 前端拿到一份类型；② **让画布有"上一版"可比** ——
+把它 `--out` 到 git 里那份路径并提交，之后模型一改，画布上就能看出加 / 改 / 删。
+
+🔴 形状的真源是 Django 的 `_meta` —— **一行正则、一段 AST 都没有**。
+   扫源码抠模型只是在一份已经结构化的东西上再猜一遍。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError
+
+# 🔴 `...` 三个点：这个模块住在 `labull_framework.management.commands` 里，而 `shape` 在
+#    `labull_framework.canvas.data` —— 少一个点就会去找 `labull_framework.management.canvas`，
+#    报的是 `ModuleNotFoundError: No module named '…management.canvas'`（真踩过，命令整个不可用）。
+from ...canvas.data import shape
+
+
+class Command(BaseCommand):
+    help = '导出当前的模型形状（画布的"上一版"就靠它进 git）'
+
+    def add_arguments(self, parser) -> None:
+        parser.add_argument(
+            '--out',
+            default=None,
+            help='写到这个路径；不给就打到 stdout（stdout 上只有这一份 JSON）',
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        payload = shape()
+        if options.get('out'):
+            path = Path(str(options['out']))
+            try:
+                # 🔴 顺手把父目录建出来：README 教的就是 `--out .labull/contract.json`，
+                #    而 `open()` 不会替你建 `.labull/`（第一次跑必然 CommandError，纯添堵）。
+                path.parent.mkdir(parents=True, exist_ok=True)
+                with path.open('w', encoding='utf-8', newline='\n') as handle:
+                    json.dump(payload, handle, ensure_ascii=False, indent=2, sort_keys=False)
+                    handle.write('\n')
+            except OSError as exc:
+                raise CommandError(f'写不出来 {path}：{exc}') from exc
+            self.stderr.write(f'已写出 {len(payload["tables"])} 张表 → {path}')
+            return
+        # 🔴 stdout 分支转义非 ASCII：Windows 控制台默认 GBK，中文会变成 U+FFFD；
+        #    而 stdout 上**只有**这份 JSON（人话一律走 stderr）。
+        self.stdout.write(json.dumps(payload, ensure_ascii=True, indent=2, sort_keys=False))

labull_framework/migrations/0001_initial.py

@@ -0,0 +1,71 @@
+# Generated by Django 6.1.1 on 2026-10-03 02:26
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='MagicBlock',
+            fields=[
+                ('id', models.TextField(help_text='功能块 id', primary_key=True, serialize=False)),
+                ('module', models.TextField(help_text='所属模块')),
+                ('name', models.TextField(help_text='可读名')),
+                ('brief', models.TextField(blank=True, default='', help_text='备注')),
+                ('enabled', models.BooleanField(default=True, help_text='是否启用')),
+                ('disabled_reason', models.TextField(blank=True, help_text='停用原因', null=True)),
+                ('health_issues', models.JSONField(blank=True, help_text='体检问题', null=True)),
+                ('health_checked_at', models.DateTimeField(blank=True, help_text='体检时间', null=True)),
+                ('files', models.JSONField(help_text='文件包')),
+                ('prev_files', models.JSONField(blank=True, help_text='上一版文件', null=True)),
+                ('prev_updated_at', models.DateTimeField(blank=True, help_text='上一版时间', null=True)),
+                ('updated_by', models.TextField(blank=True, default='', help_text='最后修改人')),
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='更新时间')),
+            ],
+            options={
+                'verbose_name': '功能块',
+                'verbose_name_plural': '功能块',
+                'db_table': 'labull_magic_block',
+            },
+        ),
+        migrations.CreateModel(
+            name='User',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('work_id', models.TextField(help_text='工号', null=True, unique=True)),
+                ('name', models.TextField(blank=True, default='', help_text='显示名')),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'verbose_name': '用户',
+                'verbose_name_plural': '用户',
+                'db_table': 'labull_user',
+                'abstract': False,
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+    ]

labull_framework/models.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+
+
+class User(AbstractUser):
+    """登录进来的人。
+
+    🔴 **身份的唯一凭据是 `username`** —— 它装的是 Authing 的 `sub`（"是同一个人"就靠它），
+    `AbstractUser` 自带 `username` 的 unique 约束，所以"同一身份两行"在库这一层就不可能发生。
+    ⚠️ 没有本地口令：登录只走 OIDC，口令列由 `set_unusable_password()` 堵死。
+
+    🔴 **"是不是管理员"用 Django 自带的 `is_staff`** —— 这里不另造角色字段。
+    要更细的粒度就用 Django 的 `Group` / `Permission`（也是原生的），本库不预置任何组。
+    """
+
+    # Authing 里的 `username`（工号）：一个工号对应一个人。
+    # ⚠️ 可空：Authing 那边没配 `username` 时**拒登**，但历史行可能没有工号。
+    work_id = models.TextField(null=True, unique=True, help_text='工号')
+
+    # 从 Authing 同步过来的显示名（同步不回来时退回 `username`）。
+    name = models.TextField(blank=True, default='', help_text='显示名')
+
+    class Meta(AbstractUser.Meta):
+        # 🔴 表名显式写：`AbstractUser` 的默认名是 `<app_label>_user`，而那张表的名字是契约的一部分。
+        db_table = 'labull_user'
+        verbose_name = '用户'
+        verbose_name_plural = '用户'
+
+
+class MagicBlock(models.Model):
+    """功能块：一个 uuid + 一段说明 + **一整个文件包**。
+
+    认块只认 `id`（开发者在页面里写死的 uuid），`name` 不做唯一约束。
+    `files` = 文件名（包内相对路径）→ 正文；入口固定 `index.open.html`，由沙箱 iframe 渲染 ——
+    **不重新编译、不重启**。
+    """
+
+    id = models.TextField(primary_key=True, help_text='功能块 id')
+    module = models.TextField(help_text='所属模块')
+    name = models.TextField(help_text='可读名')
+    brief = models.TextField(blank=True, default='', help_text='备注')
+
+    # 停用的块不渲染、它的后端也调不到。🔴 **只由体检写**（单一写者）：通过 ⇒ 启用，不通过 ⇒ 停用；
+    #   改好代码再体检一次就自动恢复。所以没有"手动启用"这个动作。
+    enabled = models.BooleanField(default=True, help_text='是否启用')
+
+    # 体检不通过时**为什么**被停用（一句话，给管理员看）；通过时清空。
+    disabled_reason = models.TextField(null=True, blank=True, help_text='停用原因')
+
+    # 逐条问题（`[{stage, kind, message}]`），抽屉才能一条条列出来；通过时是空列表。
+    health_issues = models.JSONField(null=True, blank=True, help_text='体检问题')
+    health_checked_at = models.DateTimeField(null=True, blank=True, help_text='体检时间')
+
+    files = models.JSONField(help_text='文件包')
+
+    # 上一版的那一包文件：保存是**整包替换**，这是"手滑能救回来"的底稿。
+    # 🔴 只留一版（不是版本史）：回滚是"与当前这版双向兑换"，两版就够；真正的版本管理在 git 里。
+    prev_files = models.JSONField(null=True, blank=True, help_text='上一版文件')
+    prev_updated_at = models.DateTimeField(null=True, blank=True, help_text='上一版时间')
+
+    # 最后改这个块的人（审计字段；Authing 的 `sub`，拿不到就空串）。
+    updated_by = models.TextField(blank=True, default='', help_text='最后修改人')
+
+    created_at = models.DateTimeField(auto_now_add=True, help_text='创建时间')
+    # ⚠️ 与 `prev_updated_at` 是两件事：这一列是"现在这版"的版本号（编译缓存按它做缓存键）。
+    updated_at = models.DateTimeField(auto_now=True, help_text='更新时间')
+
+    class Meta:
+        db_table = 'labull_magic_block'
+        verbose_name = '功能块'
+        verbose_name_plural = '功能块'
+
+    def __str__(self) -> str:
+        return f'{self.module}/{self.name}'