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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 1.4.1
+Version: 2.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`，所以别拿超管当后门 |
+| **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人加进**管理员角色**的组，**名单之外的一律摘掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
+| **管理员 / 默认角色** | **默认就有**：SDK 的 `0005` 迁移种下 `ADMIN`（管理员角色）/ `USER`（默认角色，新用户第一次登录自动加入）。要换码或组名就写项目自己的 data migration；两条**各恰好一条、不能同一行**，缺了 / 重了服务起不来 |
 | **看数据模型那一页** | 设 `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-2.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` 也认，本地开发不必装数据库。
+
+| 想要什么 | 怎么做 |
+|---|---|
+| **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人加进**管理员角色**的组，**名单之外的一律摘掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
+| **管理员 / 默认角色** | **默认就有**：SDK 的 `0005` 迁移种下 `ADMIN`（管理员角色）/ `USER`（默认角色，新用户第一次登录自动加入）。要换码或组名就写项目自己的 data migration；两条**各恰好一条、不能同一行**，缺了 / 重了服务起不来 |
+| **看数据模型那一页** | 设 `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-2.0.0}/labull_framework/admin.py

@@ -1,6 +1,8 @@
 """Django admin 的注册处 —— 这个库**唯一**的管理界面。
 
 🔴 它就是 Django 原生的那一套：用户 / 组 / 权限的日常维护白拿，我们不写任何自己的管理页面。
+🔴 另外登记一张**项目级**的表：`LabullRole`（码 → Django 组名）。角色是**项目数据**、表默认空，
+   框架不内置任何码；组要先在「组」里建好，这里只做配对。
 🔴 **块的代码在 admin 里只读**：它只能从 magic block 控制台写进去，因为那里有"保存即校验"那一关
    （`ast` + 子进程试加载）。admin 里放开编辑表单，就等于从 Django 的默认表单往库里塞
    **未经校验、之后会被 `exec` 执行**的代码，把"体检不过就停用"这套机制绕开。
@@ -11,7 +13,7 @@ from __future__ import annotations
 
 from django.contrib import admin
 
-from .models import MagicBlock, User
+from .models import LabullRole, MagicBlock, User
 
 
 @admin.register(User)
@@ -20,21 +22,39 @@ class UserAdmin(admin.ModelAdmin):
 
     ⚠️ `username` 装的是 Authing 的 `sub`（登录时同步进来的），所以它**只读** ——
     改它等于把这一行与那个身份切开。
+    🔴 **平台管理员是"管理员角色的组员"**（`LabullRole.is_admin` 那一行），这里不摆 `is_staff` ——
+    那一列只留给 Django 自己的 `/admin`，本项目不读它。
     """
 
-    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')}),
     )
 
 
+@admin.register(LabullRole)
+class LabullRoleAdmin(admin.ModelAdmin):
+    """项目角色：**码 → Django 组名**（框架不内置任何业务角色码；两个特殊角色由 SDK 的 0005 迁移种下）。
+
+    🔴 它是"这个项目有哪些岗"的唯一真源：`flow.py` 里只引用 `role:<码>`，不写角色表。
+    🔴 `is_admin`（管理员角色，组员就是平台管理员）与 `is_default_role`（默认角色，新用户自动加入）
+       **各恰好一条、不能同一行** —— 启动校验会拦；两条由 SDK 的 `0005` 迁移种下（`ADMIN` / `USER`）。
+    🔴 组要先在「组」里建好 —— 这里只做配对，**不建组、不建用户**。
+    """
+
+    list_display = ('code', 'name', 'group', 'is_admin', 'is_default_role')
+    list_filter = ('is_admin', 'is_default_role')
+    search_fields = ('code', 'name', 'group')
+    ordering = ('code',)
+
+
 @admin.register(MagicBlock)
 class MagicBlockAdmin(admin.ModelAdmin):
     """功能块：看状态、筛 —— **改代码不在这里**（见文件头）。"""

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

@@ -10,7 +10,7 @@ class LabullConfig(AppConfig):
     （`Accessing the database during app initialization is discouraged`），而且新项目第一次
     `migrate` 时表还不存在 —— 那时查库会让**整个命令**起不来。
 
