king-design-analyzer 2.1.9 → 2.2.0

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"
+  ]
+}

package/hooks/useOpenDialog.json

@@ -0,0 +1,43 @@
+{
+  "id": "useOpenDialog",
+  "name": "useOpenDialog",
+  "displayName": "表格操作弹窗",
+  "category": "dialog",
+  "description": "针对表格单行操作和批量操作封装弹窗打开逻辑，统一维护当前操作项和批量操作项集合。",
+  "importStatement": "import { useOpenDialog } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "tableRef",
+      "type": "Ref<Table | undefined>",
+      "required": false,
+      "description": "表格实例引用，批量操作时可从表格中读取选中项"
+    }
+  ],
+  "returnType": "{ isShowDialog: Ref<boolean>; dialogRef: Ref<any>; opCols: Ref<T[] | undefined>; opCol: Ref<T | undefined>; show: Function; hide: Function; handleClickOpBtn: Function; handleClickBatchOpBtn: Function; }",
+  "examples": [
+    {
+      "id": "table_op_dialog",
+      "title": "表格操作弹窗",
+      "description": "点击单行操作按钮时打开弹窗并记录当前行数据",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useOpenDialog } from '@ksyun-internal/versatile';\n\nconst tableRef = ref();\nconst { isShowDialog, opCol, handleClickOpBtn } = useOpenDialog(tableRef);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_table_ref",
+      "description": "批量操作场景未传入 tableRef，导致无法读取选中项",
+      "wrongCode": "const dialog = useOpenDialog();",
+      "correctCode": "const dialog = useOpenDialog(tableRef);",
+      "explanation": "如果需要 handleClickBatchOpBtn 读取表格选中项，应传入 tableRef。"
+    }
+  ],
+  "searchKeywords": [
+    "useOpenDialog",
+    "批量操作",
+    "表格操作",
+    "dialog",
+    "单行操作",
+    "tableRef"
+  ]
+}

package/hooks/usePagination.json

@@ -0,0 +1,49 @@
+{
+  "id": "usePagination",
+  "name": "usePagination",
+  "displayName": "分页状态管理",
+  "category": "pagination",
+  "description": "管理列表页常用的 page、limit、limits 以及分页变更回调，适合和 ProTable、PaginationPlus、Search 组合使用。",
+  "importStatement": "import { usePagination } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "options",
+      "type": "{ page?: number; limit?: number; limits?: number[]; callback?: (v: PaginationChangeData) => void }",
+      "required": false,
+      "description": "分页初始化配置，可预设页码、每页条数、可选 limits 及翻页后的回调"
+    }
+  ],
+  "returnType": "{ page: Ref<number>; limit: Ref<number>; limits: Ref<number[]>; pageChange: (pageParams: PaginationChangeData) => void; }",
+  "examples": [
+    {
+      "id": "basic_pagination",
+      "title": "基础分页用法",
+      "description": "通过 hook 统一管理列表页码和每页条数",
+      "code": "<script setup lang=\"ts\">\nimport { PaginationPlus, usePagination } from '@ksyun-internal/versatile';\n\nconst { page, limit, pageChange } = usePagination({\n  page: 1,\n  limit: 20,\n});\n</script>\n\n<template>\n  <PaginationPlus v-model=\"page\" v-model:limit=\"limit\" :total=\"200\" @change=\"pageChange\" />\n</template>"
+    },
+    {
+      "id": "with_callback",
+      "title": "带回调的分页",
+      "description": "在分页变化后触发数据刷新或埋点逻辑",
+      "code": "<script setup lang=\"ts\">\nimport { usePagination } from '@ksyun-internal/versatile';\n\nconst fetchList = () => console.log('reload');\nconst { page, limit, pageChange } = usePagination({\n  callback: () => fetchList(),\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "forget_limit_binding",
+      "description": "只绑定 page，没有同步维护 limit",
+      "wrongCode": "const { page } = usePagination();",
+      "correctCode": "const { page, limit } = usePagination();",
+      "explanation": "如果页面支持切换每页条数，应同时使用 hook 返回的 limit。"
+    }
+  ],
+  "searchKeywords": [
+    "usePagination",
+    "分页",
+    "page",
+    "limit",
+    "PaginationPlus",
+    "列表页"
+  ]
+}

