camunda-python 0.1.0__py3-none-any.whl

camunda/api/routers/process_instance.py

@@ -0,0 +1,106 @@
+"""流程实例端点（M6-3）：启动 / 查询 / 变量 / 删除。"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Body, Query, Request
+
+from camunda.api.deps import get_engine
+from camunda.api.pagination import DEFAULT_MAX_RESULTS, paginate
+from camunda.api.schemas import (
+    StartProcessInstanceDto,
+    from_variable_map,
+    process_instance_dto,
+    to_variable_map,
+)
+from camunda.common.exceptions import InvalidRequestException
+
+router = APIRouter(tags=["process-instance"])
+
+
+@router.post("/process-instance", summary="按 key 启动流程实例")
+def start_process_instance(
+    request: Request, body: StartProcessInstanceDto
+) -> Dict[str, Any]:
+    engine = get_engine(request)
+    if not body.definitionKey:
+        raise InvalidRequestException(
+            "启动流程须提供 definitionKey（Camunda 的 definitionId / message 启动 M6 不支持）"
+        )
+    pi = engine.start_process_instance_by_key(
+        body.definitionKey,
+        variables=from_variable_map(body.variables),
+        business_key=body.businessKey,
+    )
+    return process_instance_dto(pi, bare=bool(body.withVariablesInReturn))
+
+
+@router.get("/process-instance", summary="流程实例列表（含已结束）")
+def list_process_instances(
+    request: Request,
+    processDefinitionKey: Optional[str] = Query(default=None),
+    businessKey: Optional[str] = Query(default=None),
+    active: Optional[bool] = Query(default=None, description="true=只看运行中"),
+    bare: bool = Query(default=False, description="变量退化为裸值 map"),
+    firstResult: int = Query(default=0, ge=0, description="分页起点（0 基）"),
+    maxResults: int = Query(
+        default=DEFAULT_MAX_RESULTS, ge=1, description="分页上限（<=1000）"
+    ),
+) -> List[Dict[str, Any]]:
+    engine = get_engine(request)
+    instances = engine.list_process_instances()
+    if processDefinitionKey is not None:
+        instances = [
+            pi for pi in instances if pi.process_definition_key == processDefinitionKey
+        ]
+    if businessKey is not None:
+        instances = [pi for pi in instances if pi.business_key == businessKey]
+    if active is not None:
+        instances = [pi for pi in instances if (not pi.is_completed) == active]
+    items = [process_instance_dto(pi, bare=bare) for pi in instances]
+    return paginate(items, firstResult, maxResults)
+
+
+@router.get("/process-instance/{instance_id}", summary="按 id 取流程实例")
+def get_process_instance(
+    request: Request, instance_id: str, bare: bool = Query(default=False)
+) -> Dict[str, Any]:
+    engine = get_engine(request)
+    return process_instance_dto(engine.get_process_instance(instance_id), bare=bare)
+
+
+@router.delete("/process-instance/{instance_id}", summary="删除流程实例（历史保留）")
+def delete_process_instance(
+    request: Request, instance_id: str, reason: Optional[str] = Query(default=None)
+) -> Dict[str, Any]:
+    """删除实例：清运行时态 + RU 行，HI_PROCINST 置 DELETED（对齐 Camunda 默认）。"""
+    engine = get_engine(request)
+    engine.delete_process_instance(instance_id, reason=reason)
+    return {"deleted": True, "id": instance_id, "reason": reason}
+
+
+@router.get("/process-instance/{instance_id}/variables", summary="实例变量列表")
+def get_variables(
+    request: Request, instance_id: str, bare: bool = Query(default=False)
+) -> Dict[str, Any]:
+    engine = get_engine(request)
+    pi = engine.get_process_instance(instance_id)
+    return to_variable_map(pi.variables, bare=bare)
+
+
+@router.put(
+    "/process-instance/{instance_id}/variables/{name}", summary="设置单个实例变量"
+)
+def put_variable(
+    request: Request,
+    instance_id: str,
+    name: str,
+    # Body() 显式标注：否则 Any + 默认值会被 FastAPI 当成非 body 参数（静默收不到）
+    body: Any = Body(default=None),
+) -> Dict[str, Any]:
+    """设置变量。body 支持包装形态 {"value": x} 与裸值（如直接传 20000 / "abc"）。"""
+    engine = get_engine(request)
+    value = from_variable_map({"v": body})["v"] if isinstance(body, dict) else body
+    engine.set_variable(instance_id, name, value)
+    return {"name": name, "value": value, "processInstanceId": instance_id}

camunda/api/routers/task.py

@@ -0,0 +1,92 @@
+"""任务端点（M6-4）：查询 / 认领 / 完成 / 变量。"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Query, Request
+
+from camunda.api.deps import get_engine
+from camunda.api.pagination import DEFAULT_MAX_RESULTS, paginate
+from camunda.api.schemas import (
+    CompleteTaskDto,
+    UserIdDto,
+    from_variable_map,
+    task_dto,
+    to_variable_map,
+)
+
+router = APIRouter(tags=["task"])
+
+
+@router.get("/task", summary="任务列表（活跃待办）")
+def list_tasks(
+    request: Request,
+    processInstanceId: Optional[str] = Query(default=None),
+    assignee: Optional[str] = Query(default=None),
+    candidateUser: Optional[str] = Query(default=None),
+    unassigned: Optional[bool] = Query(default=None, description="true=只看未认领"),
+    firstResult: int = Query(default=0, ge=0, description="分页起点（0 基）"),
+    maxResults: int = Query(
+        default=DEFAULT_MAX_RESULTS, ge=1, description="分页上限（<=1000）"
+    ),
+) -> List[Dict[str, Any]]:
+    engine = get_engine(request)
+    tasks = engine.create_task_query(process_instance_id=processInstanceId)
+    if assignee is not None:
+        tasks = [t for t in tasks if t.assignee == assignee]
+    if candidateUser is not None:
+        tasks = [t for t in tasks if candidateUser in t.candidate_users]
+    if unassigned:
+        tasks = [t for t in tasks if t.assignee is None]
+    items = [task_dto(t) for t in tasks]
+    return paginate(items, firstResult, maxResults)
+
+
+@router.get("/task/{task_id}", summary="按 id 取任务")
+def get_task(request: Request, task_id: str) -> Dict[str, Any]:
+    engine = get_engine(request)
+    return task_dto(engine.get_task(task_id))
+
+
+@router.post("/task/{task_id}/claim", summary="认领任务")
+def claim_task(request: Request, task_id: str, body: UserIdDto) -> Dict[str, Any]:
+    engine = get_engine(request)
+    if not body.userId:
+        from camunda.common.exceptions import InvalidRequestException
+
+        raise InvalidRequestException("claim 需要 userId")
+    return task_dto(engine.claim_task(task_id, body.userId))
+
+
+@router.post("/task/{task_id}/unclaim", summary="取消认领")
+def unclaim_task(request: Request, task_id: str) -> Dict[str, Any]:
+    engine = get_engine(request)
+    return task_dto(engine.unclaim_task(task_id))
+
+
+@router.post("/task/{task_id}/assignee", summary="直接指派（不做已认领校验）")
+def set_assignee(request: Request, task_id: str, body: UserIdDto) -> Dict[str, Any]:
+    engine = get_engine(request)
+    return task_dto(engine.set_assignee(task_id, body.userId))
+
+
+@router.post("/task/{task_id}/complete", summary="完成任务（合并变量后推进）")
+def complete_task(
+    request: Request, task_id: str, body: Optional[CompleteTaskDto] = None
+) -> Dict[str, Any]:
+    engine = get_engine(request)
+    variables = from_variable_map(body.variables) if body is not None else {}
+    engine.complete_task(task_id, variables=variables)
+    return {"completed": True, "id": task_id}
+
+
+@router.get("/task/{task_id}/variables", summary="任务可见变量（= 实例变量）")
+def get_task_variables(
+    request: Request, task_id: str, bare: bool = Query(default=False)
+) -> Dict[str, Any]:
+    """任务变量：本项目变量为实例级（文档化差异），故返回所属实例的变量全集。"""
+    engine = get_engine(request)
+    task = engine.get_task(task_id)
+    pi = engine.get_process_instance(task.process_instance_id)
+    return to_variable_map(pi.variables, bare=bare)

