king-design-analyzer 2.1.9 → 2.2.0

package/docs_for_llm/useLayoutStandardList.doc.md

@@ -0,0 +1,38 @@
+# 标准列表页组合状态 (useLayoutStandardList)
+
+为 LayoutStandardList 组合分页、搜索、分组、排序、列设置和批量操作状态，适合标准列表页快速搭建。
+
+**关键词**: useLayoutStandardList, LayoutStandardList, 标准列表页, 分页 搜索 排序, 批量操作, 表格组合状态
+
+## 导入语句
+```typescript
+import { useLayoutStandardList } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+{ 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; ... }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 在 LayoutStandardList 外又重复手写 useSearch/usePagination/useTableSort，导致状态来源分裂
+> **错误用法**: `const search = useSearch(); const pagination = usePagination(); const state = useLayoutStandardList();`
+> **正确写法**: `const state = useLayoutStandardList();`
+> **说明**: 如果页面主体就是 LayoutStandardList，优先复用这个组合 hook。
+
+## 使用示例
+### 标准列表页容器
+在 LayoutStandardList 外层持有组合状态和实例引用
+
+```vue
+<script setup lang="ts">
+import { LayoutStandardList, useLayoutStandardList } from '@ksyun-internal/versatile';
+
+const { layoutStandardListRef, page, limit, searchItems, checkedKeys } = useLayoutStandardList();
+</script>
+
+<template>
+  <LayoutStandardList ref="layoutStandardListRef" :use-list="() => ({ loading: false, dataSource: [], total: 0 })" />
+</template>
+```
+

package/docs_for_llm/useMessage.doc.md

@@ -0,0 +1,46 @@
+# 变更消息反馈 (useMessage)
+
+为 Apollo mutation 封装统一的成功/失败消息处理逻辑，适合删除、编辑、创建等需要标准化提示文案的请求场景。
+
+**关键词**: useMessage, mutation 提示, apollo, 成功失败消息, toast, 反馈
+
+## 导入语句
+```typescript
+import { useMessage } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| onError | `UseMutationReturn<TResult, TVariables>['onError']` | 是 | mutation 返回的错误监听函数 |
+| onDone | `UseMutationReturn<TResult, TVariables>['onDone']` | 否 | mutation 返回的完成监听函数 |
+| isSuccess | `(res: FetchResult<TResult>) => boolean` | 否 | 自定义成功判定逻辑 |
+| action | `string | (() => string)` | 否 | 操作名称，用于生成成功/失败提示文案 |
+| successCallback | `(res: FetchResult<TResult>) => any` | 否 | 成功后的额外回调 |
+| failedCallback | `(e: Error) => any` | 否 | 失败后的额外回调 |
+
+## 返回值
+```typescript
+void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 接口返回结构不是标准成功态，但没有传 isSuccess，自定义失败被当成成功
+> **错误用法**: `useMessage(onError, onDone, undefined, '删除');`
+> **正确写法**: `useMessage(onError, onDone, (res) => res.data?.delete?.code === 200, '删除');`
+> **说明**: 如果后端不是默认成功结构，建议显式提供 isSuccess。
+
+## 使用示例
+### 统一处理 mutation 提示
+把创建、删除等 mutation 的消息提示收口到 hook
+
+```vue
+<script setup lang="ts">
+import { useMutation } from '@vue/apollo-composable';
+import { useMessage } from '@ksyun-internal/versatile';
+
+const { onError, onDone } = useMutation(CREATE_INSTANCE);
+useMessage(onError, onDone, undefined, '创建实例');
+</script>
+```
+

package/docs_for_llm/useModifyCache.doc.md

@@ -0,0 +1,37 @@
+# Apollo 缓存修改 (useModifyCache)
+
+返回一个可复用的 Apollo cache.modify 封装函数，适合在 mutation 后局部更新缓存而不重新发请求。
+
+**关键词**: useModifyCache, apollo cache, cache.modify, mutation, 局部更新缓存, graphql
+
+## 导入语句
+```typescript
+import { useModifyCache } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+(identify: StoreObject | Reference, fields: Cache.ModifyOptions['fields']) => void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### identify 对象缺少 Apollo 可识别的标识字段
+> **错误用法**: `modifyCache({ name: 'instance-1' }, { status: () => 'running' });`
+> **正确写法**: `modifyCache({ __typename: 'Instance', id: 'ins-1' }, { status: () => 'running' });`
+> **说明**: identify 需要能让 Apollo 唯一定位缓存实体。
+
+## 使用示例
+### 局部更新 Apollo 缓存
+在删除或编辑成功后直接修改缓存字段
+
+```vue
+<script setup lang="ts">
+import { useModifyCache } from '@ksyun-internal/versatile';
+
+const modifyCache = useModifyCache();
+modifyCache({ __typename: 'Instance', id: 'ins-1' }, {
+  name: () => 'new-name',
+});
+</script>
+```
+

