labull-framework 0.1.0__tar.gz

labull_framework-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Labull
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+第三方组件（随本包分发的成品 CSS / 字形）各自的许可归其作者所有：
+
+- PrimeVue 主题层（`Mira`）与 PrimeIcons 字形：搬入的成品 CSS，均为 MIT。
+- 其余依赖（Django、PyJWT 等）按各自许可（BSD-3-Clause / MIT）分发，未做修改。

labull_framework-0.1.0/MANIFEST.in

@@ -0,0 +1,22 @@
+# sdist 只该装 `labull_framework` 这一个 app。
+# 🔴 `backend/example/`（含 `.env` 真密钥、`db.sqlite3`、`.venv/` 整个 Django 示例项目）
+#    与仓库根的 `scratch/` 一律不进包 —— 显式排掉，不指望 setuptools 的默认扫描。
+global-exclude *.py[cod] *.pyo
+global-exclude .env .env.*
+global-exclude db.sqlite3
+global-exclude *.sqlite3
+
+prune example
+prune scratch
+prune tests
+prune .venv
+prune __pycache__
+
+include LICENSE
+include README-pypi.md
+include pyproject.toml
+
+# 包内数据（`canvas/views.py` 运行期真的会读这三个）。
+recursive-include labull_framework/canvas/static *.css *.js *.html
+recursive-include labull_framework *.pyi py.typed
+recursive-include labull_framework/migrations *.py

labull_framework-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: labull-framework
+Version: 0.1.0
+Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
+Author: Labull Framework
+License-Expression: MIT
+Keywords: django,authing,oidc,sso,magic-block
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: PyJWT[crypto]>=2.8
+Dynamic: license-file
+
+# 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` 也认，本地开发不必装数据库。
+
+| 想要什么 | 怎么做 |
+|---|---|
+| **谁是管理员** | Django 的 `is_staff`（admin 里勾，或配 `BOOTSTRAP_ADMIN_WORK_IDS` 写工号） |
+| **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
+| **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |
+
+## magic block
+
+一个块 = **一个 uuid + 一整个文件包**：
+
+```
+我的块/
+├─ index.open.html        入口（必备）
+├─ magic-block.open.yaml  清单（必备）：id / module / name / brief 四个键
+├─ 任意 js / css
+└─ backend_open.py        块自己的后端（可选）
+```
+
+块后端与项目里别的 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']`）。
+
+## 运行环境
+
+- Python ≥ 3.10
+- Django ≥ 4.2（在 6.1 上验证过）
+- PyJWT（带 `crypto` 后端）
+
+## License
+
+MIT

labull_framework-0.1.0/README-pypi.md

@@ -0,0 +1,112 @@
+# 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` 也认，本地开发不必装数据库。
+
+| 想要什么 | 怎么做 |
+|---|---|
+| **谁是管理员** | Django 的 `is_staff`（admin 里勾，或配 `BOOTSTRAP_ADMIN_WORK_IDS` 写工号） |
+| **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
+| **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |
+
+## magic block
+
+一个块 = **一个 uuid + 一整个文件包**：
+
+```
+我的块/
+├─ index.open.html        入口（必备）
+├─ magic-block.open.yaml  清单（必备）：id / module / name / brief 四个键
+├─ 任意 js / css
+└─ backend_open.py        块自己的后端（可选）
+```
+
+块后端与项目里别的 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']`）。
+
+## 运行环境
+
+- Python ≥ 3.10
+- Django ≥ 4.2（在 6.1 上验证过）
+- PyJWT（带 `crypto` 后端）
+
+## License
+
+MIT

labull_framework-0.1.0/labull_framework/__init__.py

@@ -0,0 +1,8 @@
+"""Labull Framework —— 一个可选的 Django app。
+
+只有两块业务逻辑：Authing 登录、magic block。
+其余一律走 Django 原生（用户模型、会话、权限、admin、文件字段、迁移）。
+
+🔴 本文件**什么都不 import**：子模块之间的依赖是单向的，在这里 import 会在
+"配置还没加载完"的时刻把模型拉起来（Django 里最难查的一类循环 import）。
+"""

labull_framework-0.1.0/labull_framework/admin.py

