camunda-python 0.1.0__py3-none-any.whl

camunda/__init__.py

@@ -0,0 +1,10 @@
+"""camunda-python · Camunda 7 BPMN engine reimplementation in Python 3.
+
+Semantic-aligned independent implementation (Apache-2.0). Reference baseline:
+Camunda 7.23.0 (final open-source community edition).
+"""
+
+__version__ = "0.1.0"
+
+# Engine version reported to align with Camunda semantics we target.
+CAMUNDA_COMPAT_VERSION = "7.23.0"

camunda/api/__init__.py

@@ -0,0 +1,14 @@
+"""api 包：REST 兼容层（M6 里程碑交付：FastAPI 对齐 Camunda engine-rest 常用端点）。
+
+用法：
+    from camunda.api import create_app
+    app = create_app()                 # 内存引擎
+    app = create_app(engine=engine)    # 复用既有引擎（含 Store / JobExecutor）
+
+启动：
+    uvicorn camunda.api.app:create_app --factory --port 8080
+"""
+
+from camunda.api.app import DEFAULT_PREFIX, create_app
+
+__all__ = ["create_app", "DEFAULT_PREFIX"]

camunda/api/app.py

@@ -0,0 +1,80 @@
+"""FastAPI 应用工厂（M6-1）。
+
+用法：
+    from camunda.api import create_app
+    app = create_app()                      # 内存引擎，可直接 uvicorn 跑
+    app = create_app(engine=my_engine)      # 复用已有引擎（含持久化/作业执行器）
+
+端点总前缀默认 `/engine-rest`（对齐 Camunda 7 REST），可用 prefix 覆盖。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, FastAPI
+
+from camunda import CAMUNDA_COMPAT_VERSION, __version__
+from camunda.api.errors import register_exception_handlers
+from camunda.api.routers import (
+    decision,
+    deployment,
+    history,
+    process_definition,
+    process_instance,
+    task,
+)
+from camunda.engine import ProcessEngine
+
+DEFAULT_PREFIX = "/engine-rest"
+
+_DESCRIPTION = f"""\
+camunda-python 的 REST 兼容层（M6）。
+
+对齐 Camunda {CAMUNDA_COMPAT_VERSION} engine-rest 的常用端点子集（文档化差异见
+docs/ARCHITECTURE.md 的 M6 交付记录）。
+
+- 变量入参兼容两种写法：包装形态 `{{"amount": {{"value": 1, "type": "Long"}}}}` 与裸值
+  `{{"amount": 1}}`；出参默认包装形态，带 `?bare=true` 退化为裸值 map。
+- 错误响应体统一为 `{{"type": "<异常类名>", "message": "<异常消息>"}}`。
+"""
+
+
+def create_app(
+    engine: Optional[ProcessEngine] = None,
+    prefix: str = DEFAULT_PREFIX,
+    title: str = "camunda-python REST API",
+) -> FastAPI:
+    """构造 REST 应用。
+
+    engine 为 None 时内部新建一个内存引擎（ProcessEngine()），适合 demo/测试；
+    生产用法传入带 Store 的引擎实例即可（路由只依赖引擎门面方法）。
+    """
+    app = FastAPI(title=title, version=__version__, description=_DESCRIPTION)
+    # 路由通过 request.app.state.engine 取引擎（见 camunda/api/deps.py）
+    app.state.engine = engine if engine is not None else ProcessEngine()
+    register_exception_handlers(app)
+
+    api = APIRouter(prefix=prefix)
+    api.include_router(deployment.router)
+    api.include_router(process_definition.router)
+    api.include_router(process_instance.router)
+    api.include_router(task.router)
+    api.include_router(history.router)
+    api.include_router(decision.router)
+    app.include_router(api)
+
+    @app.get("/", tags=["meta"], summary="服务元信息")
+    def index() -> dict:
+        return {
+            "name": "camunda-python",
+            "version": __version__,
+            "camundaCompat": CAMUNDA_COMPAT_VERSION,
+            "engineRestPrefix": prefix,
+        }
+
+    @app.get("/health", tags=["meta"], summary="健康检查")
+    def health() -> dict:
+        return {"status": "UP"}
+
+    return app

camunda/api/deps.py

@@ -0,0 +1,17 @@
+"""REST 层依赖注入（M6-1）。
+
+引擎实例挂在 app.state.engine（进程内单例），路由通过本模块取用，避免 routers
+与 app 互相 import 造成循环依赖。
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+
+from camunda.engine import ProcessEngine
+
+
+def get_engine(request: Request) -> ProcessEngine:
+    """取应用绑定的引擎实例（create_app 时挂到 app.state.engine）。"""
+    engine: ProcessEngine = request.app.state.engine
+    return engine