camunda/api/schemas.py

@@ -0,0 +1,200 @@
+"""REST 层 DTO 与变量序列化（M6-1）。
+
+变量形态（M6 关键兼容点，文档化差异见 docs/ARCHITECTURE.md）：
+- Camunda 7 REST 用「包装形态」：{"amount": {"value": 20000, "type": "Long"}}
+- 本实现**入参两种都收**：包装形态与裸值 {"amount": 20000} 均可（裸值按 Python 类型推断 type）
+- 出参默认走包装形态（对齐 Camunda），带 `?bare=true` 时退化成裸值 map（便于脚本直用）
+
+类型推断：Python 类型 -> Camunda 类型名（String/Boolean/Integer/Long/Double/Null/Object）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from camunda.model.execution import ProcessInstance
+from camunda.model.task import Task
+
+# ---------------------------------------------------------------------------
+# 变量序列化
+# ---------------------------------------------------------------------------
+def _type_of(value: Any) -> str:
+    """Python 值 -> Camunda 变量类型名。"""
+    if value is None:
+        return "Null"
+    if isinstance(value, bool):
+        return "Boolean"
+    if isinstance(value, int):
+        return "Long"
+    if isinstance(value, float):
+        return "Double"
+    if isinstance(value, str):
+        return "String"
+    return "Object"  # dict / list / 其余：JSON 序列化对象
+
+
+def to_variable_dto(value: Any) -> Dict[str, Any]:
+    """单变量 -> Camunda VariableValueDto。"""
+    dto: Dict[str, Any] = {"value": value, "type": _type_of(value)}
+    if dto["type"] == "Object":
+        dto["valueInfo"] = {"serializationDataFormat": "application/json"}
+    return dto
+
+
+def to_variable_map(variables: Optional[Dict[str, Any]], bare: bool = False) -> Dict[str, Any]:
+    """变量 dict -> 响应形态（bare=True 时退化为裸值 map）。"""
+    variables = variables or {}
+    if bare:
+        return dict(variables)
+    return {k: to_variable_dto(v) for k, v in variables.items()}
+
+
+def from_variable_map(payload: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """请求变量 dict -> 引擎变量 dict（兼容包装形态与裸值）。
+
+    包装形态：{"amount": {"value": 20000, "type": "Long"}} -> {"amount": 20000}
+    裸值形态：{"amount": 20000}                            -> {"amount": 20000}
+    """
+    if not payload:
+        return {}
+    out: Dict[str, Any] = {}
+    for name, spec in payload.items():
+        if isinstance(spec, dict) and "value" in spec:
+            out[name] = spec["value"]  # type 仅文档化，引擎按 Python 原生类型处理
+        else:
+            out[name] = spec
+    return out
+
+
+# ---------------------------------------------------------------------------
+# 请求 DTO
+# ---------------------------------------------------------------------------
+class VariableValueDto(BaseModel):
+    """Camunda VariableValueDto（入参；type/valueInfo 仅文档化，引擎按原生类型处理）。"""
+
+    value: Any = None
+    type: Optional[str] = None
+    valueInfo: Optional[Dict[str, Any]] = None
+
+
+class StartProcessInstanceDto(BaseModel):
+    """POST /process-instance 请求体。variables 支持包装与裸值两种形态。
+
+    definitionKey 必填（Camunda 还支持 definitionId / message 启动，M6 不支持——
+    见 docs/ARCHITECTURE.md 的 M6 文档化差异）。
+    """
+
+    definitionKey: Optional[str] = None
+    variables: Optional[Dict[str, Any]] = None
+    businessKey: Optional[str] = None
+    withVariablesInReturn: Optional[bool] = False
+
+
+class CompleteTaskDto(BaseModel):
+    """POST /task/{id}/complete 请求体。"""
+
+    variables: Optional[Dict[str, Any]] = None
+
+
+class UserIdDto(BaseModel):
+    """POST /task/{id}/claim|unclaim|assignee 请求体。"""
+
+    userId: Optional[str] = None
+
+
+class DeploymentDto(BaseModel):
+    """POST /deployment/create（JSON 便捷通道；multipart 见路由说明）。"""
+
+    xml: str = Field(..., description="BPMN 2.0 XML 文本")
+    name: Optional[str] = None
+
+
+class EvaluateDecisionDto(BaseModel):
+    """POST /decision-definition/key/{key}/evaluate 请求体。"""
+
+    variables: Optional[Dict[str, Any]] = None
+
+
+# ---------------------------------------------------------------------------
+# 响应 DTO（直接构造 dict，由 FastAPI 序列化）
+# ---------------------------------------------------------------------------
+def process_instance_dto(pi: ProcessInstance, bare: bool = False) -> Dict[str, Any]:
+    """ProcessInstance -> Camunda ProcessInstanceDto。"""
+    return {
+        "id": pi.id,
+        "definitionId": pi.process_definition_key,
+        "businessKey": pi.business_key,
+        "ended": pi.is_completed,
+        "suspended": False,
+        "variables": to_variable_map(pi.variables, bare=bare),
+    }
+
+
+def task_dto(t: Task) -> Dict[str, Any]:
+    """Task -> Camunda TaskDto。"""
+    return {
+        "id": t.id,
+        "name": t.name,
+        "assignee": t.assignee,
+        "created": t.create_time,
+        "processInstanceId": t.process_instance_id,
+        "executionId": t.execution_id,
+        "taskDefinitionKey": t.task_definition_key,
+        "candidateUsers": list(t.candidate_users),
+        "candidateGroups": list(t.candidate_groups),
+    }
+
+
+def process_definition_dto(
+    key: str, name: Optional[str], version: int
+) -> Dict[str, Any]:
+    """流程定义 -> Camunda ProcessDefinitionDto。"""
+    return {
+        "id": f"{key}:{version}",
+        "key": key,
+        "name": name,
+        "version": version,
+    }
+
+
+def activity_instance_dto(ai: Any) -> Dict[str, Any]:
+    """ActivityInstance -> Camunda HistoricActivityInstanceDto。"""
+    return {
+        "id": ai.id,
+        "activityId": ai.activity_id,
+        "activityName": ai.activity_name,
+        "activityType": None,
+        "processInstanceId": ai.process_instance_id,
+        "executionId": ai.execution_id,
+        "startTime": ai.start_time,
+        "endTime": ai.end_time,
+        "durationInMillis": None,
+    }
+
+
+def historic_task_dto(t: Task) -> Dict[str, Any]:
+    """已归档 Task -> Camunda HistoricTaskInstanceDto。"""
+    return {
+        **task_dto(t),
+        "endTime": t.end_time,
+        "deleteReason": None,
+    }
+
+
+def historic_process_instance_dto(pi: ProcessInstance) -> Dict[str, Any]:
+    """ProcessInstance -> Camunda HistoricProcessInstanceDto。"""
+    return {
+        "id": pi.id,
+        "processDefinitionKey": pi.process_definition_key,
+        "businessKey": pi.business_key,
+        "startTime": pi.start_time,
+        "endTime": pi.end_time,
+        "state": pi.state.value if hasattr(pi.state, "value") else str(pi.state),
+    }
+
+
+def decision_definition_dto(key: str, version: int, name: Optional[str]) -> Dict[str, Any]:
+    """决策定义 -> Camunda DecisionDefinitionDto。"""
+    return {"id": f"{key}:{version}", "key": key, "name": name, "version": version}

camunda/common/__init__.py

@@ -0,0 +1,19 @@
+"""公共基础：异常层次、ID 生成器。"""
+
+from camunda.common.exceptions import (
+    CamundaException,
+    NotFoundException,
+    DeploymentException,
+    ProcessInstanceException,
+    InvalidRequestException,
+)
+from camunda.common.idgen import IdGenerator
+
+__all__ = [
+    "CamundaException",
+    "NotFoundException",
+    "DeploymentException",
+    "ProcessInstanceException",
+    "InvalidRequestException",
+    "IdGenerator",
+]

camunda/common/clock.py

@@ -0,0 +1,30 @@
+"""可注入时钟：引擎与 JobExecutor 统一取当前时间。
+
+M2 用 time.strftime 散落各处取字符串时间；M3 起统一走本模块：
+- 输出为本地时区定长 ISO 字符串 "%Y-%m-%dT%H:%M:%S"（同长可字典序比较 due）
+- 测试可用 set_clock 冻结 / 拨快时间，无需真 sleep 即可验证定时器到期语义
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+_DEFAULT = lambda: time.strftime("%Y-%m-%dT%H:%M:%S")  # noqa: E731
+_fn: Callable[[], str] = _DEFAULT
+
+
+def now() -> str:
+    return _fn()
+
+
+def set_clock(fn: Callable[[], str]) -> None:
+    """替换当前时间来源（测试注入 fake clock）。"""
+    global _fn
+    _fn = fn
+
+
+def reset_clock() -> None:
+    """恢复真实系统时钟。"""
+    global _fn
+    _fn = _DEFAULT

