labull-framework 0.1.0__py3-none-any.whl

labull_framework/canvas/static/page.html

@@ -0,0 +1,52 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>数据模型</title>
+  <!-- ⚠️ `?v=` 是**给浏览器的缓存换钥匙**：这两个静态件在"这一页是公开的"之后尤其容易被缓存住，
+       改了正文而人不刷新（或刷新了也还是旧的），症状是"代码明明改了、页面却没变"（真踩过）。
+       改这两个文件时把版本号往上加一位。 -->
+  <link rel="stylesheet" href="canvas/asset/canvas.css?v=24">
+</head>
+<body>
+  <header class="bar">
+    <span class="brand">数据模型</span>
+    <span id="gitline" class="git"></span>
+    <span class="grow"></span>
+    <span id="stat" class="stat"></span>
+  </header>
+
+  <div class="toolbar">
+    <select id="module"></select>
+    <span class="legend"><i class="sw added"></i>新增</span>
+    <span class="legend"><i class="sw modified"></i>修改</span>
+    <span class="legend"><i class="sw deleted"></i>删除</span>
+    <!-- 列序开关：字段名优先 ⇄ 备注优先。文案由 canvas.js 写（状态只有一处真源）。 -->
+    <button id="order-toggle" type="button" title="切换字段行的列序：字段名优先 ⇄ 备注优先">列序：字段名优先</button>
+    <span class="grow"></span>
+    <!-- 缩放三件 + 适应视图。⚠️ `zoom` 那个百分数是 canvas.js 写的（它是缩放的唯一真源）。 -->
+    <span class="zoom-group">
+      <button id="zoom-out" type="button" title="缩小（Ctrl + 滚轮也行）">−</button>
+      <span id="zoom" class="zoom-value" title="当前缩放">100%</span>
+      <button id="zoom-in" type="button" title="放大（Ctrl + 滚轮也行）">＋</button>
+      <button id="zoom-reset" type="button" title="回到 100%">1:1</button>
+      <button id="zoom-fit" type="button" title="把图缩放到视野内">适应视图</button>
+    </span>
+    <button id="fit" type="button" title="清掉手工拖的位置，回到自动排列">自动排列</button>
+    <button id="reload" type="button" title="重新取一次数据">刷新</button>
+  </div>
+
+  <p id="alert" class="alert" hidden></p>
+
+  <main id="viewport">
+    <div id="canvas"></div>
+  </main>
+
+  <p class="hint">
+    拖动表可排版（拖完自动存）；空白处按住拖 = 平移，Ctrl + 滚轮 = 缩放；
+    点表标题展开备注与关联，点字段行展开枚举取值 / 文件去向 / 关联目标，点线上的关联键名看它的备注。
+  </p>
+  <script src="canvas/asset/canvas.js?v=24"></script>
+</body>
+</html>

labull_framework/canvas/views.py