camunda/api/errors.py

@@ -0,0 +1,84 @@
+"""Camunda 异常层次 -> HTTP 状态码映射（M6-1）。
+
+对齐 Camunda 7 REST 的错误响应体：
+    {"type": "<异常类名>", "message": "<异常消息>"}
+
+状态码决策（对齐 Camunda REST 常用语义，文档化差异见 docs/ARCHITECTURE.md）：
+- NotFoundException            404  按 id/key 查不到对象
+- DeploymentException          400  BPMN/DMN XML 语法错误或语义校验不通过
+- InvalidRequestException      400  参数或调用不合法
+- ProcessInstanceException     409  实例状态冲突（对已完成实例操作 / 定时启动流程手动启动）
+- ExpressionEvaluationException 400 FEEL/UEL 求值失败
+- CamundaException（兜底）     500  其余未分类引擎异常
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from camunda.common.exceptions import (
+    CamundaException,
+    DeploymentException,
+    ExpressionEvaluationException,
+    InvalidRequestException,
+    NotFoundException,
+    ProcessInstanceException,
+)
+
+# 异常类 -> HTTP 状态码（子类查找按 MRO 顺序从最具体开始）
+_STATUS_MAP: Dict[Type[BaseException], int] = {
+    NotFoundException: 404,
+    DeploymentException: 400,
+    InvalidRequestException: 400,
+    ProcessInstanceException: 409,
+    ExpressionEvaluationException: 400,
+    CamundaException: 500,
+}
+
+
+def status_for(exc: BaseException) -> int:
+    """按异常类型解析 HTTP 状态码（未知引擎异常兜底 500）。"""
+    for cls in type(exc).__mro__:
+        if cls in _STATUS_MAP:
+            return _STATUS_MAP[cls]
+    return 500
+
+
+def error_body(exc: BaseException) -> Dict[str, Any]:
+    """构造 Camunda 风格错误响应体。"""
+    return {"type": type(exc).__name__, "message": str(exc)}
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """注册 CamundaException 全局处理器（FastAPI 按 MRO 派发最近的 handler）。"""
+
+    @app.exception_handler(NotFoundException)
+    async def _not_found(request: Request, exc: NotFoundException) -> JSONResponse:
+        return JSONResponse(status_code=404, content=error_body(exc))
+
+    @app.exception_handler(DeploymentException)
+    async def _deployment(request: Request, exc: DeploymentException) -> JSONResponse:
+        return JSONResponse(status_code=400, content=error_body(exc))
+
+    @app.exception_handler(InvalidRequestException)
+    async def _invalid(request: Request, exc: InvalidRequestException) -> JSONResponse:
+        return JSONResponse(status_code=400, content=error_body(exc))
+
+    @app.exception_handler(ProcessInstanceException)
+    async def _conflict(
+        request: Request, exc: ProcessInstanceException
+    ) -> JSONResponse:
+        return JSONResponse(status_code=409, content=error_body(exc))
+
+    @app.exception_handler(ExpressionEvaluationException)
+    async def _expression(
+        request: Request, exc: ExpressionEvaluationException
+    ) -> JSONResponse:
+        return JSONResponse(status_code=400, content=error_body(exc))
+
+    @app.exception_handler(CamundaException)
+    async def _camunda(request: Request, exc: CamundaException) -> JSONResponse:
+        return JSONResponse(status_code=500, content=error_body(exc))

camunda/api/pagination.py

@@ -0,0 +1,74 @@
+"""REST 分页（M8）。
+
+对齐 Camunda 7 REST 分页约定：
+- 查询参数：`firstResult`（0 基偏移，默认 0）+ `maxResults`（每页上限，默认 200）
+- 响应：仍是裸数组（**不**回包 count/total），调用方通过「结果数 < maxResults」判定到达末页
+- 负值 / 越界自动 clamp 到合法区间（Camunda 对非法 firstResult 直接抛 400，
+  本项目为易用性选 clamp，文档化差异——见 docs/ARCHITECTURE.md）
+
+用法：
+
+    @router.get("/foo")
+    def list_foo(
+        request: Request,
+        firstResult: int = Query(default=0, ge=0),
+        maxResults: int = Query(default=DEFAULT_MAX_RESULTS, ge=1, le=MAX_RESULTS_LIMIT),
+    ):
+        items = ...
+        return paginate(items, firstResult, maxResults)
+
+设计动机：本项目 M6 列表端点全部 `return list`——分页前移到这里实现
+一遍，所有路由都用同一份语义与默认值，避免每个端点各写一份。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, TypeVar
+
+# Camunda 默认对 maxResults 不设硬上限；本项目为防止脚本误用拉空内存，
+# 取一个 Camunda 文档中常见的"列表默认上限 200"作为软上限。
+DEFAULT_MAX_RESULTS = 200
+MAX_RESULTS_LIMIT = 1000  # 单次请求硬上限，超过会被 clamp 到这里
+
+T = TypeVar("T")
+
+
+def normalize_pagination(
+    first_result: int, max_results: int
+) -> Dict[str, int]:
+    """把入参 clamp 到合法区间，返回 {firstResult, maxResults} dict。
+
+    - firstResult < 0 -> 0
+    - maxResults < 1 -> DEFAULT_MAX_RESULTS（前端误传 0/负数）
+    - maxResults > MAX_RESULTS_LIMIT -> MAX_RESULTS_LIMIT
+    """
+    fr = max(0, int(first_result))
+    mr = int(max_results) if max_results is not None else DEFAULT_MAX_RESULTS
+    if mr < 1:
+        mr = DEFAULT_MAX_RESULTS
+    if mr > MAX_RESULTS_LIMIT:
+        mr = MAX_RESULTS_LIMIT
+    return {"firstResult": fr, "maxResults": mr}
+
+
+def paginate(
+    items: List[T], first_result: int, max_results: int
+) -> List[T]:
+    """对列表做切片（闭区间语义）。
+
+    返回值仍是裸列表，便于 FastAPI 直接 JSON 序列化。
+    """
+    norm = normalize_pagination(first_result, max_results)
+    fr, mr = norm["firstResult"], norm["maxResults"]
+    # 起点超过尾：返回空数组（Camunda 行为相同）
+    if fr >= len(items):
+        return []
+    return items[fr : fr + mr]
+
+
+__all__ = [
+    "DEFAULT_MAX_RESULTS",
+    "MAX_RESULTS_LIMIT",
+    "normalize_pagination",
+    "paginate",
+]

