king-design-analyzer 2.1.7 → 2.2.0

package/hooks/useDialog.json

@@ -0,0 +1,49 @@
+{
+  "id": "useDialog",
+  "name": "useDialog",
+  "displayName": "弹窗状态管理",
+  "category": "dialog",
+  "description": "为 VDialog 或 Dialog 表单场景封装显隐、校验、重置和确认按钮行为，减少弹窗表单模板中的重复状态代码。",
+  "importStatement": "import { useDialog } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "emit",
+      "type": "() => any",
+      "required": false,
+      "description": "父组件传入的 emit，用于联动弹窗显隐或外部事件"
+    },
+    {
+      "name": "isShowParentDialog",
+      "type": "Ref<boolean | undefined>",
+      "required": false,
+      "description": "父级弹窗显隐状态，适合嵌套弹窗场景"
+    }
+  ],
+  "returnType": "{ dialogRef: Ref<Dialog | undefined>; isShowDialog: Ref<boolean>; formRef: Ref<Form | undefined>; validate: Function; validateByScroll: Function; reset: Function; handleClickOkBtn: Function; handleClickValidOkBtn: Function; show: Function; hide: Function; }",
+  "examples": [
+    {
+      "id": "dialog_form",
+      "title": "弹窗表单",
+      "description": "配合 VDialog 管理弹窗显隐和表单校验",
+      "code": "<script setup lang=\"ts\">\nimport { VDialog, useDialog } from '@ksyun-internal/versatile';\n\nconst { isShowDialog, formRef, show, hide, handleClickValidOkBtn } = useDialog();\n</script>\n\n<template>\n  <VDialog v-model=\"isShowDialog\" :ok=\"handleClickValidOkBtn\">\n    <Form ref=\"formRef\"></Form>\n  </VDialog>\n</template>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_form_ref",
+      "description": "调用 validate 或 handleClickValidOkBtn，但没有把 formRef 绑定到表单",
+      "wrongCode": "<Form></Form>",
+      "correctCode": "<Form ref=\"formRef\"></Form>",
+      "explanation": "校验相关方法依赖 formRef 指向真实表单实例。"
+    }
+  ],
+  "searchKeywords": [
+    "useDialog",
+    "VDialog",
+    "弹窗表单",
+    "dialog",
+    "validate",
+    "show hide"
+  ]
+}

package/hooks/useEntity.json

@@ -0,0 +1,61 @@
+{
+  "id": "useEntity",
+  "name": "useEntity",
+  "displayName": "基础实体映射",
+  "category": "state",
+  "description": "根据单个 ID 和基础列表做实体同步回调，适合简单的字符串或数字值映射场景。",
+  "importStatement": "import { useEntity } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "id",
+      "type": "Ref<string | number | undefined | null>",
+      "required": true,
+      "description": "当前选中的 ID"
+    },
+    {
+      "name": "list",
+      "type": "Ref<string[] | number[] | undefined | null>",
+      "required": true,
+      "description": "基础值列表"
+    },
+    {
+      "name": "emit",
+      "type": "(entity: string | number | null | undefined) => void",
+      "required": false,
+      "description": "值变化时的回调"
+    },
+    {
+      "name": "isNeedDefaultValue",
+      "type": "boolean",
+      "required": false,
+      "description": "是否需要默认值处理"
+    }
+  ],
+  "returnType": "void",
+  "examples": [
+    {
+      "id": "simple_entity_mapping",
+      "title": "基础值映射",
+      "description": "根据当前值从列表里查找对应实体并回调给外层",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useEntity } from '@ksyun-internal/versatile';\n\nconst id = ref('cn-beijing-6a');\nconst list = ref(['cn-beijing-6a', 'cn-shanghai-2a']);\nuseEntity(id, list, (entity) => console.log(entity));\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_return_value",
+      "description": "把 useEntity 当成返回实体 Ref 的 hook 使用",
+      "wrongCode": "const entity = useEntity(id, list);",
+      "correctCode": "useEntity(id, list, (entity) => { current.value = entity; });",
+      "explanation": "该 hook 主要通过副作用回调同步值，本身不返回实体 Ref。"
+    }
+  ],
+  "searchKeywords": [
+    "useEntity",
+    "简单实体映射",
+    "id value",
+    "回调同步",
+    "基础列表",
+    "单值"
+  ]
+}

