Metadata-Version: 2.4
Name: labull-framework
Version: 6.6.0
Summary: Labull Framework: a pluggable Django app with Authing OIDC login and soft pages
Author: Labull Framework
License-Expression: MIT
Keywords: django,authing,oidc,sso,soft-page
Classifier: Development Status :: 5 - Production/Stable
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
Requires-Dist: celery>=5.4
Dynamic: license-file

# labull-framework

一个可插拔的 **Django app**（import 名 `labull_framework`），提供三件事：

- **Authing / OIDC 登录**（**可装插件**，`plugins/authing/`）：自带认证后端，只用标准库 + PyJWT，
  不依赖任何 OIDC 客户端包。装法：`labull plugin add authing` —— **没装就没有 `/auth/*`**
  （只剩 Django admin 能登）；装上之后 `AUTHENTICATION_BACKENDS` 与管理员名单全自动。
- **软页面**：一个 uuid + 一整个文件包就是一个软页面，住在数据库里、在沙箱 iframe 里渲染，
  不重新编译、不重启；软页面可以带自己的后端 Python（`backend_open.py`）。
- **企业微信推送**（**可装插件**，不在这个 wheel 里）：给一个工号，插件自己去 Authing 查这个人的
  `wecom_userid`，再用自建应用发纯文字 / Markdown / 图片 / 文字卡片 / 图文 / 模板卡片 / 文件 / 语音 /
  视频 / 小程序通知。装法：`labull plugin add wecom` —— **没装就没有 `/px/wecom/*`**。

🔴 **数据模型图不在这个包里**：它由**插件**提供（`labull plugin init --kind launcher` 那一类独立应用）。
SDK 里没有画布代码、没有 `/px/canvas/*`、没有那个开关。

## 安装

```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.soft_page.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` 也认，本地开发不必装数据库。

🔴 那五项 `SSO_*` 只有**装了 `authing` 插件**才有人读（读它们的是插件本身）；`SSO_WEB_ORIGIN`
也必填（登录成功与登出都要往那个绝对地址回）。插件目录默认是 `BASE_DIR/plugins`，也可用
`LABULL_PLUGINS` 指过去。

| 想要什么 | 怎么做 |
|---|---|
| **谁是管理员** | 判据就是 Django 原生的 **`User.is_staff`**（框架不为这件事造 permission —— 所以 `permissions` 里一个框架自带的东西都没有）。配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— **声明式**：启动时名单里的人 `is_staff=True`、**名单之外的（非超管）一律 `False`**（没配 = 一个管理员都没有）。超管跳过、不碰 `is_superuser` |
| **权限 / 组** | 授权只有 Django 原生那一套：**`Permission`（`app_label.codename`）是契约，`Group` 只是权限包**。框架**零预置权限**（`SoftPage` / `SoftPageVersion` / `User` 都是 `default_permissions = ()`，迁移 `0007` 会把历史那几行删掉）——`permissions` 里只有**项目自己**在模型的 `Meta.permissions` 里声明的。3.0.0 建过的「平台管理员」/「普通用户」两个组现在只是空包（可填可删）。新用户默认进哪个组由**项目自己的 `post_save`** 决定（框架不装） |
| **看数据模型图** | **不在 SDK 里**：装一个画布插件（`--kind launcher` 的独立应用），从项目根的入口打开本机画布 |
| **给工号发企业微信消息** | 先装插件：`labull plugin add wecom`（**没装就没有 `/px/wecom/*`**），再配 `AUTHING_*`（管理凭据）+ `WECOM_*`（自建应用）+ `LABULL_WECOM_API_KEY`（服务端共享密钥），调 `POST /px/wecom/push`。完整说明见仓库 `docs/wecom/README.md`（Authing 权限、消息示例、`60020` IP 白名单都在那一页） |
| **软页面的依赖声明不许"用了却没声明"** | 它是**默认**行为（`LABULL_REQUIRES=error`，1.0.1 起）：代码里用了没声明的东西 ⇒ 拦住导入。⚠️ 升级前先在项目里跑一遍 `python manage.py labull_requires --write` 把存量软页面扫得到的声明补进库；`warn`（只提示不拦）与 `off`（整段不跑）都要**显式**写 |
| **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |

## 软页面

一个软页面 = **一个 uuid + 一整个文件包**：

```
我的软页面/
├─ index.open.html        入口（必备）
├─ soft-page.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
│                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `SOFT_PAGE_*`）可选
├─ 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.soft_page.sdk import SoftPageBackendAPI, errors

class Order:
    @SoftPageBackendAPI()                       # 省略 permission = 任何登录用户都能调
    def list(self, ctx, params):
        from modules.orders.models import Order
        return [{'id': o.id} for o in Order.objects.all()[:20]]

    @SoftPageBackendAPI(permission='labull_framework.edit_softpages')
    def close(self, ctx, params):
        if not params.get('id'):
            raise errors.BadRequest('要给我一个 id')
        return {'ok': True}
```

配置：环境变量里**带 `SOFT_PAGE_` 前缀**的才会进 `ctx.config`（`SOFT_PAGE_OCR_KEY=a` ⇒ `ctx.config['OCR_KEY']`）。

🔴 **弹窗走平台**：软页面里 `await softPage.dialog({ file: 'dialog/close-order.html' })` —— 那一篇是软页面包里的
一个普通 `.html`（结构与脚本都在里面），由宿主页面在真视口里渲染（前端要挂一次 `<SoftPageDialogs />`）。
软页面自己画的浮层**摆不正**：软页面可以是好几屏高，软页面里 `position: fixed` / `100vh` 的基准是"整个软页面高度"而不是那一屏。
要给这一次弹窗传参就 `{ data: {…} }`（那一篇里 `await softPage.data()`），结果由那一篇
`softPage.done({ button, values })` 交回；临时 / 极短的一篇也可以 `{ html: '…' }` 直接给一串。
尺寸、滚动、滚轮全归那一篇写（不给 `size.height` 就按内容定高）。

## 虚拟类（`@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` 就拦下）。

画布上（launcher 插件）：虚拟类是一张带 `◇` 的虚线卡片（写着"不建表"与
"谁在继承它"），继承它的表表头挂着「**◇ 泛化 · 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` 后端）
- Celery ≥ 5.4（**硬依赖**：`scheduler` 插件的时钟与执行器；broker 建议 Redis，
  但**只 import 不连** —— 没有 broker 时网站照常跑，定时任务用 `manage.py labull_schedule` 兜底）

## License

MIT
