h3factory 0.0.0-stage → 0.2.2

package/h3design/dsl.py

@@ -0,0 +1,553 @@
+# -*- coding: utf-8 -*-
+"""表单 DSL：项目定义 → 与奥驰 forms.build 同构的控件结构。
+
+项目目录约定（projects/<name>/）：
+    config.json      连接配置（缺省用工作区/用户配置；含凭据，勿提交/分享）
+    dicts.json       枚举分类，下拉/单选/复选的选项源
+    sheets/*.json    每表单一个 JSON 定义（文件名 = 表单 key）—— 推荐模式
+    forms.py         旧版 python 定义（legacy 兼容，见 examples/aochi 迁移说明）
+
+load_project() 返回 {key: loader}，loader() 产出
+    {key, title, name_schema, fields, layout, assoc, useOwner}
+其中 fields/layout 直接可喂给 newbuilder.build_schema_str / build_biz_sheet；
+useOwner 供 build 期望字段数补 OwnerId/OwnerDeptId 两系统字段。
+JSON 完整格式见 docs/schema_doc.md。"""
+import importlib.util
+import json
+import os
+import sys
+
+from . import controls as C
+
+# =====================================================================
+# 系统拥有者字段（OwnerId/OwnerDeptId）：Layout 专用伪控件，
+# 不进 fields/Properties（系统字段），Options 逐字对照线上回读样本。
+# useOwner=true 后可在 layout 行内以字符串 "OwnerId"/"OwnerDeptId" 引用。
+# =====================================================================
+_OWNER_OPT = {
+    "Key": "OwnerId", "Type": 203, "ChildControls": None, "Options": {
+        "DataField": "OwnerId", "DisplayName": "申请人", "Description": "",
+        "ControlKey": "FormUser", "Summary": "", "DisplayRule": {"Rule": ""},
+        "UnitSelectionRange": "", "IsRelatedMember": False, "ShowUnActive": False,
+        "UseDataCache": True, "CurrentUserId": False,
+        "MappingControls": '{"ParentId":"OwnerDeptId"}',
+        "OrgUnitVisible": False, "UserVisible": True, "OwnDepVisible": False,
+        "OwnDepUsersVisble": True, "IsMultiple": False, "ShowCurUser": False}}
+_OWNER_DEPT_OPT = {
+    "Key": "OwnerDeptId", "Type": 204, "ChildControls": None, "Options": {
+        "DataField": "OwnerDeptId", "DisplayName": "申请部门", "Description": "",
+        "ControlKey": "FormDepartment", "Summary": "", "DisplayRule": {"Rule": ""},
+        "UnitSelectionRange": "", "IsRelatedMember": False, "ShowUnActive": False,
+        "UseDataCache": True, "CurrentUserId": False, "MappingControls": "",
+        "OrgUnitVisible": True, "UserVisible": False, "OwnDepVisible": True,
+        "OwnDepUsersVisble": False, "IsMultiple": False}}
+
+
+def owner_presets(applicant_label="申请人", dept_label="申请部门"):
+    """两个系统拥有者布局项（拷贝后改显示名）"""
+    o, d = _OWNER_OPT, _OWNER_DEPT_OPT
+    if applicant_label != "申请人":
+        o = json.loads(json.dumps(o, ensure_ascii=False))
+        o["Options"]["DisplayName"] = applicant_label
+    if dept_label != "申请部门":
+        d = json.loads(json.dumps(d, ensure_ascii=False))
+        d["Options"]["DisplayName"] = dept_label
+    return o, d
+
+
+def _read_json(path, what=""):
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _dict_entries(proj_dir, cat):
+    """dicts.json 中分类枚举 → [{"code":..., "name":...}]。
+    条目简写（纯字符串）或 {code?, name, enabled?}；数组顺序即排序。"""
+    dp = os.path.join(proj_dir, "dicts.json")
+    if not os.path.isfile(dp):
+        raise ValueError("引用字典分类 %r 但项目缺 %s" % (cat, dp))
+    d = _read_json(dp)
+    items = d.get(cat)
+    if items is None:
+        raise ValueError("dicts.json 缺分类 %r（现有 %s）" % (cat, list(d)))
+    out = []
+    for it in items:
+        if isinstance(it, str):
+            out.append({"code": it, "name": it})
+        elif isinstance(it, dict):
+            if it.get("enabled") is False:
+                continue
+            name = it["name"]
+            out.append({"code": it.get("code") or name, "name": name})
+        else:
+            raise ValueError("分类 %r 条目须为字符串或对象: %r" % (cat, it))
+    if not out:
+        raise ValueError("分类 %r 无可启用条目" % cat)
+    return out
+
+
+def _options(proj_dir, spec):
+    """控件选项源：dict=分类名引用 dicts.json；options=字面量数组"""
+    if spec.get("dict"):
+        return [e["name"] for e in _dict_entries(proj_dir, spec["dict"])]
+    if spec.get("options"):
+        return [str(x) for x in spec["options"]]
+    raise ValueError("%s.%s 需 dict 或 options" % (spec.get("key"), spec.get("type")))
+
+
+def _rule(spec):
+    return spec.get("hideWhen") or ""
+
+
+# 联动下拉(选项来自另一张表)过滤规则序列化。声明形态（schema_doc 联动下拉章节）：
+#   {field: 源表字段编码, op: "="(缺省) | "contains", value: 常量字符串 | ref: 本表字段key}
+# 实证语法（2026-09-09 类型试验 三处载荷逐字）：常量等值 {源.字段}=="值"、
+# 动态引用 {源.字段}=={本表字段}、多值列包含 CONTAINS({源.字段},{本表字段})，
+# 条件间 " AND " 连接。发 clean 文本（== 无空格、无 NBSP）——引擎直接接受
+# （第一轮无 NBSP 样本保存成功）；NBSP/空格是 UI 重存才插入的漂移。
+def _filter_text(spec, src_code, key):
+    entries = spec.get("filter")
+    if entries in (None, [], ""):
+        return ""
+    if not isinstance(entries, list):
+        raise ValueError("%s: filter 须为条件数组（{field,op,value|ref}）" % key)
+    parts = []
+    for it in entries:
+        if not isinstance(it, dict):
+            raise ValueError("%s: filter 条目须为对象: %r" % (key, it))
+        f = it.get("field")
+        if not isinstance(f, str) or not f:
+            raise ValueError("%s: filter 条目缺 field（源表字段编码）: %r" % (key, it))
+        op, ref, value = it.get("op", "="), it.get("ref"), it.get("value")
+        lhs = "{%s.%s}" % (src_code, f)
+        if op == "contains":
+            if ref is None or "value" in it:
+                raise ValueError("%s: contains 条件须且只须 ref（本表字段 key，"
+                                 "CONTAINS 按分号串包含匹配源表该列）: %r" % (key, it))
+            parts.append("CONTAINS(%s,{%s})" % (lhs, ref))
+        elif op == "=":
+            if (ref is None) == ("value" not in it):
+                raise ValueError("%s: 等值条件须且只须 value（常量）或 ref"
+                                 "（本表字段动态引用）其一: %r" % (key, it))
+            if "value" in it:
+                if not isinstance(value, str):
+                    raise ValueError("%s: 常量 value 须为字符串（数字常量带引号"
+                                     "比较未实证）: %r" % (key, it))
+                parts.append("%s==%s" % (lhs, json.dumps(value, ensure_ascii=False)))
+            else:
+                parts.append("%s=={%s}" % (lhs, ref))
+        else:
+            raise ValueError("%s: filter op 仅支持 =/contains（实证集合），得 %r"
+                             % (key, op))
+    return " AND ".join(parts)
+
+
+def _assoc_dropdown(spec, registry, app_code):
+    """dropdown spec（带 assoc）→ C.assoc_dropdown 控件。assoc 引 registry 里
+    已注册的源表单 key（先建被引用表，同 query）；存值列与过滤条件在此校验。"""
+    key, label = spec["key"], spec.get("label") or spec["key"]
+    if spec.get("dict") or spec.get("options"):
+        raise ValueError("%s: assoc 下拉选项来自另一张表，不能再给 dict/options" % key)
+    if spec.get("default") not in (None, ""):
+        raise ValueError("%s: assoc 下拉不支持 default（存值/回显语义未实证）" % key)
+    mf = spec.get("assocField")
+    if not isinstance(mf, str) or not mf:
+        raise ValueError("%s: assoc 下拉须声明 assocField（存值列 = 源表字段编码，"
+                         "如 \"code\" 存代码、\"name\" 存名称）" % key)
+    src = _assoc_code(spec["assoc"], registry, key)
+    return C.assoc_dropdown(key, label, src, mf,
+                            filter_rule=_filter_text(spec, src, key),
+                            app_package=app_code, rule=_rule(spec))
+
+
+# 子表列支持的控件类型（UI 实证范围：文本/数字/日期/开关/单选/复选/下拉；成员/部门/
+# 关联/嵌套子表暂不开放 —— 平台 104 列节点 Options 结构未实证）
+GRID_COL_TYPES = ("text", "textarea", "number", "date", "switch",
+                  "radio", "dropdown", "checkbox_list",
+                  # 2026-09-11 起开放附件/图片列 —— 与主表同款 Options 形状，
+                  # 线上实证见 projects/_types7_online trial8（列节点回读逐键比对）
+                  "attachment", "image")
+
+# 布局项：只占版面、不是字段（不进 SchemaStr.Properties、不进 verify 的字段集）
+#   group_title —— 分组标题（type 101，Options 只有 DisplayName/Title/Alignment）
+#   description —— 描述/说明文字（type 103，Content 为富文本 HTML）
+LAYOUT_TYPES = ("group_title", "description")
+
+
+def _build_layout_item(spec):
+    """布局项 spec → controls.group_title / controls.description 控件。"""
+    t = spec["type"]
+    key = spec["key"]
+    label = spec.get("label") or spec.get("title") or key
+    if t == "group_title":
+        align = spec.get("align") or "left"
+        if align not in ("left", "center", "right"):
+            raise ValueError("%s: group_title 的 align 只支持 left/center/right" % key)
+        return C.group_title(key, label, alignment=align)
+    content = spec.get("content")
+    if content is None:
+        content = "<p>%s</p>" % label        # 简写：没给 content 就用 label 兜底
+    if not isinstance(content, str):
+        raise ValueError("%s: description 的 content 须为 HTML 字符串" % key)
+    return C.description(key, content, display_name=spec.get("title") or "描述说明",
+                         rule=_rule(spec))
+
+
+def _assoc_code(assoc, registry, label=""):
+    if not assoc:
+        return ""
+    rec = (registry or {}).get(assoc) or {}
+    code = rec.get("code")
+    if not code:
+        raise ValueError("%s关联表单 %r 未注册（registry 无 code，先建被引用表）"
+                         % (label, assoc))
+    return code
+
+
+SEQNO_KEY = "SeqNo"       # 流水号字段编码固定 SeqNo（线上样本同款），定义里可省
+
+
+def _build_control(proj_dir, spec, registry, app_code):
+    t = spec["type"]
+    key = spec.get("key") or (SEQNO_KEY if t in ("seq_no", "seqno") else None)
+    if not key:
+        raise ValueError("控件缺 key（type=%r）；只有流水号可省，编码恒为 %s"
+                         % (t, SEQNO_KEY))
+    if spec.get("assoc") and t not in ("dropdown", "query"):
+        raise ValueError("%s: %s 不支持 assoc（选项来自另一张表只有下拉实证过，"
+                         "radio/checkbox_list 不能联动）" % (key, t))
+    label = spec.get("label") or ("流水号" if t in ("seq_no", "seqno") else key)
+    common = {"required": spec.get("required", False),
+              "readonly": spec.get("readonly", False)}
+    if t == "text":
+        return C.text(key, label, default=spec.get("default", ""),
+                      placeholder=spec.get("placeholder", ""),
+                      rule=_rule(spec))
+    if t == "textarea":
+        return C.textarea(key, label, rows=spec.get("rows", 3),
+                          default=spec.get("default", ""))
+    if t == "number":
+        return C.number(key, label, decimal=spec.get("decimal", 0),
+                        default=spec.get("default"), rule=_rule(spec))
+    if t == "date":
+        return C.date_field(key, label,
+                            datetime_mode=spec.get("datetime", "yyyy-MM-dd"),
+                            rule=_rule(spec))
+    if t == "switch":
+        return C.switch_field(key, label, checked=bool(spec.get("checked", False)))
+    if t == "radio":
+        return C.radio(key, label, _options(proj_dir, spec),
+                       default=spec.get("default", ""))
+    if t == "dropdown":
+        if spec.get("assoc"):
+            return _assoc_dropdown(spec, registry, app_code)
+        return C.dropdown(key, label, _options(proj_dir, spec),
+                          default=spec.get("default", ""), rule=_rule(spec))
+    if t == "checkbox_list":
+        return C.checkbox_list(key, label, _options(proj_dir, spec),
+                               default_items=spec.get("defaults", ()))
+    if t == "member":
+        return C.member(key, label, multi=bool(spec.get("multi", False)),
+                        rule=_rule(spec))
+    if t == "department":
+        return C.department(key, label, multi=bool(spec.get("multi", False)),
+                            rule=_rule(spec))
+    if t == "query":
+        code = _assoc_code(spec.get("assoc"), registry, key)
+        return C.query(key, label, code, app_package=app_code,
+                       multi=bool(spec.get("multi", False)), rule=_rule(spec))
+    if t in ("seq_no", "seqno"):
+        if spec.get("default") or spec.get("dict") or spec.get("options"):
+            raise ValueError("%s: 流水号不能给 default/dict/options（值由平台按规则发号）"
+                             % key)
+        try:
+            inc = int(spec.get("increment", 8))
+        except (TypeError, ValueError):
+            raise ValueError("%s: 流水号 increment 须为整数（位数，如 8）" % key)
+        mode = spec.get("datetime", "YYYY")
+        if not isinstance(mode, str) or not mode:
+            raise ValueError("%s: 流水号 datetime 须为字符串（如 YYYY/YYYYMM/YYYYMMDD）"
+                             % key)
+        return C.seqno(key, label, prefix=spec.get("prefix", ""),
+                       datetime_mode=mode, increment=inc)
+    if t in ("image", "photo"):
+        return C.photo(key, label, multiple=bool(spec.get("multiple", False)),
+                       camera_only=bool(spec.get("cameraOnly", False)),
+                       watermark=bool(spec.get("watermark", False)),
+                       compression=bool(spec.get("compression", False)),
+                       rule=_rule(spec))
+    if t == "attachment":
+        try:
+            mb = int(spec.get("maxSize", 10))
+        except (TypeError, ValueError):
+            raise ValueError("%s: 附件的 maxSize 须为整数（MB）" % key)
+        return C.attachment(key, label, max_upload_size=mb, rule=_rule(spec))
+    if t in ("location", "map"):
+        try:
+            meters = int(spec.get("meters", 500))
+        except (TypeError, ValueError):
+            raise ValueError("%s: 位置的 meters 须为整数（米）" % key)
+        return C.location(key, label, meters=meters,
+                          pc_enabled=bool(spec.get("pcEnabled", True)),
+                          editable=bool(spec.get("editable", False)),
+                          rule=_rule(spec))
+    if t == "address":
+        mode = spec.get("areaMode", "P-C-T")
+        if mode != "P-C-T":
+            raise ValueError("%s: 地址的 areaMode 目前只实证过 P-C-T（省-市-县）" % key)
+        return C.area(key, label, area_mode=mode,
+                      show_detail=bool(spec.get("showDetail", True)),
+                      rule=_rule(spec))
+    raise ValueError("未知控件类型 %r（%s）" % (t, key))
+
+
+def _resolve_layout(sheet, seq_default, fields_by_key, use_owner,
+                    extras_by_key=None, sub_keys=()):
+    """layout 定义 → newbuilder.build_biz_sheet 的行序列。
+    元素 = 控件 dict（整行单个）或控件 list（一行多列 ≤4）；
+    "OwnerId"/"OwnerDeptId" 字符串须 useOwner=true 才可用。
+    布局项（分组标题/描述）**只能单独成行**，且与 UI 样本一致作顶层条目
+    （extras_by_key 按定义侧短码 DefKey 索引；key 用 GUID 见 controls.layout_key）。
+    子表 key 不可进 layout：子表整行自动排在表单底部。"""
+    extras_by_key = extras_by_key or {}
+    owner = None
+    if use_owner:
+        owner = dict(zip(("OwnerId", "OwnerDeptId"), owner_presets()))
+    lay = sheet.get("layout")
+    if lay is None:
+        if use_owner:
+            raise ValueError("%s: useOwner=true 时必须显式 layout（行内写 OwnerId/OwnerDeptId）"
+                             % sheet.get("key"))
+        return list(seq_default)                   # 全 flat：按定义顺序每控件一行
+    if lay == "auto4":                             # 每 4 个控件一行；布局项独占一行
+        rows, cur = [], []
+
+        def flush():
+            if cur:
+                rows.append(list(cur))
+                del cur[:]
+
+        if use_owner:
+            cur.extend([owner["OwnerId"], owner["OwnerDeptId"]])
+        for item in seq_default:
+            if item.get("DefKey") in extras_by_key:   # 布局项：独占一行且是**顶层条目**
+                flush()
+                rows.append(item)
+                continue
+            cur.append(item)
+            if len(cur) == 4:
+                flush()
+        flush()
+        return rows
+
+    def resolve_one(item):
+        if isinstance(item, str):
+            if item in fields_by_key:
+                return fields_by_key[item]
+            if item in extras_by_key:
+                return extras_by_key[item]
+            if item in sub_keys:
+                raise ValueError("%s: 子表 %r 不占一行多列，自动排在表单底部（勿写进 layout）"
+                                 % (sheet.get("key"), item))
+            if owner and item in owner:
+                return owner[item]
+            raise ValueError("%s: layout 行内未知 key %r" % (sheet.get("key"), item))
+        if isinstance(item, dict):
+            if "owner" in item:
+                if not use_owner:
+                    raise ValueError("layout 含 owner 元素但 useOwner 缺省")
+                if str(item["owner"]).lower() in ("user", "owner"):
+                    return owner["OwnerId"]
+                return owner["OwnerDeptId"]
+            if "key" in item and "type" not in item:    # 行内控件对象（仅 key 定位）
+                return fields_by_key[item["key"]]
+        raise ValueError("layout 行内只能放字段 key 字符串: %r" % (item,))
+
+    seq = []
+    for row in lay:
+        if not isinstance(row, list):
+            raise ValueError("layout 须为行数组 [[k1,k2,...], ...] 或 'auto4'")
+        if len(row) > 4:
+            raise ValueError("一行多列最多 4 个控件: %r" % row)
+        row_ctl = [resolve_one(i) for i in row]
+        if len(row_ctl) > 1 and any(c.get("DefKey") in extras_by_key for c in row_ctl):
+            raise ValueError("%s: 布局项（分组标题/描述）只能单独成行，不能进一行多列: %r"
+                             % (sheet.get("key"), row))
+        # 布局项与 UI 样本一致作 **顶层条目**（不是 1 子项的 102 行）——布局项
+        # 本来就只能独占一行，故这里只影响布局项；普通单控件行保持既有 102 行包裹
+        # （已建成的表就是这么建的，改了会让 verify 行组期望对不上）
+        seq.append(row_ctl[0] if len(row_ctl) == 1
+                   and row_ctl[0].get("DefKey") in extras_by_key else row_ctl)
+    return seq
+
+
+def _build_subtable(sheet_key, spec, proj_dir, registry, app_code):
+    """子表 spec → {key,label,code,fixed,cols}。
+    code：registry[sheet_key]["subs"][subkey]["code"]（child schema 编码，
+    cli build 前由 sheet_sub_specs 预注册；离线 check 未注册时留空占位）。"""
+    sk = spec["key"]
+    label = spec.get("label") or sk
+    if not isinstance(spec.get("columns"), list) or not spec["columns"]:
+        raise ValueError("子表 %r.%s 缺 columns 列表" % (sheet_key, sk))
+    try:
+        fixed = int(spec.get("fixed", 1))
+    except (TypeError, ValueError):
+        raise ValueError("子表 %r.%s 的 fixed 须为数字" % (sheet_key, sk))
+    cols = []
+    for csp in spec["columns"]:
+        ct, ck = csp.get("type"), csp.get("key")
+        if ct not in GRID_COL_TYPES:
+            raise ValueError("子表 %r.%s 列 %r: 类型 %r 不支持（子表列支持 %s）"
+                             "；成员/部门/关联/嵌套子表/位置/地址/流水号/布局项作列未实证"
+                             "——列节点照抄主表同款的 Options 形状，这几类没有可照抄的实证样本"
+                             % (sheet_key, sk, ck, ct, "/".join(GRID_COL_TYPES)))
+        if csp.get("assoc"):
+            raise ValueError("子表 %r.%s 列 %r: 列内 assoc（联动下拉）未实证，暂不支持"
+                             % (sheet_key, sk, ck))
+        cols.append(_build_control(proj_dir, csp, registry, app_code))
+    code = (((registry or {}).get(sheet_key) or {}).get("subs") or {}
+            ).get(sk, {}).get("code", "")
+    return {"key": sk, "label": label, "code": code, "fixed": fixed, "cols": cols}
+
+
+def _group_specs(proj_dir):
+    """groups.json（可选）→ 有序分组清单 [{name, icon}]；无文件 → None。
+    文件为数组或 {"groups": [...]}；条目 = 字符串或 {name}。顺序 = 应用菜单顺序。"""
+    gp = os.path.join(proj_dir, "groups.json")
+    if not os.path.isfile(gp):
+        return None
+    d = _read_json(gp)
+    lst = d if isinstance(d, list) else (d or {}).get("groups")
+    if not isinstance(lst, list):
+        raise ValueError("groups.json 须为数组或 {\"groups\": [...]}: %r" % d)
+    out = []
+    for it in lst:
+        if isinstance(it, str) and it.strip():
+            out.append({"name": it, "icon": ""})
+        elif isinstance(it, dict) and str(it.get("name") or "").strip():
+            out.append({"name": str(it["name"]).strip(),
+                        "icon": str(it.get("icon") or "")})
+        else:
+            raise ValueError("groups.json 条目须为字符串或 {name}: %r" % (it,))
+    names = [g["name"] for g in out]
+    if len(set(names)) != len(names):
+        raise ValueError("groups.json 分组名重复: %s" % names)
+    return out
+
+
+def group_order(proj_dir):
+    """有序分组名清单；无 groups.json → None（分组不校验、按表单出现顺序归组）。"""
+    gs = _group_specs(proj_dir)
+    return None if gs is None else [g["name"] for g in gs]
+
+
+def sheet_sub_specs(path):
+    """扫 sheets/<key>.json 顶层子表 spec 列表（cli build 预注册 child 编码用，
+    不加载完整控件树、不联网）。"""
+    return [c for c in _read_json(path).get("controls", [])
+            if isinstance(c, dict) and c.get("type") == "subtable"]
+
+
+def _build_json_sheet(path, proj_dir, app_code, registry, group_specs=None):
+    sheet = _read_json(path)
+    key = os.path.splitext(os.path.basename(path))[0]
+    use_owner = bool(sheet.get("useOwner", False))
+    group = str(sheet.get("group") or "").strip()
+    if group and group_specs is not None \
+            and group not in [g["name"] for g in group_specs]:
+        raise ValueError("%s: 分组 %r 未在 groups.json 声明（现有 %s）"
+                         % (key, group, [g["name"] for g in group_specs]))
+    controls, subs, extras, seq_default, fields_by_key, assoc = [], [], [], [], {}, {}
+    extras_by_key = {}
+    for spec in sheet.get("controls", []):
+        if spec.get("type") == "subtable":
+            subs.append(_build_subtable(key, spec, proj_dir, registry, app_code))
+            continue
+        if spec.get("type") in LAYOUT_TYPES:          # 分组标题 / 描述：布局项
+            ctl = _build_layout_item(spec)
+            # 布局项的 Key 是 uuid5(短码)（见 controls.layout_key），定义侧短码在 DefKey：
+            # layout 行/去重都按短码走，回读与 verify 比对按 GUID key 走（同线上）
+            if ctl["DefKey"] in fields_by_key or ctl["DefKey"] in extras_by_key:
+                raise ValueError("%s: 控件 key 重复 %r" % (key, ctl["DefKey"]))
+            extras.append(ctl)
+            extras_by_key[ctl["DefKey"]] = ctl
+            seq_default.append(ctl)
+            continue
+        ctl = _build_control(proj_dir, spec, registry, app_code)
+        if ctl["Key"] in ("OwnerId", "OwnerDeptId"):
+            raise ValueError("OwnerId/OwnerDeptId 是系统字段，用 useOwner + layout 引用，"
+                             "不要放进 controls")
+        if ctl["Key"] in fields_by_key or ctl["Key"] in extras_by_key:
+            raise ValueError("%s: 控件 key 重复 %r" % (key, ctl["Key"]))
+        controls.append(ctl)
+        seq_default.append(ctl)
+        fields_by_key[ctl["Key"]] = ctl
+        if spec.get("type") in ("query", "dropdown") and spec.get("assoc"):
+            # 注册 assoc 关系（check/verify 展示用）；构建载荷侧 query 走 kwargs、
+            # 联动下拉走 Options.BOSchemaCode，此处只需登记不重复解析
+            assoc[ctl["Key"]] = {"assoc_schema_code":
+                                 ctl["Options"].get("BOSchemaCode", "")}
+    # 联动下拉的 filter 动态引用（ref）必须指向本表已有字段（级联链上源）
+    for spec in sheet.get("controls", []):
+        if spec.get("type") != "dropdown" or not spec.get("assoc"):
+            continue
+        for it in spec.get("filter") or []:
+            ref = (it or {}).get("ref")
+            if ref is not None and ref not in fields_by_key:
+                raise ValueError("%s: filter 动态引用 %r 不是本表字段"
+                                 "（ref 写本表单 controls 的 key）" % (key, ref))
+    layout = _resolve_layout(sheet, seq_default, fields_by_key, use_owner,
+                             extras_by_key=extras_by_key,
+                             sub_keys=tuple(s["key"] for s in subs))
+    return {"key": key,
+            "title": sheet.get("title") or key,
+            "name_schema": sheet.get("nameSchema") or "",
+            "fields": controls, "layout": layout, "assoc": assoc,
+            "useOwner": use_owner, "group": group, "extras": extras,
+            "subs": subs, "_source": os.path.relpath(path, proj_dir)}
+
+
+def _legacy_loaders(proj_dir, app_code, registry):
+    """旧版 forms.py（奥驰样式）→ {key: loader}。forms.py 保持自身约定：
+    BUILDERS 表 + build(key, app_code, rule_table_code=, apply_table_code=)"""
+    forms_path = os.path.join(proj_dir, "forms.py")
+    # legacy forms.py 顶层 import controls —— 新位置在 h3design/；兼容旧工程同目录写法
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))   # h3design/
+    sys.path.insert(0, proj_dir)
+    try:
+        mod_name = "_legacy_forms_" + str(abs(hash(forms_path)))
+        spec = importlib.util.spec_from_file_location(mod_name, forms_path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+    finally:
+        sys.path.pop(0)
+        sys.path.pop(0)
+    builders = getattr(mod, "BUILDERS")
+    t1 = ((registry or {}).get("table1") or {}).get("code", "")
+    t4 = ((registry or {}).get("table4") or {}).get("code", "")
+    out = {}
+    for key in builders:
+        def loader(key=key):
+            return mod.build(key, app_code, rule_table_code=t1,
+                             apply_table_code=t4)
+        out[key] = loader
+    return out
+
+
+def load_project(proj_dir, app_code, registry):
+    """项目全部表单 loader。JSON(sheets/*.json) 优先，legacy forms.py 合并。"""
+    out = {}
+    sj = os.path.join(proj_dir, "sheets")
+    gspecs = _group_specs(proj_dir)
+    if os.path.isdir(sj):
+        for fn in sorted(os.listdir(sj)):
+            if fn.endswith(".json"):
+                path = os.path.join(sj, fn)
+                out[os.path.splitext(fn)[0]] = (
+                    lambda p=path: _build_json_sheet(p, proj_dir, app_code,
+                                                     registry, gspecs))
+    if os.path.isfile(os.path.join(proj_dir, "forms.py")):
+        out.update(_legacy_loaders(proj_dir, app_code, registry))
+    if not out:
+        raise ValueError("项目 %r 没有定义：缺 sheets/*.json 或 forms.py" % proj_dir)
+    return out