labull-framework 3.0.7__tar.gz → 3.0.9__tar.gz

{labull_framework-3.0.7/labull_framework.egg-info → labull_framework-3.0.9}/PKG-INFO

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

{labull_framework-3.0.7 → labull_framework-3.0.9}/labull_framework/magic_block/devkit.py

@@ -1583,7 +1583,7 @@ def dev_doc(blocks: int) -> str:
 9. **业务功能说明写在块包内的 `README.open.md` 里、不在清单里**（`brief` 只是清单里那句短话）：写业务用途、谁在什么场景用、输入输出的含义与边界；`detail` 是遗留键，老块里还留着的话读回时会搬进这个文件。**它每一趟都要跟着改**：这一版块变成什么样，它就写成什么样 —— 老功能的说明不做保留地删掉（与第 5 节"改老功能就整段删掉旧的"是同一条规矩，只是落在文档上）。
 10. **依赖声明写在清单的 `requires` 里**（可选）：项目模型 / pip 包 / settings 键 / `BLOCK_*` 变量 / 跨块地址这些用到就声明 —— 它**不授予任何能力**，只是让平台把"外部依赖"核对一遍、换项目或改配置后替你**报出来**；草稿不用手写，导出的 `requires.open.yaml` 会把建议写在注释里，读回时**只合并**那一处。
 11. **块完全独立、不许跨块**：块与块之间**不共享文件、不共享代码、不互相引用** —— 你要用的东西就在这个块自己的文件夹里。规矩适用于所有方向：不去读 / 引另一个块的任何文件，不把"公共文件"放在 `workspace/` 顶层或两个块之间指望两个块共用，也不假设自己的代码会被别的块用到。**一份代码要服务两个块就只有两个合法去处**：各块里**各写一份**（复制），或者放进**项目**里的公共模块（那是普通 Python，块后端能 import —— 见第 1 节 `requires` 怎么报备；⚠️ 加这个公共模块要动**项目**的代码，按规矩 13 先问用户）。前端更简单：包内相对路径引用的文件**必须在这个块文件夹里**，`../` 爬到别的块去的一律不算（宿主也不会替你内联它）。
-12. **所有弹窗都走 `MagicBlockDialogs`**：块里**不许自己画弹窗 / 浮层 / 遮罩**（`position: fixed` / `100vh` / 手写 `.modal` 那一类）。要弹就 `await magicBlock.dialog({{…}})`，由**应用根上挂的那一个 `<MagicBlockDialogs />`** 在真视口里渲染（块可以有好几屏高，自己画的浮层会被摆到看不见的地方）；要自己写整篇就传 `{{ html }}`，里面用 `magicBlock.done({{…}})` 交回选择。应用那边没挂 `<MagicBlockDialogs />` 时调用会**当场报一句人话**（不是静默失败）。
+12. **所有弹窗都走 `MagicBlockDialogs`**：块里**不许自己画弹窗 / 浮层 / 遮罩**（`position: fixed` / `100vh` / 手写 `.modal` 那一类）。要弹就 `await magicBlock.dialog({{…}})`，由**应用根上挂的那一个 `<MagicBlockDialogs />`** 在真视口里渲染（块可以有好几屏高，自己画的浮层会被摆到看不见的地方）；要自己写整篇就传 `{{ html }}`，里面用 `magicBlock.done({{…}})` 交回选择。**弹窗多大不用你算**：`{{ html }}` 那一型的面板**按内容定高**（短的就小的、长了到 `90dvh` 封顶后整篇自滚），`size.height` 只是**上限**不是"必须占这么高"；而且**露面之后尺寸固定**（内容再变多只在里面滚，不会"先小后大"）⇒ 异步取的数据要在 `dialog()` 之前 await 好。**要看原图 / PDF 别塞进 `html`**（那条 512 KB 上限会把图缩掉）：走 `dialog({{ html, assets: {{ 名字: dataURL }} }})` + 弹窗里 `await magicBlock.assets()`。应用那边没挂 `<MagicBlockDialogs />` 时调用会**当场报一句人话**（不是静默失败）。
 13. **一趟只动一个块，越界先问**：每次开发**只在当前 workspace 的一个块里**做。要动**第二个块**、或者要改**平台的前后端代码**（`backend/` / `frontend/`），**必须先向用户提问、得到同意才继续**；块里**不许把平台代码当自己的改**（它不进块包，还会影响别的块）。展开见 2.1。
 
 > 拿不准就把"我打算这么做"写下来先说一遍 —— 这里面的多数是"想清楚就不会犯"的。

{labull_framework-3.0.7 → labull_framework-3.0.9}/labull_framework/magic_block/service.py

@@ -68,6 +68,28 @@ class BlockNotFound(Exception):
         self.status = 404
 
 