package/hooks/useEventListener.json

@@ -0,0 +1,61 @@
+{
+  "id": "useEventListener",
+  "name": "useEventListener",
+  "displayName": "事件监听封装",
+  "category": "event",
+  "description": "为 HTMLElement、window、document 或 Ref 目标统一注册事件监听，并支持 throttle、debounce 与原生 addEventListener 配置。",
+  "importStatement": "import { useEventListener } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "target",
+      "type": "HTMLElement | Window | Document | Ref<HTMLElement | null> | (() => HTMLElement | null)",
+      "required": true,
+      "description": "监听目标"
+    },
+    {
+      "name": "event",
+      "type": "string",
+      "required": true,
+      "description": "事件名"
+    },
+    {
+      "name": "handler",
+      "type": "EventListenerOrEventListenerObject",
+      "required": true,
+      "description": "事件处理函数"
+    },
+    {
+      "name": "options",
+      "type": "{ throttle?: number; debounce?: number; nativeOptions?: boolean | AddEventListenerOptions }",
+      "required": false,
+      "description": "监听配置，支持节流、防抖和原生监听选项"
+    }
+  ],
+  "returnType": "void",
+  "examples": [
+    {
+      "id": "window_resize",
+      "title": "监听窗口尺寸变化",
+      "description": "在页面中节流监听 resize 事件",
+      "code": "<script setup lang=\"ts\">\nimport { useEventListener } from '@ksyun-internal/versatile';\n\nuseEventListener(window, 'resize', () => {\n  console.log('resize');\n}, { throttle: 200 });\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "throttle_and_debounce_conflict",
+      "description": "同时配置 throttle 和 debounce，但没有明确预期",
+      "wrongCode": "useEventListener(window, 'scroll', onScroll, { throttle: 100, debounce: 100 });",
+      "correctCode": "根据场景二选一：节流滚动用 throttle，输入联想用 debounce。",
+      "explanation": "两者语义不同，建议根据业务场景明确选一种。"
+    }
+  ],
+  "searchKeywords": [
+    "useEventListener",
+    "事件监听",
+    "window resize",
+    "debounce",
+    "throttle",
+    "addEventListener"
+  ]
+}

package/hooks/useFalseUntilTruthy.json

@@ -0,0 +1,43 @@
+{
+  "id": "useFalseUntilTruthy",
+  "name": "useFalseUntilTruthy",
+  "displayName": "延迟转真布尔态",
+  "category": "state",
+  "description": "将任意响应式值映射成布尔值，并在首次变为 truthy 前始终保持 false，适合权限、异步加载完成态和懒渲染控制。",
+  "importStatement": "import { useFalseUntilTruthy } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "value",
+      "type": "MaybeRefOrGetter<any>",
+      "required": true,
+      "description": "任意响应式值、getter 或普通值"
+    }
+  ],
+  "returnType": "Readonly<Ref<boolean>>",
+  "examples": [
+    {
+      "id": "guard_render",
+      "title": "控制懒渲染",
+      "description": "在异步数据真正可用前保持 false，避免中间闪烁",
+      "code": "<script setup lang=\"ts\">\nimport { computed } from 'vue';\nimport { useFalseUntilTruthy } from '@ksyun-internal/versatile';\n\nconst dataReady = computed(() => true);\nconst canRender = useFalseUntilTruthy(dataReady);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_reset_false",
+      "description": "期望值在 truthy 之后再次回到 false",
+      "wrongCode": "const visible = useFalseUntilTruthy(flag); // 认为 flag 再次 false 时 visible 也会 false",
+      "correctCode": "如需双向切换，请直接使用 computed(() => !!flag.value)",
+      "explanation": "这个 hook 的语义是“在首次变为 truthy 前保持 false”，不是通用的布尔映射。"
+    }
+  ],
+  "searchKeywords": [
+    "useFalseUntilTruthy",
+    "false until truthy",
+    "懒渲染",
+    "加载完成",
+    "布尔态",
+    "权限准备"
+  ]
+}

