Metadata-Version: 2.4
Name: labull-framework
Version: 0.1.4.5
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` 也认，本地开发不必装数据库。

| 想要什么 | 怎么做 |
|---|---|
| **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
| **看数据模型那一页** | 设 `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