@@ -0,0 +1,121 @@
+"""画布那四个视图：那一页、它要的数据、拖拽位置、以及页面自己的 js / css。
+
+🔴 **这一页公开**（`/`、`/canvas`、`/canvas/layout`、`/canvas/asset/*` 都不校验身份）：
+   它是**开发期看数据库结构的工具**，打开就能看，不必先登录 —— 调模型的时候还要先去 Authing
+   转一圈实在碍事。所以**唯一的开关是那个环境变量**（`LABULL_SCHEMA_CANVAS`，默认关）：
+
+        LABULL_SCHEMA_CANVAS=off    这一页根本不存在（`/` 404）—— **生产环境的默认值**
+        LABULL_SCHEMA_CANVAS=auto   只在 DEBUG 时挂上
+        LABULL_SCHEMA_CANVAS=on     总是挂上
+
+   ⚠️ 打开它就等于把**全部表结构**摊在一个不需要登录的 URL 上。要么别在公网开，
+      要么在 nginx / 反向代理那一层给它加 Basic 认证或 IP 白名单 —— 那种"谁知道这个地址"的
+      隐蔽性不算保护。
+
+🔴 **静态件不注册 `django.contrib.staticfiles`**：由本模块一条视图读**包内文件**。
+   理由：为一个页面去加一个 app + 一套 `STATIC_URL` 约定，是把"装法"变复杂；
+   而"只读白名单里的那几个名字"本身就是一道安全边界。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse
+from django.middleware.csrf import get_token
+from django.views.decorators.http import require_http_methods
+
+from ..jsonio import json_response, problem
+from . import data as payload
+
+_ASSETS_DIR = Path(__file__).resolve().parent / 'static'
+
+#: 页面允许取的**那几个**文件（白名单，不是黑名单）：名字对不上就 404，不拼路径。
+_ASSETS = {
+    'canvas.js': 'text/javascript; charset=utf-8',
+    'canvas.css': 'text/css; charset=utf-8',
+}
+
+#: 那一页的 HTML。
+_PAGE = _ASSETS_DIR / 'page.html'
+
+
+@require_http_methods(['GET'])
+def page(request: HttpRequest) -> HttpResponse:
+    """根路径那一页（**公开**，见模块头那段说明）。
+
+    🔴 顺手 `get_token()`：这一页要能**存拖动位置**（`POST /canvas/layout`，走 Django 的双提交
+       CSRF）。而"第一枚 CSRF cookie 从哪来"必须有确定答案 —— 这里种下它。
+       ⚠️ 名字不能写死：cookie 名与头名都是跨语言契约（见 `settings.py` 里那两个常量），
+          所以页面自己不去猜，由 `/canvas/csrf` 告诉它。
+    """
+    get_token(request)
+    if not _PAGE.is_file():
+        return problem('页面文件缺失（包内 static/page.html 不在）。', 500)
+    return HttpResponse(_PAGE.read_text(encoding='utf-8'), content_type='text/html; charset=utf-8')
+
+
+@require_http_methods(['GET'])
+def csrf(request: HttpRequest) -> HttpResponse:
+    """告诉页面：CSRF 的 cookie 叫什么、请求头叫什么、这枚值是多少。
+
+    🔴 为什么不写死在 `canvas.js` 里：那两个名字是**跨语言契约**（`settings.py` 的
+       `CSRF_COOKIE_NAME` / `CSRF_HEADER_NAME`），写死的话项目一改名，
+       症状是"拖动位置存不上，而页面不报任何错"（真踩过：一直 403）。
+    🔴 `CSRF_HEADER_NAME` 是 Django 的**内部形式**（`HTTP_X_LABULL_CSRF`），
+       而浏览器 `fetch` 要的是**头名本身**（`X-Labull-Csrf`）—— 这里转好再给，
+       别让每个前端各写一遍这段转换（写错的表现同样是"静默 403"）。
+    """
+    token = get_token(request)
+    return json_response(
+        {
+            'cookie': settings.CSRF_COOKIE_NAME,
+            'header': _header_name(settings.CSRF_HEADER_NAME),
+            'token': token,
+        }
+    )
+
+
+def _header_name(raw: str) -> str:
+    """`HTTP_X_LABULL_CSRF` ⇒ `X-Labull-Csrf`（Django 内部形式 → HTTP 头名）。"""
+    name = str(raw or '')
+    if name.upper().startswith('HTTP_'):
+        name = name[5:]
+    return '-'.join(part.capitalize() for part in name.split('_') if part)
+
+
+@require_http_methods(['GET'])
+def data(request: HttpRequest) -> HttpResponse:
+    """画布整包数据（**公开**）。"""
+    return json_response(payload.payload())
+
+
+@require_http_methods(['GET', 'POST'])
+def layout(request: HttpRequest) -> HttpResponse:
+    """读 / 存拖拽位置（存不下也不报错 —— 退回自动布局是正常状态）。**公开**。"""
+    if request.method == 'GET':
+        return json_response(payload.read_layout())
+    try:
+        body = json.loads(request.body or b'{}')
+    except ValueError:
+        return problem('body 不是合法 JSON。', 400)
+    return json_response(payload.write_layout(body))
+
+
+@require_http_methods(['GET'])
+def asset(request: HttpRequest, name: str) -> HttpResponse:
+    """页面自己的 js / css（只认白名单里的名字）。**公开**。
+
+    🔴 回话里带 `Cache-Control: no-cache`：这一页是**开发期工具**，它的 js / css 会被人反复改。
+       让浏览器把旧正文留着，症状是"代码明明改了、页面却没变"（真踩过：一个早已修掉的统计数字
+       在页面上留了好几轮）。`no-cache` 不是"不缓存"，是"每次先来问一句"——够用且不影响离线。
+    """
+    content_type = _ASSETS.get(name)
+    path = _ASSETS_DIR / name
+    if content_type is None or not path.is_file():
+        return problem(f'没有这个静态件：{name}', 404)
+    response = HttpResponse(path.read_text(encoding='utf-8'), content_type=content_type)
+    response['Cache-Control'] = 'no-cache'
+    return response

labull_framework/env.py

@@ -0,0 +1,187 @@
+"""环境变量的唯一入口：读值、加载 `.env`、给块的配置白名单，以及**有哪几个变量**这份清单。
+
+🔴 `.env` 解析器只有这一处（Django 自己不读 `.env`，标准库也没有这回事）。
+   两处各解析一遍的后果是"平台读得到、你的代码读不到" —— 最难查的一类不一致。
+🔴 `ENV_ITEMS` 是"平台读哪些环境变量"的**唯一真源**：开发包里的 `backend.lock.pyi`
+   照它铺一份给块作者看，登录那一组的必填清单与 `.env` 例子也从它取（见 `auth/sso.py`）。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+#: 给块的配置前缀：`BLOCK_OCR_KEY=abc` ⇒ 块后端里 `ctx.config['OCR_KEY'] == 'abc'`。
+#: 🔴 这是**白名单**（不是黑名单）：想让块读一项，就给那个变量加这个前缀，不用改库的代码。
+BLOCK_CONFIG_PREFIX = 'BLOCK_'
+
+#: `.env` 里一行的形状。允许 `export` 前缀、行首缩进、`=` 两边空白；
+#: 🔴 **不剥行内注释**（值里真带 `#` 的密钥不该被截断）、**不做变量展开**（那会让"谁先谁后"变成隐式规则）。
+_ENV_LINE = re.compile(r'^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$')
+
+
+def load_env_file(path: str | Path) -> None:
+    """把一份 `.env` 并进 `os.environ`（在 `settings.py` 的**第一行**调一次）。
+
+    🔴 必须排在读 `os.environ` 之前：顺序反了，`.env` 里给的值读不到，
+       而报出来的症状是"我配了，它还是不生效"。
+    🔴 `.env` **覆盖**进程环境：它是项目的配置真源，而进程里可能留着同名的外部变量。
+    🔴 用 `utf-8-sig` 读：编辑器存"UTF-8 带 BOM"时那个 BOM 会粘在第一个键名前面，
+       而 `^\\s*` 不匹配它 ⇒ 第一行**静默消失**（症状是"我明明配了它"）。
+    ⚠️ 文件不在 = 什么都不做（不抛、不报）：缺配置该由**用到它的那一刻**报出来。
+    """
+    source = Path(path)
+    if not source.is_file():
+        return
+    values: dict[str, str] = {}
+    for line in source.read_text(encoding='utf-8-sig').splitlines():
+        match = _ENV_LINE.match(line)
+        if not match:
+            continue  # 空行与 `#` 注释都走这一条
+        raw = match.group(2).strip()
+        quoted = len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ('"', "'")
+        values[match.group(1)] = raw[1:-1] if quoted else raw
+    os.environ.update(values)
+
+
+def read_env(name: str) -> str:
+    """读一个环境变量（空串当没写 —— `.env` 里 `KEY=` 是常态），去掉首尾空白。"""
+    return str(os.environ.get(name, '') or '').strip()
+
+
+def block_config(env: Mapping[str, str] | None = None) -> dict[str, str]:
+    """给块的配置：带 `BLOCK_` 前缀的那几个，**剥掉前缀当键**。
+
+    🔴 没配的键在 `ctx.config` 上**不存在**（别拿 `None` 当默认值使，先判 `'X' in ctx.config`）；
+       配成空串的**照给**（`BLOCK_X=` ⇒ `ctx.config['X'] == ''`）。
+    🔴 剥完是空串的**不算键**（`BLOCK_=` 不可能是名字）。
+    🔴 别的变量一个都不给块 —— 数据库连接串、SSO 密钥都不在这里。
+    """
+    source = os.environ if env is None else env
+    result: dict[str, str] = {}
+    for name, value in source.items():
+        if not name.startswith(BLOCK_CONFIG_PREFIX):
+            continue
+        key = name[len(BLOCK_CONFIG_PREFIX):]
+        if key:
+            result[key] = value
+    return result
+
+
+# ──────────────────────────── "有哪几个环境变量"这份清单 ────────────────────────────
+
+#: 登录那一组的组名。🔴 `auth/sso.py` 按它取必填清单（**不抄第二份名单**）。
+LOGIN_GROUP = '登录（Authing OIDC）'
+
+
+@dataclass(frozen=True)
+class EnvItem:
+    """一个环境变量在**开发包**里被看到的样子。
+
+    🔴 `hint` 是"能直接粘进 `.env` 的一行"：缺必填时那句报错就照它说（见 `auth/sso.py`）——
+       只说"缺了"的报错，用户还得自己去翻文档才知道那一行该怎么写。
+    🔴 **这里永远不写值**：这份清单会铺进开发包（跟着块作者的编辑器走），而环境里有
+       数据库连接串与登录密钥。块的配置面是白名单，同一个道理。
+    """
+
+    #: 变量名。⚠️ 前缀那一条写的是 `BLOCK_*` —— 它不是一个真名字，是一族名字的前缀。
+    name: str
+    #: 这个变量管什么（一句人话）。
+    brief: str
+    #: 能直接粘进 `.env` 的一行（没有例子就是空串）。
+    hint: str = ''
+    #: 必填吗（缺了就跑不起来的那几项）。
+    required: bool = False
+    #: 分组（开发包里按它分段；"哪几项是登录用的"也从这里取）。
+    group: str = '平台'
+
+
+#: 平台读的**全部**环境变量 —— 唯一真源。
+#:
+#: 🔴 它是一份**清单**，不是"读值的入口"：各处仍然各读各的（`read_env('DATABASE_URL')` 之类）。
+#:    两者对不上的风险由 `tools/sdk-check-py.mjs` 兜住：它扫一遍库里所有 `read_env('<名字>')`
+#:    字面量，漏在这份清单外的当场报红。
+ENV_ITEMS: tuple[EnvItem, ...] = (
+    # ── 登录（Authing OIDC）：这四项不配就没人能登录 ──
+    EnvItem(
+        name='SSO_ISSUER',
+        brief='Authing 的 OIDC 发证地址（OIDC discovery 就在它下面）',
+        hint='SSO_ISSUER=https://<你的域名>.authing.cn/oidc',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_CLIENT_ID',
+        brief='Authing 应用的 App ID',
+        hint='SSO_CLIENT_ID=<Authing 应用的 App ID>',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_CLIENT_SECRET',
+        brief='Authing 应用的 App Secret（**只在服务端**用，别带进前端）',
+        hint='SSO_CLIENT_SECRET=<Authing 应用的 App Secret>',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_REDIRECT_URI',
+        brief='登录回调地址（必须与 Authing 应用里登记的那个逐字一致）',
+        hint='SSO_REDIRECT_URI=http://localhost:8000/auth/callback',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_WEB_ORIGIN',
+        brief='登录成功后把人送回哪个前端地址（不写就用 auth/sso.py 里的默认值）',
+        hint='SSO_WEB_ORIGIN=http://localhost:5173',
+        group=LOGIN_GROUP,
+    ),
+    # ── 跨源与数据库 ──
+    EnvItem(
+        name='CORS_ORIGIN',
+        brief='允许跨源访问的前端地址（逗号分隔）；它同时是 CSRF 信任名单的来源',
+        hint='CORS_ORIGIN=http://localhost:5173',
+        group='跨源与数据库',
+    ),
+    EnvItem(
+        name='DATABASE_URL',
+        brief='项目数据库连接串（postgres://… 形式）；不写就用项目自己 settings 里的 DATABASES',
+        hint='DATABASE_URL=postgres://user:password@127.0.0.1:5432/app',
+        group='跨源与数据库',
+    ),
+    # ── 平台开关 ──
+    EnvItem(
+        name='BOOTSTRAP_ADMIN_WORK_IDS',
+        brief='启动时按工号把这些人设成管理员（逗号分隔，上限 200；只增不减）',
+        hint='BOOTSTRAP_ADMIN_WORK_IDS=1001',
+        group='平台开关',
+    ),
+    EnvItem(
+        name='LABULL_SCHEMA_CANVAS',
+        brief='数据模型那一页的开关：on 常开 / auto 只在 DEBUG 开 / 其余（默认）不开',
+        hint='LABULL_SCHEMA_CANVAS=on',
+        group='平台开关',
+    ),
+    EnvItem(
+        name='LABULL_CONTRACT_PATH',
+        brief='模型形状那份 JSON 的落点（画布拿它比"上一版"；默认 .labull/contract.json）',
+        hint='LABULL_CONTRACT_PATH=.labull/contract.json',
+        group='平台开关',
+    ),
+    # ── 块的配置面 ──
+    EnvItem(
+        name=f'{BLOCK_CONFIG_PREFIX}*',
+        brief='块的配置面：**只有**带这个前缀的变量才进 ctx.config（前缀剥掉当键，别的变量一个都不给块）',
+        hint=f'{BLOCK_CONFIG_PREFIX}OCR_KEY=xxx',
+        group='块的配置',
+    ),
+)
+
+
+def required_items(group: str) -> tuple[EnvItem, ...]:
+    """某一组里必填的那几项（顺序 = `ENV_ITEMS` 里的顺序，所以报错顺序稳定）。"""
+    return tuple(item for item in ENV_ITEMS if item.group == group and item.required)