package/hooks/useGetCopyAuthText.json

@@ -0,0 +1,36 @@
+{
+  "id": "useGetCopyAuthText",
+  "name": "useGetCopyAuthText",
+  "displayName": "复制授权文案",
+  "category": "auth",
+  "description": "根据服务名和策略名生成复制授权相关文案，适合复制账号权限说明或 AK/SK 授权提示。",
+  "importStatement": "import { useGetCopyAuthText } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "(serviceNames: string | Record<string, string[]>, policyName: string) => string | undefined",
+  "examples": [
+    {
+      "id": "copy_auth_text",
+      "title": "生成复制授权提示",
+      "description": "根据服务和策略名输出授权说明文案",
+      "code": "<script setup lang=\"ts\">\nimport { useGetCopyAuthText } from '@ksyun-internal/versatile';\n\nconst getCopyAuthText = useGetCopyAuthText();\nconst text = getCopyAuthText('KEC', 'KecReadOnlyAccess');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "invalid_policy_name",
+      "description": "策略名传入页面展示文案而不是实际 policyName",
+      "wrongCode": "getCopyAuthText('KEC', '云服务器只读');",
+      "correctCode": "getCopyAuthText('KEC', 'KecReadOnlyAccess');",
+      "explanation": "第二个参数应使用真实策略标识，而不是中文标题。"
+    }
+  ],
+  "searchKeywords": [
+    "useGetCopyAuthText",
+    "复制授权文案",
+    "policyName",
+    "AKSK",
+    "权限说明",
+    "授权提示"
+  ]
+}

package/hooks/useGetUserPermission.json

@@ -0,0 +1,55 @@
+{
+  "id": "useGetUserPermission",
+  "name": "useGetUserPermission",
+  "displayName": "用户权限判断",
+  "category": "auth",
+  "description": "根据用户列表和目标权限集合计算当前数据是否具备权限，适合列表操作按钮、批量操作和详情页权限门禁判断。",
+  "importStatement": "import { useGetUserPermission } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "users",
+      "type": "Ref<User[] | null | undefined>",
+      "required": true,
+      "description": "用户或授权主体列表"
+    },
+    {
+      "name": "permissions",
+      "type": "string[]",
+      "required": true,
+      "description": "目标权限编码列表"
+    },
+    {
+      "name": "key",
+      "type": "keyof User",
+      "required": false,
+      "description": "权限字段所在的属性名，不传时使用默认字段"
+    }
+  ],
+  "returnType": "ComputedRef<boolean>",
+  "examples": [
+    {
+      "id": "permission_guard",
+      "title": "控制按钮是否可操作",
+      "description": "根据用户权限列表生成可直接用于模板的布尔值",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useGetUserPermission } from '@ksyun-internal/versatile';\n\nconst users = ref([{ actions: ['instance:view', 'instance:delete'] }]);\nconst canDelete = useGetUserPermission(users, ['instance:delete'], 'actions');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "wrong_key_field",
+      "description": "传入的 key 不是权限字段，导致结果始终错误",
+      "wrongCode": "useGetUserPermission(users, ['instance:delete'], 'name');",
+      "correctCode": "useGetUserPermission(users, ['instance:delete'], 'actions');",
+      "explanation": "key 应指向用户对象中真正存放权限列表的字段。"
+    }
+  ],
+  "searchKeywords": [
+    "useGetUserPermission",
+    "权限判断",
+    "操作权限",
+    "按钮禁用",
+    "auth",
+    "permission"
+  ]
+}

package/hooks/useGroup.json