package/hooks/usePersist.json

@@ -0,0 +1,61 @@
+{
+  "id": "usePersist",
+  "name": "usePersist",
+  "displayName": "本地持久化",
+  "category": "state",
+  "description": "将响应式数据持久化到 localStorage 或 sessionStorage，适合保存列表筛选、用户偏好和表格配置。",
+  "importStatement": "import { usePersist } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "key",
+      "type": "string",
+      "required": true,
+      "description": "存储键名"
+    },
+    {
+      "name": "defaultValue",
+      "type": "T",
+      "required": true,
+      "description": "初始化默认值"
+    },
+    {
+      "name": "options",
+      "type": "PersistOptions<T>",
+      "required": false,
+      "description": "持久化配置，可切换 storage、自定义序列化和 watch 行为"
+    }
+  ],
+  "returnType": "Ref<T>",
+  "examples": [
+    {
+      "id": "persist_table_fields",
+      "title": "持久化表格配置",
+      "description": "保存用户的列显隐或筛选配置",
+      "code": "<script setup lang=\"ts\">\nimport { usePersist } from '@ksyun-internal/versatile';\n\nconst tableFields = usePersist('table-fields', ['name', 'status']);\n</script>"
+    },
+    {
+      "id": "session_storage",
+      "title": "使用 sessionStorage",
+      "description": "仅在当前会话内保留搜索状态",
+      "code": "<script setup lang=\"ts\">\nimport { usePersist } from '@ksyun-internal/versatile';\n\nconst searchState = usePersist('instance-search', { key: 'name', value: '' }, {\n  storage: sessionStorage,\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "unstable_key",
+      "description": "使用会变化的 key，导致同一份状态被重复写入",
+      "wrongCode": "usePersist(`table-${Date.now()}`, []);",
+      "correctCode": "usePersist('instance-table-fields', []);",
+      "explanation": "key 应保持稳定，否则无法复用持久化结果。"
+    }
+  ],
+  "searchKeywords": [
+    "usePersist",
+    "localStorage",
+    "sessionStorage",
+    "持久化",
+    "列表偏好",
+    "缓存状态"
+  ]
+}

package/hooks/usePoll.json

@@ -0,0 +1,43 @@
+{
+  "id": "usePoll",
+  "name": "usePoll",
+  "displayName": "查询轮询",
+  "category": "data",
+  "description": "包装 Apollo 查询结果并启用轮询场景，适合在列表页、详情页中持续刷新接口数据。",
+  "importStatement": "import { usePoll } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "result",
+      "type": "UseQueryReturn<any, any>",
+      "required": true,
+      "description": "Apollo useQuery 返回的查询对象"
+    }
+  ],
+  "returnType": "UseQueryReturn<any, any>",
+  "examples": [
+    {
+      "id": "apollo_poll",
+      "title": "轮询查询结果",
+      "description": "对 useQuery 返回值启用轮询式刷新",
+      "code": "<script setup lang=\"ts\">\nimport { useQuery } from '@vue/apollo-composable';\nimport { usePoll } from '@ksyun-internal/versatile';\n\nconst queryResult = useQuery(GET_INSTANCE_LIST);\nconst pollResult = usePoll(queryResult);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "non_query_result",
+      "description": "传入普通 Promise 或自定义对象而不是 Apollo 查询返回值",
+      "wrongCode": "const result = usePoll(fetchList());",
+      "correctCode": "const result = usePoll(useQuery(GET_LIST));",
+      "explanation": "usePoll 依赖 Apollo 的 UseQueryReturn 结构。"
+    }
+  ],
+  "searchKeywords": [
+    "usePoll",
+    "轮询",
+    "apollo",
+    "useQuery",
+    "自动刷新",
+    "列表轮询"
+  ]
+}

