labull-framework 1.0.0__tar.gz → 1.0.2__tar.gz

{labull_framework-1.0.0/labull_framework.egg-info → labull_framework-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 1.0.0
+Version: 1.0.2
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT
@@ -95,7 +95,7 @@ CORS_ORIGIN=http://localhost:5173
 |---|---|
 | **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
 | **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
-| **让块的依赖声明拦住保存** | 设 `LABULL_REQUIRES=error`（默认 `warn`：判据照跑、**只提示不拦保存**；`off` 整段不跑） |
+| **块的依赖声明不许"用了却没声明"** | 它是**默认**行为（`LABULL_REQUIRES=error`，1.0.1 起）：代码里用了没声明的东西 ⇒ 拦住保存。⚠️ 升级前先在项目里跑一遍 `python manage.py labull_requires --write` 把存量块扫得到的声明补进库；`warn`（只提示不拦）与 `off`（整段不跑）都要**显式**写 |
 | **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |
 
 ## magic block
@@ -107,7 +107,8 @@ CORS_ORIGIN=http://localhost:5173
 ├─ index.open.html        入口（必备）
 ├─ magic-block.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
 │                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `BLOCK_*`）可选
-├─ README.open.md         **业务功能说明**（Markdown，可选）：这一段的家就是这份文件，不在清单里
+├─ README.open.md         **业务功能说明**（Markdown）：这一段的家就是这份文件，不在清单里
+│                         （**每个块都会有一份** —— 导出时无条件铺，没写就是空文件）
 ├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的：正文进清单的 `requires`，注释是扫代码的建议）
 ├─ 任意 js / css
 ├─ excluded/_*            你自己的地盘（测试 / 草稿）：**照样进库，执行时忽略**
@@ -138,6 +139,11 @@ class Order:
 
 配置：环境变量里**带 `BLOCK_` 前缀**的才会进 `ctx.config`（`BLOCK_OCR_KEY=a` ⇒ `ctx.config['OCR_KEY']`）。
 
+🔴 **弹窗走平台**：块里 `await magicBlock.dialog({ title, body, fields, buttons })` —— 由宿主页面渲染
+（前端要挂一次 `<MagicBlockDialogs />`）。块自己画的浮层**摆不正**：块可以是好几屏高，块里
+`position: fixed` / `100vh` 的基准是"整块高度"而不是用户那一屏。要自己写整篇就传 `{ html }`，
+宿主给一个确定大小的面板 + 另一格沙箱 iframe 装它，里面用 `magicBlock.done({ button, values })` 交回选择。
+
 ## 虚拟类（`@virtual_class`）
 
 几张表共有同一批列时，写一个**虚拟类**：一个**不建表的抽象模型**，自己那几列会被继承到子表上。

{labull_framework-1.0.0 → labull_framework-1.0.2}/README-pypi.md

@@ -67,7 +67,7 @@ CORS_ORIGIN=http://localhost:5173
 |---|---|
 | **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
 | **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
-| **让块的依赖声明拦住保存** | 设 `LABULL_REQUIRES=error`（默认 `warn`：判据照跑、**只提示不拦保存**；`off` 整段不跑） |
+| **块的依赖声明不许"用了却没声明"** | 它是**默认**行为（`LABULL_REQUIRES=error`，1.0.1 起）：代码里用了没声明的东西 ⇒ 拦住保存。⚠️ 升级前先在项目里跑一遍 `python manage.py labull_requires --write` 把存量块扫得到的声明补进库；`warn`（只提示不拦）与 `off`（整段不跑）都要**显式**写 |
 | **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |
 
 ## magic block
@@ -79,7 +79,8 @@ CORS_ORIGIN=http://localhost:5173
 ├─ index.open.html        入口（必备）
 ├─ magic-block.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
 │                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `BLOCK_*`）可选
-├─ README.open.md         **业务功能说明**（Markdown，可选）：这一段的家就是这份文件，不在清单里
+├─ README.open.md         **业务功能说明**（Markdown）：这一段的家就是这份文件，不在清单里
+│                         （**每个块都会有一份** —— 导出时无条件铺，没写就是空文件）
 ├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的：正文进清单的 `requires`，注释是扫代码的建议）
 ├─ 任意 js / css
 ├─ excluded/_*            你自己的地盘（测试 / 草稿）：**照样进库，执行时忽略**
@@ -110,6 +111,11 @@ class Order:
 
 配置：环境变量里**带 `BLOCK_` 前缀**的才会进 `ctx.config`（`BLOCK_OCR_KEY=a` ⇒ `ctx.config['OCR_KEY']`）。
 
+🔴 **弹窗走平台**：块里 `await magicBlock.dialog({ title, body, fields, buttons })` —— 由宿主页面渲染
+（前端要挂一次 `<MagicBlockDialogs />`）。块自己画的浮层**摆不正**：块可以是好几屏高，块里
+`position: fixed` / `100vh` 的基准是"整块高度"而不是用户那一屏。要自己写整篇就传 `{ html }`，
+宿主给一个确定大小的面板 + 另一格沙箱 iframe 装它，里面用 `magicBlock.done({ button, values })` 交回选择。
+
 ## 虚拟类（`@virtual_class`）
 
 几张表共有同一批列时，写一个**虚拟类**：一个**不建表的抽象模型**，自己那几列会被继承到子表上。

{labull_framework-1.0.0 → labull_framework-1.0.2}/labull_framework/canvas/data.py

@@ -481,9 +481,9 @@ def _fields_of(model: Any) -> tuple[list[dict[str, Any]], list[dict[str, Any]],
             #    它的正向声明住在 **Django 自己的源码**里，而"上一版"那一份只扫项目与装着的
             #    第三方 app（`shape_ast._reverses()` 里 `if target is None or not self._installed(...)`
             #    那一句）⇒ 基线里**永远没有**这一条，于是画布常年报一处假的"新增的关联"。
-            #    实测就是它：装了 `django.contrib.admin` 时用户表上那条 `labull_user.logentry`
-            #    （`gitinfo._known_limitation()` 原来把它记成"这条路固有的边界"，其实两边
-            #    **用同一条判据**就能对齐：不画的表，两边都不挂它的反向关联）。
+            #    实测就是它：装了 `django.contrib.admin` 时用户表上那条 `labull_user.logentry`。
+            #    ⚠️ 这条边界**只能靠"不画的表两边都不挂它的反向关联"来对齐**（见下面那句
+            #    `SKIP_TABLES` 判定）—— 想靠"在基线里把它剔掉"是越剔越糟，别再去试。
             if _table_of_model(target) in SKIP_TABLES:
                 continue
             # 🔴 一对一反过来的**基数也是 `1`**：这一头只对应一行（`OneToOneRel.one_to_one`）。

{labull_framework-1.0.0 → labull_framework-1.0.2}/labull_framework/canvas/gitinfo.py

@@ -242,29 +242,18 @@ def baseline_tables() -> list[dict[str, Any]] | None:
           而且不需要任何人记得维护什么文件；
        ② 退到提交里那份 `contract.json`（老做法）：只在①读不出来时用
           （源码语法坏掉 / 模型写在 `models/` 包里这种今天不支持的形状）。
-    ⚠️ 有一类**已知的**假差异（装了 `django.contrib.admin` 时用户表上那条 `logentry`），
-       见 `_known_limitation()` —— 那是"从源码算"这条路的固有边界，不是可以顺手滤掉的噪声
-       （试过滤，越滤越糟）。
+    ⚠️ 有一类**已知的**假差异：装了 `django.contrib.admin` 的项目里，`LogEntry` 有一条外键指向
+       **你的**用户表 ⇒ `_meta.get_fields()` 会在你的用户表上给出 `logentry` 这条反向关联，
+       而它的正向声明在 Django 自己的源码里（这个项目的 git 里一行都没有）—— 所以"从源码算基线"
+       这条路**永远算不出它**（画布上会常年挂着一条"新增的关联"）。
+       🔴 这是这条路的**固有边界，不是可以顺手滤掉的噪声**：试过两条路（靠"差分反推来源"、
+       靠 `origin` 标记）都**越滤越糟** —— 剔掉之后基线里没有、现在这一份里有，差异恰好从
+       "没多出来"变成"新增"。要根治只能让基线也算上 Django 那边的正向声明，那是另一件事。
     """
     derived = _revision_tables()
     return derived if derived is not None else contract_tables()
 
 
-def _known_limitation() -> str:
-    """这一层**已知**的一类假差异（写给下一个人看，别再去踩）。
-
-    装过 `django.contrib.admin` 的项目里，`django.contrib.admin.LogEntry` 有一条外键指向**你的**
-    用户表 ⇒ `_meta.get_fields()` 会在你的用户表上给出 `logentry` 这条反向关联，
-    而它的正向声明在 Django 自己的源码里（这个项目的 git 里一行都没有）——
-    所以"从源码算基线"这条路**永远算不出它**，画布上会常年挂着一条"新增的关联"。
-    ⚠️ 试过在基线里把它剔掉（两条路都试过：靠"差分反推来源"、靠 `origin` 标记）：
-       **越剔越糟** —— 剔掉之后基线里没有、现在这一份里有，差异恰好从"没多出来"变成"新增"。
-       要根治只能"让基线多知道一条 Django 自己那边的关联"，那是另一件事（读 Django 的源码 +
-       把它的正向声明也算进来）。今天只留这一条说明。
-    """
-    return 'labull_user.logentry（装了 admin 时）'
-
-
 def contract_tables() -> list[dict[str, Any]] | None:
     """提交里那份 `contract.json` 的形状（**兜底**来源；没有就是 `None`）。
 
@@ -425,27 +414,6 @@ def _sources_state() -> float:
     return newest
 
 
-def _newest_mtime(path: Path) -> float:
-    """这个路径（文件就自己，目录就**递归**）里最新的 mtime（拿不到回 `0.0`）。
-
-    ⚠️ 只对**小的那几棵**目录树用它（`refs` / `logs`，一个仓库几十个文件）。
-       **不要拿它去递归 `.git` 自己**：那底下有 `objects/`，一个仓库几千上万个对象 ——
-       真踩过：这一层是每次访问缓存都要走的，递归一遍 `.git` 让"热"的那次从 1ms 涨到 340ms，
-       `tools/baseline-cases.py` 里那条"第二次走缓存"的判据当场就红了。
-    """
-    try:
-        newest = path.stat().st_mtime
-    except OSError:
-        return 0.0
-    if path.is_dir():
-        for child in path.rglob('*'):
-            try:
-                newest = max(newest, child.stat().st_mtime)
-            except OSError:
-                continue
-    return newest
-
-
 def _git_state(roots: list[Path | None]) -> float:
     """这几个路径**各自最近那个** `.git` 里，"一变就该重算"的东西的最新 mtime（没有 git 回 `0.0`）。
 
@@ -458,9 +426,9 @@ def _git_state(roots: list[Path | None]) -> float:
        · `index` —— `git add`；
        · **当前那个分支的 ref 文件 + `HEAD` 里的提交号**（见 `_head_marker()`）—— **提交**；
        · `packed-refs` —— 打包过的仓库（`git gc` / 服务器上克隆下来的）。
-    🔴 **递归 `refs/**` 那一版删掉了**（真踩过）：`_newest_mtime()` 会把 `refs` 与 `logs` 整棵小树
-       走一遍，而"平台那些 app 各自一个仓库"让这件事**按 app 数乘上去** —— 实测一次画布要
-       多花 ~200ms（profiler 里 `_newest_mtime` 是最大的一块）。改成"读 `.git/HEAD` 找到当前
+    🔴 **从前那一版是"递归 `refs/**` + `logs/**` 数最新的 mtime"**（真踩过）：它会把那两棵小树
+       整个走一遍，而"平台那些 app 各自一个仓库"让这件事**按 app 数乘上去** —— 实测一次画布要
+       多花 ~200ms（profiler 里递归那一块是最大的）。改成"读 `.git/HEAD` 找到当前
        分支、只 stat 那**一个** ref 文件"之后：提交照样能看见（ref 文件被重写），
        而代价从"几十上百次 stat"降到"两三次"。⚠️ 判据是 `HEAD` 里那个提交号、
        **不是 `pytest.ini` 那种 `paths` 里的 `logs/HEAD`** —— 后者只在 reflog 开着时才变。

{labull_framework-1.0.0 → labull_framework-1.0.2}/labull_framework/canvas/shape_ast.py

@@ -243,6 +243,9 @@ class _Project:
         #: 字段工厂函数（`def current_assignees_field(...)`）的记忆：**函数名 → 那个 `def`**。
         #: 🔴 连 `None` 一起记：一个工厂会被好几张表用到，不记"没有"就等于**每张表都起一次 git**。
         self._helpers: dict[str, ast.FunctionDef | None] = {}
+        #: "**一个类自己**继承完之后的完整字段表"的记忆（见 `_own_fields()`）：键是
+        #: `'app.类名'` 或外部基类的模块路径。同一个基类会被好几张表用到，不记就重复解析。
+        self._own_cache: dict[str, dict[str, tuple[ast.Call, dict[str, ast.expr]]]] = {}
         #: app 标签（`'masterdata'` / `'apps.masterdata'`）：`lookup()` 要拿它去认源码里的懒引用
         #: （见那个函数）。懒算 —— 没碰上带点懒引用的项目一次都不建（见 `_labels()`）。
         self._label_cache: list[str] | None = None
@@ -447,6 +450,32 @@ class _Project:
             return self.table_name(model)
         return KNOWN_TARGET_TABLES.get(self._external_name(call), '')
 
+    def external_target_name(self, call: ast.Call) -> str:
+        """这条关联指向的**外部**模型名（`groups` ⇒ `'Group'`）；不是外部 / 认不出回空串。
+
+        🔴 为什么不直接照搬 `_meta` 那条路：`resolve_relation()` **只认本项目里声明过的模型**
+           （那条 docstring 里写着"认不出就回 `None`，一个都不猜"），所以 `auth.Group` 那类
+           对端在那一层是 `None` ⇒ 关联的 `target` 是空串、`targetTable` 靠
+           `KNOWN_TARGET_TABLES` 兜住。两处**必须一致**：`target` 与 `targetTable` 都取自
+           同一份"已知外部表"清单，猜不出来就两个都给空。
+        """
+        return self._external_name(call)
+
+    def external_m2m_table(self, model: _Model, name: str, call: ast.Call) -> str:
+        """默认多对多中间表名（Django `ManyToManyField._get_m2m_db_table()` 的那一条算式）。
+
+        Django 的正文就是一句：`opts.db_table` 拼上字段名 —— `labull_user` + `groups` ⇒
+        `labull_user_groups`。⚠️ 前缀是**声明那一头**的表名，与对端（`auth.Group`）无关
+        （"两个模型名按字母序拼"是中间表**模型**的默认 `db_table`，不是这一条）。
+
+        ⚠️ 只对**认出对端**的那几条成立：对端在本项目里没有同名模型是"这是外部关联"的判据，
+           认不出来的对端连模型名都没有，硬拼一个表名就是编 —— 那种情况老实回空串
+           （`_meta` 那边此刻也不会给 `via`）。
+        """
+        if not self.external_target_name(call):
+            return ''
+        return f'{self.table_name(model)}_{name}'
+
     def known_primary_type(self, model: _Model | None, call: ast.Call) -> str:
         """一条外键列的**库类型**（对端主键那一列的类型）。
 
@@ -605,18 +634,20 @@ class _Project:
     def _merge(self, model: _Model) -> list[tuple[str, ast.Call, dict[str, ast.expr]]]:
         """真干活的那一半：MRO + 外部基类 + 剔掉非字段 + 补齐主键（见 `fields_of()` 的说明）。"""
         package = self._pkg(model.app)
+        # 🔴 **按 MRO 从子类往基类走**，而每一个类都拿"**它自己**继承完之后的完整字段表"
+        #    （`_own_fields()` 递归同一个规则）—— 这正是 Django `ModelBase.__new__` 干的事：
+        #    它 `for base in new_class.mro()`（**自然序**）逐个抽象基类把 `base._meta.fields`
+        #    抄进子类，`field_names` 用来去重 ⇒ 同名的那一列**挪到子类的位置上**。
+        #    ⚠️ 从前这里是 `for base in reversed(mro)` + 一个全局字典，等于假设"Django 是
+        #       从最远的基类往子类铺"。那个假设**在多继承上就是错的**：`A(AbstractBaseUser,
+        #       PermissionsMixin)` 的自然 MRO 里 `AbstractBaseUser` 在 `PermissionsMixin`
+        #       **前面**，于是 `is_superuser` 被摆到 `password` 前面，而 Django 给的是
+        #       `password / last_login / is_superuser / …` —— 列一模一样、只是次序错，
+        #       而 `_compare_key()` 比的是**有序**的列列表 ⇒ 没动过的 `labull_user`
+        #       常年挂一处假的"已改动"（`sdk-check-py` 判据①②报的就是它）。
         merged: dict[str, tuple[ast.Call, dict[str, ast.expr]]] = {}
-        # 🔴 **按 MRO 从子类往基类走**（`reversed(mro)`）：次序与 Django 的 `_get_fields()`
-        #    一致 —— 它**先递归父类**、最后才 `+= self.local_fields`。所以最靠前的类是
-        #    子类（它的字段最后落位、覆盖基类同名那一列时也是挪到子类的位置上），
-        #    而基类的字段先落位。🔴 判据不只是好看：`_compare_key()` 比的是**有序**的列列表，
-        #    次序错一位就是一处"改过"。
-        #    ⚠️ 这里是 `reversed`，**不是**自然序 —— 文档串头一句 `[模型, 基类, …]` 说的是
-        #       `mro()` 的返回值，别照着它把这一句改掉（真验过：改了之后抽象基类那几列
-        #       `created_at` 会从 `id` 后面掉到整张表的最后，⑦ 那条夹具当场变红）。
-        for base in reversed(self.mro(model, package)):
-            for name, call, kwargs in self._declared(base):
-                merged[name] = (call, kwargs)
+        for base in self.mro(model, package):
+            merged.update(self._own_fields(base))
         # 🔴 **先剔掉"不是字段"的那些，再判主键**：`objects = Manager()` 这种在解析阶段是
         #    "暂收"的（见 `_is_field_call()`），真正的判据在这里 —— 不剔的话它会在表上
         #    凭空多出一列，而且 `Manager(primary_key=True)` 那种写法还会把合成主键挤掉。
@@ -659,6 +690,31 @@ class _Project:
                 kept[name] = (call, kwargs)
         return kept
 
+    def _own_fields(self, node: Any) -> dict[str, tuple[ast.Call, dict[str, ast.expr]]]:
+        """**一个类自己**继承完之后的完整字段表（不含它子类加的东西）。
+
+        :param node: MRO 上的一个条目 —— 本项目里的模型（`_Model`）或一个外部基类的字符串键。
+
+        🔴 为什么必须**每个类各算一份**，不能像从前那样把全部基类的声明铺进一个字典：
+            Django 抄的是 `base._meta.fields`（**那个基类自己的完整字段表**，已含它继承来的），
+            而"同名覆盖"是在**子类那一步**发生的。两者在"子类和某个抽象基类声明了同一列"
+            时给出**不同的次序**（Django 把那一列挪到子类的位置上）—— 而次序参与判据。
+        🔴 递归走**同一个规则**（自然 MRO + 逐类 update）⇒ 与 Django 的 `mro()` 逐层一致。
+            ⚠️ 这条路**不会成环**：MRO 本身就是线性的，每个类的 `lin()` 只包含它自己那条链。
+        """
+        key = node if isinstance(node, str) else f'{node.app}.{node.name}'
+        if key in self._own_cache:
+            return self._own_cache[key]
+        out: dict[str, tuple[ast.Call, dict[str, ast.expr]]] = {}
+        for base in self.mro(node, self._pkg(node.app) if not isinstance(node, str) else ''):
+            if (base if isinstance(base, str) else f'{base.app}.{base.name}') == key:
+                continue   # 自己这一层的声明由下面那一句收（顺序：先基类、后自己）
+            out.update(self._own_fields(base))
+        for name, call, kwargs in self._declared(node):
+            out[name] = (call, kwargs)
+        self._own_cache[key] = out
+        return out
+
     def mro(self, model: _Model, package: str = '') -> list[Any]:
         """一个模型的 MRO（含**外部**基类）：`[模型, 基类, …, Model]`（C3 线性化）。
 
@@ -730,11 +786,29 @@ class _Project:
                     out.append(resolved)
             return out
 
+        #: 正在算的那条链（**防环专用**）。🔴 它必须是**另一个**集合，不能拿 `memo` 兼职：
+        #    `memo[key] = [key]` 那种"先占位"的写法把**没算完**的结果写进了备忘 ——
+        #    而链上任何一个类**都可能在算完之前被问到第二次**（多继承就是这条路：
+        #    算 `AbstractUser` 时先算 `AbstractBaseUser`，而它的线性化里已经包含
+        #    `AbstractUser` 的兄弟 `PermissionsMixin`）。那一次拿到的是"只有我自己"的
+        #    半成品，它随后被**当成正确结果用**，而且**谁先被问到就决定了对错** ——
+        #    实测：`AbstractUser(AbstractBaseUser, PermissionsMixin)` 的 MRO 变成
+        #    `[…, PermissionsMixin, AbstractBaseUser, AbstractUser]`，于是一张表上
+        #    `is_superuser` 排到了 `password` 前面 ⇒ `_compare_key()` 逐位比列 ⇒
+        #    没动过的 `labull_user` 常年挂一处假的"已改动"（列一模一样、只是次序错）。
+        #    ⚠️ 那条判据（`sdk-check-py` 判据①②）在**真环**不在时永远看不见这件事：
+        #       它只在"同一个类被间接问到两次"的多继承项目上才露出来。
+        active: set[str] = set()
+
         def lin(key: str) -> list[str]:
             """C3：`lin(C) = [C] + merge(lin(B1), …, [B1, …])`（`merge` 取每个序列的下一个可用头）。"""
             if key in memo:
                 return memo[key]
-            memo[key] = [key]   # 防环：先占位（真环只出现在手滑的代码里，不该把整页带炸）
+            if key in active:
+                # 真环（手滑写出来的 `class A(B)` / `class B(A)`）：只回它自己，
+                # **不写 memo** —— 免得把一个半成品记成结论。
+                return [key]
+            active.add(key)
             # ⚠️ `bases_of(key)` 只算**一次**：它是"读一个文件 + 解析"的量级，而下面两处都要用。
             bases = bases_of(key)
             seqs: list[list[str]] = [list(lin(base)) for base in bases]
@@ -760,6 +834,7 @@ class _Project:
                     if seq and seq[0] == pick:
                         seq.pop(0)
             memo[key] = out
+            active.discard(key)   # 算完了才算离开这条链：`break` 那条路也走得到这里
             return out
 
         result: list[Any] = []
@@ -995,8 +1070,9 @@ class _Project:
                 if kind == 'manyToMany':
                     relations.append(_relation(
                         name, kind, cardinality, target,
+                        target_name=self.external_target_name(call),
                         target_table=target_table,
-                        via=self._through(call, model),
+                        via=self._through(call, model) or self.external_m2m_table(model, name, call),
                         external=external,
                     ))
                     continue
@@ -1615,6 +1691,7 @@ def _relation(
     cardinality: str,
     target: _Model | None,
     *,
+    target_name: str = '',
     target_table: str = '',
     column: str | None = None,
     via: str | None = None,
@@ -1625,6 +1702,11 @@ def _relation(
 ) -> dict[str, Any]:
     """一条关联（与 `data._relation_of()` 同形 —— 键少一个就可能被当成"改过"）。
 
+    :param target_name: 对端**模型名**。⚠️ 外部对端（`auth.Group` 那两张）在本项目里
+        `resolve_relation()` 认不出来（它只认声明过的模型），所以要由调用方从
+        `KNOWN_TARGET_TABLES` 那一份清单里把名字递进来 —— 不递的话 `target` 是空串，
+        而 `_meta` 给的是 `'Group'` ⇒ 判据"两份形状必须同形"当场红
+        （列与指向都对，只有名字那一格空着）。
     :param external: 这一条是**靠 `KNOWN_TARGET_TABLES` 兜出来的**（对端是 Django 自带的表）。
         多带一个 `origin` 键：`gitinfo` 会把这几条从基线里剔掉 —— 它们的**正向声明**
         在 Django 的源码里（本项目一行都没有），留着会在画布上变成一条常年不消的"新增"。
@@ -1635,7 +1717,7 @@ def _relation(
         'field': name,
         'kind': kind,
         'cardinality': cardinality,
-        'target': target.name if target is not None else '',
+        'target': target.name if target is not None else target_name,
         'targetTable': target_table or (target.name if target is not None else ''),
         'column': column,
         'via': via,

{labull_framework-1.0.0 → labull_framework-1.0.2}/labull_framework/env.py

@@ -14,11 +14,11 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Mapping
 
-from .magic_block.sdk import BLOCK_DEEPCHECK, BLOCK_PROBE, BLOCK_REQUIRES
+from .magic_block.sdk import BLOCK_CONFIG_PREFIX, BLOCK_DEEPCHECK, BLOCK_PROBE, BLOCK_REQUIRES
 
 #: 给块的配置前缀：`BLOCK_OCR_KEY=abc` ⇒ 块后端里 `ctx.config['OCR_KEY'] == 'abc'`。
 #: 🔴 这是**白名单**（不是黑名单）：想让块读一项，就给那个变量加这个前缀，不用改库的代码。
-BLOCK_CONFIG_PREFIX = 'BLOCK_'
+#: ⚠️ 字面量的真源在 `sdk`（上面那行 import）—— 这里**不许**再写一遍 `'BLOCK_'`。
 
 #: `.env` 里一行的形状。允许 `export` 前缀、行首缩进、`=` 两边空白；
 #: 🔴 **不剥行内注释**（值里真带 `#` 的密钥不该被截断）、**不做变量展开**（那会让"谁先谁后"变成隐式规则）。
@@ -201,11 +201,14 @@ ENV_ITEMS: tuple[EnvItem, ...] = (
         group='平台开关',
     ),
     # 🔴 依赖声明（`requires`）那一层的开关（名字的真源在 `magic_block/sdk.py`）：
-    #    默认 `warn` —— 存量块的清单里一个声明都没有，一上线就硬报错等于让每个块集体停用。
+    #    默认 `error`（1.0.1 起）—— "先警告、后强制"里的**后强制**已经落地了。
+    #    ⚠️ 代价如实说：库里那些**还没声明**的存量块会集体判不合格（全部停用），
+    #       所以升级前先用 `manage.py labull_requires --write` 把扫得到的声明批量补进库
+    #       （那条命令就是为这个默认值而存在的：它是这条路上唯一的恢复口）。
     EnvItem(
         name=BLOCK_REQUIRES,
-        brief='块「依赖声明」（requires）那一层的开关：off 整段不跑 / warn（默认）只提示不拦 / error 变成硬判据',
-        hint=f'{BLOCK_REQUIRES}=error',
+        brief='块「依赖声明」（requires）那一层的开关：off 整段不跑 / warn 只提示不拦（要显式写）/ error（默认）变成硬判据',
+        hint=f'{BLOCK_REQUIRES}=warn',
         group='平台开关',
     ),
     # 🔴 体检那条链一次开几个口子（名字的真源在 `magic_block/parallel.py` 的 `ENV_WORKERS`）。

{labull_framework-1.0.0 → labull_framework-1.0.2}/labull_framework/magic_block/blockpackage.py

@@ -30,10 +30,7 @@ import ast
 from dataclasses import dataclass, field
 from typing import Any
 
-from .sdk import BLOCK_BACKEND_FILE, is_excluded
-
-#: 块后端的入口文件（**契约**：这个名字不变；它同时是"主文件"）。
-ENTRY_FILE = BLOCK_BACKEND_FILE
+from .sdk import is_excluded
 
 
 def python_files(files: dict[str, str] | None) -> list[tuple[str, str]]:
@@ -56,24 +53,13 @@ def python_files(files: dict[str, str] | None) -> list[tuple[str, str]]:
 class LoadedBlock:
     """一次加载的结果。
 
-    · `namespaces`：每个 `.py` 各一份命名空间（键是包内相对路径）；
     · `classes`：**包里所有文件**里定义的类（`类名 → 类`）—— 路由判据要它；
     · `errors`：逐条"哪个文件怎么了"（作者一眼看得出是哪一份的问题）。
     """
 
-    namespaces: dict[str, dict[str, Any]] = field(default_factory=dict)
     classes: dict[str, type] = field(default_factory=dict)
     errors: list[str] = field(default_factory=list)
 
-    @property
-    def ok(self) -> bool:
-        return not self.errors
-
-    @property
-    def namespace(self) -> dict[str, Any]:
-        """主文件那份命名空间（老调用点用得多；主文件不在包里就是空的）。"""
-        return self.namespaces.get(ENTRY_FILE, {})
-
 
 def load_block(files: dict[str, str], tag: str = '') -> LoadedBlock:
     """把包内每个 `.py` 各执行一次（互不影响），收集它们的类。
@@ -90,7 +76,6 @@ def load_block(files: dict[str, str], tag: str = '') -> LoadedBlock:
         except BaseException as exc:  # noqa: BLE001 —— 逐文件报，不让它带崩别的文件
             result.errors.append(f'{relative} 加载失败：{type(exc).__name__}: {exc}')
             continue
-        result.namespaces[relative] = namespace
         for name, value in namespace.items():
             # 只看**这个文件自己定义**的公开类（`import` 进来的名字也在命名空间里，但它们
             # 属于别的文件 —— 那样同一个类会被扫两遍、还可能把项目里的类当成路由类）。

{labull_framework-1.0.0 → labull_framework-1.0.2}/labull_framework/magic_block/deepcheck.py

@@ -509,6 +509,9 @@ def _any_probe_note():
 #    走，所以不额外起进程；`LABULL_REQUIRES=off` 时父进程根本不递（整段不跑）。
 # 🔴 **"代码用了却没声明"不在这里**（那一半是纯 `ast`，落在 `validate.check_requires`）：
 #    两半分开放，是因为这一半要运行环境、那一半不要 —— 混在一起会让"没 Django 时连静态判据都没跑"。
+# 🔴 **分档不在这里**（`warn` / `error` 是父进程的事，而 `LABULL_REQUIRES` 的默认档
+#    1.0.1 起是 `error`；`warn` 要显式写）：这一层只报"事实"，落位由 `_requires_check()` 按
+#    父进程递进来的 `mode` 做 —— 分档只有一处判据（`validate.requires_mode()`），两处各判一次迟早漂。
 
 _REQUIRES = _GIVEN.get('requires') if isinstance(_GIVEN.get('requires'), dict) else None
 
@@ -589,8 +592,8 @@ def _model_of(path):
 def _requires_hard():
     """"声明了但它不存在"的逐条报文（**确定**的那一档）。
 
-    ⚠️ 这里**不分档**（`warn` / `error` 是父进程的事）：这一层只报"事实"，
-       分档只有一处判据（`validate.requires_mode()`），两处各判一次迟早漂。
+    ⚠️ 这里**不分档**（`warn` / `error` 是父进程的事，默认档见 `validate.requires_mode()`）：
+       这一层只报"事实"，而分档只有一处判据，两处各判一次迟早漂。
     """
     import importlib
     from importlib import metadata
@@ -659,9 +662,11 @@ def _requires_hard():
 
 
 def _requires_check():
-    """跑一遍依赖声明的"存不存在"，并按开关落位（`warn` ⇒ 只进备注）。
+    """跑一遍依赖声明的"存不存在"，并按开关落位（`error` ⇒ 硬判据；`warn` ⇒ 只进备注）。
 
     ⚠️ 判据自己崩了**不算这个块的错**（软失败口径见文件头）：只记一句说明。
+    ⚠️ 兜底值与 `validate.requires_mode()` 的默认档**必须同一个**（1.0.1 起是 `error`）：
+       写 `warn` 的话，一份没有 `mode` 键的 payload 会悄悄退回 1.0.0 的旧行为。
     """
     if not _REQUIRES:
         return
@@ -673,7 +678,7 @@ def _requires_check():
         return
     if not hard:
         return
-    if str(_REQUIRES.get('mode') or 'warn') == 'error':
+    if str(_REQUIRES.get('mode') or 'error') == 'error':
         for message in hard:
             _STATIC.append(_issue('requires', message))
         return
@@ -809,6 +814,11 @@ def _value_model(node, imports):
         model = _manager_of(func.value)
         if model is None and isinstance(func.value, ast.Call):
             model = _value_model(func.value, imports)  # 链子的里层必须自己也是"查这批 / 查一行"
+            # 🔴 这一行与 `validate._manager_model()` 是**同一个口径**（那一份也是"一个循环同时剥
+            #    `Call` 与 `Attribute`、中间夹着 Call 也照样往左走"）。两处**必须一起改** ——
+            #    一份真源做不到：那边是 `%` 拼出来的子进程模板字符串，这边是普通函数。
+            #    只改一边的症状：`surface` 草稿与深检对同一个模型各说一套（用户截图报的漏建议
+            #    `StockTransaction.log_event` 就是 `_manager_model` 那一侧停了、这一侧没停）。
         if model is None:
             return None
         # 🔴 "查一批"也算（`for row in OrderRow.objects.all()` 里的 iter 就是这一句）：