+def block_type_of(files: dict[str, str] | None) -> tuple[str, str]:
+    """这一包的**块类型**：`(清单里写的名字, 中文标签)`。
+
+    🔴 回话里的 `type` 就是它：管理台按它决定"这一块要不要多显示一段"（流程块要画流程图，普通块不要）。
+    🔴 **不是判据**：这里不判"这个类型合不合法"（那是 `manifest` 与 `blocktypes.check()` 的事），
+       只把清单里那一格读出来。
+    ⚠️ 清单读不出来（缺 / 写坏）或类型不在注册表里 ⇒ `('', '')`：那是"不知道是哪一类"，
+       与"这是普通块"是两件事 —— 前端因此不会给一个坏清单画流程图。
+    """
+    from . import blocktypes  # 函数内 import：类型注册表要 import 各类型模块（含子进程那一套）
+
+    try:
+        found, problems = manifest.read_manifest(files or {})
+        if problems or not found:
+            return '', ''
+        name = blocktypes.declared(found)
+    except Exception:  # noqa: BLE001 —— 清单读不出来不该让整份清单请求炸掉
+        return '', ''
+    kind = blocktypes.get(name)
+    return name, (kind.label if kind is not None else '')
+
+
 class MagicBlockService:
     """块的存储与下发（无状态：状态在库里 + 注册表的缓存里）。"""
 
@@ -154,6 +176,10 @@ class MagicBlockService:
         🔴 这里算的 `code`（有效代码行数）**只回数字与一份按文件的明细，不回正文**：
            控制台要的是"这块有多大"，而不是把每个块的代码都拉到浏览器里
            （20 个块一起拉就是几百 KB 的白流量）。
