labull-framework 0.1.0__py3-none-any.whl

labull_framework/canvas/data.py

@@ -0,0 +1,523 @@
+"""画布要的数据：从模型元数据算出来，再与 git 里那份比出加 / 改 / 删。"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from django.apps import apps
+from django.conf import settings
+
+from .. import env
+
+#: 拖拽位置的落点（相对项目根）。🚫 不落盘也能用（没有这个目录就不持久化，不报错）。
+LAYOUT_FILE = '.labull/schema-layout.json'
+
+#: 不画这几张：它们是**Django 自己的**（会话 / 权限 / 内容类型 / 后台日志），
+#: 与"这个项目的数据模型"无关，摆在图上只会淹掉真正的业务表。
+SKIP_TABLES = frozenset(
+    {
+        'auth_group',
+        'auth_group_permissions',
+        'auth_permission',
+        'auth_user_groups',
+        'auth_user_user_permissions',
+        'django_admin_log',
+        'django_content_type',
+        'django_migrations',
+        'django_session',
+    }
+)
+
+
+def enabled() -> bool:
+    """那一页开不开：`on` 常开；`auto` 只在 `DEBUG` 时开；其余（含默认 `off`）不开。"""
+    switch = env.read_env('LABULL_SCHEMA_CANVAS').lower()
+    if switch == 'on':
+        return True
+    if switch == 'auto':
+        return bool(getattr(settings, 'DEBUG', False))
+    return False
+
+
+def _relation_of(field: Any, kind: str, cardinality: str, target: Any, **extra: Any) -> dict[str, Any]:
+    """一条关联在画布上的全部信息（**唯一一处**拼这个字典）。
+
+    🔴 `null` / `unique` 也要给：关联键名旁边那两个小标（必填 / 可空、唯一）就读它们。
+       只有**真列**才有这两项 —— 反向关联在库里没有这一列，所以那两个键是 `None`（不是 `False`：
+       `False` 会被前端读成"非空"，对这个字段来说是句谎话）。
+    """
+    item: dict[str, Any] = {
+        'field': field.name,
+        'kind': kind,
+        'cardinality': cardinality,
+        'target': target.__name__ if target else '',
+        'targetTable': str(target._meta.db_table) if target else '',
+        'column': None,
+        'via': None,
+        'brief': _brief(field),
+        # 真列才有的那几项；反向 / 多对多用 `None` 表示"这一侧没有列"。
+        'null': bool(getattr(field, 'null', False)) if kind in ('foreignKey', 'oneToOne') else None,
+        'unique': bool(getattr(field, 'unique', False)) if kind in ('foreignKey', 'oneToOne') else None,
+    }
+    item.update(extra)
+    return item
+
+
+def _brief(obj: Any) -> str:
+    """模型的 docstring / 字段的 `help_text` —— 画布上的"备注"就读它。
+
+    🔴 **整段都留着，不砍成一行**：点开表标题时要看到完整的说明（那才是"备注"的用处）。
+       画布上那一行短标签用 `_brief_line()` 取首行。
+    """
+    text = (getattr(obj, 'help_text', '') or getattr(obj, '__doc__', '') or '').strip()
+    if not text:
+        return ''
+    # 🔴 `help_text` 常常是"订单号"这种一行；模型 docstring 可能多段 —— 去掉每行的公共缩进，
+    #    别把源码里的缩进带到页面上。
+    lines = [line.rstrip() for line in text.splitlines()]
+    indents = [len(line) - len(line.lstrip()) for line in lines if line.strip()]
+    cut = min(indents) if indents else 0
+    return '\n'.join(line[cut:] for line in lines).strip()
+
+
+def _brief_line(obj: Any) -> str:
+    """备注的首行（画布上那行短标签用）。"""
+    brief = _brief(obj)
+    return brief.splitlines()[0].strip() if brief else ''
+
+
+def _type_of(field: Any) -> str:
+    """Django 字段 → **库里那一列的真实类型**（画布右侧那个小字）。
+
+    🔴 这里只回答"数据库里长什么样"；"这个字段在 Django 里是什么"由 `_kind_of` 回答。
+       两者刻意分开：`FileField` 在库里就是一列 varchar，而人关心的是"这是个文件字段"。
+    """
+    from django.db import models
+
+    mapping = (
+        (models.BigAutoField, 'bigint'),
+        (models.BigIntegerField, 'bigint'),
+        (models.AutoField, 'integer'),
+        (models.IntegerField, 'integer'),
+        (models.SmallIntegerField, 'integer'),
+        (models.PositiveIntegerField, 'integer'),
+        (models.BooleanField, 'boolean'),
+        (models.DateField, 'date'),
+        (models.DateTimeField, 'timestamp'),
+        (models.TimeField, 'time'),
+        (models.DurationField, 'interval'),
+        (models.DecimalField, 'numeric'),
+        (models.FloatField, 'real'),
+        (models.JSONField, 'jsonb'),
+        (models.UUIDField, 'uuid'),
+        (models.BinaryField, 'bytea'),
+        (models.FileField, 'varchar'),
+        (models.ImageField, 'varchar'),
+        (models.EmailField, 'varchar'),
+        (models.URLField, 'varchar'),
+        (models.SlugField, 'varchar'),
+        (models.GenericIPAddressField, 'inet'),
+        (models.CharField, 'varchar'),
+        (models.TextField, 'text'),
+    )
+    for cls, name in mapping:
+        if isinstance(field, cls):
+            return name
+    return 'text'
+
+
+def _kind_of(field: Any) -> str:
+    """Django 字段的**种类**（画布左侧那个彩色小标：枚举 / 文件 / 关联 / 金额 …）。
+
+    ⚠️ 顺序有意义：`ImageField` 是 `FileField` 的子类、`EmailField` 是 `CharField` 的子类 ——
+       具体的必须先判，否则全都会被归成父类那一档。
+    """
+    from django.db import models
+
+    if getattr(field, 'is_relation', False):
+        if field.one_to_one:
+            return 'oneToOne'
+        if field.many_to_many:
+            return 'manyToMany'
+        return 'foreignKey'
+    if getattr(field, 'choices', None):
+        return 'enum'
+    # 具体类型要排在父类前面（见上面那条警告）。
+    for cls, name in (
+        (models.ImageField, 'image'),
+        (models.FileField, 'file'),
+        (models.EmailField, 'email'),
+        (models.URLField, 'url'),
+        (models.SlugField, 'slug'),
+        (models.UUIDField, 'uuid'),
+        (models.GenericIPAddressField, 'ip'),
+        (models.JSONField, 'json'),
+        (models.DecimalField, 'money'),
+        (models.DurationField, 'duration'),
+        (models.DateTimeField, 'datetime'),
+        (models.DateField, 'date'),
+        (models.TimeField, 'time'),
+        (models.BooleanField, 'boolean'),
+        (models.BinaryField, 'binary'),
+        (models.TextField, 'text'),
+        (models.CharField, 'varchar'),
+        (models.IntegerField, 'integer'),
+        (models.FloatField, 'float'),
+    ):
+        if isinstance(field, cls):
+            return name
+    return 'other'
+
+
+def _file_of(field: Any) -> dict[str, Any] | None:
+    """文件 / 图片字段那一行额外信息：上传到哪、是不是必填、能传什么。
+
+    🔴 路径按**相对项目根**显示（`media/…`）：绝对路径在页面上没有信息量，
+       而且会把开发机的目录结构暴露出去。
+    """
+    from django.db import models
+
+    if not isinstance(field, models.FileField):
+        return None
+    base = getattr(settings, 'BASE_DIR', None)
+    upload = getattr(field, 'upload_to', None)
+    location = ''
+    if upload:
+        location = upload if isinstance(upload, str) else getattr(upload, '__name__', str(upload))
+        if base is not None and location.startswith(str(base)):
+            location = str(Path(location).relative_to(base)).replace('\\', '/')
+    return {
+        'uploadTo': location or None,
+        'storage': type(field.storage).__name__ if getattr(field, 'storage', None) is not None else None,
+        'widthField': getattr(field, 'width_field', None) or None,
+        'heightField': getattr(field, 'height_field', None) or None,
+    }
+
+
+def _shape_field(field: Any, model: Any) -> dict[str, Any]:
+    """一个字段在画布上的全部信息（**唯一一处**拼这个字典）。"""
+    kind = _kind_of(field)
+    item: dict[str, Any] = {
+        'name': field.name,
+        'column': str(field.attname),
+        'type': _type_of(field),
+        'kind': kind,
+        'primary': bool(field.primary_key),
+        'null': bool(getattr(field, 'null', False)),
+        'blank': bool(getattr(field, 'blank', False)),
+        'unique': bool(getattr(field, 'unique', False)) and not field.primary_key,
+        'brief': _brief(field),
+        'briefLine': _brief_line(field),
+        'enum': _enum_of(field),
+        'file': _file_of(field),
+        # 默认值也要能看（`default=Status.OPEN` 这类信息在页面上很有用）。
+        'default': _default_of(field),
+    }
+    if kind in ('foreignKey', 'oneToOne', 'manyToMany'):
+        target = field.related_model
+        item['target'] = {
+            'table': str(target._meta.db_table) if target else '',
+            'name': target.__name__ if target else '',
+            'label': str(getattr(target._meta, 'verbose_name', '') or '') if target else '',
+        }
+        item['onDelete'] = getattr(getattr(field, 'remote_field', None), 'on_delete', None).__name__ if getattr(field, 'remote_field', None) and getattr(field.remote_field, 'on_delete', None) else None
+        if kind == 'manyToMany':
+            through = getattr(getattr(field, 'remote_field', None), 'through', None)
+            item['via'] = str(through._meta.db_table) if through is not None else None
+    return item
+
+
+def _default_of(field: Any) -> str | None:
+    """默认值的人类写法（`NOT_PROVIDED` / 可调用的 / 枚举取值都要说得清）。"""
+    from django.db.models import NOT_PROVIDED
+
+    if getattr(field, 'has_default', lambda: False)():
+        default = getattr(field, 'default', None)
+        if default is NOT_PROVIDED:
+            return None
+        if callable(default):
+            return f'{getattr(default, "__name__", default)}()'
+        return str(getattr(default, 'value', default))
+    # `auto_now_add` / `auto_now` 不是 default，但页面上得看得见。
+    if getattr(field, 'auto_now_add', False):
+        return 'auto_now_add'
+    if getattr(field, 'auto_now', False):
+        return 'auto_now'
+    return None
+
+
+def _verbose(model: Any) -> str:
+    """模型的中文名（`Meta.verbose_name`）—— 有就显示，没有就空着。"""
+    return str(getattr(model._meta, 'verbose_name', '') or '')
+
+
+def shape() -> dict[str, list[dict[str, Any]]]:
+    """当前的模型形状（进程内现算，不需要任何文件）。
+
+    🔴 这里**只读 Django 的 `_meta`**：docstring 当表备注、`help_text` 当字段备注、
+       `choices` 当枚举、`related_model` 当关联 —— 一行正则、一段 AST 都没有。
+       扫源码抠这些信息只是在一份已经结构化的东西上再猜一遍。
+    """
+    tables: list[dict[str, Any]] = []
+    for model in apps.get_models():
+        if str(model._meta.db_table) in SKIP_TABLES:
+            continue
+        label = str(model._meta.app_label)
+        fields: list[dict[str, Any]] = []
+        relations: list[dict[str, Any]] = []
+        for field in model._meta.get_fields():
+            if getattr(field, 'many_to_many', False):
+                target = field.related_model
+                through = getattr(getattr(field, 'remote_field', None), 'through', None)
+                relations.append(
+                    _relation_of(
+                        field,
+                        'manyToMany',
+                        '*',
+                        target,
+                        via=str(getattr(through._meta, 'db_table', '') or '') or None,
+                    )
+                )
+                continue
+            if getattr(field, 'one_to_many', False) and not getattr(field, 'one_to_one', False):
+                # 🔴 **反向那一侧也要画**：从 `Customer` 看不到"它被多少订单引用"，
+                #    图就是半个 —— 老项目那套连线两边都连。反向是**只读**的（库里没有这一列）。
+                # ⚠️ 反向的一对一**跳过**：它的正向那一边已经画了一条线，两边都画就成了两条重合的线。
+                target = field.related_model
+                relations.append(_relation_of(field, 'reverse', '*', target, readonly=True))
+                continue
+            if not hasattr(field, 'attname'):
+                continue
+            if getattr(field, 'is_relation', False):
+                target = field.related_model
+                # 🔴 基数：`1` = 这一头只指一行（外键 / 一对一）；`*` = 多（多对多）。
+                #    连线两端各画一个，合起来就是"一对多""多对多"。
+                kind = 'oneToOne' if field.one_to_one else 'foreignKey'
+                relations.append(
+                    _relation_of(field, kind, '1', target, column=str(field.attname))
+                )
+            fields.append(_shape_field(field, model))
+        tables.append(
+            {
+                'name': model.__name__,
+                'table': str(model._meta.db_table),
+                'module': label,
+                'verbose': _verbose(model),
+                'brief': _brief(model),
+                'briefLine': _brief_line(model),
+                'fields': fields,
+                'relations': relations,
+            }
+        )
+    tables.sort(key=lambda item: (item['module'], item['table']))
+    return {'tables': tables}
+
+
+def _type_of(field: Any) -> str:
+    """Django 字段 → 契约里那几种类型之一。
+
+    🔴 文件列**没有单独的类型**：`FileField` 在库里就是一列 varchar，所以按 `text` 报。
+    """
+    from django.db import models
+
+    mapping = (
+        (models.BigAutoField, 'bigint'),
+        (models.BigIntegerField, 'bigint'),
+        (models.AutoField, 'integer'),
+        (models.IntegerField, 'integer'),
+        (models.SmallIntegerField, 'integer'),
+        (models.BooleanField, 'boolean'),
+        (models.DateField, 'date'),
+        (models.DateTimeField, 'timestamp'),
+        (models.DecimalField, 'numeric'),
+        (models.FloatField, 'real'),
+        (models.JSONField, 'jsonb'),
+    )
+    for cls, name in mapping:
+        if isinstance(field, cls):
+            return name
+    if isinstance(field, (models.CharField, models.SlugField)):
+        return 'varchar'
+    return 'text'
+
+
+def _enum_of(field: Any) -> dict[str, Any] | None:
+    """枚举列：`TextChoices` 在 `_meta` 里只剩「取值 → 中文名」这两样。"""
+    choices = list(getattr(field, 'choices', None) or [])
+    if not choices:
+        return None
+    values = [str(value) for value, _ in choices]
+    labels = {str(value): str(label) for value, label in choices}
+    return {'values': values, 'labels': labels}
+
+
+def payload() -> dict[str, Any]:
+    """画布整包：当前形状 + 与 git 那份比出来的三态 + 头部那行 git 信息 + 布局。
+
+    🔴 **被删掉的表也要带上**（`deletedTables`）：不然页面上只有"删除 N"这个数字，
+       看不到删掉的是哪张、原来有哪些列 —— 那正是重构时最需要看的东西。
+       它们从基线那份契约里取，列结构与当前形状同形（老契约里没有的新字段按缺省补）。
+    """
+    from . import gitinfo
+
+    current = shape()
+    current_tables = current['tables']
+    baseline = gitinfo.baseline_tables()
+    diff = _diff(baseline, current_tables)
+    return {
+        'tables': current_tables,
+        'deletedTables': _deleted_tables(baseline, diff['deleted']),
+        'diff': diff,
+        # 逐列的差异（`表名 → {added, modified, deleted}`）：前端拿它给**整行**上色。
+        'fieldDiff': _field_diff(baseline, current_tables),
+        'git': gitinfo.head(),
+        'baseline': 'none' if baseline is None else 'present',
+        'layout': read_layout(),
+    }
+
+
+def _deleted_tables(baseline: list[dict[str, Any]] | None, deleted: list[str]) -> list[dict[str, Any]]:
+    """基线里有、现在没有的那些表（补上新契约才有的键，免得前端到处判空）。"""
+    if not baseline or not deleted:
+        return []
+    wanted = set(deleted)
+    out: list[dict[str, Any]] = []
+    for table in baseline:
+        if str(table.get('table')) not in wanted:
+            continue
+        item = dict(table)
+        item.setdefault('verbose', '')
+        item.setdefault('briefLine', item.get('brief', ''))
+        fields = []
+        for field in item.get('fields') or []:
+            field = dict(field)
+            field.setdefault('kind', 'other')
+            field.setdefault('briefLine', field.get('brief', ''))
+            field.setdefault('blank', False)
+            field.setdefault('unique', False)
+            fields.append(field)
+        item['fields'] = fields
+        item.setdefault('relations', [])
+        out.append(item)
+    return out
+
+
+def _field_diff(baseline: list[dict[str, Any]] | None, current_tables: list[dict[str, Any]]) -> dict[str, dict[str, list[str]]]:
+    """每一张表里**哪几列**是新增 / 改过 / 删掉的（键是列名）。
+
+    🔴 为什么要在后端算：书**没有 git 基线**时前端手里只有"现在这一份"，
+       它无从知道哪一列是新的。差异的判据只能有一处（就是这里），前端只负责上色。
+    🔴 只拿基线里那几张**现在还在**的表来比：被删掉的那些表由 `deletedTables` 整块呈现，
+       不需要再逐列标一遍。
+    🔴 判据与 `_compare_key()` 同源：**列的类型 / 主键 / 可空 / 唯一变了才算改**，
+       备注文案（`brief`）变了不算 —— 否则给某个字段补一句说明，整张表就满屏黄。
+    """
+    if not baseline:
+        return {}
+    before = {str(t.get('table')): _columns_of(t) for t in baseline}
+    out: dict[str, dict[str, list[str]]] = {}
+    for table in current_tables:
+        name = str(table.get('table'))
+        old = before.get(name)
+        if old is None:
+            continue  # 新增的表整块标色，不必逐列
+        new = _columns_of(table)
+        added = [key for key in new if key not in old]
+        removed = [key for key in old if key not in new]
+        changed = [
+            key
+            for key, column in new.items()
+            if key in old and _column_key(old[key]) != _column_key(column)
+        ]
+        if added or removed or changed:
+            out[name] = {'added': sorted(added), 'modified': sorted(changed), 'deleted': sorted(removed)}
+    return out
+
+
+def _columns_of(table: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """一张表的列（老契约用 `fields`、新契约用 `columns`，两个都认）。"""
+    columns = table.get('columns') if isinstance(table.get('columns'), list) else table.get('fields')
+    return {str(column.get('name')): column for column in columns or [] if isinstance(column, dict)}
+
+
+def _column_key(column: dict[str, Any]) -> Any:
+    """一列**用来比差异的那部分**（与 `_compare_key()` 里那一条同一份判据）。"""
+    return (
+        str(column.get('column') or column.get('name') or ''),
+        column.get('type'),
+        bool(column.get('primary')),
+        bool(column.get('null')),
+        bool(column.get('unique')),
+    )
+
+
+def _compare_key(table: dict[str, Any]) -> Any:
+    """一张表**用来比差异的那部分**（表名 + 列的形状）。
+
+    🔴 为什么不能整份对象直接 `!=`：契约里除了结构还有**文案与修饰**（`brief` / `briefLine` /
+       `verbose` / `kind` …），而这一页每次打开都可能给它们补点东西 ——
+       一旦补了，**没人碰过的表**也会被判成"修改"（真踩过：给 `brief` 补了一段 docstring，
+       于是三张没动过的表全变"修改"，那个功能就等于坏了）。
+       判据只留"改了什么才算改了结构"：列名 / 列名 / 类型 / 主键 / 可空 / 唯一。
+    ⚠️ 老契约用 `fields` 这个键，新契约用 `columns`：两个都要认，否则升级那一刻所有表都成"新增"。
+    """
+    columns = table.get('columns') if isinstance(table.get('columns'), list) else table.get('fields')
+    shape = []
+    for column in columns or []:
+        if not isinstance(column, dict):
+            continue
+        shape.append(_column_key(column))
+    return (table.get('table') or table.get('name'), shape)
+
+
+def _diff(baseline: list[dict[str, Any]] | None, current: list[dict[str, Any]]) -> dict[str, list[str]]:
+    """逐表逐列比出加 / 改 / 删。
+
+    🔴 **`baseline is None`（没有可比基线）⇒ 一条差异都不报**：把它当成"所有表都是新增"
+       会让一张干净的图满屏假红。三种输入各说各的：`None` = 没法比；`[]` = 基线里确实一张表都没有。
+    🔴 比的是 `_compare_key()`（结构），不是整份对象 —— 理由见那个函数。
+    """
+    if baseline is None:
+        return {'added': [], 'modified': [], 'deleted': []}
+    before = {str(t.get('table')): _compare_key(t) for t in baseline}
+    after = {str(t.get('table')): _compare_key(t) for t in current}
+    added = [name for name in after if name not in before]
+    deleted = [name for name in before if name not in after]
+    modified = [name for name in after if name in before and before[name] != after[name]]
+    return {
+        'added': sorted(added),
+        'modified': sorted(modified),
+        'deleted': sorted(deleted),
+    }
+
+
+def read_layout() -> dict[str, Any]:
+    """读拖拽位置（没有 / 读不出来都回空对象 —— 退回自动布局，不是错误）。"""
+    path = _layout_path()
+    if path is None or not path.is_file():
+        return {}
+    try:
+        parsed = json.loads(path.read_text(encoding='utf-8'))
+    except (OSError, ValueError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def write_layout(data: Any) -> dict[str, Any]:
+    """存拖拽位置。⚠️ 落点不存在就**不落盘**（也不报错）：这一页不该要求项目有某个目录。"""
+    path = _layout_path()
+    if path is None or not isinstance(data, dict):
+        return read_layout()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding='utf-8')
+    except OSError:
+        return {}
+    return data
+
+
+def _layout_path():
+    base = getattr(settings, 'BASE_DIR', None)
+    return (base / LAYOUT_FILE) if base else None

labull_framework/canvas/gitinfo.py

@@ -0,0 +1,155 @@
+"""画布要的 git 那一半：当前提交、那一行备注、以及**上一版**的模型形状。
+
+🔴 **基线就是当前提交（HEAD），不是 `HEAD~1`**：画布要回答的是"你现在改了什么"。
+   用 `HEAD~1` 的话，只有一个提交的项目会拿到空基线、页面永远显示"没有变化" —— 对新项目等于失效。
+🔴 **不是仓库 / 取不到那份文件 ⇒ 回 `None`**（"没有可比基线"是**正常状态**，不是错误）。
+🔴 这一层的输出只影响"差异"那几列；**当前形状完全不依赖 git**（它读的是进程内的模型元数据）。
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from django.conf import settings
+
+#: 模型形状 JSON 的落点（相对项目根）。它由 `manage.py labull_contract --out` 写出，**可选**：
+#: 不写就没有"上一版"可比，画布只画当前这份。
+DEFAULT_CONTRACT_PATH = '.labull/contract.json'
+
+#: git 单次调用的超时（秒）：它是画布页面的一个同步依赖，卡住就等于页面卡住。
+_TIMEOUT = 5
+
+
+def _run(args: list[str], cwd: Path) -> str | None:
+    """跑一条只读的 git 命令，返回 stdout（失败一律回 `None`）。
+
+    🔴 **必须显式 `encoding='utf-8'`**：`text=True` 在 Windows 上默认用**系统 ANSI 代码页（GBK）**
+       解码，而提交说明是中文 UTF-8 ⇒ 解码线程抛 `UnicodeDecodeError`，`stdout` 变成 `None`，
+       于是下一句 `.strip()` 报 `'NoneType' object has no attribute 'strip'` ——
+       症状是 `/canvas` 直接 500，而真因跟"模型"一个字都没关系（真踩过）。
+       `errors='replace'` 是第二道保险：真碰上编码诡异的输出，也宁可显示成问号，不要让整页崩掉。
+    """
+    try:
+        done = subprocess.run(
+            ['git', *args],
+            cwd=str(cwd),
+            capture_output=True,
+            encoding='utf-8',
+            errors='replace',
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        # git 没装 / 不是仓库 / 超时：都是"这一层拿不到信息"，不是错误（差异那几列留空即可）。
+        return None
+    output = done.stdout or ''
+    return output.strip() if done.returncode == 0 else None
+
+
+def _root() -> Path | None:
+    """项目根（`settings.BASE_DIR`）—— 那条"相对项目"的契约路径是相对它算的。"""
+    base = getattr(settings, 'BASE_DIR', None)
+    return Path(base) if base else None
+
+
+def _repo_root() -> Path | None:
+    """**git 仓库根**（`git rev-parse --show-toplevel`）。
+
+    🔴 为什么不能拿 `BASE_DIR` 当仓库根：`BASE_DIR` 是**项目**根（示例里是 `backend/example`），
+       而 `git show HEAD:<路径>` 里的路径是**相对仓库根**的。仓库根只要在更上面一层
+       （这个仓库就是：`BASE_DIR` 在 `backend/example`，仓库根在它上两层），
+       那条命令就会失败、`baseline_tables()` 永远回 `None` ——
+       症状是画布永远显示"没有可比基线"，而"提交过契约"这件事一点错都不报（真踩过）。
+    """
+    base = _root()
+    if base is None:
+        return None
+    top = _run(['rev-parse', '--show-toplevel'], base)
+    return Path(top) if top else None
+
+
+def contract_path() -> str:
+    """那份 JSON 的落点（项目可用 `LABULL_CONTRACT_PATH` 覆盖）。"""
+    from .. import env
+
+    return env.read_env('LABULL_CONTRACT_PATH') or DEFAULT_CONTRACT_PATH
+
+
+def _repo_relative_contract(repo: Path) -> str | None:
+    """契约路径换算成**相对仓库根**的形式（`git show` / `git diff` 认这个）。
+
+    契约在仓库外面（项目根不在仓库里，或者契约被 `LABULL_CONTRACT_PATH` 指到外面）⇒ `None`：
+    那种"这份文件不受版本控制"的情况就是**没有可比基线**，不是错误。
+    """
+    base = _root()
+    if base is None:
+        return None
+    absolute = (base / contract_path()).resolve()
+    try:
+        relative = absolute.relative_to(repo.resolve())
+    except ValueError:
+        return None
+    return relative.as_posix()
+
+
+def head() -> dict[str, Any] | None:
+    """头部那一行：提交号 / 备注 / 有没有父提交 / 这次改了哪些文件。
+
+    备注优先取中文（`备注：` 那一行，否则含中文的首行）—— 中文项目里英文的 commit 标题没什么信息量。
+    """
+    root = _root()
+    if root is None:
+        return None
+    full = _run(['rev-parse', 'HEAD'], root)
+    if not full:
+        return None
+    message = _run(['log', '-1', '--pretty=format:%s'], root) or ''
+    parent = _run(['rev-parse', f'{full}~1'], root)
+    files = (_run(['diff', '--name-only', parent, full], root) or '').splitlines() if parent else []
+    return {
+        'hash': full[:8],
+        'msg': _chinese_remark(message),
+        'hasParent': bool(parent),
+        'files': [line.strip() for line in files if line.strip()],
+        'baseRev': full[:8],
+    }
+
+
+def _chinese_remark(message: str) -> str:
+    for line in message.splitlines():
+        head, sep, tail = line.strip().partition('：')
+        if sep and head.lower() in ('备注', 'remark') and tail.strip():
+            return tail.strip()
+    for line in message.splitlines():
+        text = line.strip()
+        if text and any('\u4e00' <= ch <= '\u9fa5' for ch in text):
+            return text
+    return message.splitlines()[0].strip() if message else ''
+
+
+def baseline_tables() -> list[dict[str, Any]] | None:
+    """**上一版**的表定义（从 git 的那个提交里取）。
+
+    三种返回值的语义不同，别混：`None` = 没有可比基线（不是仓库 / 提交里没有那份文件 / 文件坏了）；
+    `[]` = 有基线，但基线里确实一张表都没有；有内容 = 正常逐表比。
+    """
+    repo = _repo_root()
+    if repo is None:
+        return None
+    relative = _repo_relative_contract(repo)
+    if relative is None:
+        return None
+    text = _run(['show', f'HEAD:{relative}'], repo)
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        # 提交里那份坏了（手改过 / 写到一半就提交了）⇒ 当"没有基线"，
+        # 而不是拿半份数据去比（那会报出一堆假的新增 / 删除）。
+        return None
+    tables = parsed.get('tables') if isinstance(parsed, dict) else None
+    return tables if isinstance(tables, list) else None