package/docs_for_llm/useOpenDialog.doc.md

@@ -0,0 +1,41 @@
+# 表格操作弹窗 (useOpenDialog)
+
+针对表格单行操作和批量操作封装弹窗打开逻辑，统一维护当前操作项和批量操作项集合。
+
+**关键词**: useOpenDialog, 批量操作, 表格操作, dialog, 单行操作, tableRef
+
+## 导入语句
+```typescript
+import { useOpenDialog } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| tableRef | `Ref<Table | undefined>` | 否 | 表格实例引用，批量操作时可从表格中读取选中项 |
+
+## 返回值
+```typescript
+{ isShowDialog: Ref<boolean>; dialogRef: Ref<any>; opCols: Ref<T[] | undefined>; opCol: Ref<T | undefined>; show: Function; hide: Function; handleClickOpBtn: Function; handleClickBatchOpBtn: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 批量操作场景未传入 tableRef，导致无法读取选中项
+> **错误用法**: `const dialog = useOpenDialog();`
+> **正确写法**: `const dialog = useOpenDialog(tableRef);`
+> **说明**: 如果需要 handleClickBatchOpBtn 读取表格选中项，应传入 tableRef。
+
+## 使用示例
+### 表格操作弹窗
+点击单行操作按钮时打开弹窗并记录当前行数据
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useOpenDialog } from '@ksyun-internal/versatile';
+
+const tableRef = ref();
+const { isShowDialog, opCol, handleClickOpBtn } = useOpenDialog(tableRef);
+</script>
+```
+

package/docs_for_llm/usePagination.doc.md

@@ -0,0 +1,60 @@
+# 分页状态管理 (usePagination)
+
+管理列表页常用的 page、limit、limits 以及分页变更回调，适合和 ProTable、PaginationPlus、Search 组合使用。
+
+**关键词**: usePagination, 分页, page, limit, PaginationPlus, 列表页
+
+## 导入语句
+```typescript
+import { usePagination } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ page?: number; limit?: number; limits?: number[]; callback?: (v: PaginationChangeData) => void }` | 否 | 分页初始化配置，可预设页码、每页条数、可选 limits 及翻页后的回调 |
+
+## 返回值
+```typescript
+{ page: Ref<number>; limit: Ref<number>; limits: Ref<number[]>; pageChange: (pageParams: PaginationChangeData) => void; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 只绑定 page，没有同步维护 limit
+> **错误用法**: `const { page } = usePagination();`
+> **正确写法**: `const { page, limit } = usePagination();`
+> **说明**: 如果页面支持切换每页条数，应同时使用 hook 返回的 limit。
+
+## 使用示例
+### 基础分页用法
+通过 hook 统一管理列表页码和每页条数
+
+```vue
+<script setup lang="ts">
+import { PaginationPlus, usePagination } from '@ksyun-internal/versatile';
+
+const { page, limit, pageChange } = usePagination({
+  page: 1,
+  limit: 20,
+});
+</script>
+
+<template>
+  <PaginationPlus v-model="page" v-model:limit="limit" :total="200" @change="pageChange" />
+</template>
+```
+
+### 带回调的分页
+在分页变化后触发数据刷新或埋点逻辑
+
+```vue
+<script setup lang="ts">
+import { usePagination } from '@ksyun-internal/versatile';
+
+const fetchList = () => console.log('reload');
+const { page, limit, pageChange } = usePagination({
+  callback: () => fetchList(),
+});
+</script>
+```
+

package/docs_for_llm/usePersist.doc.md

@@ -0,0 +1,54 @@
+# 本地持久化 (usePersist)
+
+将响应式数据持久化到 localStorage 或 sessionStorage，适合保存列表筛选、用户偏好和表格配置。
+
+**关键词**: usePersist, localStorage, sessionStorage, 持久化, 列表偏好, 缓存状态
+
+## 导入语句
+```typescript
+import { usePersist } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| key | `string` | 是 | 存储键名 |
+| defaultValue | `T` | 是 | 初始化默认值 |
+| options | `PersistOptions<T>` | 否 | 持久化配置，可切换 storage、自定义序列化和 watch 行为 |
+
+## 返回值
+```typescript
+Ref<T>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 使用会变化的 key，导致同一份状态被重复写入
+> **错误用法**: `usePersist(`table-${Date.now()}`, []);`
+> **正确写法**: `usePersist('instance-table-fields', []);`
+> **说明**: key 应保持稳定，否则无法复用持久化结果。
+
+## 使用示例
+### 持久化表格配置
+保存用户的列显隐或筛选配置
+
+```vue
+<script setup lang="ts">
+import { usePersist } from '@ksyun-internal/versatile';
+
+const tableFields = usePersist('table-fields', ['name', 'status']);
+</script>
+```
+
+### 使用 sessionStorage
+仅在当前会话内保留搜索状态
+
+```vue
+<script setup lang="ts">
+import { usePersist } from '@ksyun-internal/versatile';
+
+const searchState = usePersist('instance-search', { key: 'name', value: '' }, {
+  storage: sessionStorage,
+});
+</script>
+```
+

package/docs_for_llm/usePoll.doc.md

@@ -0,0 +1,41 @@
+# 查询轮询 (usePoll)
+
+包装 Apollo 查询结果并启用轮询场景，适合在列表页、详情页中持续刷新接口数据。
+
+**关键词**: usePoll, 轮询, apollo, useQuery, 自动刷新, 列表轮询
+
+## 导入语句
+```typescript
+import { usePoll } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| result | `UseQueryReturn<any, any>` | 是 | Apollo useQuery 返回的查询对象 |
+
+## 返回值
+```typescript
+UseQueryReturn<any, any>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 传入普通 Promise 或自定义对象而不是 Apollo 查询返回值
+> **错误用法**: `const result = usePoll(fetchList());`
+> **正确写法**: `const result = usePoll(useQuery(GET_LIST));`
+> **说明**: usePoll 依赖 Apollo 的 UseQueryReturn 结构。
+
+## 使用示例
+### 轮询查询结果
+对 useQuery 返回值启用轮询式刷新
+
+```vue
+<script setup lang="ts">
+import { useQuery } from '@vue/apollo-composable';
+import { usePoll } from '@ksyun-internal/versatile';
+
+const queryResult = useQuery(GET_INSTANCE_LIST);
+const pollResult = usePoll(queryResult);
+</script>
+```
+

package/docs_for_llm/useRoutePlus.doc.md

@@ -0,0 +1,34 @@
+# 增强路由读取 (useRoutePlus)
+
+对 vue-router 的 route 做包装，直接返回 params、query 及其 refs，便于在组合式函数中按字段响应式使用。
+
+**关键词**: useRoutePlus, route params, query refs, vue-router, 详情页参数, 路由读取
+
+## 导入语句
+```typescript
+import { useRoutePlus } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+{ $route: RouteLocationNormalizedLoadedGeneric; params: Record<string, string>; paramRefs: ToRefs<Record<string, string>>; query: LocationQuery; queryRefs: ToRefs<LocationQuery>; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接修改 paramRefs/queryRefs，期望同步改写路由地址
+> **错误用法**: `paramRefs.id.value = '2';`
+> **正确写法**: `如需跳转，请配合 useRouterPlus 或 router.push。`
+> **说明**: 这个 hook 主要用于读取路由状态，不负责写回 URL。
+
+## 使用示例
+### 读取详情页路由参数
+把详情页 id 和 query 参数拆成可直接使用的 refs
+
+```vue
+<script setup lang="ts">
+import { useRoutePlus } from '@ksyun-internal/versatile';
+
+const { params, paramRefs, queryRefs } = useRoutePlus();
+</script>
+```
+

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>
+```
+