@@ -0,0 +1,49 @@
+{
+  "id": "useGroup",
+  "name": "useGroup",
+  "displayName": "数据分组映射",
+  "category": "data",
+  "description": "根据输入数据源和分组函数生成实体列表与分组结果，适合把接口返回的数据整理成按键聚合的展示结构。",
+  "importStatement": "import { useGroup } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "packages",
+      "type": "(() => P[] | undefined) | Ref<P[] | undefined>",
+      "required": true,
+      "description": "原始数据源，可传 getter 或 Ref"
+    },
+    {
+      "name": "forEach",
+      "type": "(pkg: P, fn: (key: K, data: T) => void) => void",
+      "required": true,
+      "description": "遍历函数，用于从每个数据项中提取分组 key 和实体数据"
+    }
+  ],
+  "returnType": "{ entities: Ref<T[] | undefined>; grouped: Ref<Record<K, P[]> | undefined>; }",
+  "examples": [
+    {
+      "id": "group_instances",
+      "title": "按状态分组实例列表",
+      "description": "把列表数据转换成状态分组结构，便于生成统计和分段展示",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useGroup } from '@ksyun-internal/versatile';\n\nconst packages = ref([\n  { id: '1', status: 'running', name: '实例1' },\n  { id: '2', status: 'stopped', name: '实例2' },\n]);\n\nconst { entities, grouped } = useGroup(packages, (pkg, push) => {\n  push(pkg.status, pkg);\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "forget_push",
+      "description": "forEach 中没有调用回调函数，导致 grouped 为空",
+      "wrongCode": "useGroup(packages, (pkg) => { console.log(pkg); });",
+      "correctCode": "useGroup(packages, (pkg, push) => { push(pkg.status, pkg); });",
+      "explanation": "hook 依赖回调函数收集 key 和 data，没有 push 就不会产生分组结果。"
+    }
+  ],
+  "searchKeywords": [
+    "useGroup",
+    "分组",
+    "grouped",
+    "entities",
+    "数据整理",
+    "聚合展示"
+  ]
+}

package/hooks/useIdEntities.json

@@ -0,0 +1,61 @@
+{
+  "id": "useIdEntities",
+  "name": "useIdEntities",
+  "displayName": "ID 列表映射实体列表",
+  "category": "state",
+  "description": "根据多个 ID 从实体列表中映射出对应的实体数组，适合多选组件、批量操作和多实体回显场景。",
+  "importStatement": "import { useIdEntities } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "ids",
+      "type": "Ref<(string | number)[] | undefined | null>",
+      "required": true,
+      "description": "选中的 ID 列表"
+    },
+    {
+      "name": "list",
+      "type": "Ref<Entity[] | undefined | null>",
+      "required": true,
+      "description": "实体源列表"
+    },
+    {
+      "name": "key",
+      "type": "keyof Entity",
+      "required": true,
+      "description": "用于匹配的实体主键字段"
+    },
+    {
+      "name": "emit",
+      "type": "(entity: Entity[] | undefined) => void",
+      "required": false,
+      "description": "实体数组变化时的回调"
+    }
+  ],
+  "returnType": "Ref<Entity[] | undefined>",
+  "examples": [
+    {
+      "id": "multi_select_entities",
+      "title": "多选值回显实体数组",
+      "description": "根据选中的多个 ID 计算出完整对象列表",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useIdEntities } from '@ksyun-internal/versatile';\n\nconst ids = ref(['ws-1', 'ws-2']);\nconst list = ref([\n  { WorkspaceId: 'ws-1', WorkspaceName: '工作空间1' },\n  { WorkspaceId: 'ws-2', WorkspaceName: '工作空间2' },\n]);\nconst entities = useIdEntities(ids, list, 'WorkspaceId');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "single_id_instead_of_array",
+      "description": "把单个 ID 当作 ids 传入",
+      "wrongCode": "useIdEntities(id, list, 'id');",
+      "correctCode": "useIdEntities(ids, list, 'id');",
+      "explanation": "这个 hook 面向多值场景，首参应是 ID 数组 Ref。"
+    }
+  ],
+  "searchKeywords": [
+    "useIdEntities",
+    "多选实体映射",
+    "ids",
+    "entity list",
+    "批量回显",
+    "多选"
+  ]
+}

package/hooks/useInterval.json

