@josephyan/qingflow-cli 0.2.0-beta.55

package/src/qingflow_mcp/solution/compiler/portal_compiler.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..spec_models import PortalSourceType, SolutionSpec
+from .form_compiler import default_member_auth
+from .icon_utils import encode_workspace_icon
+
+
+def compile_portal(spec: SolutionSpec) -> dict[str, Any] | None:
+    if not spec.preferences.create_portal or not spec.portal.enabled or not spec.portal.sections:
+        return None
+    components: list[dict[str, Any]] = []
+    for ordinal, section in enumerate(spec.portal.sections, start=1):
+        component: dict[str, Any] = {
+            "sectionId": section.section_id,
+            "title": section.title,
+            "sourceType": section.source_type.value,
+            "ordinal": ordinal,
+            **section.config,
+        }
+        if section.source_type == PortalSourceType.chart:
+            component["chartRef"] = {"entity_id": section.entity_id, "chart_id": section.chart_id}
+        elif section.source_type == PortalSourceType.view:
+            component["viewRef"] = {"entity_id": section.entity_id, "view_id": section.view_id}
+        elif section.source_type == PortalSourceType.text:
+            component["text"] = section.text or ""
+        elif section.source_type == PortalSourceType.link:
+            component["url"] = section.url or ""
+        components.append(component)
+    return {
+        "create_payload": {
+            "dashName": spec.portal.name or f"{spec.solution_name} 首页",
+            "dashIcon": encode_workspace_icon(
+                icon=spec.portal.icon,
+                color=spec.portal.color,
+                title=spec.portal.name or f"{spec.solution_name} 首页",
+                fallback_icon_name="view-grid",
+            ),
+            "auth": default_member_auth(),
+            "hideCopyright": False,
+            "tags": [{"tagId": "__PACKAGE_TAG_ID__", "ordinal": 1}],
+            "dashGlobalConfig": {"layout": "default"},
+        },
+        "update_payload": {
+            "dashName": spec.portal.name or f"{spec.solution_name} 首页",
+            "dashIcon": encode_workspace_icon(
+                icon=spec.portal.icon,
+                color=spec.portal.color,
+                title=spec.portal.name or f"{spec.solution_name} 首页",
+                fallback_icon_name="view-grid",
+            ),
+            "auth": default_member_auth(),
+            "hideCopyright": False,
+            "tags": [{"tagId": "__PACKAGE_TAG_ID__", "ordinal": 1}],
+            "dashGlobalConfig": {"layout": "default"},
+            "components": components,
+            **spec.portal.config,
+        },
+    }

package/src/qingflow_mcp/solution/compiler/view_compiler.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..spec_models import EntitySpec, ViewType
+from .form_compiler import default_member_auth
+
+
+VIEW_TYPE_MAP = {
+    ViewType.table: "tableView",
+    ViewType.card: "cardView",
+    ViewType.board: "boardView",
+    ViewType.gantt: "ganttView",
+    ViewType.hierarchy: "hierarchyView",
+}
+
+
+def compile_views(entity: EntitySpec) -> list[dict[str, Any]]:
+    views: list[dict[str, Any]] = []
+    for ordinal, view in enumerate(entity.views, start=1):
+        views.append(
+            {
+                "view_id": view.view_id,
+                "name": view.name,
+                "type": view.type.value,
+                "create_payload": {
+                    "appKey": "__APP_KEY__",
+                    "viewgraphName": view.name,
+                    "viewgraphType": VIEW_TYPE_MAP[view.type],
+                    "auth": default_member_auth(),
+                    "beingPinNavigate": True,
+                    "viewgraphQueIds": list(view.field_ids),
+                    "viewgraphQuestions": [],
+                    "ordinal": ordinal,
+                    "beingShowTitleQue": view.type in (ViewType.card, ViewType.board, ViewType.gantt, ViewType.hierarchy),
+                    "beingShowCover": False,
+                    "viewgraphLimitType": 1,
+                    "viewgraphLimit": view.filters,
+                    "sortType": "defaultSort",
+                    "viewgraphSorts": view.sort,
+                    **view.config,
+                },
+                "column_widths": view.column_widths,
+                "member_config": view.member_config,
+                "apply_config": view.apply_config,
+                "group_by_field_id": view.group_by_field_id,
+                "config": view.config,
+                "being_default": view.being_default,
+            }
+        )
+    return views

