king-design-analyzer 2.1.9 → 2.2.1

package/docs_for_llm/useRouterPlus.doc.md

@@ -0,0 +1,34 @@
+# 增强路由跳转 (useRouterPlus)
+
+对 vue-router 的导航能力做统一封装，提供新开页签跳转和可回退的导航能力。
+
+**关键词**: useRouterPlus, goNewPage, goBack, 路由跳转, 新开页签, vue-router
+
+## 导入语句
+```typescript
+import { useRouterPlus } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+{ $router: Router; goNewPage: (to: string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric, currentLocation?: RouteLocationNormalizedLoadedGeneric) => void; goBack: (back?: string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric) => void; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 调用 goBack 但没有提供兜底地址，历史栈不足时体验不稳定
+> **错误用法**: `goBack();`
+> **正确写法**: `goBack({ name: 'instance-list' });`
+> **说明**: 在业务列表/详情页之间跳转时，建议提供明确回退目标。
+
+## 使用示例
+### 跳转详情页或新页签打开
+在列表页操作列中统一处理跳转行为
+
+```vue
+<script setup lang="ts">
+import { useRouterPlus } from '@ksyun-internal/versatile';
+
+const { goNewPage, goBack } = useRouterPlus();
+</script>
+```
+

package/docs_for_llm/useSearch.doc.md

@@ -0,0 +1,68 @@
+# 搜索状态管理 (useSearch)
+
+管理 Search 和 SearchItems 常用的搜索状态，统一维护 searchKey、searchValue、searchItems 及其变更方法。配合列表页分页时可在筛选变化后重置页码。
+
+**关键词**: useSearch, Search, SearchItems, 列表筛选, 搜索状态, 检索条件
+
+## 导入语句
+```typescript
+import { useSearch } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ defaultSearchKey?: string; page?: Ref<number> }` | 否 | 初始化配置，可指定默认搜索字段，并传入分页页码以便搜索变化时联动重置 |
+
+## 返回值
+```typescript
+{ searchKey: Ref<string>; searchKeyRela: Ref<string>; searchValue: Ref<string>; searchItems: Ref<T | undefined>; searchItemsRef: Ref<any>; handleChangeSearchValue: Function; handleChangeSingleValue: Function; handleChangeSearchSingleValue: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 列表页搜索变化时没有传入 page，导致筛选后仍停留在旧页码
+> **错误用法**: `const search = useSearch();`
+> **正确写法**: `const search = useSearch({ page });`
+> **说明**: 在分页列表中建议把 page 传给 useSearch，让搜索条件变化时同步回到第一页。
+
+### 重复自己维护 searchKey/searchValue，和 hook 返回值并存
+> **错误用法**: `const searchKey = ref('name'); const searchValue = ref(''); const { searchItems } = useSearch();`
+> **正确写法**: `const { searchKey, searchValue, searchItems } = useSearch({ defaultSearchKey: 'name' });`
+> **说明**: 优先使用 useSearch 返回的整套状态，避免来源分裂。
+
+## 使用示例
+### 列表页搜索状态
+在列表页中统一维护搜索 key、搜索值和搜索项
+
+```vue
+<script setup lang="ts">
+import { Search, SearchItems, usePagination, useSearch } from '@ksyun-internal/versatile';
+
+const { page } = usePagination();
+const { searchKey, searchValue, searchItems } = useSearch({
+  defaultSearchKey: 'name',
+  page,
+});
+</script>
+
+<template>
+  <Search v-model:search-key="searchKey" v-model:search-value="searchValue" :searches="[]" />
+  <SearchItems v-model="searchItems" />
+</template>
+```
+
+### 手动处理搜索值变更
+通过返回的方法接管批量搜索或单值搜索的更新逻辑
+
+```vue
+<script setup lang="ts">
+import { useSearch } from '@ksyun-internal/versatile';
+
+const { handleChangeSearchValue } = useSearch();
+
+const onSearch = (value?: string) => {
+  handleChangeSearchValue(value, value);
+};
+</script>
+```
+

package/docs_for_llm/useShell.doc.md

@@ -0,0 +1,43 @@
+# Shell 内容挂载 (useShell)
+
+在弹窗显示时把 shell 或命令内容挂载到指定容器引用，适合命令预览、终端输出展示等场景。
+
+**关键词**: useShell, shell, 命令预览, dialog content, 终端输出, shellRef
+
+## 导入语句
+```typescript
+import { useShell } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| content | `WatchSource<string | undefined | null>` | 是 | 需要展示的 shell 内容 |
+| isShowDialog | `Ref<boolean>` | 是 | 弹窗显隐状态 |
+
+## 返回值
+```typescript
+{ shellRef: Ref<any> }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 传入一次性字符串字面量，后续更新不会同步
+> **错误用法**: `useShell('kubectl get pods', isShowDialog);`
+> **正确写法**: `const content = ref('kubectl get pods'); useShell(content, isShowDialog);`
+> **说明**: 内容建议使用 Ref 或 getter，便于后续更新时同步渲染。
+
+## 使用示例
+### 命令预览弹窗
+在弹窗打开时渲染命令或脚本内容
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useShell } from '@ksyun-internal/versatile';
+
+const content = ref('kubectl get pods');
+const isShowDialog = ref(false);
+const { shellRef } = useShell(content, isShowDialog);
+</script>
+```
+

package/docs_for_llm/useSkip.doc.md

@@ -0,0 +1,41 @@
+# 头部返回跳转 (useSkip)
+
+从 Header 的 back 配置中提取统一跳转逻辑，适合详情页和购买链路页的返回按钮行为。
+
+**关键词**: useSkip, Header back, 返回跳转, 详情页返回, goLink, layout header
+
+## 导入语句
+```typescript
+import { useSkip } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| back | `Ref<LayoutHeaderProps['back']>` | 是 | Header 的 back 配置项 |
+
+## 返回值
+```typescript
+{ goLink: () => any }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接传普通对象而不是 Ref，导致 back 配置变化无法联动
+> **错误用法**: `useSkip({ to: { name: 'list' } });`
+> **正确写法**: `const back = ref({ to: { name: 'list' } }); useSkip(back);`
+> **说明**: hook 设计为消费 Header back 的响应式配置。
+
+## 使用示例
+### Header 返回按钮
+复用 Header back 配置实现统一返回跳转
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useSkip } from '@ksyun-internal/versatile';
+
+const back = ref({ to: { name: 'instance-list' } });
+const { goLink } = useSkip(back);
+</script>
+```
+