camunda/common/exceptions.py

@@ -0,0 +1,34 @@
+"""camunda-python 统一异常层次。
+
+对齐 Camunda 语义：
+- CamundaException        引擎根异常（对应 Java ProcessEngineException）
+- NotFoundException       对象不存在（对应 ProcessEngineException 派生的 NotFound 语义）
+- DeploymentException     部署失败（XML 解析/校验错误）
+- ProcessInstanceException 流程实例状态非法操作
+- InvalidRequestException 参数/调用不合法
+- ExpressionEvaluationException 表达式求值失败（FEEL/UEL，M5）
+"""
+
+
+class CamundaException(Exception):
+    """引擎根异常。"""
+
+
+class NotFoundException(CamundaException):
+    """按 id/key 查找对象不存在。"""
+
+
+class DeploymentException(CamundaException):
+    """BPMN 部署失败：XML 格式错误、语义校验不通过。"""
+
+
+class ProcessInstanceException(CamundaException):
+    """流程实例上的非法状态操作（如对已结束实例 start/complete）。"""
+
+
+class InvalidRequestException(CamundaException):
+    """参数或调用不合法。"""
+
+
+class ExpressionEvaluationException(CamundaException):
+    """表达式求值失败：FEEL 语法不支持 / 类型不匹配 / 未定义变量路径（M5）。"""