package/hooks/useRoutePlus.json

@@ -0,0 +1,36 @@
+{
+  "id": "useRoutePlus",
+  "name": "useRoutePlus",
+  "displayName": "增强路由读取",
+  "category": "router",
+  "description": "对 vue-router 的 route 做包装，直接返回 params、query 及其 refs，便于在组合式函数中按字段响应式使用。",
+  "importStatement": "import { useRoutePlus } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "{ $route: RouteLocationNormalizedLoadedGeneric; params: Record<string, string>; paramRefs: ToRefs<Record<string, string>>; query: LocationQuery; queryRefs: ToRefs<LocationQuery>; }",
+  "examples": [
+    {
+      "id": "route_params",
+      "title": "读取详情页路由参数",
+      "description": "把详情页 id 和 query 参数拆成可直接使用的 refs",
+      "code": "<script setup lang=\"ts\">\nimport { useRoutePlus } from '@ksyun-internal/versatile';\n\nconst { params, paramRefs, queryRefs } = useRoutePlus();\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_writeback",
+      "description": "直接修改 paramRefs/queryRefs，期望同步改写路由地址",
+      "wrongCode": "paramRefs.id.value = '2';",
+      "correctCode": "如需跳转，请配合 useRouterPlus 或 router.push。",
+      "explanation": "这个 hook 主要用于读取路由状态，不负责写回 URL。"
+    }
+  ],
+  "searchKeywords": [
+    "useRoutePlus",
+    "route params",
+    "query refs",
+    "vue-router",
+    "详情页参数",
+    "路由读取"
+  ]
+}

package/hooks/useRouterPlus.json

@@ -0,0 +1,36 @@
+{
+  "id": "useRouterPlus",
+  "name": "useRouterPlus",
+  "displayName": "增强路由跳转",
+  "category": "router",
+  "description": "对 vue-router 的导航能力做统一封装，提供新开页签跳转和可回退的导航能力。",
+  "importStatement": "import { useRouterPlus } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "{ $router: Router; goNewPage: (to: string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric, currentLocation?: RouteLocationNormalizedLoadedGeneric) => void; goBack: (back?: string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric) => void; }",
+  "examples": [
+    {
+      "id": "go_detail_page",
+      "title": "跳转详情页或新页签打开",
+      "description": "在列表页操作列中统一处理跳转行为",
+      "code": "<script setup lang=\"ts\">\nimport { useRouterPlus } from '@ksyun-internal/versatile';\n\nconst { goNewPage, goBack } = useRouterPlus();\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_back_fallback",
+      "description": "调用 goBack 但没有提供兜底地址，历史栈不足时体验不稳定",
+      "wrongCode": "goBack();",
+      "correctCode": "goBack({ name: 'instance-list' });",
+      "explanation": "在业务列表/详情页之间跳转时，建议提供明确回退目标。"
+    }
+  ],
+  "searchKeywords": [
+    "useRouterPlus",
+    "goNewPage",
+    "goBack",
+    "路由跳转",
+    "新开页签",
+    "vue-router"
+  ]
+}

package/hooks/useSearch.json