@@ -0,0 +1,55 @@
+{
+  "id": "useInterval",
+  "name": "useInterval",
+  "displayName": "可暂停定时器",
+  "category": "timer",
+  "description": "对 setInterval 做响应式封装，提供 pause、resume 和 isActive，适合轮询、时钟和自动刷新场景。",
+  "importStatement": "import { useInterval } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "cb",
+      "type": "() => void",
+      "required": true,
+      "description": "定时执行的回调"
+    },
+    {
+      "name": "interval",
+      "type": "MaybeRefOrGetter<number>",
+      "required": false,
+      "description": "时间间隔，默认值由上游实现决定"
+    },
+    {
+      "name": "options",
+      "type": "UseIntervalOptions",
+      "required": false,
+      "description": "定时器配置，可设置 immediate 和 immediateCallback"
+    }
+  ],
+  "returnType": "{ isActive: Readonly<ShallowRef<boolean>>; pause: () => void; resume: () => void; }",
+  "examples": [
+    {
+      "id": "auto_refresh",
+      "title": "自动刷新列表",
+      "description": "以固定间隔刷新列表数据，并可手动暂停",
+      "code": "<script setup lang=\"ts\">\nimport { useInterval } from '@ksyun-internal/versatile';\n\nconst { pause, resume, isActive } = useInterval(() => {\n  console.log('refresh');\n}, 5000, { immediate: true });\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_resume_recreate",
+      "description": "暂停后修改了 interval，却以为 resume 会自动重建旧定时器逻辑",
+      "wrongCode": "pause(); interval.value = 1000; resume();",
+      "correctCode": "确认 interval 是响应式输入，或重新创建 useInterval。",
+      "explanation": "建议明确 interval 的响应式来源，避免把它当成一次性静态参数。"
+    }
+  ],
+  "searchKeywords": [
+    "useInterval",
+    "定时器",
+    "pause",
+    "resume",
+    "自动刷新",
+    "轮询"
+  ]
+}

package/hooks/useLayoutStandardList.json

@@ -0,0 +1,36 @@
+{
+  "id": "useLayoutStandardList",
+  "name": "useLayoutStandardList",
+  "displayName": "标准列表页组合状态",
+  "category": "table",
+  "description": "为 LayoutStandardList 组合分页、搜索、分组、排序、列设置和批量操作状态，适合标准列表页快速搭建。",
+  "importStatement": "import { useLayoutStandardList } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "{ layoutStandardListRef: Ref<any>; page: Ref<number>; limit: Ref<number>; searchValue: Ref<string>; searchItems: Ref<Record<string, any> | undefined>; group: Ref<Record<string, any>>; sort: Ref<TableSortValue>; checkedKeys: Ref<string[]>; tableRef: Ref<Table | undefined>; refetch: any; loading: any; isShowDialog: Ref<boolean>; showFilterTableFieldsDialog: Function; ... }",
+  "examples": [
+    {
+      "id": "standard_list_ref",
+      "title": "标准列表页容器",
+      "description": "在 LayoutStandardList 外层持有组合状态和实例引用",
+      "code": "<script setup lang=\"ts\">\nimport { LayoutStandardList, useLayoutStandardList } from '@ksyun-internal/versatile';\n\nconst { layoutStandardListRef, page, limit, searchItems, checkedKeys } = useLayoutStandardList();\n</script>\n\n<template>\n  <LayoutStandardList ref=\"layoutStandardListRef\" :use-list=\"() => ({ loading: false, dataSource: [], total: 0 })\" />\n</template>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "duplicate_inner_hooks",
+      "description": "在 LayoutStandardList 外又重复手写 useSearch/usePagination/useTableSort，导致状态来源分裂",
+      "wrongCode": "const search = useSearch(); const pagination = usePagination(); const state = useLayoutStandardList();",
+      "correctCode": "const state = useLayoutStandardList();",
+      "explanation": "如果页面主体就是 LayoutStandardList，优先复用这个组合 hook。"
+    }
+  ],
+  "searchKeywords": [
+    "useLayoutStandardList",
+    "LayoutStandardList",
+    "标准列表页",
+    "分页 搜索 排序",
+    "批量操作",
+    "表格组合状态"
+  ]
+}

package/hooks/useMessage.json