+        🔴 `type` / `typeLabel` 是**块类型**（清单里的 `type:`）：控制台按它决定"这一块要多显示什么"
+           —— 流程块点开要画流程图（`GET /magic-blocks/<id>/flow`），普通块不多显示任何东西。
+           ⚠️ 这里只读清单那一格（`block_type_of`），**不跑 `flow.py`**：跑一遍是子进程、每块 0.4 秒，
+           挂在这条"打开抽屉就要一次"的口上不合适。
         🔴 算它必须读 `files` 那一列（清单上别的字段都不用），所以下面用 `.only(...)`
            把列收窄到"清单要的 + files"—— `health_issues` 那几列在大块上不小。
         """
@@ -179,6 +205,7 @@ class MagicBlockService:
             tags = self.normalize_tags(row.tags)
             if wanted and wanted not in [item.lower() for item in tags]:
                 continue
+            type_name, type_label = block_type_of(row.files or {})
             out.append(
                 {
                     'id': row.id,
@@ -195,6 +222,11 @@ class MagicBlockService:
                     'enabled': _enabled_of(row),
                     'disabledReason': row.disabled_reason or '',
                     'issues': health_issues(row),
+                    # 🔴 **块类型**（清单里 `type:` 那一格）：控制台按它决定"点开这一块要多显示什么"。
+                    #    普通块（plain，缺省）不需要多余的展示；流程块要画 `flow.py` 里那条流程图。
+                    #    ⚠️ 只读清单，不执行 `flow.py`（见 docstring 最后那一条）。
+                    'type': type_name,
+                    'typeLabel': type_label,
                     'updatedAt': iso(row.updated_at),
                     'fileNames': sorted_files(row.files or {}),
                     # 🔴 **代码行数**（控制台那一栏）：`{total, files, byFile}`。
@@ -529,6 +561,33 @@ class MagicBlockService:
             raise SaveRejected('写完详情之后读不回来，请检查数据库连接')
         return saved
 
+    # ──────────────────────────── 流程声明（流程图那一条口） ────────────────────────────
+    def flow(self, block_id: str) -> dict:
+        """这一块的**流程声明快照**（`flow.py` 里那条 `Flow` 的归一化形状；管理台画流程图用）。
+
+        :returns: `{id, type, typeLabel, spec}` —— `spec` 是 `Flow.spec()` 那一份纯数据，
+            不是流程块 / `flow.py` 跑不起来 / 注册了不止一条 ⇒ **`None`**（不是 500）。
+
+        🔴 为什么是**单独一条口**、不塞进 `index()`：这份快照要在**子进程**里把 `flow.py` 跑一遍
+           （`blocktypes.spec_of`，结论按整包正文的摘要缓存）。挂在"打开抽屉就会请求"的清单上，
+           块一多就是每块 0.4 秒 × N；而点开某一块时等一次是值得的。
+        🔴 拿不到快照**不报错**：流程图那一栏会照实说"算不出来"，原因在那几条体检结论里
+           （`health_issues` 早把 `flow.py` 的报错原文列出来了）—— 这里再造一份文案就是第二处真源。
+        """
+        row = self.get(block_id)
+        if row is None:
+            raise BlockNotFound(f'没有这个 magic block：{block_id}')
+        files = dict(row.files or {})
+        from . import blocktypes  # 函数内 import：类型注册表会 import 各类型模块（含子进程那一套）
+
+        name, label = block_type_of(files)
+        return {
+            'id': row.id,
+            'type': name,
+            'typeLabel': label,
+            'spec': blocktypes.spec_of(files),
+        }
+
     # ──────────────────────────── 版本史 ────────────────────────────
     def versions(self, block_id: str) -> list[dict]:
         """这一块的版本列表（**新的在前**）：`number / files 数 / 谁传的 / 什么时候 / 是不是当前**。

{labull_framework-3.0.7 → labull_framework-3.0.9}/labull_framework/magic_block/views.py

@@ -27,6 +27,7 @@ from .service import (
     MagicBlockService,
     SaveRejected,
     api_dts,
+    block_type_of,
     health_issues,
     iso,
     sorted_files,
@@ -137,6 +138,7 @@ def _row_view(row: Any) -> dict:
     """
     service = MagicBlockService()
     routes, dts = service.api_manifest(row.id)
+    type_name, type_label = block_type_of(row.files or {})
     return {
         'id': row.id,
         'module': row.module,
@@ -147,6 +149,10 @@ def _row_view(row: Any) -> dict:
         'detail': row.detail or '',
         # 依赖声明（清单里那个可选的 `requires`）：块详情里那一栏"依赖"读它。
         'requires': requires.requires_declared(row.files or {})[0],
+        # 块类型（清单里 `type:` 那一格）+ 中文标签：控制台按它决定"这一块要多显示什么"
+        # （流程块点开画流程图，普通块不多显示）。空串 = 清单读不出来 / 类型不在注册表里。
+        'type': type_name,
+        'typeLabel': type_label,
         'enabled': row.enabled is not False,
         'disabledReason': row.disabled_reason or '',
         'issues': health_issues(row),
@@ -275,6 +281,28 @@ def detail_field_view(request: HttpRequest, block_id: str) -> HttpResponse:
     return _json(_row_view(row))
 
 
+@edit_only
+def flow_view(request: HttpRequest, block_id: str) -> HttpResponse:
+    """`GET /magic-blocks/<id>/flow` —— 这一块的**流程声明快照**（管理台画流程图用）。
+
+    回话：`{id, type, typeLabel, spec}`。`spec` 是 `flow.py` 里那条 `Flow` 的归一化形状
+    （状态 / 动作 / 谁能办 / 内容 key，见 `flow.Flow.spec()`），`None` = 不是流程块 / 算不出来。
+
+    🔴 为什么单独一条口（用户要求"workflow 块点进去可以看到由 flow.py 构建的流程图"）：
+       快照要在**子进程**里真的把 `flow.py` 跑一遍（`blocktypes.spec_of`，按包正文摘要缓存）。
+       塞进 `GET /magic-blocks/index` 的话，打开抽屉就要为每个块付一次子进程的钱。
+    🔴 `spec` 拿不到时回 **200 + `null`**，不是 404 / 500：块本身没问题，只是"这条流程声明算不出来"
+       —— 原因已经在那几条体检结论里了（`issues` 带 `flow.py` 的报错原话），这里不另写一份话。
+    """
+    refused = _method(request, 'GET')
+    if refused is not None:
+        return refused
+    try:
+        return _json(MagicBlockService().flow(block_id))
+    except BlockNotFound as exc:
+        return problem(exc.message, 404)
+
+
 @edit_only
 def versions_view(request: HttpRequest, block_id: str, number: str | None = None) -> HttpResponse:
     """`/magic-blocks/<id>/versions[/<number>]` —— 版本史的读、切、删、下。

{labull_framework-3.0.7 → labull_framework-3.0.9}/labull_framework/urls.py

@@ -79,6 +79,9 @@ urlpatterns: list[Any] = [
     # 🔴 只改详情介绍那一条，同一个理由（详情是"给人读的一段话"，不是代码）。
     #    ⚠️ 与 `labull-blocks-detail`（`magic-blocks/<block_id>` 那一行本身）不是一回事。
     path('magic-blocks/<str:block_id>/detail', block_views.detail_field_view, name='labull-blocks-detail-field'),
+    # 🔴 流程声明那一条（管理台画流程图）：`flow.py` 的归一化快照，**按需取、一次一块**
+    #    （算一次要起子进程跑 `flow.py`，不能挂在"打开抽屉就要请求"的那条清单口上）。
+    path('magic-blocks/<str:block_id>/flow', block_views.flow_view, name='labull-blocks-flow'),
     # 🔴 版本史那一条排在 `<block_id>` **之前**（同一个理由：路径前缀更长的那条要先匹配）。
     #    `GET/POST/DELETE …/versions[/<n>]` 五个动作都在同一个视图里分流（见 `versions_view`）。
     re_path(r'^magic-blocks/(?P<block_id>[^/]+)/versions(?:/(?P<number>\d+))?$',

{labull_framework-3.0.7 → labull_framework-3.0.9/labull_framework.egg-info}/PKG-INFO

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

{labull_framework-3.0.7 → labull_framework-3.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "labull-framework"
-version = "3.0.7"
+version = "3.0.9"
 description = "Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks"
 readme = "README-pypi.md"
 requires-python = ">=3.10"