@@ -0,0 +1,56 @@
+{
+  "id": "useSearch",
+  "name": "useSearch",
+  "displayName": "搜索状态管理",
+  "category": "search",
+  "description": "管理 Search 和 SearchItems 常用的搜索状态，统一维护 searchKey、searchValue、searchItems 及其变更方法。配合列表页分页时可在筛选变化后重置页码。",
+  "importStatement": "import { useSearch } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "options",
+      "type": "{ defaultSearchKey?: string; page?: Ref<number> }",
+      "required": false,
+      "description": "初始化配置，可指定默认搜索字段，并传入分页页码以便搜索变化时联动重置"
+    }
+  ],
+  "returnType": "{ searchKey: Ref<string>; searchKeyRela: Ref<string>; searchValue: Ref<string>; searchItems: Ref<T | undefined>; searchItemsRef: Ref<any>; handleChangeSearchValue: Function; handleChangeSingleValue: Function; handleChangeSearchSingleValue: Function; }",
+  "examples": [
+    {
+      "id": "list_search",
+      "title": "列表页搜索状态",
+      "description": "在列表页中统一维护搜索 key、搜索值和搜索项",
+      "code": "<script setup lang=\"ts\">\nimport { Search, SearchItems, usePagination, useSearch } from '@ksyun-internal/versatile';\n\nconst { page } = usePagination();\nconst { searchKey, searchValue, searchItems } = useSearch({\n  defaultSearchKey: 'name',\n  page,\n});\n</script>\n\n<template>\n  <Search v-model:search-key=\"searchKey\" v-model:search-value=\"searchValue\" :searches=\"[]\" />\n  <SearchItems v-model=\"searchItems\" />\n</template>"
+    },
+    {
+      "id": "search_callback",
+      "title": "手动处理搜索值变更",
+      "description": "通过返回的方法接管批量搜索或单值搜索的更新逻辑",
+      "code": "<script setup lang=\"ts\">\nimport { useSearch } from '@ksyun-internal/versatile';\n\nconst { handleChangeSearchValue } = useSearch();\n\nconst onSearch = (value?: string) => {\n  handleChangeSearchValue(value, value);\n};\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_page_link",
+      "description": "列表页搜索变化时没有传入 page，导致筛选后仍停留在旧页码",
+      "wrongCode": "const search = useSearch();",
+      "correctCode": "const search = useSearch({ page });",
+      "explanation": "在分页列表中建议把 page 传给 useSearch，让搜索条件变化时同步回到第一页。"
+    },
+    {
+      "id": "manual_duplicate_state",
+      "description": "重复自己维护 searchKey/searchValue，和 hook 返回值并存",
+      "wrongCode": "const searchKey = ref('name'); const searchValue = ref(''); const { searchItems } = useSearch();",
+      "correctCode": "const { searchKey, searchValue, searchItems } = useSearch({ defaultSearchKey: 'name' });",
+      "explanation": "优先使用 useSearch 返回的整套状态，避免来源分裂。"
+    }
+  ],
+  "searchKeywords": [
+    "useSearch",
+    "Search",
+    "SearchItems",
+    "列表筛选",
+    "搜索状态",
+    "检索条件"
+  ]
+}

package/hooks/useShell.json

@@ -0,0 +1,49 @@
+{
+  "id": "useShell",
+  "name": "useShell",
+  "displayName": "Shell 内容挂载",
+  "category": "dialog",
+  "description": "在弹窗显示时把 shell 或命令内容挂载到指定容器引用，适合命令预览、终端输出展示等场景。",
+  "importStatement": "import { useShell } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "content",
+      "type": "WatchSource<string | undefined | null>",
+      "required": true,
+      "description": "需要展示的 shell 内容"
+    },
+    {
+      "name": "isShowDialog",
+      "type": "Ref<boolean>",
+      "required": true,
+      "description": "弹窗显隐状态"
+    }
+  ],
+  "returnType": "{ shellRef: Ref<any> }",
+  "examples": [
+    {
+      "id": "shell_dialog",
+      "title": "命令预览弹窗",
+      "description": "在弹窗打开时渲染命令或脚本内容",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useShell } from '@ksyun-internal/versatile';\n\nconst content = ref('kubectl get pods');\nconst isShowDialog = ref(false);\nconst { shellRef } = useShell(content, isShowDialog);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "content_not_watch_source",
+      "description": "传入一次性字符串字面量，后续更新不会同步",
+      "wrongCode": "useShell('kubectl get pods', isShowDialog);",
+      "correctCode": "const content = ref('kubectl get pods'); useShell(content, isShowDialog);",
+      "explanation": "内容建议使用 Ref 或 getter，便于后续更新时同步渲染。"
+    }
+  ],
+  "searchKeywords": [
+    "useShell",
+    "shell",
+    "命令预览",
+    "dialog content",
+    "终端输出",
+    "shellRef"
+  ]
+}