package/docs_for_llm/useStorageIdEntity.doc.md

@@ -0,0 +1,46 @@
+# 带存储的 ID 实体映射 (useStorageIdEntity)
+
+在 useIdEntity 的基础上增加存储键能力，适合把当前选中的实体 ID 与本地缓存联动，支持刷新后恢复选择。
+
+**关键词**: useStorageIdEntity, 本地记忆选择, storage, 实体映射, 刷新恢复, workspace
+
+## 导入语句
+```typescript
+import { useStorageIdEntity } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id | `Ref<string | number | undefined | null>` | 是 | 当前选中的实体 ID |
+| list | `Ref<Entity[] | undefined | null>` | 是 | 实体源列表 |
+| key | `keyof Entity` | 是 | 实体主键字段 |
+| storageName | `string` | 否 | 本地存储使用的键名 |
+| emit | `(entity: Entity | undefined) => void` | 否 | 实体变化时的回调 |
+
+## 返回值
+```typescript
+Ref<Entity | undefined>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 多个页面复用同一个 storageName，导致选择串数据
+> **错误用法**: `useStorageIdEntity(id, list, 'id', 'selected-id');`
+> **正确写法**: `useStorageIdEntity(id, list, 'id', 'instance-workspace-id');`
+> **说明**: storageName 建议按业务域区分，避免不同页面互相覆盖。
+
+## 使用示例
+### 记住上次选择的实体
+页面刷新后仍恢复用户上次选择的对象
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useStorageIdEntity } from '@ksyun-internal/versatile';
+
+const selectedId = ref('ws-001');
+const workspaceList = ref([{ WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' }]);
+const currentWorkspace = useStorageIdEntity(selectedId, workspaceList, 'WorkspaceId', 'workspace-id');
+</script>
+```
+

package/docs_for_llm/useStore.doc.md

@@ -0,0 +1,34 @@
+# 轻量全局状态 (useStore)
+
+读取和写入 versatile 内部维护的轻量全局状态，当前暴露地域 key 和地域列表的读写能力。
+
+**关键词**: useStore, regionKey, regionList, 全局状态, 地域缓存, 共享状态
+
+## 导入语句
+```typescript
+import { useStore } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+{ setRegionKey: (regionKey: string) => void; setRegionList: (regionList: any[]) => void; regionKey: ComputedRef<string>; regionList: ComputedRef<any[]>; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接修改 regionList/regionKey，而不是走 setter
+> **错误用法**: `regionKey.value = 'cn-beijing-6';`
+> **正确写法**: `setRegionKey('cn-beijing-6');`
+> **说明**: 返回的状态是 computed，只读修改应通过 setter 完成。
+
+## 使用示例
+### 共享地域状态
+在 Region、AZ 或购买页中共享当前地域选择
+
+```vue
+<script setup lang="ts">
+import { useStore } from '@ksyun-internal/versatile';
+
+const { regionKey, regionList, setRegionKey, setRegionList } = useStore();
+</script>
+```
+

package/docs_for_llm/useTable.doc.md

@@ -0,0 +1,57 @@
+# 表格状态管理 (useTable)
+
+集中管理表格勾选、展开、列显隐和导出相关状态，适合原子 Table 和业务表格容器共享同一套表格控制逻辑。
+
+**关键词**: useTable, Table, 勾选状态, 列显隐, 导出表格, rowKey
+
+## 导入语句
+```typescript
+import { useTable } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ rowKey?: string; notCheckTip?: string; tableFields?: TableFields }` | 否 | 表格配置，可指定 rowKey、未勾选提示文案和列配置定义 |
+
+## 返回值
+```typescript
+{ checkedKeys: Ref<string[]>; expandedKeys: Ref<(string | number)[]>; isChecked: ComputedRef<number>; canCheck: ComputedRef<{ disabled: boolean; msg: string }>; tableRef: Ref<Table | undefined>; componentRef: Ref<any>; noCheckedColFields: Ref<string[]>; setRowKey: Function; exportTableData: Function; hideCol: Function; getTableColTitle: ((key: string) => string) | null; initTableColumnProps: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 多选或导出场景没有稳定 rowKey，导致勾选数据不稳定
+> **错误用法**: `const table = useTable();`
+> **正确写法**: `const table = useTable({ rowKey: 'id' });`
+> **说明**: 在业务表格中建议显式指定 rowKey，避免勾选项和导出数据映射错乱。
+
+## 使用示例
+### 管理表格勾选和列显隐
+在列表页中集中维护勾选状态和动态列配置
+
+```vue
+<script setup lang="ts">
+import { useTable } from '@ksyun-internal/versatile';
+
+const tableFields = [
+  { key: 'name', label: '实例名称', checked: true },
+  { key: 'status', label: '状态', checked: true },
+];
+const { checkedKeys, tableRef, canCheck, initTableColumnProps } = useTable({
+  rowKey: 'id',
+  tableFields,
+});
+</script>
+```
+
+### 导出当前表格数据
+通过 hook 暴露的导出方法触发表格导出
+
+```vue
+<script setup lang="ts">
+import { useTable } from '@ksyun-internal/versatile';
+
+const { exportTableData } = useTable({ rowKey: 'id' });
+</script>
+```
+

package/docs_for_llm/useTableGroup.doc.md

@@ -0,0 +1,47 @@
+# 表格分组筛选状态 (useTableGroup)
+
+管理 Table 或 ProTable 的 group 筛选状态，并可与 SearchItems 联动生成可展示的筛选项。
+
+**关键词**: useTableGroup, group, ProTable, 表格筛选, SearchItems, 状态分组
+
+## 导入语句
+```typescript
+import { useTableGroup } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ page?: Ref<number>; key?: string; defalutValue?: any; searchItemsRef?: Ref<any>; labelMaps?: Record<string, string> | Ref<Record<string, string>>; groupLabel?: string | Record<string, string | { label: string }>; isShowSearchItem?: boolean }` | 否 | 分组筛选配置，可联动分页、SearchItems 和字段标签映射 |
+
+## 返回值
+```typescript
+{ status: ComputedRef<any>; group: Ref<Record<string, any>>; resetGroup: Function; changeGroup: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### SearchItems 展示 group 条件时没有提供 labelMaps 或 groupLabel
+> **错误用法**: `useTableGroup({ searchItemsRef });`
+> **正确写法**: `useTableGroup({ searchItemsRef, labelMaps, groupLabel: '状态' });`
+> **说明**: 如果要把 group 同步到 SearchItems，建议补齐展示文案映射。
+
+## 使用示例
+### 配合 ProTable 的 group 筛选
+将 group 状态和 SearchItems 联动，统一驱动表格筛选
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { usePagination, useTableGroup } from '@ksyun-internal/versatile';
+
+const { page } = usePagination();
+const searchItemsRef = ref();
+const { group, changeGroup, resetGroup } = useTableGroup({
+  page,
+  key: 'status',
+  searchItemsRef,
+  labelMaps: { using: '运行中', shutdown: '已关机' },
+});
+</script>
+```
+

package/docs_for_llm/useTableSort.doc.md

@@ -0,0 +1,40 @@
+# 表格排序状态 (useTableSort)
+
+统一管理表格排序字段和方向，并提供多种派生排序状态，适合请求参数、UI 高亮和布尔/整数映射场景。
+
+**关键词**: useTableSort, 排序, TableSortValue, ProTable, 列表排序, sort
+
+## 导入语句
+```typescript
+import { useTableSort } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| page | `Ref<number | undefined>` | 否 | 分页页码，传入后在切换排序时可联动重置页码 |
+
+## 返回值
+```typescript
+{ sort: Ref<TableSortValue>; curSortKey: ComputedRef<string | undefined>; curSortType: ComputedRef<'desc' | 'asc' | undefined>; curSortTypeByInt: ComputedRef<0 | 1 | -1>; curSortTypeByBoolean: ComputedRef<boolean | ''>; changeSort: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 自己维护 asc/desc 和 0/1/-1 的映射，重复实现 hook 已有能力
+> **错误用法**: `const sortType = computed(() => sort.value.type === 'asc' ? 1 : -1);`
+> **正确写法**: `const { curSortTypeByInt } = useTableSort(page);`
+> **说明**: hook 已经提供多种派生排序表示，优先复用。
+
+## 使用示例
+### 列表排序状态
+将排序状态集中管理，并把变更方法绑定给表格
+
+```vue
+<script setup lang="ts">
+import { usePagination, useTableSort } from '@ksyun-internal/versatile';
+
+const { page } = usePagination();
+const { sort, curSortKey, curSortType, changeSort } = useTableSort(page);
+</script>
+```
+

package/docs_for_llm/useToState.doc.md

@@ -0,0 +1,112 @@
+# Props 转 State (useToState)
+
+将 props 中的属性转换为响应式 state，支持 v-model 双向绑定。当 props 变化时自动更新 state，当 state 变化时自动触发 emit 更新父组件。
+
+**关键词**: useToState, props, state, v-model, 双向绑定, 响应式
+
+## 导入语句
+```typescript
+import { useToState } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| props | `P extends object` | 是 | 组件的 props 对象（通过 defineProps 获取） |
+| key | `keyof P` | 是 | 要监听的 prop 名称（字符串） |
+| emit | `Emits<K & string, P[K]>` | 是 | 组件的 emit 函数（通过 defineEmits 获取），需要包含 update:key 事件 |
+| defaults | `NonNullable<P[K]>` | 否 | 默认值。如果提供，返回的 Ref 将保证不为 undefined |
+
+## 重载签名 (Overloads)
+### `useToState<P, K>(props: P, key: K, emit: Emits): Ref<P[K]>`
+基础用法，返回可能为 undefined 的响应式值
+
+### `useToState<P, K>(props: P, key: K, emit: Emits, defaults: NonNullable<P[K]>): Ref<NonNullable<P[K]>>`
+带默认值用法，返回保证非 undefined 的响应式值
+
+## 返回值
+```typescript
+Ref<P[K]>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 忘记传递 emit 参数
+> **错误用法**: `const value = useToState(props, 'modelValue');`
+> **正确写法**: `const value = useToState(props, 'modelValue', emit);`
+> **说明**: useToState 需要 emit 函数来实现双向绑定，缺少 emit 会导致编译错误
+
+### emit 没有定义对应的 update:key 事件
+> **错误用法**: `const emit = defineEmits(['change']);
+const value = useToState(props, 'modelValue', emit);`
+> **正确写法**: `const emit = defineEmits(['update:modelValue']);
+const value = useToState(props, 'modelValue', emit);`
+> **说明**: useToState 内部会调用 emit('update:key', newValue)，必须在 defineEmits 中声明对应事件
+
+### key 参数不是 props 中定义的属性
+> **错误用法**: `const props = defineProps<{ name: string }>();
+const value = useToState(props, 'age', emit);`
+> **正确写法**: `const props = defineProps<{ name: string; age?: number }>();
+const value = useToState(props, 'age', emit);`
+> **说明**: key 必须是 props 中已定义的属性名
+
+## 使用示例
+### 基础用法
+将 modelValue prop 转换为响应式 state
+
+```vue
+<script setup lang="ts">
+import { useToState } from '@ksyun-internal/versatile';
+
+type Props = { modelValue?: string };
+type Emits = { (e: 'update:modelValue', v?: string): void };
+
+const props = defineProps<Props>();
+const emit = defineEmits<Emits>();
+
+const value = useToState(props, 'modelValue', emit);
+</script>
+<template>
+  <input v-model="value" />
+</template>
+```
+
+### 带默认值用法
+提供默认值，确保返回值不为 undefined
+
+```vue
+<script setup lang="ts">
+import { useToState } from '@ksyun-internal/versatile';
+
+const props = defineProps<{ count?: number }>();
+const emit = defineEmits(['update:count']);
+
+// 默认值为 0，count 永远不为 undefined
+const count = useToState(props, 'count', emit, 0);
+</script>
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+### 对象类型值
+将对象类型的 prop 转换为响应式 state
+
+```vue
+<script setup lang="ts">
+import { useToState } from '@ksyun-internal/versatile';
+
+type FormData = { name: string; age: number };
+type Props = { modelValue?: FormData };
+type Emits = { (e: 'update:modelValue', v?: FormData): void };
+
+const props = defineProps<Props>();
+const emit = defineEmits<Emits>();
+
+const formData = useToState(props, 'modelValue', emit, { name: '', age: 0 });
+</script>
+<template>
+  <input v-model="formData.name" />
+  <input v-model.number="formData.age" />
+</template>
+```
+

package/docs_for_llm/useUser.doc.md

@@ -0,0 +1,38 @@
+# 当前用户信息 (useUser)
+
+获取当前登录用户信息，适合在业务组件中读取 root 权限、当前用户 ID 或账号属性。
+
+**关键词**: useUser, 当前用户, 权限, isRoot, curUserId, 账号信息
+
+## 导入语句
+```typescript
+import { useUser } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+Ref<UserInfo | undefined>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接访问 user.value 的属性，没有处理未加载完成的情况
+> **错误用法**: `const isRoot = user.value.isRoot;`
+> **正确写法**: `const isRoot = user.value?.isRoot;`
+> **说明**: 返回值是 Ref<UserInfo | undefined>，初始化阶段可能为空。
+
+## 使用示例
+### 读取当前用户信息
+在页面初始化时获取当前用户及权限信息
+
+```vue
+<script setup lang="ts">
+import { useUser } from '@ksyun-internal/versatile';
+
+const user = useUser();
+</script>
+
+<template>
+  <div v-if="user">{{ user.curUserId }}</div>
+</template>
+```
+

package/docs_for_llm/useValidForm.doc.md

@@ -0,0 +1,41 @@
+# 表单校验管理 (useValidForm)
+
+封装 Form 实例的校验、重置和滚动定位能力，适合页面表单和弹窗表单统一管理。
+
+**关键词**: useValidForm, 表单校验, Form, validateByScroll, reset, 滚动定位
+
+## 导入语句
+```typescript
+import { useValidForm } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| models | `Ref<T>` | 否 | 表单模型对象，可在 reset 时恢复默认值 |
+
+## 返回值
+```typescript
+{ formRef: Ref<Form | undefined>; validate: Function; validateByScroll: Function; reset: Function; scrollIntoFirstInvalidFormItem: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 希望 reset 恢复初始模型，但没有把 models 传给 hook
+> **错误用法**: `const { reset } = useValidForm();`
+> **正确写法**: `const { reset } = useValidForm(models);`
+> **说明**: 如果需要重置业务表单值，建议把模型 Ref 传入 useValidForm。
+
+## 使用示例
+### 页面表单校验
+在提交前统一校验并定位第一个错误项
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useValidForm } from '@ksyun-internal/versatile';
+
+const models = ref({ name: '', region: '' });
+const { formRef, validateByScroll } = useValidForm(models);
+</script>
+```
+