@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanmetric/references/metric-api-contract.schema.json

@@ -0,0 +1,349 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.dev/schemas/guanmetric/metric-api-contract-1.0.json",
+  "title": "GuanData metric create, update, detail and list API contract",
+  "description": "用于 Agent 构造指标写请求、解析后端原始响应的宽松契约。后端可能增加字段，因此响应对象允许 additionalProperties。",
+  "oneOf": [
+    { "$ref": "#/$defs/createRequest" },
+    { "$ref": "#/$defs/updateRequest" },
+    { "$ref": "#/$defs/listRequest" },
+    { "$ref": "#/$defs/mutationSuccessResponse" },
+    { "$ref": "#/$defs/listResponse" },
+    { "$ref": "#/$defs/detailResponse" }
+  ],
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    },
+    "user": {
+      "type": "object",
+      "required": ["uId", "name"],
+      "properties": {
+        "uId": { "$ref": "#/$defs/nonEmptyString" },
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "avatar": { "type": "string" },
+        "isDel": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "field": {
+      "type": "object",
+      "required": ["fdId"],
+      "properties": {
+        "dsId": { "type": "string" },
+        "fdId": { "$ref": "#/$defs/nonEmptyString" },
+        "name": { "type": "string" },
+        "fdType": { "type": "string" },
+        "metaType": { "type": "string" },
+        "granularity": { "type": "string" },
+        "subs": { "type": "array", "items": { "$ref": "#/$defs/field" } },
+        "publicDimensions": { "type": "array" }
+      },
+      "additionalProperties": true
+    },
+    "metricReference": {
+      "type": "object",
+      "required": ["id", "name", "subType", "status"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "name": { "type": "string" },
+        "subType": { "enum": ["ATOMIC", "COMPOSITE", "DERIVED", "SHORTCUT"] },
+        "status": { "type": "string" },
+        "desc": { "type": "string" },
+        "timeDim": { "oneOf": [{ "$ref": "#/$defs/field" }, { "type": "null" }] }
+      },
+      "additionalProperties": true
+    },
+    "commonCreateFields": {
+      "type": "object",
+      "required": ["projectId", "subType", "name", "desc", "parentDirId", "businessOwner", "publish"],
+      "properties": {
+        "projectId": { "$ref": "#/$defs/nonEmptyString" },
+        "subType": { "enum": ["ATOMIC", "COMPOSITE", "DERIVED"] },
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "engName": { "type": "string" },
+        "desc": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "businessOwner": { "$ref": "#/$defs/nonEmptyString" },
+        "publish": { "type": "boolean" },
+        "format": { "type": "object" },
+        "filter": { "type": ["object", "null"] },
+        "bizAttrs": { "type": "array" },
+        "dynamicParameters": { "type": "array" },
+        "bizMetricId": { "type": "string" }
+      }
+    },
+    "commonUpdateFields": {
+      "type": "object",
+      "required": ["projectId", "subType", "name", "desc", "publish"],
+      "properties": {
+        "projectId": { "$ref": "#/$defs/nonEmptyString" },
+        "subType": { "enum": ["ATOMIC", "COMPOSITE", "DERIVED"] },
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "engName": { "type": "string" },
+        "desc": { "$ref": "#/$defs/nonEmptyString" },
+        "publish": { "type": "boolean" },
+        "format": { "type": "object" },
+        "filter": { "type": ["object", "null"] },
+        "bizAttrs": { "type": "array" },
+        "dynamicParameters": { "type": "array" },
+        "bizMetricId": { "type": "string" }
+      }
+    },
+    "atomicSource": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["fdId", "aggrType"],
+          "properties": {
+            "fdId": { "$ref": "#/$defs/nonEmptyString" },
+            "aggrType": { "enum": ["SUM", "MIN", "MAX", "AVG", "CNT", "CNT_DISTINCT", "NUL"] }
+          },
+          "not": { "required": ["formulaField"] }
+        },
+        {
+          "type": "object",
+          "required": ["formulaField"],
+          "properties": {
+            "formulaField": {
+              "type": "object",
+              "required": ["fdFormula"],
+              "properties": { "fdFormula": { "$ref": "#/$defs/nonEmptyString" } },
+              "additionalProperties": false
+            }
+          },
+          "not": { "anyOf": [{ "required": ["fdId"] }, { "required": ["aggrType"] }] }
+        }
+      ]
+    },
+    "atomicCreateRequest": {
+      "allOf": [
+        { "$ref": "#/$defs/commonCreateFields" },
+        { "$ref": "#/$defs/atomicSource" },
+        {
+          "type": "object",
+          "required": ["dsId", "applicableDims"],
+          "properties": {
+            "subType": { "const": "ATOMIC" },
+            "dsId": { "$ref": "#/$defs/nonEmptyString" },
+            "applicableDims": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/nonEmptyString" } },
+            "timeDim": { "type": "string" },
+            "sourceMetricId": { "type": "string" }
+          }
+        }
+      ],
+      "unevaluatedProperties": true
+    },
+    "atomicUpdateRequest": {
+      "allOf": [
+        { "$ref": "#/$defs/commonUpdateFields" },
+        { "$ref": "#/$defs/atomicSource" },
+        {
+          "type": "object",
+          "required": ["dsId", "applicableDims"],
+          "properties": {
+            "subType": { "const": "ATOMIC" },
+            "dsId": { "$ref": "#/$defs/nonEmptyString" },
+            "applicableDims": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/nonEmptyString" } },
+            "timeDim": { "type": "string" },
+            "sourceMetricId": { "type": "string" }
+          }
+        }
+      ],
+      "unevaluatedProperties": true
+    },
+    "compositeBody": {
+      "type": "object",
+      "required": ["formula", "useExpressionMetricCommonDims", "applicableDims"],
+      "properties": {
+        "subType": { "const": "COMPOSITE" },
+        "formula": { "$ref": "#/$defs/nonEmptyString" },
+        "useExpressionMetricCommonDims": { "type": "boolean" },
+        "applicableDims": { "type": "array", "items": { "$ref": "#/$defs/nonEmptyString" } },
+        "timeDim": { "type": "string" }
+      }
+    },
+    "derivedBody": {
+      "type": "object",
+      "required": ["deriveSetting"],
+      "properties": {
+        "subType": { "const": "DERIVED" },
+        "baseMetricId": { "type": "string" },
+        "deriveSetting": { "$ref": "#/$defs/deriveSetting" }
+      }
+    },
+    "deriveSetting": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["deriveType", "advType", "advValue"],
+          "properties": {
+            "deriveType": { "const": "ORDINARY" },
+            "advType": { "enum": ["COMPARATIVE", "RECENT_X", "XTD", "LAST", "BIZ_CONDITION"] },
+            "advValue": {
+              "type": "object",
+              "required": ["advType"],
+              "properties": {
+                "advType": { "enum": ["COMPARATIVE", "RECENT_X", "XTD", "LAST", "BIZ_CONDITION"] }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["deriveType", "formula"],
+          "properties": {
+            "deriveType": { "const": "COMPOSITE" },
+            "formula": { "$ref": "#/$defs/nonEmptyString" }
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+    "createRequest": {
+      "oneOf": [
+        { "$ref": "#/$defs/atomicCreateRequest" },
+        {
+          "allOf": [{ "$ref": "#/$defs/commonCreateFields" }, { "$ref": "#/$defs/compositeBody" }],
+          "unevaluatedProperties": true
+        },
+        {
+          "allOf": [{ "$ref": "#/$defs/commonCreateFields" }, { "$ref": "#/$defs/derivedBody" }],
+          "unevaluatedProperties": true
+        }
+      ]
+    },
+    "updateRequest": {
+      "oneOf": [
+        { "$ref": "#/$defs/atomicUpdateRequest" },
+        {
+          "allOf": [{ "$ref": "#/$defs/commonUpdateFields" }, { "$ref": "#/$defs/compositeBody" }],
+          "unevaluatedProperties": true
+        },
+        {
+          "allOf": [{ "$ref": "#/$defs/commonUpdateFields" }, { "$ref": "#/$defs/derivedBody" }],
+          "unevaluatedProperties": true
+        }
+      ]
+    },
+    "listRequest": {
+      "type": "object",
+      "properties": {
+        "projectId": { "type": "string" },
+        "dirId": { "type": "string" },
+        "status": { "type": "string" },
+        "nameLike": { "type": "string" },
+        "subTypes": { "type": "string", "description": "逗号分隔，不是 JSON 数组" },
+        "orderBy": { "type": "string" },
+        "creator": { "type": "array", "items": { "type": "string" } },
+        "businessOwner": { "type": "array", "items": { "type": "string" } },
+        "bizAttrSearch": { "type": "array" },
+        "desc": { "type": "string" },
+        "favorite": { "type": "boolean" },
+        "canUse": { "type": "boolean" },
+        "isMarket": { "type": "boolean" },
+        "offset": { "type": "integer", "minimum": 0 },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
+      },
+      "additionalProperties": false
+    },
+    "mutationSuccessResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": {
+          "type": "object",
+          "required": ["id"],
+          "properties": { "id": { "$ref": "#/$defs/nonEmptyString" } },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "metricSummary": {
+      "type": "object",
+      "required": ["id", "projectId", "status", "subType", "name", "dirId", "canManage", "canUse"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "projectId": { "$ref": "#/$defs/nonEmptyString" },
+        "status": { "type": "string" },
+        "subType": { "enum": ["ATOMIC", "COMPOSITE", "DERIVED", "SHORTCUT"] },
+        "name": { "type": "string" },
+        "desc": { "type": "string" },
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "businessOwner": { "$ref": "#/$defs/user" },
+        "creator": { "$ref": "#/$defs/user" },
+        "canManage": { "type": "boolean" },
+        "canUse": { "type": "boolean" },
+        "timeDim": { "oneOf": [{ "$ref": "#/$defs/field" }, { "type": "null" }] },
+        "hasDraft": { "type": ["boolean", "null"] },
+        "favorite": { "type": "boolean" },
+        "approvalStatus": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "listResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": {
+          "type": "object",
+          "required": ["contents", "count"],
+          "properties": {
+            "contents": { "type": "array", "items": { "$ref": "#/$defs/metricSummary" } },
+            "count": { "type": "integer", "minimum": 0 },
+            "limit": { "type": "integer" },
+            "returnedCount": { "type": "integer" },
+            "dirPath": { "type": "array" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "metricDetail": {
+      "type": "object",
+      "required": ["id", "projectId", "parentDirId", "subType", "status", "name"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "projectId": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "subType": { "enum": ["ATOMIC", "COMPOSITE", "DERIVED", "SHORTCUT"] },
+        "uniformResourceType": { "type": "string" },
+        "status": { "type": "string" },
+        "name": { "type": "string" },
+        "desc": { "type": "string" },
+        "dsInfo": { "type": "object" },
+        "fdInfos": { "type": "array", "items": { "$ref": "#/$defs/field" } },
+        "aggrType": { "type": ["string", "null"] },
+        "formulaField": { "type": ["object", "null"] },
+        "formula": { "type": "string" },
+        "deriveSetting": { "$ref": "#/$defs/deriveSetting" },
+        "baseMetric": { "$ref": "#/$defs/metricReference" },
+        "referencedMetrics": { "type": "array", "items": { "$ref": "#/$defs/metricReference" } },
+        "applicableDims": { "type": "array", "items": { "$ref": "#/$defs/field" } },
+        "timeDim": { "oneOf": [{ "$ref": "#/$defs/field" }, { "type": "null" }] },
+        "businessOwner": { "$ref": "#/$defs/user" },
+        "creator": { "$ref": "#/$defs/user" },
+        "canManage": { "type": "boolean" },
+        "canUse": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "detailResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "$ref": "#/$defs/metricDetail" }
+      },
+      "additionalProperties": true
+    }
+  }
+}