@@ -0,0 +1,73 @@
+{
+  "id": "useMessage",
+  "name": "useMessage",
+  "displayName": "变更消息反馈",
+  "category": "feedback",
+  "description": "为 Apollo mutation 封装统一的成功/失败消息处理逻辑，适合删除、编辑、创建等需要标准化提示文案的请求场景。",
+  "importStatement": "import { useMessage } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "onError",
+      "type": "UseMutationReturn<TResult, TVariables>['onError']",
+      "required": true,
+      "description": "mutation 返回的错误监听函数"
+    },
+    {
+      "name": "onDone",
+      "type": "UseMutationReturn<TResult, TVariables>['onDone']",
+      "required": false,
+      "description": "mutation 返回的完成监听函数"
+    },
+    {
+      "name": "isSuccess",
+      "type": "(res: FetchResult<TResult>) => boolean",
+      "required": false,
+      "description": "自定义成功判定逻辑"
+    },
+    {
+      "name": "action",
+      "type": "string | (() => string)",
+      "required": false,
+      "description": "操作名称，用于生成成功/失败提示文案"
+    },
+    {
+      "name": "successCallback",
+      "type": "(res: FetchResult<TResult>) => any",
+      "required": false,
+      "description": "成功后的额外回调"
+    },
+    {
+      "name": "failedCallback",
+      "type": "(e: Error) => any",
+      "required": false,
+      "description": "失败后的额外回调"
+    }
+  ],
+  "returnType": "void",
+  "examples": [
+    {
+      "id": "mutation_feedback",
+      "title": "统一处理 mutation 提示",
+      "description": "把创建、删除等 mutation 的消息提示收口到 hook",
+      "code": "<script setup lang=\"ts\">\nimport { useMutation } from '@vue/apollo-composable';\nimport { useMessage } from '@ksyun-internal/versatile';\n\nconst { onError, onDone } = useMutation(CREATE_INSTANCE);\nuseMessage(onError, onDone, undefined, '创建实例');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "no_success_judge",
+      "description": "接口返回结构不是标准成功态，但没有传 isSuccess，自定义失败被当成成功",
+      "wrongCode": "useMessage(onError, onDone, undefined, '删除');",
+      "correctCode": "useMessage(onError, onDone, (res) => res.data?.delete?.code === 200, '删除');",
+      "explanation": "如果后端不是默认成功结构，建议显式提供 isSuccess。"
+    }
+  ],
+  "searchKeywords": [
+    "useMessage",
+    "mutation 提示",
+    "apollo",
+    "成功失败消息",
+    "toast",
+    "反馈"
+  ]
+}

package/hooks/useModifyCache.json

@@ -0,0 +1,36 @@
+{
+  "id": "useModifyCache",
+  "name": "useModifyCache",
+  "displayName": "Apollo 缓存修改",
+  "category": "data",
+  "description": "返回一个可复用的 Apollo cache.modify 封装函数，适合在 mutation 后局部更新缓存而不重新发请求。",
+  "importStatement": "import { useModifyCache } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "(identify: StoreObject | Reference, fields: Cache.ModifyOptions['fields']) => void",
+  "examples": [
+    {
+      "id": "apollo_modify_cache",
+      "title": "局部更新 Apollo 缓存",
+      "description": "在删除或编辑成功后直接修改缓存字段",
+      "code": "<script setup lang=\"ts\">\nimport { useModifyCache } from '@ksyun-internal/versatile';\n\nconst modifyCache = useModifyCache();\nmodifyCache({ __typename: 'Instance', id: 'ins-1' }, {\n  name: () => 'new-name',\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "invalid_identify",
+      "description": "identify 对象缺少 Apollo 可识别的标识字段",
+      "wrongCode": "modifyCache({ name: 'instance-1' }, { status: () => 'running' });",
+      "correctCode": "modifyCache({ __typename: 'Instance', id: 'ins-1' }, { status: () => 'running' });",
+      "explanation": "identify 需要能让 Apollo 唯一定位缓存实体。"
+    }
+  ],
+  "searchKeywords": [
+    "useModifyCache",
+    "apollo cache",
+    "cache.modify",
+    "mutation",
+    "局部更新缓存",
+    "graphql"
+  ]
+}