camunda/api/routers/__init__.py

@@ -0,0 +1,5 @@
+"""REST 路由分包（M6）。
+
+按 Camunda engine-rest 资源划分：deployment / process-definition /
+process-instance / task / history / decision-definition。
+"""

camunda/api/routers/decision.py

@@ -0,0 +1,57 @@
+"""DMN 决策端点（M6-6）：定义查询 + 决策求值。
+
+DMN 部署走 /deployment/create（含 decision 子元素的 XML 自动分派到 deploy_dmn）。
+"""
+
+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 EvaluateDecisionDto, decision_definition_dto, from_variable_map
+
+router = APIRouter(tags=["decision-definition"])
+
+
+@router.get("/decision-definition", summary="决策定义列表")
+def list_decision_definitions(
+    request: Request,
+    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)
+    items = [
+        decision_definition_dto(d["key"], d["version"], d["name"])
+        for d in engine.list_decision_definitions()
+    ]
+    return paginate(items, firstResult, maxResults)
+
+
+@router.get("/decision-definition/key/{key}", summary="按 key 取最新版本的决策定义")
+def get_decision_definition_by_key(request: Request, key: str) -> Dict[str, Any]:
+    engine = get_engine(request)
+    dec = engine.get_decision_definition(key)
+    return decision_definition_dto(key, engine.get_decision_version(key), dec.name)
+
+
+@router.post(
+    "/decision-definition/key/{key}/evaluate", summary="求值决策表（返回原始结果）"
+)
+def evaluate_decision(
+    request: Request, key: str, body: Optional[EvaluateDecisionDto] = None
+) -> Dict[str, Any]:
+    """求值决策表。
+
+    返回 `result` 为引擎原始结果形态（单输出列 -> 标量；多输出列 -> dict；
+    RULE ORDER/COLLECT -> 列表；无命中 -> None / []），不做 Camunda 的
+    DmnDecisionResultEntries 包装（文档化差异）。
+    """
+    engine = get_engine(request)
+    variables = from_variable_map(body.variables) if body is not None else {}
+    result = engine.evaluate_decision(key, variables)
+    return {"key": key, "variables": variables, "result": result}