@@ -0,0 +1,63 @@
+"""Django admin 的注册处 —— 这个库**唯一**的管理界面。
+
+🔴 它就是 Django 原生的那一套：用户 / 组 / 权限的日常维护白拿，我们不写任何自己的管理页面。
+🔴 **块的代码在 admin 里只读**：它只能从 magic block 控制台写进去，因为那里有"保存即校验"那一关
+   （`ast` + 子进程试加载）。admin 里放开编辑表单，就等于从 Django 的默认表单往库里塞
+   **未经校验、之后会被 `exec` 执行**的代码，把"体检不过就停用"这套机制绕开。
+   要看、要筛、要重跑体检 —— admin 全都能做；要改代码 —— 去控制台。
+"""
+
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .magic_block import health
+from .models import MagicBlock, User
+
+
+@admin.register(User)
+class UserAdmin(admin.ModelAdmin):
+    """用户：Django 自带的那份管身份，我们只把自加的字段摆进去。
+
+    ⚠️ `username` 装的是 Authing 的 `sub`（登录时同步进来的），所以它**只读** ——
+    改它等于把这一行与那个身份切开。
+    """
+
+    list_display = ('username', 'work_id', 'name', 'is_staff', 'is_active', 'last_login')
+    list_filter = ('is_staff', 'is_superuser', 'is_active')
+    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': ('last_login', 'date_joined')}),
+    )
+
+
+@admin.register(MagicBlock)
+class MagicBlockAdmin(admin.ModelAdmin):
+    """功能块：看状态、筛、重跑体检 —— **改代码不在这里**（见文件头）。"""
+
+    list_display = ('id', 'module', 'name', 'enabled', 'health_checked_at', 'updated_at')
+    list_filter = ('module', 'enabled')
+    search_fields = ('id', 'name', 'brief')
+    ordering = ('module', 'name')
+    # 🔴 全字段只读：块的正文与体检结论都由控制台 / 体检模块写。
+    readonly_fields = tuple(field.name for field in MagicBlock._meta.fields)
+    actions = ('rerun_health',)
+
+    @admin.action(description='重新体检选中的块')
+    def rerun_health_action(self, request, queryset):
+        """只体检选中的那几块（全量体检在每次 `migrate` 与进程启动时各跑一次）。"""
+        summary = health.check_all_blocks(list(queryset.values_list('id', flat=True)))
+        self.message_user(
+            request,
+            f'体检 {summary["checked"]} 块：通过 {summary["passed"]}，停用 {summary["disabled"]}。',
+        )
+        return None
+
+    def has_add_permission(self, request) -> bool:
+        # 块的 uuid 由开发者在前端写死（`<MagicBlockHost uuid="…">`），admin 里"新增"没有意义。
+        return False

labull_framework-0.1.0/labull_framework/apps.py

@@ -0,0 +1,33 @@
+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()

labull_framework-0.1.0/labull_framework/auth/__init__.py

@@ -0,0 +1,4 @@
+# 🔴 本文件故意是空的：这里**不许 import 任何子模块**。
+# 原因：子模块会 import 模型，而 Django 加载 app 时会先 import 本包 ——
+# 在配置（`AUTH_USER_MODEL` / `INSTALLED_APPS`）读完之前碰模型，就是那个
+# `AppRegistryNotReady` 的循环 import。要用哪一个子模块，就写全路径去 import 它。

labull_framework-0.1.0/labull_framework/auth/backend.py

