camunda-python 0.1.0__py3-none-any.whl

camunda/parser/dmn_parser.py

@@ -0,0 +1,225 @@
+"""DMN 1.1/1.3 XML 解析器（lxml，M5-1）。
+
+职责（对齐 Camunda dmn-model 的解析部分、与 bpmn_parser 同风格）：
+1. 解析 XML -> DmnModel（含多个 Decision）
+2. decisionTable 结构：inputs（inputExpression 文本）/ outputs / rules
+   （inputEntry/outputEntry 的 dmn:text 原文）
+3. 校验：hitPolicy 合法、COLLECT aggregator 合法、entry 数量与列对齐、
+   非 decisionTable 形态（literalExpression 等）明确报错
+
+命名空间处理策略：只用 localName 分派（DMN 1.1/1.3 同构），不校验版本。
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from lxml import etree
+
+from camunda.common.exceptions import DeploymentException
+from camunda.model.dmn import (
+    AGGREGATORS,
+    HIT_POLICIES,
+    Decision,
+    DecisionTable,
+    DmnInput,
+    DmnModel,
+    DmnOutput,
+    DmnRule,
+)
+
+
+def _local(tag: str) -> str:
+    """lxml tag 形如 {ns}localName -> localName。"""
+    return tag.rsplit("}", 1)[-1]
+
+
+def _children(el: etree._Element, local_name: str) -> List[etree._Element]:
+    return [c for c in el if isinstance(c.tag, str) and _local(c.tag) == local_name]
+
+
+def _text_of(el: Optional[etree._Element]) -> str:
+    """取元素文本（None 安全）。"""
+    return (el.text or "") if el is not None else ""
+
+
+def _normalize_entry(text: str) -> Optional[str]:
+    """单元格文本归一：空 / '-' -> None（通配或空输出）；其余 strip。"""
+    t = text.strip()
+    if t in ("", "-"):
+        return None
+    return t
+
+
+def parse_dmn_xml(xml_text: str, source_name: Optional[str] = None) -> DmnModel:
+    """解析 DMN XML 文本 -> DmnModel。失败抛 DeploymentException。"""
+    try:
+        root = etree.fromstring(xml_text.encode("utf-8"))
+    except etree.XMLSyntaxError as e:
+        raise DeploymentException(f"DMN XML 语法错误: {e}") from e
+
+    if _local(root.tag) != "definitions":
+        raise DeploymentException(
+            f"DMN 根元素须为 definitions，实际 {_local(root.tag)!r}"
+        )
+
+    model = DmnModel(source_name=source_name, source_xml=xml_text)
+    for el in root:
+        if not isinstance(el.tag, str):
+            continue
+        if _local(el.tag) == "decision":
+            model.decisions.append(_parse_decision(el))
+    if not model.decisions:
+        raise DeploymentException("DMN definitions 未包含任何 decision")
+    return model
+
+
+def parse_dmn_file(path: str) -> DmnModel:
+    """解析 .dmn 文件（demo/测试便捷入口）。"""
+    with open(path, "r", encoding="utf-8") as f:
+        return parse_dmn_xml(f.read(), source_name=path.rsplit("/", 1)[-1])
+
+
+def _parse_decision(el: etree._Element) -> Decision:
+    dec_id = el.get("id")
+    if not dec_id:
+        raise DeploymentException("decision 缺少 id 属性")
+    dec = Decision(id=dec_id, name=el.get("name"))
+
+    for child in el:
+        if not isinstance(child.tag, str):
+            continue
+        ln = _local(child.tag)
+        if ln == "decisionTable":
+            dec.decision_table = _parse_decision_table(child)
+        elif ln == "variable":
+            continue  # decision 输出类型声明，M5 不消费
+        else:
+            # literalExpression / relation / invocation / context -> 明确报错
+            raise DeploymentException(
+                f"decision {dec_id!r} 仅支持 decisionTable 形态，"
+                f"遇到不支持的子元素 {ln!r}（M5 文档化差异）"
+            )
+    if dec.decision_table is None:
+        raise DeploymentException(f"decision {dec_id!r} 缺少 decisionTable")
+    return dec
+
+
+def _parse_decision_table(el: etree._Element) -> DecisionTable:
+    hit_policy = (el.get("hitPolicy") or "UNIQUE").strip().upper()
+    if hit_policy not in HIT_POLICIES:
+        raise DeploymentException(
+            f"未知 hitPolicy: {el.get('hitPolicy')!r}（支持 {sorted(HIT_POLICIES)}）"
+        )
+    aggregator = el.get("aggregation")
+    aggregator = aggregator.strip().upper() if aggregator else None
+    if aggregator is not None and aggregator not in AGGREGATORS:
+        raise DeploymentException(
+            f"未知 aggregation: {el.get('aggregation')!r}（支持 {sorted(AGGREGATORS)}）"
+        )
+    if aggregator is not None and hit_policy != "COLLECT":
+        raise DeploymentException(
+            f"aggregation 仅在 hitPolicy=COLLECT 下合法（当前 {hit_policy!r}）"
+        )
+
+    table = DecisionTable(
+        id=el.get("id"), hit_policy=hit_policy, aggregator=aggregator
+    )
+    for child in el:
+        if not isinstance(child.tag, str):
+            continue
+        ln = _local(child.tag)
+        if ln == "input":
+            table.inputs.append(_parse_input(child))
+        elif ln == "output":
+            table.outputs.append(_parse_output(child))
+        elif ln == "rule":
+            table.rules.append(_parse_rule(child))
+        # annotation / informationRequirement 等忽略
+
+    if not table.outputs:
+        raise DeploymentException(
+            f"decisionTable {table.id!r} 至少需要一个 output 列"
+        )
+    _validate_entry_alignment(table)
+    return table
+
+
+def _parse_input(el: etree._Element) -> DmnInput:
+    expr_el = None
+    for c in _children(el, "inputExpression"):
+        expr_el = c
+        break
+    if expr_el is None:
+        raise DeploymentException(f"input {el.get('id')!r} 缺少 inputExpression")
+    return DmnInput(
+        id=el.get("id"),
+        name=el.get("label"),
+        expression=_text_of(expr_el).strip(),
+        type_ref=expr_el.get("typeRef"),
+    )
+
+
+def _parse_output(el: etree._Element) -> DmnOutput:
+    return DmnOutput(
+        id=el.get("id"),
+        name=el.get("name"),
+        label=el.get("label"),
+        type_ref=el.get("typeRef"),
+        output_values=_parse_output_values(el),
+    )
+
+
+def _parse_output_values(el: etree._Element) -> List[str]:
+    """outputValues 子元素：逗号分隔的 FEEL 字面量列表（尊重引号内的逗号）。"""
+    for child in el:
+        if isinstance(child.tag, str) and _local(child.tag) == "outputValues":
+            texts = _children(child, "text")
+            raw = _text_of(texts[0]) if texts else ""
+            parts: List[str] = []
+            buf: List[str] = []
+            in_quote = False
+            for ch in raw:
+                if ch == '"':
+                    in_quote = not in_quote
+                    buf.append(ch)
+                elif ch == "," and not in_quote:
+                    parts.append("".join(buf).strip())
+                    buf = []
+                else:
+                    buf.append(ch)
+            parts.append("".join(buf).strip())
+            return [p for p in parts if p]
+    return []
+
+
+def _parse_rule(el: etree._Element) -> DmnRule:
+    rule = DmnRule(id=el.get("id"))
+    for child in el:
+        if not isinstance(child.tag, str):
+            continue
+        ln = _local(child.tag)
+        if ln == "inputEntry":
+            rule.input_entries.append(_normalize_entry(_text_of(_children(child, "text")[0]) if _children(child, "text") else ""))
+        elif ln == "outputEntry":
+            texts = _children(child, "text")
+            rule.output_entries.append(
+                _normalize_entry(_text_of(texts[0]) if texts else "")
+            )
+        # description / annotationEntry 忽略
+    return rule
+
+
+def _validate_entry_alignment(table: DecisionTable) -> None:
+    """规则行 entry 数量与列对齐校验（DMN 规范要求严格对应）。"""
+    for rule in table.rules:
+        if len(rule.input_entries) != len(table.inputs):
+            raise DeploymentException(
+                f"rule {rule.id!r} 的 inputEntry 数 {len(rule.input_entries)}"
+                f" 与 input 列数 {len(table.inputs)} 不一致"
+            )
+        if len(rule.output_entries) != len(table.outputs):
+            raise DeploymentException(
+                f"rule {rule.id!r} 的 outputEntry 数 {len(rule.output_entries)}"
+                f" 与 output 列数 {len(table.outputs)} 不一致"
+            )

camunda/persistence/__init__.py

@@ -0,0 +1,21 @@
+"""persistence 包：SQLAlchemy 2.0 持久层（M2 里程碑交付）。
+
+- entities.py   ACT_RE_*/ACT_RU_*/ACT_HI_* ORM 实体（对齐 Camunda 表契约）
+- store.py      快照同步 + 存取门面（SQLite/PostgreSQL url 均可）
+"""
+
+from camunda.persistence.store import (
+    ActivitySnap,
+    ExecutionSnap,
+    ProcInstSnap,
+    Store,
+    TaskSnap,
+)
+
+__all__ = [
+    "Store",
+    "ProcInstSnap",
+    "ExecutionSnap",
+    "TaskSnap",
+    "ActivitySnap",
+]

camunda/persistence/entities.py

@@ -0,0 +1,202 @@
+"""SQLAlchemy 2.0 ORM 实体：对齐 Camunda ACT_* 表契约。
+
+表契约（对齐 Camunda 7 的 MyBatis 表）：
+- ACT_RE_DEPLOYMENT / ACT_RE_PROCDEF   静态定义（M2 简化：资源 xml 直接存 prodef 行）
+- ACT_RU_EXECUTION / ACT_RU_TASK /
+  ACT_RU_VARIABLE                     运行时瞬时态（RU = running）
+- ACT_HI_PROCINST / ACT_HI_ACTINST /
+  ACT_HI_TASKINST / ACT_HI_VARINST    历史归档
+
+M2 差异说明（文档化）：
+- Camunda 用 bytearray 表存资源 -> M2 直接存 prodef.resource_xml 文本
+- Camunda HI_VARINST 每次变更追加版本 -> M2 按实例快照（每实例每变量一行）
+- Camunda 变量挂 execution -> M2 引擎变量为实例级，VARIABLE 表挂 proc_inst
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import Integer, String, Text
+from sqlalchemy.dialects.mysql import MEDIUMTEXT
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+# MySQL 方言下 TEXT 上限 64KB（65535 字节），BPMN 资源 XML 与变量 JSON 可能
+# 超限（MySQL 报 Data too long）；此处统一把大文本列在 MySQL 声明为
+# MEDIUMTEXT（16MB）。SQLite/PostgreSQL 的 Text 无长度限制，with_variant
+# 不影响这两者。无迁移工具：MySQL 上需 DROP 重建或手动 ALTER 已有列。
+BIG_TEXT = Text().with_variant(MEDIUMTEXT(), "mysql")
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# 静态定义（RE）
+# ---------------------------------------------------------------------------
+class DeploymentEntity(Base):
+    """一次部署（对齐 ACT_RE_DEPLOYMENT）。"""
+
+    __tablename__ = "ACT_RE_DEPLOYMENT"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    name_: Mapped[str | None] = mapped_column("NAME_", String(255), nullable=True)
+    deploy_time_: Mapped[str] = mapped_column("DEPLOY_TIME_", String(32))
+
+
+class ProcDefEntity(Base):
+    """流程定义（对齐 ACT_RE_PROCDEF）。
+
+    Camunda 主键是 ID_，同 KEY_ 可多版本（VERSION_ 递增）。M2 主键 = f"{key}:{version}"。
+    """
+
+    __tablename__ = "ACT_RE_PROCDEF"
+
+    id_: Mapped[str] = mapped_column("ID_", String(128), primary_key=True)
+    key_: Mapped[str] = mapped_column("KEY_", String(128), index=True)
+    name_: Mapped[str | None] = mapped_column("NAME_", String(255), nullable=True)
+    version_: Mapped[int] = mapped_column("VERSION_", default=1)
+    deployment_id_: Mapped[str] = mapped_column("DEPLOYMENT_ID_", String(64))
+    resource_xml_: Mapped[str] = mapped_column("RESOURCE_XML_", BIG_TEXT)
+    is_executable_: Mapped[bool] = mapped_column("IS_EXECUTABLE_", default=True)
+
+
+# ---------------------------------------------------------------------------
+# 运行时（RU）
+# ---------------------------------------------------------------------------
+class ExecutionEntity(Base):
+    """执行树节点（对齐 ACT_RU_EXECUTION）。
+
+    只保存 ACTIVE 的 execution（ENDED 的随历史归档，RU 表语义）。
+    """
+
+    __tablename__ = "ACT_RU_EXECUTION"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    process_instance_id_: Mapped[str] = mapped_column("PROC_INST_ID_", String(64), index=True)
+    parent_id_: Mapped[str | None] = mapped_column("PARENT_ID_", String(64), nullable=True)
+    activity_id_: Mapped[str | None] = mapped_column("ACT_ID_", String(255), nullable=True)
+    role_: Mapped[str] = mapped_column("ROLE_", String(16), default="TOKEN")
+    # M4-2c4：多实例状态 JSON（容器 total/active/completed/next_index/... 或实例
+    # {"index": i}）。Camunda 以 loopCounter 等 ACT_RU_VARIABLE + IS_SCOPE_ 关联
+    # 表达；M2 简化：实例级变量 + 此列直存容器状态（崩溃恢复必需）。
+    mi_: Mapped[str | None] = mapped_column("MI_", BIG_TEXT, nullable=True)
+    # Camunda 还有 IS_CONCURRENT_ / IS_SCOPE_ 等；role 已覆盖 M1 语义
+
+
+class TaskEntity(Base):
+    """待办任务（对齐 ACT_RU_TASK）。"""
+
+    __tablename__ = "ACT_RU_TASK"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    name_: Mapped[str | None] = mapped_column("NAME_", String(255), nullable=True)
+    process_instance_id_: Mapped[str] = mapped_column("PROC_INST_ID_", String(64), index=True)
+    execution_id_: Mapped[str] = mapped_column("EXECUTION_ID_", String(64))
+    task_definition_key_: Mapped[str] = mapped_column("TASK_DEF_KEY_", String(255))
+    assignee_: Mapped[str | None] = mapped_column("ASSIGNEE_", String(255), nullable=True)
+    create_time_: Mapped[str] = mapped_column("CREATE_TIME_", String(32))
+
+
+class VariableEntity(Base):
+    """流程变量（对齐 ACT_RU_VARIABLE；M2 实例级，复合主键 proc_inst+name）。"""
+
+    __tablename__ = "ACT_RU_VARIABLE"
+
+    id_: Mapped[str] = mapped_column("ID_", String(96), primary_key=True)
+    process_instance_id_: Mapped[str] = mapped_column("PROC_INST_ID_", String(64), index=True)
+    name_: Mapped[str] = mapped_column("NAME_", String(255))
+    type_: Mapped[str] = mapped_column("TYPE_", String(32))          # Java 类型名
+    text_: Mapped[str | None] = mapped_column("TEXT_", BIG_TEXT, nullable=True)  # JSON 序列化
+
+
+class JobEntity(Base):
+    """可调度作业（对齐 ACT_RU_JOB，M3 核心子集）。
+
+    - 实例级 job（timer-catch / async-continuation）：PROC_INST_ID_ 有值，
+      随实例 RU 快照全量重写
+    - 定义级 job（timer-start）：PROC_INST_ID_ 为 NULL，PROC_DEF_KEY_ + ACT_ID_
+      指向流程与 startEvent；部署新版本时整组重建
+    - LOCK_OWNER_ / LOCK_EXP_TIME_ 预留多实例抢占（M3 单进程不使用）
+    """
+
+    __tablename__ = "ACT_RU_JOB"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    job_type_: Mapped[str] = mapped_column("TYPE_", String(32))
+    process_instance_id_: Mapped[str | None] = mapped_column(
+        "PROC_INST_ID_", String(64), nullable=True, index=True
+    )
+    execution_id_: Mapped[str | None] = mapped_column(
+        "EXECUTION_ID_", String(64), nullable=True
+    )
+    process_definition_key_: Mapped[str | None] = mapped_column(
+        "PROC_DEF_KEY_", String(128), nullable=True, index=True
+    )
+    node_id_: Mapped[str | None] = mapped_column("ACT_ID_", String(255), nullable=True)
+    duedate_: Mapped[str] = mapped_column("DUEDATE_", String(32), index=True)
+    created_: Mapped[str] = mapped_column("CREATED_", String(32))
+    retries_: Mapped[int] = mapped_column("RETRIES_", Integer, default=3)
+    repeat_: Mapped[str | None] = mapped_column("REPEAT_", BIG_TEXT, nullable=True)  # JSON
+    lock_owner_: Mapped[str | None] = mapped_column(
+        "LOCK_OWNER_", String(255), nullable=True
+    )
+    lock_expire_time_: Mapped[str | None] = mapped_column(
+        "LOCK_EXP_TIME_", String(32), nullable=True
+    )
+
+
+# ---------------------------------------------------------------------------
+# 历史（HI）
+# ---------------------------------------------------------------------------
+class HistProcInstEntity(Base):
+    """流程实例历史（对齐 ACT_HI_PROCINST）。"""
+
+    __tablename__ = "ACT_HI_PROCINST"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    process_definition_key_: Mapped[str] = mapped_column("PROC_DEF_KEY_", String(128), index=True)
+    business_key_: Mapped[str | None] = mapped_column("BUSINESS_KEY_", String(255), nullable=True)
+    state_: Mapped[str] = mapped_column("STATE_", String(16))        # ACTIVE/COMPLETED
+    start_time_: Mapped[str] = mapped_column("START_TIME_", String(32))
+    end_time_: Mapped[str | None] = mapped_column("END_TIME_", String(32), nullable=True)
+
+
+class HistActInstEntity(Base):
+    """活动实例历史（对齐 ACT_HI_ACTINST）。"""
+
+    __tablename__ = "ACT_HI_ACTINST"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    process_instance_id_: Mapped[str] = mapped_column("PROC_INST_ID_", String(64), index=True)
+    activity_id_: Mapped[str] = mapped_column("ACT_ID_", String(255))
+    activity_name_: Mapped[str | None] = mapped_column("ACT_NAME_", String(255), nullable=True)
+    execution_id_: Mapped[str] = mapped_column("EXECUTION_ID_", String(64))
+    start_time_: Mapped[str] = mapped_column("START_TIME_", String(32))
+    end_time_: Mapped[str | None] = mapped_column("END_TIME_", String(32), nullable=True)
+
+
+class HistTaskInstEntity(Base):
+    """任务实例历史（对齐 ACT_HI_TASKINST；M2 在 complete 时写入快照）。"""
+
+    __tablename__ = "ACT_HI_TASKINST"
+
+    id_: Mapped[str] = mapped_column("ID_", String(64), primary_key=True)
+    process_instance_id_: Mapped[str] = mapped_column("PROC_INST_ID_", String(64), index=True)
+    task_definition_key_: Mapped[str] = mapped_column("TASK_DEF_KEY_", String(255))
+    name_: Mapped[str | None] = mapped_column("NAME_", String(255), nullable=True)
+    execution_id_: Mapped[str] = mapped_column("EXECUTION_ID_", String(64))
+    assignee_: Mapped[str | None] = mapped_column("ASSIGNEE_", String(255), nullable=True)
+    create_time_: Mapped[str] = mapped_column("CREATE_TIME_", String(32))
+    end_time_: Mapped[str | None] = mapped_column("END_TIME_", String(32), nullable=True)
+
+
+class HistVarInstEntity(Base):
+    """变量历史（对齐 ACT_HI_VARINST；M2 实例快照语义）。"""
+
+    __tablename__ = "ACT_HI_VARINST"
+
+    id_: Mapped[str] = mapped_column("ID_", String(96), primary_key=True)
+    process_instance_id_: Mapped[str] = mapped_column("PROC_INST_ID_", String(64), index=True)
+    name_: Mapped[str] = mapped_column("NAME_", String(255))
+    type_: Mapped[str] = mapped_column("TYPE_", String(32))
+    text_: Mapped[str | None] = mapped_column("TEXT_", BIG_TEXT, nullable=True)