camunda/api/routers/deployment.py

@@ -0,0 +1,139 @@
+"""部署端点（M6-2）：POST /deployment/create + GET /deployment。
+
+BPMN 与 DMN 共用同一端点：按 XML 根元素的子元素自动分派
+（含 decision -> DMN，含 process -> BPMN；两者根元素都叫 definitions）。
+
+对齐 Camunda：multipart/form-data，字段名 `data`，可多文件一次部署。
+本项目额外提供 JSON 便捷通道 `POST /deployment/create/xml`（curl/脚本免构造 multipart）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, File, Query, Request, UploadFile
+from lxml import etree
+
+from camunda.api.deps import get_engine
+from camunda.api.pagination import DEFAULT_MAX_RESULTS, paginate
+from camunda.api.schemas import DeploymentDto, decision_definition_dto, process_definition_dto
+from camunda.common.exceptions import DeploymentException, InvalidRequestException
+from camunda.parser import parse_bpmn_xml
+from camunda.parser.dmn_parser import parse_dmn_xml
+
+router = APIRouter(tags=["deployment"])
+
+
+def _local(tag: str) -> str:
+    """lxml tag 形如 {ns}localName -> localName。"""
+    return tag.rsplit("}", 1)[-1]
+
+
+def _classify(xml: str) -> str:
+    """判定 XML 种类：'bpmn' / 'dmn'（无法判定抛 DeploymentException）。"""
+    try:
+        root = etree.fromstring(xml.encode("utf-8"))
+    except etree.XMLSyntaxError as e:
+        raise DeploymentException(f"XML 语法错误: {e}") from e
+    for child in root:
+        if not isinstance(child.tag, str):
+            continue
+        if _local(child.tag) == "decision":
+            return "dmn"
+        if _local(child.tag) == "process":
+            return "bpmn"
+    raise DeploymentException(
+        "XML 根元素内未发现 process 或 decision 子元素，无法判定 BPMN / DMN"
+    )
+
+
+def _deploy_xml(engine, xml: str, name: Optional[str] = None) -> Dict[str, List[str]]:
+    """部署一份 XML，返回 {"process_keys": [...], "decision_keys": [...]}。"""
+    kind = _classify(xml)
+    if kind == "bpmn":
+        keys = engine.deploy(parse_bpmn_xml(xml, source_name=name), name=name)
+        return {"process_keys": list(keys), "decision_keys": []}
+    keys = engine.deploy_dmn(parse_dmn_xml(xml, source_name=name), name=name)
+    return {"process_keys": [], "decision_keys": list(keys)}
+
+
+def _deployment_body(
+    engine, deployments: List[Dict[str, Any]], name: Optional[str] = None
+) -> Dict[str, Any]:
+    """聚合若干次部署记录 -> Camunda DeploymentWithDefinitionsDto 形态。"""
+    proc_defs: Dict[str, Any] = {}
+    dec_defs: Dict[str, Any] = {}
+    dep_id = None
+    dep_time = None
+    for dep in deployments:
+        dep_id = dep["id"]
+        dep_time = dep["time"]
+        for key in dep["process_keys"]:
+            version = engine.get_definition_version(key)
+            proc_defs[f"{key}:{version}"] = process_definition_dto(
+                key, engine.get_process_definition(key).name, version
+            )
+        for key in dep["decision_keys"]:
+            version = engine.get_decision_version(key)
+            dec_defs[f"{key}:{version}"] = decision_definition_dto(
+                key, version, engine.get_decision_definition(key).name
+            )
+    return {
+        "id": dep_id,
+        "name": name,
+        "time": dep_time,
+        "deployedProcessDefinitions": proc_defs,
+        "deployedDecisionDefinitions": dec_defs,
+    }
+
+
+@router.post("/deployment/create", summary="部署 BPMN/DMN XML（multipart）")
+async def create_deployment(
+    request: Request,
+    data: Optional[List[UploadFile]] = File(default=None, alias="data"),
+) -> Dict[str, Any]:
+    """multipart 部署，字段名 `data`，可多文件（对齐 Camunda 7 REST）。"""
+    engine = get_engine(request)
+    if not data:
+        raise InvalidRequestException(
+            "缺少上传文件：form-data 字段名须为 data，可重复携带多个 .bpmn / .dmn"
+        )
+    deployments: List[Dict[str, Any]] = []
+    for upload in data:
+        content = (await upload.read()).decode("utf-8")
+        before = len(engine.list_deployments())
+        _deploy_xml(engine, content, name=upload.filename)
+        deployments.extend(engine.list_deployments()[before:])
+    return _deployment_body(engine, deployments)
+
+
+@router.post("/deployment/create/xml", summary="部署 BPMN/DMN XML（JSON 便捷通道）")
+def create_deployment_xml(request: Request, body: DeploymentDto) -> Dict[str, Any]:
+    """JSON 便捷通道（本项目扩展）：body = {"xml": "...", "name": "..."}。"""
+    engine = get_engine(request)
+    before = len(engine.list_deployments())
+    _deploy_xml(engine, body.xml, name=body.name)
+    return _deployment_body(engine, engine.list_deployments()[before:], name=body.name)
+
+
+@router.get("/deployment", summary="部署列表")
+def list_deployments(
+    request: Request,
+    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)
+    items = [
+        {
+            "id": d["id"],
+            "name": d["name"],
+            "time": d["time"],
+            "source": d["source"],
+            "process_keys": list(d["process_keys"]),
+            "decision_keys": list(d["decision_keys"]),
+        }
+        for d in engine.list_deployments()
+    ]
+    return paginate(items, firstResult, maxResults)

camunda/api/routers/history.py

@@ -0,0 +1,128 @@
+"""历史端点（M6-5）：实例 / 任务 / 活动 / 变量历史。
+
+数据源：引擎内存中保留的流程实例（含已结束的——实例完成后仍留在
+`_instances`，仅 state 置 COMPLETED）。启用 Store 时 ACT_HI_* 表同步写入，
+但本端点统一走内存视图，保证两种模式下行为一致（文档化差异：历史查询
+不做跨重启回溯，被 DELETE 删除的实例在内存视图中不再可见）。
+"""
+
+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 (
+    activity_instance_dto,
+    historic_process_instance_dto,
+    historic_task_dto,
+    to_variable_map,
+)
+
+router = APIRouter(tags=["history"])
+
+
+@router.get("/history/process-instance", summary="历史流程实例")
+def list_historic_process_instances(
+    request: Request,
+    processDefinitionKey: Optional[str] = Query(default=None),
+    finished: Optional[bool] = Query(default=None, description="true=只看已结束"),
+    businessKey: Optional[str] = Query(default=None),
+    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 finished is not None:
+        instances = [pi for pi in instances if pi.is_completed == finished]
+    items = [historic_process_instance_dto(pi) for pi in instances]
+    return paginate(items, firstResult, maxResults)
+
+
+@router.get("/history/process-instance/{instance_id}", summary="单个历史流程实例")
+def get_historic_process_instance(
+    request: Request, instance_id: str
+) -> Dict[str, Any]:
+    engine = get_engine(request)
+    return historic_process_instance_dto(engine.get_process_instance(instance_id))
+
+
+@router.get("/history/task", summary="历史任务（已归档 + 待办）")
+def list_historic_tasks(
+    request: Request,
+    processInstanceId: Optional[str] = Query(default=None),
+    finished: 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)
+    out: List[Dict[str, Any]] = []
+    instances = engine.list_process_instances()
+    if processInstanceId is not None:
+        instances = [pi for pi in instances if pi.id == processInstanceId]
+    for pi in instances:
+        if finished is not True:
+            out.extend(historic_task_dto(t) for t in pi.completed_tasks)
+        if finished is not False:
+            # 待办任务（end_time 为空）也纳入历史视图，对齐 Camunda HistoricTaskInstance
+            out.extend(
+                historic_task_dto(t)
+                for t in engine.create_task_query(process_instance_id=pi.id)
+            )
+    return paginate(out, firstResult, maxResults)
+
+
+@router.get("/history/activity-instance", summary="历史活动实例")
+def list_historic_activity_instances(
+    request: Request,
+    processInstanceId: Optional[str] = Query(default=None),
+    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 processInstanceId is not None:
+        instances = [pi for pi in instances if pi.id == processInstanceId]
+    items = [activity_instance_dto(ai) for pi in instances for ai in pi.activity_history]
+    return paginate(items, firstResult, maxResults)
+
+
+@router.get("/history/variable-instance", summary="历史变量（实例级快照）")
+def list_historic_variable_instances(
+    request: Request,
+    processInstanceId: Optional[str] = Query(default=None),
+    bare: bool = Query(default=False),
+    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 processInstanceId is not None:
+        instances = [pi for pi in instances if pi.id == processInstanceId]
+    out: List[Dict[str, Any]] = []
+    for pi in instances:
+        for name, dto in to_variable_map(pi.variables, bare=bare).items():
+            if bare:
+                out.append(
+                    {"processInstanceId": pi.id, "name": name, "value": dto}
+                )
+            else:
+                out.append({"processInstanceId": pi.id, "name": name, **dto})
+    return paginate(out, firstResult, maxResults)

camunda/api/routers/process_definition.py

@@ -0,0 +1,49 @@
+"""流程定义端点（M6-2）：GET /process-definition。"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+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 process_definition_dto
+
+router = APIRouter(tags=["process-definition"])
+
+
+@router.get("/process-definition", summary="流程定义列表")
+def list_process_definitions(
+    request: Request,
+    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)
+    items = [
+        process_definition_dto(d["key"], d["name"], d["version"])
+        for d in engine.list_process_definitions()
+    ]
+    return paginate(items, firstResult, maxResults)
+
+
+@router.get("/process-definition/key/{key}", summary="按 key 取最新版本的流程定义")
+def get_process_definition_by_key(request: Request, key: str) -> Dict[str, Any]:
+    engine = get_engine(request)
+    proc = engine.get_process_definition(key)
+    return process_definition_dto(key, proc.name, engine.get_definition_version(key))
+
+
+@router.get("/process-definition/key/{key}/xml", summary="取流程定义 XML")
+def get_process_definition_xml(request: Request, key: str) -> Dict[str, Any]:
+    engine = get_engine(request)
+    version = engine.get_definition_version(key)
+    return {
+        "id": f"{key}:{version}",
+        "key": key,
+        "version": version,
+        # 部署时未带 source_xml（如直接 deploy(BpmnModel) 构造）则为 None
+        "bpmn20Xml": engine.get_process_definition_xml(key),
+    }