labull-framework 0.1.32__tar.gz → 0.1.34__tar.gz

{labull_framework-0.1.32/labull_framework.egg-info → labull_framework-0.1.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 0.1.32
+Version: 0.1.34
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT
@@ -134,6 +134,82 @@ class Order:
 
 配置：环境变量里**带 `BLOCK_` 前缀**的才会进 `ctx.config`（`BLOCK_OCR_KEY=a` ⇒ `ctx.config['OCR_KEY']`）。
 
+## 虚拟类（`@virtual_class`）
+
+几张表共有同一批列时，写一个**虚拟类**：一个**不建表的抽象模型**，自己那几列会被继承到子表上。
+
+```python
+from django.db import models
+from labull_framework.virtual import virtual_class, VirtualModel
+
+
+@virtual_class
+class Contact(VirtualModel):
+    """联系人：个人与单位共有的那几列。"""
+    name = models.CharField('名称', max_length=64)
+
+    class Meta:
+        abstract = True          # 🔴 必须有（见下）
+
+
+class Person(Contact):
+    birthday = models.DateField('生日', null=True, blank=True)
+
+
+class Company(Contact):
+    tax_no = models.CharField('税号', max_length=32, blank=True, default='')
+```
+
+`Person` / `Company` 的表里**真的有** `name` 这一列（Django 把抽象基类的字段复制进子类）；
+而 `makemigrations` **只为这两张具体表建表** —— `Contact` 在库里没有对应的表。
+
+两条会真的出错的判据：
+
+1. **`class Meta: abstract = True` 不能省**（`@virtual_class` 替不了它：Django 在 `ModelBase` 里
+   读的是**类体那个 `Meta`**，读完就把非抽象模型登记进 app registry 了）。漏了会让这个类**真的建一张表**，
+   所以装饰器发现这件事时**当场抛 `TypeError`** 并把该补的那一行写给你。
+2. **`@virtual_class` 写在所有装饰器的最上面**（它执行时那个类必须已经是一个 Django 模型）；
+   另外**外键不能指向虚拟类**（抽象模型没有 `objects`，Django 在 `manage.py check` 就拦下）。
+
+`LABULL_SCHEMA_CANVAS=on` 时打开 `/`：虚拟类是一张带 `◇` 的虚线卡片（写着"不建表"与"谁在继承它"），
+继承它的表表头挂着「**◇ 泛化 · Contact**」—— 鼠标停一下看泛化名与整条链，点一下跳过去。
+改动（含"哪张表的泛化父类变了"）与表一样进画布那份差异。
+
+### 平台自带：WorkflowModel（流转记录）
+
+要记"这件事是谁、什么时候、怎么走过来的"的表，**继承它就行**（不用自己写抽象基类）：
+
+```python
+from django.db import models
+from labull_framework.models import WorkflowModel
+
+
+class PurchaseOrder(WorkflowModel):
+    """采购申请：全过程记在继承来的 log 那一列里。"""
+    title = models.CharField('标题', max_length=128)
+
+    class Meta:
+        verbose_name = '采购申请'      # 🔴 一定要自己写（不然继承来的是基类那个名字）
+```
+
+它给子表带上三列：`log`（流转日志，JSON 数组）、`created_at`（创建时间）与 `updated_at`（自动时间）。
+读写走类上的助手，别在调用点自己拼字典：
+
+```python
+WorkflowModel.append_log(row, 'submit', actor=user.name, note='提交审批')
+row.save(update_fields=['log'])
+WorkflowModel.log_of(row)              # → [{'at': ..., 'action': 'submit', ...}, ...]
+WorkflowModel.last_log(row, 'approve') # → 最后一次批准（没有就 None）
+```
+
+画布上它是一张带 `◇` 的**虚拟卡片**（在 `labull_framework` 模块里），
+继承它的表表头挂着「◇ 泛化 · WorkflowModel」。
+
+- **当前状态用列**（要能筛选、能索引），`log` 只回答"怎么走到这一步的"。
+- `log` 是**一列 JSON、不是一张子表**（刻意取舍）：代价是跨表查流水要全表扫 JSON ——
+  真到那一步就该给它建一张真表。
+- 🔴 **块后端不要 import 它**（平台内部模型），开发包的清单里也不会给出那句 import 提示。
+
 ## 运行环境
 
 - Python ≥ 3.10

{labull_framework-0.1.32 → labull_framework-0.1.34}/README-pypi.md

@@ -106,6 +106,82 @@ class Order:
 
 配置：环境变量里**带 `BLOCK_` 前缀**的才会进 `ctx.config`（`BLOCK_OCR_KEY=a` ⇒ `ctx.config['OCR_KEY']`）。
 
+## 虚拟类（`@virtual_class`）
+
+几张表共有同一批列时，写一个**虚拟类**：一个**不建表的抽象模型**，自己那几列会被继承到子表上。
+
+```python
+from django.db import models
+from labull_framework.virtual import virtual_class, VirtualModel
+
+
+@virtual_class
+class Contact(VirtualModel):
+    """联系人：个人与单位共有的那几列。"""
+    name = models.CharField('名称', max_length=64)
+
+    class Meta:
+        abstract = True          # 🔴 必须有（见下）
+
+
+class Person(Contact):
+    birthday = models.DateField('生日', null=True, blank=True)
+
+
+class Company(Contact):
+    tax_no = models.CharField('税号', max_length=32, blank=True, default='')
+```
+
+`Person` / `Company` 的表里**真的有** `name` 这一列（Django 把抽象基类的字段复制进子类）；
+而 `makemigrations` **只为这两张具体表建表** —— `Contact` 在库里没有对应的表。
+
+两条会真的出错的判据：
+
+1. **`class Meta: abstract = True` 不能省**（`@virtual_class` 替不了它：Django 在 `ModelBase` 里
+   读的是**类体那个 `Meta`**，读完就把非抽象模型登记进 app registry 了）。漏了会让这个类**真的建一张表**，
+   所以装饰器发现这件事时**当场抛 `TypeError`** 并把该补的那一行写给你。
+2. **`@virtual_class` 写在所有装饰器的最上面**（它执行时那个类必须已经是一个 Django 模型）；
+   另外**外键不能指向虚拟类**（抽象模型没有 `objects`，Django 在 `manage.py check` 就拦下）。
+
+`LABULL_SCHEMA_CANVAS=on` 时打开 `/`：虚拟类是一张带 `◇` 的虚线卡片（写着"不建表"与"谁在继承它"），
+继承它的表表头挂着「**◇ 泛化 · Contact**」—— 鼠标停一下看泛化名与整条链，点一下跳过去。
+改动（含"哪张表的泛化父类变了"）与表一样进画布那份差异。
+
+### 平台自带：WorkflowModel（流转记录）
+
+要记"这件事是谁、什么时候、怎么走过来的"的表，**继承它就行**（不用自己写抽象基类）：
+
+```python
+from django.db import models
+from labull_framework.models import WorkflowModel
+
+
+class PurchaseOrder(WorkflowModel):
+    """采购申请：全过程记在继承来的 log 那一列里。"""
+    title = models.CharField('标题', max_length=128)
+
+    class Meta:
+        verbose_name = '采购申请'      # 🔴 一定要自己写（不然继承来的是基类那个名字）
+```
+
+它给子表带上三列：`log`（流转日志，JSON 数组）、`created_at`（创建时间）与 `updated_at`（自动时间）。
+读写走类上的助手，别在调用点自己拼字典：
+
+```python
+WorkflowModel.append_log(row, 'submit', actor=user.name, note='提交审批')
+row.save(update_fields=['log'])
+WorkflowModel.log_of(row)              # → [{'at': ..., 'action': 'submit', ...}, ...]
+WorkflowModel.last_log(row, 'approve') # → 最后一次批准（没有就 None）
+```
+
+画布上它是一张带 `◇` 的**虚拟卡片**（在 `labull_framework` 模块里），
+继承它的表表头挂着「◇ 泛化 · WorkflowModel」。
+
+- **当前状态用列**（要能筛选、能索引），`log` 只回答"怎么走到这一步的"。
+- `log` 是**一列 JSON、不是一张子表**（刻意取舍）：代价是跨表查流水要全表扫 JSON ——
+  真到那一步就该给它建一张真表。
+- 🔴 **块后端不要 import 它**（平台内部模型），开发包的清单里也不会给出那句 import 提示。
+
 ## 运行环境
 
 - Python ≥ 3.10

{labull_framework-0.1.32 → labull_framework-0.1.34}/labull_framework/canvas/__init__.py

@@ -2,7 +2,8 @@
 
 **没有前端工程、没有构建、没有生成物、不读任何项目文件**：
 "当前长什么样"直接读 Django 的模型元数据（进程内的 `_meta`），
-"上一版长什么样"从 git 的那个提交里取一份模型形状 JSON（取不到就只画当前这份）。
+"上一版长什么样"是**从那个提交的源码现算的**（`ast` 解析那个提交里的 `models.py`，
+起不来时退回提交里那份契约 JSON）—— 见 `gitinfo.py` 的文件头，那里是这一条的真源。
 
 🔴 默认**关**：一个环境变量打开（`LABULL_SCHEMA_CANVAS` = `on` / `auto` / `off`）。
    这一页把全部表名、字段名、关联、备注摊在一个 URL 上 —— 那是业务结构本身，
@@ -11,6 +12,9 @@
 🔴 **打开之后这一页不看身份**（不需要登录，也不要求 staff）：它是开发期调模型用的工具，
    每次看一眼都要先去 Authing 转一圈太碍事。所以那道**开关就是唯一的边界**：
    只在开发机上开 `on`，公网要么别开、要么在反向代理那一层加 Basic 认证 / IP 白名单。
+
+🔴 图上有**两类节点**：库里的**表**，以及**虚拟类**（`@virtual_class` 的抽象模型，不建表 ——
+   见 `labull_framework/virtual.py` 的文件头）。两份都是"从真源算出来的"，这里不需要额外维护什么。
 """
 
 from __future__ import annotations