@@ -0,0 +1,144 @@
+"""OIDC 认证后端：把回调那一步**已经验过的** claims 变成一行 `User`。
+
+🔴 **为什么还要一个认证后端**：OIDC 不是 Django 认识的密码后端（没有 `password` 可比），
+   但我们要的只是它的 `authenticate()` 这一步 —— **会话仍然完全交给 Django 的 `login()`**，
+   所以这个类**不碰会话**、也**不校验 token**（验签是 `sso.py` 的事，视图验完才把 claims 送进来）。
+
+🔴 **权限一个字都不给**：Django 有 `is_staff` / `is_superuser` / `Group` / `Permission`，
+   登录这件事只负责"你是谁"；"你能干什么"由管理员在 admin 里给。
+   所以新建的用户三个布尔位就是 `is_staff=False` / `is_superuser=False` / `is_active=True`。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.contrib.auth import get_user_model
+from django.db import IntegrityError, transaction
+
+logger = logging.getLogger(__name__)
+
+#: 缺工号时那句固定报文。
+#: 🔴 没有工号就**拒登**（不落库）：工号是"这个人在组织里是谁"，缺了它这条身份没有意义，
+#: 而"先放进来再补"会让库里留下一批永远要人回头去认的账号。
+NO_WORK_ID_TEXT = (
+    '你的账号在 Authing 里没有 `username`（工号），不放行 —— '
+    '请管理员在 Authing 里给这个账号补上工号后重试。'
+)
+
+#: 老用户每次登录只允许被刷新的两列。🔴 抄进 `update_fields` 的那一份必须是**白名单**：
+#: 一旦顺手写成"全部字段"，管理员在 admin 里设的 `is_staff` / 组 / 权限就会被一次登录冲掉。
+UPDATABLE_FIELDS: tuple[str, ...] = ('name', 'work_id')
+
+
+class LoginRejected(Exception):
+    """这次登录不放行，**一个字都不落库**，报文直接给用户看（视图回 401）。"""
+
+
+class NoWorkId(LoginRejected):
+    """缺工号（`username`）那一支。
+
+    ⚠️ 单独一个类型只是为了让人读日志时一眼看出是哪一支；视图对两者的处理是同一件
+       （401 + 原样报文），所以它们共一个父类、只在视图里 catch 一次。
+    """
+
+
+def _text(value: Any) -> str:
+    """把一个 claim 当字符串用（不是字符串就算空）。
+
+    ⚠️ 不用 `str()` 硬转：claim 完全由 IdP 决定，`str(None)` 会得到 `'None'` ——
+    那是一个**看起来像工号**的东西，它会进唯一索引，然后下一个人永远登不进来。
+    """
+    return value if isinstance(value, str) else ''
+
+
+def _work_id_of(source: Any) -> str:
+    """取工号（**只认 `username`**）。
+
+    🔴 只认这一个键：Authing 为 workId 特设的就是它；OIDC 标准里的 `preferred_username`
+       常常是邮箱 / 昵称，收进来就等于让一个不是工号的东西占住唯一索引。
+    """
+    return _text(source.get('username')).strip() if isinstance(source, dict) else ''
+
+
+def _claim_keys_of(source: Any) -> list[str]:
+    """一份 claim 里**真实出现**的键名（排序后）。
+
+    🔴 只列键名、永不列值：值是 PII（姓名 / 邮箱 / 工号），而这句话要回给浏览器、也会进日志。
+       键名恰好回答得了那个真问题 ——"工号该补在哪个键上"。
+    """
+    return sorted(str(key) for key in source) if isinstance(source, dict) else []
+
+
+class OidcBackend:
+    """`AUTHENTICATION_BACKENDS` 里那一个；`claims` / `userinfo` 由回调视图传进来。"""
+
+    def authenticate(
+        self, request: Any, claims: dict | None = None, userinfo: dict | None = None, **kwargs: Any
+    ):
+        """按 claims 造 / 更新用户行，回 `User` 或 `None`（拒登时抛 `LoginRejected`）。
+
+        ⚠️ 视图已经验过签名，这里只看 claim 的值 —— 再验一次会变成"两处口径"。
+        🔴 不认识的凭据（`username` / `password` 那类）一律回 `None`：`authenticate()` 是
+           Django 的框架出口，凭据不对就抛异常的后端会让 `client.login()` 这类正常调用直接 500。
+        """
+        if claims is None and userinfo is None:
+            # 没有我们认的那两样东西 ⇒ 这不是能靠 OIDC 验的身份（交给别的后端或直接失败）。
+            return None
+        return self._upsert(claims, userinfo)
+
+    def get_user(self, user_id: Any):
+        """按主键取人 —— `AuthenticationMiddleware` 每个请求都靠它把会话里的 id 换回 `User`。
+
+        🔴 少了这个方法，登录那一刻是好的，**下一个请求就 500**（框架在恢复身份时会找它）。
+        ⚠️ 不查 `is_active`：账号停用该由 Django 的 `user_can_authenticate` 判（它就在
+           `login()` / `get_user()` 那条路上），在这里再判一次就是同一条规矩两处口径。
+        """
+        return get_user_model().objects.filter(pk=user_id).first()
+
+    def _upsert(self, claims: dict | None, userinfo: dict | None):
+        """真正的映射（见模块头）：`sub` → `username`、`username` → `work_id`、`name` → `name`。"""
+        data = claims if isinstance(claims, dict) else {}
+        profile = userinfo if isinstance(userinfo, dict) else {}
+        sub = _text(data.get('sub')).strip()
+        if not sub:
+            # 🔴 连"是谁"都定不下来 ⇒ 一个字都不落库（`sub` 是唯一凭据）。
+            raise LoginRejected('id_token 里没有 sub，无法定位用户。')
+
+        # 🔴 工号先看 id_token、再看用户信息接口：Authing 默认不把用户资料放进 id_token，
+        #    所以"id_token 里没有 username"**不等于**"这个人没有工号"。
+        work_id = _work_id_of(data) or _work_id_of(profile)
+        if not work_id:
+            raise NoWorkId(
+                f'{NO_WORK_ID_TEXT}这次 id_token 的键名有 {_claim_keys_of(data)}、'
+                f'用户信息接口的键名有 {_claim_keys_of(profile)}，两处都没有 username。'
+            )
+
+        user_model = get_user_model()
+        current = user_model.objects.filter(username=sub).first()
+        name = _text(data.get('name')) or sub
+        if current is not None:
+            # 🔴 老用户只刷新这两列：`is_staff` / `is_superuser` / 组与权限归管理员，
+            #    密码根本没有（见 `set_unusable_password`）。
+            current.name = name
+            current.work_id = work_id
+            current.save(update_fields=list(UPDATABLE_FIELDS))
+            return current
+
+        try:
+            # ⚠️ `atomic()` 是必须的：唯一约束撞了之后 `IntegrityError` 会让**外层事务**
+            #    也进入"已中止"状态，后面那条重查会抛 `TransactionManagementError`。
+            with transaction.atomic():
+                user = user_model(username=sub, name=name, work_id=work_id)
+                user.set_unusable_password()
+                user.save()
+            return user
+        except IntegrityError:
+            # 并发首登：另一个请求刚插进去。重查拿**赢家写下的那一行** ——
+            # `get_or_create` 在这里回的是它自己那个没落库的对象，拿它写会话就会指向不存在的行。
+            winner = user_model.objects.filter(username=sub).first()
+            if winner is None:
+                logger.error('首次落库撞了唯一约束，按 username=%s 却查不到那一行（多半是工号重复）。', sub)
+                return None
+            return winner

labull_framework-0.1.0/labull_framework/auth/bootstrap.py

@@ -0,0 +1,47 @@
+"""启动时按 `BOOTSTRAP_ADMIN_WORK_IDS` 给点名的人 `is_staff=True` —— **这是"第一个管理员从哪来"的唯一入口**。
+
+🔴 为什么需要它：权限是 Django 的 `is_staff` / `Group`，而库里一行用户都没有时，没有任何人能进
+   admin 去勾那个框（我们**没有自己写的管理界面**，admin 只有 `is_staff` 的人能进）——
+   所以第一个管理员只能从配置里点名。
+🔴 **只增不减**：把某人从清单里删掉、重启，他的 `is_staff` 留着。摘权限必须是人明说的动作
+   （去 admin 里取消勾选），不能由"改一次 `.env` + 重启"完成。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..env import read_env
+from ..models import User
+
+logger = logging.getLogger(__name__)
+
+MAX_WORK_IDS = 200
+
+
+def sync_staff_work_ids() -> int:
+    """给清单里命中的用户补 `is_staff`，回这次改了几个人。
+
+    🔴 **永不抛**：这是启动路径，库连不上 / 表还没迁移都只该在日志里留一句 ——
+       补管理员失败没有理由让整个后端起不来。
+    """
+    raw = read_env('BOOTSTRAP_ADMIN_WORK_IDS')
+    work_ids = [item.strip() for item in raw.split(',') if item.strip()]
+    if not work_ids:
+        return 0  # 没配就什么都不做（清单本来就是可选的）。
+    if len(work_ids) > MAX_WORK_IDS:
+        logger.warning(
+            'BOOTSTRAP_ADMIN_WORK_IDS 有 %s 个工号，本次只处理前 %s 个（上限 %s）：'
+            '请拆成多批，或确认这一行是不是误粘了。',
+            len(work_ids), MAX_WORK_IDS, MAX_WORK_IDS,
+        )
+        work_ids = work_ids[:MAX_WORK_IDS]
+
+    try:
+        # 🔴 用 `update()` 而不是逐个 `save()`：它不会碰 `date_joined` / `last_login` 这类
+        #    自动字段（"改动角色"不该让"这个人什么时候注册的"跟着变），也一条 SQL 就完事。
+        # ⚠️ 不带 `is_staff=False` 那一半：只增不减，见模块头。
+        return User.objects.filter(work_id__in=work_ids).update(is_staff=True)
+    except Exception as error:  # noqa: BLE001 —— 见 docstring：启动路径永不抛
+        logger.error('按 BOOTSTRAP_ADMIN_WORK_IDS 补 is_staff 失败（不影响启动）：%s', error)
+        return 0