package/src/qingflow_mcp/solution/compiler/workflow_compiler.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..spec_models import EntitySpec, WorkflowNodeType
+
+
+WORKFLOW_TYPE_MAP = {
+    WorkflowNodeType.start: {"type": 0, "dealType": 3},
+    WorkflowNodeType.branch: {"type": 1, "dealType": None},
+    WorkflowNodeType.audit: {"type": 0, "dealType": 0},
+    WorkflowNodeType.fill: {"type": 0, "dealType": 1},
+    WorkflowNodeType.copy: {"type": 0, "dealType": 2},
+    WorkflowNodeType.webhook: {"type": 3, "dealType": 10},
+    WorkflowNodeType.condition: {"type": 2, "dealType": None},
+}
+
+
+def _default_audit_user_infos() -> dict[str, Any]:
+    return {
+        "member": [],
+        "depart": [],
+        "role": [],
+        "dynamic": [],
+        "includeSubDeparts": None,
+        "externalMemberList": [],
+        "externalDepartList": [],
+        "role_refs": [],
+    }
+
+
+def compile_workflow(entity: EntitySpec) -> dict[str, Any] | None:
+    workflow = entity.workflow
+    if workflow is None or not workflow.enabled:
+        return None
+    actions: list[dict[str, Any]] = []
+    seen_node_ids: set[str] = set()
+    created_extra_branch_lanes: set[str] = set()
+    start_node_ids = {
+        node.node_id
+        for node in workflow.nodes
+        if node.node_type == WorkflowNodeType.start
+    }
+    for node in workflow.nodes:
+        if node.node_type == WorkflowNodeType.start:
+            seen_node_ids.add(node.node_id)
+            continue
+        if node.parent_node_id and node.parent_node_id not in seen_node_ids:
+            raise ValueError(f"workflow node '{node.node_id}' must appear after parent node '{node.parent_node_id}'")
+        if node.branch_parent_id and node.branch_parent_id not in seen_node_ids:
+            raise ValueError(f"workflow node '{node.node_id}' must appear after branch node '{node.branch_parent_id}'")
+        branch_index = _branch_index(node)
+        branch_lane_ref = _branch_lane_ref(node.branch_parent_id, branch_index) if node.branch_parent_id else None
+        if branch_lane_ref and branch_index > 2 and branch_lane_ref not in created_extra_branch_lanes:
+            actions.append(
+                {
+                    "action": "create_sub_branch",
+                    "node_id": branch_lane_ref,
+                    "payload": {
+                        "editVersionNo": 1,
+                        "auditNodeRef": node.branch_parent_id,
+                    },
+                }
+            )
+            created_extra_branch_lanes.add(branch_lane_ref)
+        lane_only = bool((node.config or {}).get("__lane_only__")) and node.node_type == WorkflowNodeType.condition and branch_lane_ref
+        if lane_only:
+            lane_payload = {key: value for key, value in node.config.items() if key != "__lane_only__"}
+            actions.append(
+                {
+                    "action": "update_node",
+                    "node_id": branch_lane_ref,
+                    "node_name": node.name,
+                    "node_type": node.node_type.value,
+                    "payload": {
+                        "editVersionNo": 1,
+                        "auditNodeName": node.name,
+                        "type": WORKFLOW_TYPE_MAP[node.node_type]["type"],
+                        "dealType": WORKFLOW_TYPE_MAP[node.node_type]["dealType"],
+                        **lane_payload,
+                    },
+                }
+            )
+            seen_node_ids.add(node.node_id)
+            continue
+        actions.append(
+            {
+                "action": "add_node",
+                "node_id": node.node_id,
+                "node_name": node.name,
+                "node_type": node.node_type.value,
+                "payload": {
+                    "editVersionNo": 1,
+                    "auditNodeName": node.name,
+                    "type": WORKFLOW_TYPE_MAP[node.node_type]["type"],
+                    "dealType": WORKFLOW_TYPE_MAP[node.node_type]["dealType"],
+                    "prevNodeRef": _prev_node_ref(node, branch_lane_ref, start_node_ids),
+                    "auditUserInfos": _build_audit_user_infos(node)
+                    if node.node_type in {WorkflowNodeType.audit, WorkflowNodeType.fill, WorkflowNodeType.copy}
+                    else None,
+                    **node.config,
+                },
+            }
+        )
+        seen_node_ids.add(node.node_id)
+    return {
+        "global_settings": {
+            "editVersionNo": 1,
+            **workflow.global_settings,
+        },
+        "actions": actions,
+    }
+
+
+def _build_audit_user_infos(node) -> dict[str, Any]:
+    audit_user_infos = _default_audit_user_infos()
+    assignees = node.assignees or {}
+    member_uids = assignees.get("member_uids") or []
+    if member_uids:
+        audit_user_infos["member"] = [
+            {"uid": uid, "beingFrontendConfig": True}
+            for uid in member_uids
+            if isinstance(uid, int) and uid > 0
+        ]
+    role_refs = assignees.get("role_refs") or []
+    if role_refs:
+        audit_user_infos["role_refs"] = [role_ref for role_ref in role_refs if role_ref]
+    role_entries = assignees.get("role_entries") or []
+    if role_entries:
+        audit_user_infos["role"] = [
+            {
+                "roleId": int(entry.get("roleId") or entry.get("role_id")),
+                "roleName": entry.get("roleName") or entry.get("role_name") or str(entry.get("roleId") or entry.get("role_id")),
+                "roleIcon": entry.get("roleIcon") or entry.get("role_icon") or "ex-user-outlined",
+                "beingFrontendConfig": True,
+            }
+            for entry in role_entries
+            if isinstance(entry, dict) and isinstance(entry.get("roleId") or entry.get("role_id"), int) and int(entry.get("roleId") or entry.get("role_id")) > 0
+        ]
+    include_sub_departs = assignees.get("include_sub_departs")
+    if include_sub_departs is not None:
+        audit_user_infos["includeSubDeparts"] = bool(include_sub_departs)
+    return audit_user_infos
+
+
+def _prev_node_ref(node, branch_lane_ref: str | None, start_node_ids: set[str]) -> str:
+    if branch_lane_ref:
+        if node.parent_node_id and node.parent_node_id != node.branch_parent_id:
+            return node.parent_node_id
+        return branch_lane_ref
+    if node.parent_node_id in start_node_ids:
+        return "__applicant__"
+    return node.parent_node_id or "__applicant__"
+
+
+def _branch_index(node) -> int:
+    config = node.config or {}
+    raw_value = getattr(node, "branch_index", None)
+    if raw_value is None:
+        raw_value = config.get("branch_index", config.get("branchIndex", config.get("lane_index", config.get("laneIndex", 1))))
+    try:
+        branch_index = int(raw_value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"workflow node '{node.node_id}' has invalid branch index '{raw_value}'") from exc
+    if branch_index <= 0:
+        raise ValueError(f"workflow node '{node.node_id}' branch index must be positive")
+    return branch_index
+
+
+def _branch_lane_ref(branch_parent_id: str | None, branch_index: int) -> str:
+    if not branch_parent_id:
+        raise ValueError("branch_parent_id is required for branch lane references")
+    return f"__branch_lane__{branch_parent_id}__{branch_index}"