camunda/common/idgen.py

@@ -0,0 +1,23 @@
+"""ID 生成器：对齐 Camunda 实体主键语义（UUID 版本）。"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Callable
+
+# 可注入的 ID 生成函数（测试可替换为序列号以便断言）。
+_generator: Callable[[], str] = lambda: uuid.uuid4().hex
+
+
+def set_id_generator(fn: Callable[[], str]) -> None:
+    """替换全局 ID 生成策略（主要用于测试确定性）。"""
+    global _generator
+    _generator = fn
+
+
+class IdGenerator:
+    """每次调用生成一个新的实体 ID。"""
+
+    @staticmethod
+    def next_id() -> str:
+        return _generator()

camunda/common/timers.py

@@ -0,0 +1,106 @@
+"""ISO-8601 时长 / 周期与 cron 触发时间计算（M3）。
+
+BPMN timerEventDefinition 取值对齐 Camunda 7 语义：
+- timeDuration  : ISO-8601 时长（如 PT30S / PT1H / P1D）→ 相对 duedate
+- timeDate      : 绝对时间点（ISO-8601，可带 Z/时区偏移）→ 一次性 duedate
+- timeCycle     : cron 表达式（quartz 风格，croniter 求值）或 ISO-8601 重复
+                  周期 R[n]/PT..（如 R3/PT10S = 每 10 秒一次共 3 次）
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional
+
+# 引擎统一时间格式（与 clock.now() 一致；定长可字典序比较）
+ISO_FORMAT = "%Y-%m-%dT%H:%M:%S"
+
+# ISO-8601 时长：P[nW] | P[nD][T[nH][nM][n[.f]S]]
+_ISO_DURATION_RE = re.compile(
+    r"^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$"
+)
+# ISO-8601 重复周期：R[n]/<时长>（带起点形式 R/<date>/<dur> 暂不支持）
+_ISO_REPEAT_RE = re.compile(r"^R(\d*)/(.+)$")
+
+
+def format_iso(dt: datetime) -> str:
+    """datetime -> 本地定长 ISO 字符串。"""
+    return dt.strftime(ISO_FORMAT)
+
+
+def parse_iso(text: str) -> datetime:
+    """定长 ISO 字符串 -> datetime。"""
+    return datetime.strptime(text, ISO_FORMAT)
+
+
+def parse_trigger_date(text: str) -> str:
+    """timeDate 文本 -> 本地定长 ISO 字符串（对齐引擎时钟时区）。"""
+    raw = text.strip()
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(raw)
+    except ValueError:
+        # 退化为引擎定长格式直解（无时区本地时间）
+        return format_iso(datetime.strptime(raw, ISO_FORMAT))
+    if dt.tzinfo is not None:
+        dt = dt.astimezone()  # 转本地时区
+    return format_iso(dt)
+
+
+def parse_iso_duration(text: str) -> float:
+    """ISO-8601 时长文本 -> 秒（浮点，支持小数秒）。
+
+    例：PT30S -> 30；PT1H30M -> 5400；P1D -> 86400；P1W -> 604800。
+    非法输入抛 ValueError（部署期即暴露配置错误）。
+    """
+    t = text.strip()
+    sign = -1.0 if t.startswith("-") else 1.0
+    t = t.lstrip("+-")
+    m = _ISO_DURATION_RE.fullmatch(t)
+    if not m or not any(m.groups()):
+        raise ValueError(f"非法 ISO-8601 时长: {text!r}")
+    weeks, days, hours, minutes, seconds = m.groups()
+    total = (
+        (int(weeks) if weeks else 0) * 604800
+        + (int(days) if days else 0) * 86400
+        + (int(hours) if hours else 0) * 3600
+        + (int(minutes) if minutes else 0) * 60
+        + (float(seconds) if seconds else 0.0)
+    )
+    return sign * total
+
+
+def parse_iso_repeat(text: str) -> Optional[Dict[str, Any]]:
+    """ISO-8601 重复周期 R[n]/PT.. -> repeat 字典；非该格式返回 None。
+
+    repeat = {"kind": "interval", "seconds": float, "count": int | None}
+    count=None 表示无限重复。
+    """
+    m = _ISO_REPEAT_RE.fullmatch(text.strip())
+    if not m:
+        return None
+    count = int(m.group(1)) if m.group(1) else None
+    seconds = parse_iso_duration(m.group(2))
+    return {"kind": "interval", "seconds": seconds, "count": count}
+
+
+def next_trigger(repeat: Dict[str, Any], after: datetime) -> datetime:
+    """计算 timerCycle 在 after 之后的下一触发时刻。
+
+    repeat:
+    - {"kind": "interval", "seconds": s, "count": n|None}  间隔重复
+    - {"kind": "cron", "expr": "..."}                      quartz/cron 表达式
+    """
+    if repeat["kind"] == "interval":
+        return after + timedelta(seconds=repeat["seconds"])
+    if repeat["kind"] == "cron":
+        try:
+            from croniter import croniter
+        except ImportError as e:  # 依赖缺失时给出可操作提示
+            raise RuntimeError(
+                "timerCycle 使用 cron 表达式需要安装依赖 croniter"
+            ) from e
+        return croniter(repeat["expr"], after).get_next(datetime)
+    raise ValueError(f"不支持的周期类型: {repeat!r}")

camunda/dmn/__init__.py

@@ -0,0 +1,5 @@
+"""dmn 包：DMN 决策引擎（M5 里程碑交付：决策表求值 + FEEL 表达式子集）。"""
+
+from camunda.dmn.engine import DmnEngine
+
+__all__ = ["DmnEngine"]