package/hooks/useSkip.json

@@ -0,0 +1,43 @@
+{
+  "id": "useSkip",
+  "name": "useSkip",
+  "displayName": "头部返回跳转",
+  "category": "router",
+  "description": "从 Header 的 back 配置中提取统一跳转逻辑，适合详情页和购买链路页的返回按钮行为。",
+  "importStatement": "import { useSkip } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "back",
+      "type": "Ref<LayoutHeaderProps['back']>",
+      "required": true,
+      "description": "Header 的 back 配置项"
+    }
+  ],
+  "returnType": "{ goLink: () => any }",
+  "examples": [
+    {
+      "id": "header_back",
+      "title": "Header 返回按钮",
+      "description": "复用 Header back 配置实现统一返回跳转",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useSkip } from '@ksyun-internal/versatile';\n\nconst back = ref({ to: { name: 'instance-list' } });\nconst { goLink } = useSkip(back);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "plain_object_back",
+      "description": "直接传普通对象而不是 Ref，导致 back 配置变化无法联动",
+      "wrongCode": "useSkip({ to: { name: 'list' } });",
+      "correctCode": "const back = ref({ to: { name: 'list' } }); useSkip(back);",
+      "explanation": "hook 设计为消费 Header back 的响应式配置。"
+    }
+  ],
+  "searchKeywords": [
+    "useSkip",
+    "Header back",
+    "返回跳转",
+    "详情页返回",
+    "goLink",
+    "layout header"
+  ]
+}

package/hooks/useStorageIdEntity.json

@@ -0,0 +1,67 @@
+{
+  "id": "useStorageIdEntity",
+  "name": "useStorageIdEntity",
+  "displayName": "带存储的 ID 实体映射",
+  "category": "state",
+  "description": "在 useIdEntity 的基础上增加存储键能力，适合把当前选中的实体 ID 与本地缓存联动，支持刷新后恢复选择。",
+  "importStatement": "import { useStorageIdEntity } 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<Entity[] | undefined | null>",
+      "required": true,
+      "description": "实体源列表"
+    },
+    {
+      "name": "key",
+      "type": "keyof Entity",
+      "required": true,
+      "description": "实体主键字段"
+    },
+    {
+      "name": "storageName",
+      "type": "string",
+      "required": false,
+      "description": "本地存储使用的键名"
+    },
+    {
+      "name": "emit",
+      "type": "(entity: Entity | undefined) => void",
+      "required": false,
+      "description": "实体变化时的回调"
+    }
+  ],
+  "returnType": "Ref<Entity | undefined>",
+  "examples": [
+    {
+      "id": "remember_selected_workspace",
+      "title": "记住上次选择的实体",
+      "description": "页面刷新后仍恢复用户上次选择的对象",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useStorageIdEntity } from '@ksyun-internal/versatile';\n\nconst selectedId = ref('ws-001');\nconst workspaceList = ref([{ WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' }]);\nconst currentWorkspace = useStorageIdEntity(selectedId, workspaceList, 'WorkspaceId', 'workspace-id');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "shared_storage_name",
+      "description": "多个页面复用同一个 storageName，导致选择串数据",
+      "wrongCode": "useStorageIdEntity(id, list, 'id', 'selected-id');",
+      "correctCode": "useStorageIdEntity(id, list, 'id', 'instance-workspace-id');",
+      "explanation": "storageName 建议按业务域区分，避免不同页面互相覆盖。"
+    }
+  ],
+  "searchKeywords": [
+    "useStorageIdEntity",
+    "本地记忆选择",
+    "storage",
+    "实体映射",
+    "刷新恢复",
+    "workspace"
+  ]
+}