package/src/qingflow_mcp/solution/design_session.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from enum import Enum
+from typing import Any
+
+from .compiler import compile_solution
+from .normalizer import normalize_solution_spec
+from .spec_models import SolutionSpec
+
+
+class DesignStage(str, Enum):
+    discover = "discover"
+    design = "design"
+    experience = "experience"
+    finalize = "finalize"
+
+
+STAGE_ORDER = [DesignStage.discover, DesignStage.design, DesignStage.experience]
+
+LIST_MERGE_KEYS = {
+    "entities": "entity_id",
+    "roles": "role_id",
+    "requirements": "requirement_id",
+    "success_metrics": "metric_id",
+    "fields": "field_id",
+    "subfields": "field_id",
+    "relations": "relation_id",
+    "lifecycle_stages": "stage_id",
+    "views": "view_id",
+    "charts": "chart_id",
+    "nodes": "node_id",
+    "sections": "section_id",
+    "items": "item_id",
+    "children": "item_id",
+    "entity_scopes": "entity_id",
+}
+
+
+def merge_design_payload(base: Any, patch: Any, *, key_hint: str | None = None) -> Any:
+    if patch is None:
+        return deepcopy(base)
+    if base is None:
+        return deepcopy(patch)
+    if isinstance(base, dict) and isinstance(patch, dict):
+        merged = deepcopy(base)
+        for key, value in patch.items():
+            merged[key] = merge_design_payload(merged.get(key), value, key_hint=key)
+        return merged
+    if isinstance(base, list) and isinstance(patch, list):
+        merge_key = LIST_MERGE_KEYS.get(key_hint or "")
+        if merge_key and _can_merge_named_list(base, patch, merge_key):
+            return _merge_named_list(base, patch, merge_key)
+        return deepcopy(patch)
+    return deepcopy(patch)
+
+
+def evaluate_design_session(stage_payloads: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    discover_spec = merge_design_payload({}, stage_payloads.get(DesignStage.discover.value, {}))
+    design_spec = merge_design_payload(discover_spec, stage_payloads.get(DesignStage.design.value, {}))
+    experience_spec = merge_design_payload(design_spec, stage_payloads.get(DesignStage.experience.value, {}))
+
+    discover_missing = _validate_discover_stage(discover_spec)
+    design_missing = _blocked("discover", discover_missing) if discover_missing else _validate_design_stage(design_spec)
+    experience_missing = _blocked("design", design_missing) if design_missing else _validate_experience_stage(experience_spec)
+
+    stage_results = {
+        DesignStage.discover.value: _stage_result(discover_missing),
+        DesignStage.design.value: _stage_result(design_missing, blocked=bool(discover_missing)),
+        DesignStage.experience.value: _stage_result(experience_missing, blocked=bool(design_missing)),
+    }
+    current_stage = _current_stage(discover_missing, design_missing, experience_missing)
+    status = "ready" if current_stage == DesignStage.finalize.value else "active"
+    return {
+        "status": status,
+        "current_stage": current_stage,
+        "next_stage": None if current_stage == DesignStage.finalize.value else current_stage,
+        "stage_results": stage_results,
+        "merged_design_spec": experience_spec,
+    }
+
+
+def finalize_design_session(stage_payloads: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    evaluation = evaluate_design_session(stage_payloads)
+    if evaluation["current_stage"] != DesignStage.finalize.value:
+        raise ValueError("design session is not ready to finalize")
+    parsed = SolutionSpec.model_validate(evaluation["merged_design_spec"])
+    normalized = normalize_solution_spec(parsed)
+    compiled = compile_solution(normalized)
+    return {
+        **evaluation,
+        "normalized_solution_spec": normalized.model_dump(mode="json"),
+        "execution_plan": compiled.execution_plan.as_dict(),
+    }
+
+
+def _stage_result(missing_requirements: list[str], *, blocked: bool = False) -> dict[str, Any]:
+    if blocked and missing_requirements:
+        status = "blocked"
+    elif missing_requirements:
+        status = "pending"
+    else:
+        status = "completed"
+    return {
+        "status": status,
+        "missing_requirements": missing_requirements,
+    }
+
+
+def _current_stage(discover_missing: list[str], design_missing: list[str], experience_missing: list[str]) -> str:
+    if discover_missing:
+        return DesignStage.discover.value
+    if design_missing:
+        return DesignStage.design.value
+    if experience_missing:
+        return DesignStage.experience.value
+    return DesignStage.finalize.value
+
+
+def _blocked(previous_stage: str, previous_missing: list[str]) -> list[str]:
+    return [f"{previous_stage} stage is incomplete"] if previous_missing else []
+
+
+def _validate_discover_stage(spec: dict[str, Any]) -> list[str]:
+    missing: list[str] = []
+    solution_name = spec.get("solution_name")
+    if not isinstance(solution_name, str) or not solution_name.strip():
+        missing.append("solution_name is required")
+
+    entities = spec.get("entities")
+    if not isinstance(entities, list) or not entities:
+        missing.append("entities must be a non-empty list")
+        return missing
+
+    seen_entity_ids: set[str] = set()
+    for entity in entities:
+        entity_id = entity.get("entity_id")
+        display_name = entity.get("display_name")
+        kind = entity.get("kind")
+        if not entity_id:
+            missing.append("each entity must declare entity_id")
+            continue
+        if entity_id in seen_entity_ids:
+            missing.append(f"entity '{entity_id}' is duplicated")
+            continue
+        seen_entity_ids.add(entity_id)
+        if not display_name:
+            missing.append(f"entity '{entity_id}' must declare display_name")
+        if not kind:
+            missing.append(f"entity '{entity_id}' must declare kind")
+        fields = entity.get("fields")
+        if not isinstance(fields, list) or not fields:
+            missing.append(f"entity '{entity_id}' must declare fields")
+            continue
+        field_ids = {field.get("field_id") for field in fields if isinstance(field, dict)}
+        if kind in {"master", "transaction"}:
+            title_field_id = entity.get("title_field_id")
+            if not title_field_id:
+                missing.append(f"entity '{entity_id}' must explicitly declare title_field_id")
+            elif title_field_id not in field_ids:
+                missing.append(f"entity '{entity_id}' title_field_id '{title_field_id}' is missing from fields")
+        if entity.get("workflow") or entity.get("lifecycle_stages"):
+            status_field_id = entity.get("status_field_id")
+            if not status_field_id:
+                missing.append(f"entity '{entity_id}' must explicitly declare status_field_id")
+            elif status_field_id not in field_ids:
+                missing.append(f"entity '{entity_id}' status_field_id '{status_field_id}' is missing from fields")
+    return missing
+
+
+def _validate_design_stage(spec: dict[str, Any]) -> list[str]:
+    missing: list[str] = []
+    for entity in spec.get("entities", []):
+        entity_id = entity.get("entity_id", "<unknown>")
+        if "form_layout" not in entity:
+            missing.append(f"entity '{entity_id}' must explicitly declare form_layout")
+        if "workflow" not in entity:
+            missing.append(f"entity '{entity_id}' must explicitly declare workflow")
+        if "views" not in entity:
+            missing.append(f"entity '{entity_id}' must explicitly declare views")
+        if "charts" not in entity:
+            missing.append(f"entity '{entity_id}' must explicitly declare charts")
+        if "sample_records" not in entity:
+            missing.append(f"entity '{entity_id}' must explicitly declare sample_records")
+    return missing
+
+
+def _validate_experience_stage(spec: dict[str, Any]) -> list[str]:
+    missing: list[str] = []
+    if "portal" not in spec:
+        missing.append("portal must be explicitly declared")
+    else:
+        portal = spec.get("portal") or {}
+        if portal.get("enabled", True) and not portal.get("sections"):
+            missing.append("portal.sections must be provided when portal.enabled is true")
+    if "navigation" not in spec:
+        missing.append("navigation must be explicitly declared")
+    else:
+        navigation = spec.get("navigation") or {}
+        if navigation.get("enabled", True) and not navigation.get("items"):
+            missing.append("navigation.items must be provided when navigation.enabled is true")
+    return missing
+
+
+def _can_merge_named_list(base: list[Any], patch: list[Any], merge_key: str) -> bool:
+    items = [*base, *patch]
+    if not items:
+        return False
+    return all(isinstance(item, dict) and merge_key in item for item in items)
+
+
+def _merge_named_list(base: list[dict[str, Any]], patch: list[dict[str, Any]], merge_key: str) -> list[dict[str, Any]]:
+    merged = [deepcopy(item) for item in base]
+    index = {item[merge_key]: position for position, item in enumerate(merged)}
+    for item in patch:
+        item_key = item[merge_key]
+        if item_key in index:
+            merged[index[item_key]] = merge_design_payload(merged[index[item_key]], item)
+        else:
+            index[item_key] = len(merged)
+            merged.append(deepcopy(item))
+    return merged

package/src/qingflow_mcp/solution/design_store.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import os
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..config import get_mcp_home
+from .design_session import DesignStage
+from .run_store import resolve_storage_path, utc_now
+
+
+def get_design_sessions_path() -> Path:
+    custom_home = os.getenv("QINGFLOW_MCP_DESIGN_HOME")
+    if custom_home:
+        return Path(custom_home).expanduser()
+    return get_mcp_home() / "design-sessions"
+
+
+@dataclass(slots=True)
+class DesignSessionStore:
+    path: Path
+    data: dict[str, Any]
+
+    @classmethod
+    def open(cls, *, session_id: str, metadata: dict[str, Any] | None = None) -> "DesignSessionStore":
+        base_dir = get_design_sessions_path()
+        base_dir.mkdir(parents=True, exist_ok=True)
+        path = resolve_storage_path(base_dir, key=session_id, id_field="session_id")
+        if path.exists():
+            data = json.loads(path.read_text(encoding="utf-8"))
+            stored_session_id = data.get("session_id")
+            if stored_session_id != session_id:
+                raise ValueError(f"existing design session at '{path}' belongs to '{stored_session_id}', not '{session_id}'")
+        else:
+            data = {
+                "session_id": session_id,
+                "status": "active",
+                "current_stage": DesignStage.discover.value,
+                "metadata": metadata or {},
+                "stage_payloads": {
+                    DesignStage.discover.value: {},
+                    DesignStage.design.value: {},
+                    DesignStage.experience.value: {},
+                },
+                "stage_results": {},
+                "merged_design_spec": {},
+                "normalized_solution_spec": None,
+                "execution_plan": None,
+                "created_at": utc_now(),
+                "updated_at": utc_now(),
+            }
+            path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+        return cls(path=path, data=data)
+
+    def set_metadata(self, metadata: dict[str, Any]) -> None:
+        if metadata:
+            self.data["metadata"] = deepcopy(metadata)
+            self._flush()
+
+    def set_stage_payload(self, stage: str, payload: dict[str, Any]) -> None:
+        self.data.setdefault("stage_payloads", {})
+        self.data["stage_payloads"][stage] = deepcopy(payload)
+        self._flush()
+
+    def get_stage_payload(self, stage: str) -> dict[str, Any]:
+        return deepcopy(self.data.get("stage_payloads", {}).get(stage, {}))
+
+    def update_progress(self, *, status: str, current_stage: str, stage_results: dict[str, Any], merged_design_spec: dict[str, Any]) -> None:
+        self.data["status"] = status
+        self.data["current_stage"] = current_stage
+        self.data["stage_results"] = deepcopy(stage_results)
+        self.data["merged_design_spec"] = deepcopy(merged_design_spec)
+        self._flush()
+
+    def mark_finalized(self, *, normalized_solution_spec: dict[str, Any], execution_plan: dict[str, Any]) -> None:
+        self.data["status"] = "finalized"
+        self.data["current_stage"] = DesignStage.finalize.value
+        self.data["normalized_solution_spec"] = deepcopy(normalized_solution_spec)
+        self.data["execution_plan"] = deepcopy(execution_plan)
+        self._flush()
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "session_id": self.data["session_id"],
+            "status": self.data["status"],
+            "current_stage": self.data["current_stage"],
+            "metadata": deepcopy(self.data.get("metadata", {})),
+            "stage_results": deepcopy(self.data.get("stage_results", {})),
+            "merged_design_spec": deepcopy(self.data.get("merged_design_spec", {})),
+            "normalized_solution_spec": deepcopy(self.data.get("normalized_solution_spec")),
+            "execution_plan": deepcopy(self.data.get("execution_plan")),
+            "session_path": str(self.path),
+        }
+
+    def _flush(self) -> None:
+        self.data["updated_at"] = utc_now()
+        self.path.write_text(json.dumps(self.data, ensure_ascii=False, indent=2), encoding="utf-8")