labull_framework/jsonio.py

@@ -0,0 +1,57 @@
+"""JSON 线格式的唯一出口。
+
+🔴 三件事都只有一处实现：回一份 JSON、回一句人话的报错、"没登录"那句报文。
+两处各写一份的后果是前端要按两种形状判错 —— 那种漂最难查。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from django.http import JsonResponse
+
+#: "没登录"那句报文。**唯一一份**（尾部的句号是报文的一部分）。
+NO_IDENTITY_MESSAGE = '还没有登录，或者会话已经失效了。'
+
+
+def json_response(data: Any, status: int = 200) -> JsonResponse:
+    """回一份 JSON。
+
+    🔴 `ensure_ascii=False`：否则给管理员看的中文操作指引全变 `\\uXXXX`，等于报文不存在。
+    🔴 **`charset=utf-8` 要显式写**：Django 默认只回 `application/json`，而**没有 charset 的 JSON
+       按标准默认是 UTF-8、按某些客户端的实现不是** —— 那会让中文在浏览器里变乱码，
+       而症状看着像"后端没转义对"。带 BOM 的请求体（Windows 编辑器常见）也靠它才解得对。
+    ⚠️ `data` 只能是可序列化的**数据**（dict / list / 标量）：块返回值那种"已经编好的 JSON 文本"
+       由 `dispatch` 自己回 `HttpResponse`，不走这里 —— 走这里就会被再编一遍（变成带引号的字符串）。
+    """
+    return JsonResponse(
+        data,
+        safe=False,
+        status=status,
+        content_type='application/json; charset=utf-8',
+        json_dumps_params={'ensure_ascii': False},
+    )
+
+
+def problem(message: str, status: int) -> JsonResponse:
+    """回一句人话的报错（形状与前端约定的 `{statusCode, message}` 一致）。"""
+    return json_response({'statusCode': status, 'message': message}, status=status)
+
+
+def no_identity() -> JsonResponse:
+    """回 401 的唯一出口。"""
+    return problem(NO_IDENTITY_MESSAGE, 401)
+
+
+def iso_utc(value: datetime | None) -> str | None:
+    """时间序列化**只有这一处**：UTC、毫秒精度、`Z` 结尾。
+
+    🔴 两份形状（一处毫秒、一处 `isoformat()`）迟早让前端做两套解析 —— 所以只留这一份。
+    """
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    value = value.astimezone(timezone.utc)
+    return value.strftime('%Y-%m-%dT%H:%M:%S.') + f'{value.microsecond // 1000:03d}Z'

labull_framework/magic_block/__init__.py

@@ -0,0 +1,2 @@
+# 这个包刻意保持为空：子模块之间的依赖是单向的（sdk ← validate ← service ← views），
+# 在这里 import 任何东西都会让那条单向链变成环 —— 保存路径会在导入期就炸。