-    🔴 启动时要做的两件事（重设管理员名单 → 全量体检）在 `wsgi.py` 里一行显式调用：
+    🔴 启动时要做的三件事（校验角色 → 重设管理员名单 → 全量体检）在 `wsgi.py` 里一行显式调用：
         ```python
         from labull_framework.magic_block.health import startup_once
         startup_once()
@@ -29,5 +29,9 @@ class LabullConfig(AppConfig):
         # 延迟 import：此刻 app 注册表已经就绪，但避免模块级 import 造成加载顺序问题。
         # 钩子是"库自己正常工作"的一部分（体检库里存着的块），**不是**对使用者项目的检查。
         from .magic_block import health
+        from .roles import install_check
 
         health.install_hook()
+        # 🔴 只**注册**一条 system check（不在这里查库）：`manage.py check` / `runserver` 会在
+        #    真正查库之前把"两个特殊角色配错了"报出来；表还没迁移时那条 check 自己会跳过。
+        install_check()

{labull_framework-1.4.1 → labull_framework-2.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`。
+   登录这件事只负责"你是谁"；"你能干什么"由**项目角色表**（`LabullRole`）与 Django 的组决定。
+   新建的用户布尔位是 `is_staff=False` / `is_superuser=False` / `is_active=True`（`is_staff` 只留给
+   Django 自己的 `/admin`，平台的管理员看**管理员角色**）。
+🔴 **新用户默认加入默认角色**（`LabullRole.is_default_role` 那一行的组）：这是"新来的人至少有个身份"
+   的唯一入口；工号在 `BOOTSTRAP_ADMIN_WORK_IDS` 里的新同事还会顺手进**管理员角色**的组。
+   老用户的组与权限**不动**（归管理员）。
 """
 
 from __future__ import annotations
@@ -28,10 +32,46 @@ NO_WORK_ID_TEXT = (
 )
 
 #: 老用户每次登录只允许被刷新的两列。🔴 抄进 `update_fields` 的那一份必须是**白名单**：
-#: 一旦顺手写成"全部字段"，管理员在 admin 里设的 `is_staff` / 组 / 权限就会被一次登录冲掉。
+#: 一旦顺手写成"全部字段"，管理员在 admin 里设的组 / 权限就会被一次登录冲掉。
 UPDATABLE_FIELDS: tuple[str, ...] = ('name', 'work_id')
 
 
+def _join_group(user, name: str) -> None:
+    """把这个用户加进某个组（组不存在就建）；失败只记日志 —— 加组不该让人登不进来。"""
+    if not name:
+        return
+    from django.contrib.auth.models import Group
+
+    try:
+        group, _created = Group.objects.get_or_create(name=name)
+        user.groups.add(group)
+    except Exception as error:  # noqa: BLE001
+        logger.error('新用户加入组「%s」失败（不影响登录）：%s', name, error)
+
+
+def _join_default_role(user) -> None:
+    """把这个**新用户**加进默认角色的组（没有默认角色 ⇒ 什么都不做）。
+
+    🔴 只对**新建**的用户调：老用户的组归管理员，登录不许重排它。
+    """
+    from ..roles import default_role_group
+
+    _join_group(user, default_role_group())
+
+
+def _maybe_join_admin_role(user) -> None:
+    """工号在 `BOOTSTRAP_ADMIN_WORK_IDS` 名单里 ⇒ 顺手加进**管理员角色**的组。
+
+    🔴 启动时的 `sync_admin_work_ids()` 只管库里已经有的人；这是"名单里那个新同事
+       第一次登录就已经是管理员"的那一半（同一个解析函数，名单不会两处不一致）。
+    """
+    from ..roles import admin_role_group
+    from .bootstrap import configured_admin_work_ids
+
+    if str(user.work_id or '') and str(user.work_id) in set(configured_admin_work_ids()):
+        _join_group(user, admin_role_group())
+
+
 class LoginRejected(Exception):
     """这次登录不放行，**一个字都不落库**，报文直接给用户看（视图回 401）。"""
 
@@ -119,7 +159,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
@@ -133,6 +173,8 @@ class OidcBackend:
                 user = user_model(username=sub, name=name, work_id=work_id)
                 user.set_unusable_password()
                 user.save()
+                _join_default_role(user)
+                _maybe_join_admin_role(user)
             return user
         except IntegrityError:
             # 并发首登：另一个请求刚插进去。重查拿**赢家写下的那一行** ——