labull-framework 1.4.1__tar.gz → 3.0.0__tar.gz

{labull_framework-1.4.1/labull_framework.egg-info → labull_framework-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 1.4.1
+Version: 3.0.0
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT
@@ -93,7 +93,8 @@ CORS_ORIGIN=http://localhost:5173
 
 | 想要什么 | 怎么做 |
 |---|---|
-| **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
+| **谁是管理员** | 判据是**权限** `labull_framework.edit_magic_block`（不是组名、不是 `is_staff`）。配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人加进**持有那个权限的组**（按权限找组，改组名不影响），**名单之外的一律摘掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
+| **默认组（权限包）** | **默认就有**：SDK 的 `0006` 迁移建「平台管理员」（`edit_magic_block` / `manage_users` / `view_magicblock`）与「普通用户」（`view_magicblock`）两个组，**只建组和权限、不加人**。组名只是标签，判据永远是权限；新用户默认进哪个组由**项目自己的 `post_save`** 决定（框架不装） |
 | **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
 | **块的依赖声明不许"用了却没声明"** | 它是**默认**行为（`LABULL_REQUIRES=error`，1.0.1 起）：代码里用了没声明的东西 ⇒ 拦住保存。⚠️ 升级前先在项目里跑一遍 `python manage.py labull_requires --write` 把存量块扫得到的声明补进库；`warn`（只提示不拦）与 `off`（整段不跑）都要**显式**写 |
 | **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |

{labull_framework-1.4.1 → labull_framework-3.0.0}/README-pypi.md

@@ -1,205 +1,206 @@
-# labull-framework
-
-一个可插拔的 **Django app**（import 名 `labull_framework`），提供两件事：
-
-- **Authing / OIDC 登录**：自带的认证后端，只用标准库 + PyJWT，不依赖任何 OIDC 客户端包。
-- **magic block**：一个 uuid + 一整个文件包就是一个功能块，住在数据库里、在沙箱 iframe 里渲染，
-  不重新编译、不重启；块可以带自己的后端 Python（`backend_open.py`）。
-
-另附一个可选的 **数据模型页**（`LABULL_SCHEMA_CANVAS=on` 才开）。
-
-## 安装
-
-```bash
-pip install labull-framework
-```
-
-## 接进一个 Django 项目
-
-`settings.py` 里三件事：
-
-```python
-from labull_framework.env import load_env_file
-load_env_file(BASE_DIR / '.env')            # ① 第一行：读 .env
-
-AUTH_USER_MODEL = 'labull_framework.User'   # ② 第一次 migrate 之前就要设好
-
-from labull_framework.settings import apply_platform_settings
-apply_platform_settings(globals())          # ③ 最后一行：把平台的设置补进来
-```
-
-`urls.py` 里一行：
-
-```python
-from labull_framework.urls import urlpatterns as labull_urls
-urlpatterns = [*labull_urls, path('admin/', admin.site.urls)]
-```
-
-`wsgi.py` 里一行（**别漏**，重设管理员名单与启动体检都在这里）：
-
-```python
-from labull_framework.magic_block.health import startup_once
-startup_once()
-```
-
-然后：
-
-```bash
-python manage.py migrate
-python manage.py runserver
-```
-
-`.env` 最少要这几项：
-
-```ini
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/app
-SSO_ISSUER=https://<你的域名>.authing.cn/oidc
-SSO_CLIENT_ID=<Authing 应用 ID>
-SSO_CLIENT_SECRET=<Authing 应用密钥>
-SSO_REDIRECT_URI=http://localhost:8000/auth/callback
-SSO_WEB_ORIGIN=http://localhost:5173
-CORS_ORIGIN=http://localhost:5173
-```
-
-`sqlite:///db.sqlite3` 也认，本地开发不必装数据库。
-
-| 想要什么 | 怎么做 |
-|---|---|
-| **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
-| **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
-| **块的依赖声明不许"用了却没声明"** | 它是**默认**行为（`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
-
-一个块 = **一个 uuid + 一整个文件包**：
-
-```
-我的块/
-├─ index.open.html        入口（必备）
-├─ magic-block.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
-│                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `BLOCK_*`）可选
-├─ README.open.md         **业务功能说明**（Markdown）：这一段的家就是这份文件，不在清单里
-│                         （**每个块都会有一份** —— 导出时无条件铺，没写就是空文件）
-├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的：正文进清单的 `requires`，注释是扫代码的建议）
-├─ 任意 js / css
-├─ .exclude/              你自己的地盘（测试 / 草稿）：**永远不进库**，也不跟着块走
-└─ backend_open.py        块自己的后端（可选）
-```
-
-测试 / 草稿 / 参考实现放块里的 `.exclude/`（老名字 `excluded/` 在迁移期照样认）：判据只有一条 ——
-**路径里有一段叫 `.exclude`**，与文件名怎么写无关（`test.py` / `_test.py` 一视同仁）。里面的东西
-**永远不进库**：导出不铺、读回不扫、保存不存、版本史里没有；「清空并导出」也不会删它，它是**你这台机器上的**
-草稿区。摆法是**一个需求一个文件夹**（`<日期>-<需求简称>`，最多留 3 个），测试代码与测试产物都放进去。
-平台不会替你跑它们，自己 `node` / `python` 跑：`node .exclude/<需求文件夹>/test.mjs`。
-
-块后端与项目里别的 Python 代码没有区别：
-
-```python
-from labull_framework.magic_block.sdk import MagicBackendAPI, errors
-
-class Order:
-    @MagicBackendAPI()                       # 省略 permission = 任何登录用户都能调
-    def list(self, ctx, params):
-        from modules.orders.models import Order
-        return [{'id': o.id} for o in Order.objects.all()[:20]]
-
-    @MagicBackendAPI(permission='labull_framework.edit_blocks')
-    def close(self, ctx, params):
-        if not params.get('id'):
-            raise errors.BadRequest('要给我一个 id')
-        return {'ok': True}
-```
-
-配置：环境变量里**带 `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`）
-
-几张表共有同一批列时，写一个**虚拟类**：一个**不建表的抽象模型**，自己那几列会被继承到子表上。
-
-```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
-- Django ≥ 4.2（在 6.1 上验证过）
-- PyJWT（带 `crypto` 后端）
-
-## License
-
-MIT
+# labull-framework
+
+一个可插拔的 **Django app**（import 名 `labull_framework`），提供两件事：
+
+- **Authing / OIDC 登录**：自带的认证后端，只用标准库 + PyJWT，不依赖任何 OIDC 客户端包。
+- **magic block**：一个 uuid + 一整个文件包就是一个功能块，住在数据库里、在沙箱 iframe 里渲染，
+  不重新编译、不重启；块可以带自己的后端 Python（`backend_open.py`）。
+
+另附一个可选的 **数据模型页**（`LABULL_SCHEMA_CANVAS=on` 才开）。
+
+## 安装
+
+```bash
+pip install labull-framework
+```
+
+## 接进一个 Django 项目
+
+`settings.py` 里三件事：
+
+```python
+from labull_framework.env import load_env_file
+load_env_file(BASE_DIR / '.env')            # ① 第一行：读 .env
+
+AUTH_USER_MODEL = 'labull_framework.User'   # ② 第一次 migrate 之前就要设好
+
+from labull_framework.settings import apply_platform_settings
+apply_platform_settings(globals())          # ③ 最后一行：把平台的设置补进来
+```
+
+`urls.py` 里一行：
+
+```python
+from labull_framework.urls import urlpatterns as labull_urls
+urlpatterns = [*labull_urls, path('admin/', admin.site.urls)]
+```
+
+`wsgi.py` 里一行（**别漏**，重设管理员名单与启动体检都在这里）：
+
+```python
+from labull_framework.magic_block.health import startup_once
+startup_once()
+```
+
+然后：
+
+```bash
+python manage.py migrate
+python manage.py runserver
+```
+
+`.env` 最少要这几项：
+
+```ini
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/app
+SSO_ISSUER=https://<你的域名>.authing.cn/oidc
+SSO_CLIENT_ID=<Authing 应用 ID>
+SSO_CLIENT_SECRET=<Authing 应用密钥>
+SSO_REDIRECT_URI=http://localhost:8000/auth/callback
+SSO_WEB_ORIGIN=http://localhost:5173
+CORS_ORIGIN=http://localhost:5173
+```
+
+`sqlite:///db.sqlite3` 也认，本地开发不必装数据库。
+
+| 想要什么 | 怎么做 |
+|---|---|
+| **谁是管理员** | 判据是**权限** `labull_framework.edit_magic_block`（不是组名、不是 `is_staff`）。配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人加进**持有那个权限的组**（按权限找组，改组名不影响），**名单之外的一律摘掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
+| **默认组（权限包）** | **默认就有**：SDK 的 `0006` 迁移建「平台管理员」（`edit_magic_block` / `manage_users` / `view_magicblock`）与「普通用户」（`view_magicblock`）两个组，**只建组和权限、不加人**。组名只是标签，判据永远是权限；新用户默认进哪个组由**项目自己的 `post_save`** 决定（框架不装） |
+| **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
+| **块的依赖声明不许"用了却没声明"** | 它是**默认**行为（`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
+
+一个块 = **一个 uuid + 一整个文件包**：
+
+```
+我的块/
+├─ index.open.html        入口（必备）
+├─ magic-block.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
+│                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `BLOCK_*`）可选
+├─ README.open.md         **业务功能说明**（Markdown）：这一段的家就是这份文件，不在清单里
+│                         （**每个块都会有一份** —— 导出时无条件铺，没写就是空文件）
+├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的：正文进清单的 `requires`，注释是扫代码的建议）
+├─ 任意 js / css
+├─ .exclude/              你自己的地盘（测试 / 草稿）：**永远不进库**，也不跟着块走
+└─ backend_open.py        块自己的后端（可选）
+```
+
+测试 / 草稿 / 参考实现放块里的 `.exclude/`（老名字 `excluded/` 在迁移期照样认）：判据只有一条 ——
+**路径里有一段叫 `.exclude`**，与文件名怎么写无关（`test.py` / `_test.py` 一视同仁）。里面的东西
+**永远不进库**：导出不铺、读回不扫、保存不存、版本史里没有；「清空并导出」也不会删它，它是**你这台机器上的**
+草稿区。摆法是**一个需求一个文件夹**（`<日期>-<需求简称>`，最多留 3 个），测试代码与测试产物都放进去。
+平台不会替你跑它们，自己 `node` / `python` 跑：`node .exclude/<需求文件夹>/test.mjs`。
+
+块后端与项目里别的 Python 代码没有区别：
+
+```python
+from labull_framework.magic_block.sdk import MagicBackendAPI, errors
+
+class Order:
+    @MagicBackendAPI()                       # 省略 permission = 任何登录用户都能调
+    def list(self, ctx, params):
+        from modules.orders.models import Order
+        return [{'id': o.id} for o in Order.objects.all()[:20]]
+
+    @MagicBackendAPI(permission='labull_framework.edit_blocks')
+    def close(self, ctx, params):
+        if not params.get('id'):
+            raise errors.BadRequest('要给我一个 id')
+        return {'ok': True}
+```
+
+配置：环境变量里**带 `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`）
+
+几张表共有同一批列时，写一个**虚拟类**：一个**不建表的抽象模型**，自己那几列会被继承到子表上。
+
+```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
+- Django ≥ 4.2（在 6.1 上验证过）
+- PyJWT（带 `crypto` 后端）
+
+## License
+
+MIT

{labull_framework-1.4.1 → labull_framework-3.0.0}/labull_framework/admin.py

@@ -1,6 +1,9 @@
 """Django admin 的注册处 —— 这个库**唯一**的管理界面。
 
 🔴 它就是 Django 原生的那一套：用户 / 组 / 权限的日常维护白拿，我们不写任何自己的管理页面。
+🔴 **授权只看 `Permission`**（`app_label.codename`）：组只是权限包（"组"里打包权限、"用户"里加组）；
+   平台自己的两个权限住在 `MagicBlock.Meta.permissions`（`edit_magic_block` / `manage_users`）。
+   两个默认组（`平台管理员` / `普通用户`）由迁移建好 —— 组名只是标签，代码不按它判断任何事。
 🔴 **块的代码在 admin 里只读**：它只能从 magic block 控制台写进去，因为那里有"保存即校验"那一关
    （`ast` + 子进程试加载）。admin 里放开编辑表单，就等于从 Django 的默认表单往库里塞
    **未经校验、之后会被 `exec` 执行**的代码，把"体检不过就停用"这套机制绕开。
@@ -20,17 +23,22 @@ class UserAdmin(admin.ModelAdmin):
 
     ⚠️ `username` 装的是 Authing 的 `sub`（登录时同步进来的），所以它**只读** ——
     改它等于把这一行与那个身份切开。
+    🔴 **"是不是平台管理员" = 有没有 `labull_framework.edit_magic_block`**（`permissions.is_admin()`）——
+    直接给在这个人身上、或者他所在的某个权限包里都算。这里不摆 `is_staff`：
+    那一列只留给 Django 自己的 `/admin`，平台不读它。
+    🔴 `groups` / `user_permissions` 两栏就是全部授权入口（组是权限包，权限码才是契约）。
+    新用户**不自动进任何组**：那是项目的数据/策略（框架不装 `post_save`）。
     """
 
-    list_display = ('username', 'work_id', 'name', 'is_staff', 'is_active', 'last_login')
-    list_filter = ('is_staff', 'is_superuser', 'is_active')
+    list_display = ('username', 'work_id', 'name', 'is_active', 'last_login')
+    list_filter = ('is_active', 'is_superuser')
     search_fields = ('username', 'work_id', 'name')
     ordering = ('-date_joined',)
     readonly_fields = ('username', 'last_login', 'date_joined')
     fieldsets = (
         (None, {'fields': ('username', 'password')}),
         ('身份', {'fields': ('work_id', 'name', 'email')}),
-        ('权限', {'fields': ('is_active', 'is_staff', 'is_superuser', 'groups', 'user_permissions')}),
+        ('权限', {'fields': ('is_active', 'is_superuser', 'groups', 'user_permissions')}),
         ('时间', {'fields': ('last_login', 'date_joined')}),
     )
 

{labull_framework-1.4.1 → labull_framework-3.0.0}/labull_framework/apps.py

@@ -1,33 +1,35 @@
-from __future__ import annotations
-
-from django.apps import AppConfig
-
-
-class LabullConfig(AppConfig):
-    """这个 app 的登记项。
-
-    🔴 `ready()` 里**只挂一个钩子，不碰数据库**：Django 对"在 `ready()` 里查库"会明确警告
-    （`Accessing the database during app initialization is discouraged`），而且新项目第一次
-    `migrate` 时表还不存在 —— 那时查库会让**整个命令**起不来。
-
-    🔴 启动时要做的两件事（重设管理员名单 → 全量体检）在 `wsgi.py` 里一行显式调用：
-        ```python
-        from labull_framework.magic_block.health import startup_once
-        startup_once()
-        ```
-        那一行是**契约**（函数名与签名都不要改）：`runserver` / gunicorn / uwsgi / ASGI
-        都从那里进来，所以它天然是"每个进程一次"的地方。
-    ⚠️ 它**不是** `post_migrate` 的替代：那个只在迁移之后发（管"库刚被改过"），
-        而启动体检只有 `startup_once()` 能做。
-    """
-
-    default_auto_field = 'django.db.models.BigAutoField'
-    name = 'labull_framework'
-    verbose_name = 'Labull Framework'
-
-    def ready(self) -> None:
-        # 延迟 import：此刻 app 注册表已经就绪，但避免模块级 import 造成加载顺序问题。
-        # 钩子是"库自己正常工作"的一部分（体检库里存着的块），**不是**对使用者项目的检查。
-        from .magic_block import health
-
-        health.install_hook()
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class LabullConfig(AppConfig):
+    """这个 app 的登记项。
+
+    🔴 `ready()` 里**只挂一个钩子，不碰数据库**：Django 对"在 `ready()` 里查库"会明确警告
+    （`Accessing the database during app initialization is discouraged`），而且新项目第一次
+    `migrate` 时表还不存在 —— 那时查库会让**整个命令**起不来。
+    🔴 `ready()` 里**不装任何 `post_save` / `user_logged_in` 接收器**：框架不给新用户加组
+    （那是项目的数据/策略，示例项目给了一份可复制的实现：`backend/example/canvasdemo/signals.py`）。
+
+    🔴 启动时要做的两件事（重设管理员名单 → 全量体检）在 `wsgi.py` 里一行显式调用：
+        ```python
+        from labull_framework.magic_block.health import startup_once
+        startup_once()
+        ```
+        那一行是**契约**（函数名与签名都不要改）：`runserver` / gunicorn / uwsgi / ASGI
+        都从那里进来，所以它天然是"每个进程一次"的地方。
+    ⚠️ 它**不是** `post_migrate` 的替代：那个只在迁移之后发（管"库刚被改过"），
+        而启动体检只有 `startup_once()` 能做。
+    """
+
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'labull_framework'
+    verbose_name = 'Labull Framework'
+
+    def ready(self) -> None:
+        # 延迟 import：此刻 app 注册表已经就绪，但避免模块级 import 造成加载顺序问题。
+        # 钩子是"库自己正常工作"的一部分（体检库里存着的块），**不是**对使用者项目的检查。
+        from .magic_block import health
+
+        health.install_hook()

{labull_framework-1.4.1 → labull_framework-3.0.0}/labull_framework/auth/backend.py

@@ -5,8 +5,12 @@
    所以这个类**不碰会话**、也**不校验 token**（验签是 `sso.py` 的事，视图验完才把 claims 送进来）。
 
 🔴 **权限一个字都不给**：Django 有 `is_staff` / `is_superuser` / `Group` / `Permission`，
-   登录这件事只负责"你是谁"；"你能干什么"由管理员在 admin 里给。
-   所以新建的用户三个布尔位就是 `is_staff=False` / `is_superuser=False` / `is_active=True`。
+   登录这件事只负责"你是谁"；"你能干什么"只看 **`Permission`**（`app_label.codename`），
+   组只是权限包。新建的用户布尔位是 `is_staff=False` / `is_superuser=False` / `is_active=True`
+   （`is_staff` 只留给 Django 自己的 `/admin`；平台的管理员看 `edit_magic_block` 这个权限）。
+🔴 **新用户不自动进任何组**（框架不装 `post_save` / `user_logged_in`）：新来的人默认属于哪个组是
+   **项目的数据/策略**，由项目自己决定（示例项目给了一份可复制的实现：
+   `backend/example/canvasdemo/signals.py`）。老用户的组与权限**不动**（归管理员）。
 """
 
 from __future__ import annotations
@@ -28,7 +32,7 @@ NO_WORK_ID_TEXT = (
 )
 
 #: 老用户每次登录只允许被刷新的两列。🔴 抄进 `update_fields` 的那一份必须是**白名单**：
-#: 一旦顺手写成"全部字段"，管理员在 admin 里设的 `is_staff` / 组 / 权限就会被一次登录冲掉。
+#: 一旦顺手写成"全部字段"，管理员在 admin 里设的组 / 权限就会被一次登录冲掉。
 UPDATABLE_FIELDS: tuple[str, ...] = ('name', 'work_id')
 
 
@@ -119,7 +123,7 @@ class OidcBackend:
         current = user_model.objects.filter(username=sub).first()
         name = _text(data.get('name')) or sub
         if current is not None:
-            # 🔴 老用户只刷新这两列：`is_staff` / `is_superuser` / 组与权限归管理员，
+            # 🔴 老用户只刷新这两列：组 / 权限 / is_superuser 归管理员，
             #    密码根本没有（见 `set_unusable_password`）。
             current.name = name
             current.work_id = work_id