@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/localized/zh-CN/skills/fec-code-smells/references/smell-to-refactoring-map.md

@@ -0,0 +1,265 @@
+# 坏味道到重构手法映射
+
+候选手法只用于辅助选择。必须结合实际成因、前置条件、风险和“最小安全变化”判断，不能按关键词机械套用。
+
+## SMELL-MYSTERIOUS-NAME — 神秘命名（Mysterious Name）
+
+**主要/辅助候选**
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-RENAME-VARIABLE`
+- `RF-RENAME-FIELD`
+
+**选择提示**
+- 先确认“神秘命名”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-DUPLICATED-CODE — 重复代码（Duplicated Code）
+
+**主要/辅助候选**
+- `RF-EXTRACT-FUNCTION`
+- `RF-SLIDE-STATEMENTS`
+- `RF-PULL-UP-METHOD`
+
+**选择提示**
+- 先确认“重复代码”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-LONG-FUNCTION — 过长函数（Long Function）
+
+**主要/辅助候选**
+- `RF-EXTRACT-FUNCTION`
+- `RF-REPLACE-TEMP-WITH-QUERY`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-PRESERVE-WHOLE-OBJECT`
+- `RF-REPLACE-FUNCTION-WITH-COMMAND`
+- `RF-DECOMPOSE-CONDITIONAL`
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+- `RF-SPLIT-LOOP`
+
+**选择提示**
+- 先确认“过长函数”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-LONG-PARAMETER-LIST — 过长参数列表（Long Parameter List）
+
+**主要/辅助候选**
+- `RF-REPLACE-PARAMETER-WITH-QUERY`
+- `RF-PRESERVE-WHOLE-OBJECT`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-REMOVE-FLAG-ARGUMENT`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+
+**选择提示**
+- 先确认“过长参数列表”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-GLOBAL-DATA — 全局数据（Global Data）
+
+**主要/辅助候选**
+- `RF-ENCAPSULATE-VARIABLE`
+
+**选择提示**
+- 先确认“全局数据”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-MUTABLE-DATA — 可变数据（Mutable Data）
+
+**主要/辅助候选**
+- `RF-ENCAPSULATE-VARIABLE`
+- `RF-SPLIT-VARIABLE`
+- `RF-SLIDE-STATEMENTS`
+- `RF-EXTRACT-FUNCTION`
+- `RF-SEPARATE-QUERY-FROM-MODIFIER`
+- `RF-REMOVE-SETTING-METHOD`
+- `RF-REPLACE-DERIVED-VARIABLE-WITH-QUERY`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+- `RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`
+- `RF-CHANGE-REFERENCE-TO-VALUE`
+
+**选择提示**
+- 先确认“可变数据”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-DIVERGENT-CHANGE — 发散式变化（Divergent Change）
+
+**主要/辅助候选**
+- `RF-SPLIT-PHASE`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+- `RF-EXTRACT-CLASS`
+
+**选择提示**
+- 先确认“发散式变化”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-SHOTGUN-SURGERY — 霰弹式修改（Shotgun Surgery）
+
+**主要/辅助候选**
+- `RF-MOVE-FUNCTION`
+- `RF-MOVE-FIELD`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+- `RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`
+- `RF-SPLIT-PHASE`
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+
+**选择提示**
+- 先确认“霰弹式修改”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-FEATURE-ENVY — 依恋情结（Feature Envy）
+
+**主要/辅助候选**
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+
+**选择提示**
+- 先确认“依恋情结”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-DATA-CLUMPS — 数据泥团（Data Clumps）
+
+**主要/辅助候选**
+- `RF-EXTRACT-CLASS`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-PRESERVE-WHOLE-OBJECT`
+
+**选择提示**
+- 先确认“数据泥团”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-PRIMITIVE-OBSESSION — 基本类型偏执（Primitive Obsession）
+
+**主要/辅助候选**
+- `RF-REPLACE-PRIMITIVE-WITH-OBJECT`
+- `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+- `RF-EXTRACT-CLASS`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+
+**选择提示**
+- 先确认“基本类型偏执”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-REPEATED-SWITCHES — 重复的 switch（Repeated Switches）
+
+**主要/辅助候选**
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+
+**选择提示**
+- 先确认“重复的 switch”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-LOOPS — 循环语句（Loops）
+
+**主要/辅助候选**
+- `RF-REPLACE-LOOP-WITH-PIPELINE`
+
+**选择提示**
+- 先确认“循环语句”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-LAZY-ELEMENT — 冗赘的元素（Lazy Element）
+
+**主要/辅助候选**
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+- `RF-COLLAPSE-HIERARCHY`
+
+**选择提示**
+- 先确认“冗赘的元素”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-SPECULATIVE-GENERALITY — 夸夸其谈通用性（Speculative Generality）
+
+**主要/辅助候选**
+- `RF-COLLAPSE-HIERARCHY`
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-REMOVE-DEAD-CODE`
+
+**选择提示**
+- 先确认“夸夸其谈通用性”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-TEMPORARY-FIELD — 临时字段（Temporary Field）
+
+**主要/辅助候选**
+- `RF-EXTRACT-CLASS`
+- `RF-MOVE-FUNCTION`
+- `RF-INTRODUCE-SPECIAL-CASE`
+
+**选择提示**
+- 先确认“临时字段”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-MESSAGE-CHAINS — 过长的消息链（Message Chains）
+
+**主要/辅助候选**
+- `RF-HIDE-DELEGATE`
+- `RF-EXTRACT-FUNCTION`
+- `RF-MOVE-FUNCTION`
+
+**选择提示**
+- 先确认“过长的消息链”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-MIDDLE-MAN — 中间人（Middle Man）
+
+**主要/辅助候选**
+- `RF-REMOVE-MIDDLE-MAN`
+- `RF-INLINE-FUNCTION`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+
+**选择提示**
+- 先确认“中间人”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-INSIDER-TRADING — 内幕交易（Insider Trading）
+
+**主要/辅助候选**
+- `RF-MOVE-FUNCTION`
+- `RF-MOVE-FIELD`
+- `RF-HIDE-DELEGATE`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+
+**选择提示**
+- 先确认“内幕交易”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-LARGE-CLASS — 过大的类（Large Class）
+
+**主要/辅助候选**
+- `RF-EXTRACT-CLASS`
+- `RF-EXTRACT-SUPERCLASS`
+- `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`
+
+**选择提示**
+- 先确认“过大的类”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-ALTERNATIVE-CLASSES-DIFFERENT-INTERFACES — 异曲同工的类（Alternative Classes with Different Interfaces）
+
+**主要/辅助候选**
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-SUPERCLASS`
+
+**选择提示**
+- 先确认“异曲同工的类”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-DATA-CLASS — 纯数据类（Data Class）
+
+**主要/辅助候选**
+- `RF-ENCAPSULATE-RECORD`
+- `RF-REMOVE-SETTING-METHOD`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+- `RF-SPLIT-PHASE`
+
+**选择提示**
+- 先确认“纯数据类”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-REFUSED-BEQUEST — 被拒绝的遗赠（Refused Bequest）
+
+**主要/辅助候选**
+- `RF-PUSH-DOWN-METHOD`
+- `RF-PUSH-DOWN-FIELD`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+
+**选择提示**
+- 先确认“被拒绝的遗赠”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。
+
+## SMELL-COMMENTS — 注释（Comments）
+
+**主要/辅助候选**
+- `RF-EXTRACT-FUNCTION`
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-INTRODUCE-ASSERTION`
+
+**选择提示**
+- 先确认“注释”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。

package/localized/zh-CN/skills/fec-component-testing/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: fec-component-testing
+description: 用于编写或审查靠近 UI 代码的前端单元、组件或轻量集成测试，包括 React Testing Library、Vue Test Utils、hooks/composables、props/emits、回调、可访问查询、user-event 交互、mock、loading/error/empty 状态和回归覆盖。若是测试分层规划、真实浏览器旅程或现有验证失败，优先选择对应测试或验证工作流；中文触发词包括 组件测试、组件单测、单元测试、轻量集成测试。
+---
+
+# 组件测试
+
+## 用途
+
+用贴近代码和用户行为的测试验证纯逻辑、组件契约与轻量模块协作，减少重构和 UI 交互回归。
+
+## 流程
+
+### 1. 先确定测试层级
+
+- 单元测试：纯函数、hooks/composables、utils、状态逻辑、schema。
+- 组件测试：props/emits、回调、用户交互、loading/error/empty、mock 边界。
+- 轻量集成测试：表单 + API mock + Router/Store/Provider 上下文。
+
+跨页面真实浏览器流程分流到 E2E workflow；测试层选择不清楚时先做测试分层规划。
+
+### 2. 优先按用户可感知行为测试
+
+每个测试保持 Arrange / Act / Assert 清晰分段：准备数据和渲染、执行用户动作、断言用户可见结果或公开契约。
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SearchBox } from "./SearchBox";
+
+test("submits the entered keyword", async () => {
+  const user = userEvent.setup();
+  const onSearch = vi.fn();
+
+  render(<SearchBox onSearch={onSearch} />);
+
+  await user.type(screen.getByRole("searchbox", { name: /keyword/i }), "orders");
+  await user.click(screen.getByRole("button", { name: /search/i }));
+
+  expect(onSearch).toHaveBeenCalledWith("orders");
+});
+```
+
+### 3. Vue 组件使用可访问查询或明确文本断言
+
+```ts
+import { mount } from "@vue/test-utils";
+import UserMenu from "./UserMenu.vue";
+
+test("emits logout when the logout item is clicked", async () => {
+  const wrapper = mount(UserMenu, {
+    props: { userName: "Ada" },
+  });
+
+  await wrapper.get('[data-testid="logout-button"]').trigger("click");
+
+  expect(wrapper.emitted("logout")).toHaveLength(1);
+});
+```
+
+优先使用角色、标签和可见文本；仅在没有稳定语义时使用 `data-testid`。
+
+### 4. 控制 mock 边界
+
+```ts
+vi.mock("../api/users", () => ({
+  fetchUsers: vi.fn(async () => [{ id: "1", name: "Ada" }]),
+}));
+```
+
+- mock 网络、时间、路由和浏览器 API。
+- 不 mock 被测组件的内部函数。
+- 对设计系统基础组件只做轻量 mock，保留可访问行为。
+- mock 数据应表达业务场景，不使用只有测试作者能理解的随意字符串。
+- 共享 fixture 应保持可读，复杂对象用 builder 补默认值；每个测试只覆盖与场景相关的字段。
+- mock 网络时优先模拟用户可见结果和错误形状，不复制后端实现细节。
+
+### 5. 覆盖关键状态
+
+每个复杂组件至少覆盖：
+
+- 默认渲染。
+- 用户交互和回调。
+- loading / empty / error。
+- 权限或禁用态。
+- 键盘交互和焦点行为（适用时）。
+
+### 6. 保持测试可维护
+
+```ts
+function setup() {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<ProfileForm onSubmit={onSubmit} />);
+  return { user, onSubmit };
+}
+```
+
+将重复渲染逻辑放入 `setup`，但不要隐藏测试的核心操作和断言。
+
+### 7. 回归测试先证明问题
+
+- Bug 修复先写能复现失败的最小测试。
+- 失败原因应指向用户行为或公开契约，而不是导入错误、测试环境或等待方式。
+- 修复后保留回归测试，避免把验证只留在手工步骤里。
+
+## 约束
+
+- 避免测试实现细节，例如内部 state 名称、私有函数调用、DOM 层级快照。
+- 不把 snapshot 作为交互组件的主要断言；它只能辅助检查稳定静态输出。
+- 异步断言使用 `findBy*` 或 `waitFor`，不要用固定延迟。
+- 测试名称应描述用户场景，而不是函数名。
+- 组件测试不能替代 E2E；路由、真实浏览器兼容和跨页流程仍需 E2E。
+- 不在测试里复制组件实现逻辑；否则测试会和错误实现一起通过。
+- 不在测试间共享可变 fixture、全局 store 或 fake timer 状态；每个用例独立 setup 和 cleanup。
+
+## 预期输出
+
+产出与组件同目录或项目约定目录下的测试文件，覆盖核心交互、状态和回归场景。验证时运行项目现有 test 命令，确认失败信息能定位到用户行为或组件契约。

package/localized/zh-CN/skills/fec-data-fetching/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: fec-data-fetching
+description: 用于实现或审查前端服务端状态流程：类型化查询、请求缓存、失效、mutation、乐观更新、无限查询、预取、SSR hydration 或 API 层整合。不要用于本地 UI 状态或 Service Worker 缓存；中文触发词包括 数据获取、缓存、乐观更新。
+---
+
+# Server State 数据获取
+
+## 用途
+
+为前端 server state 建立清晰的数据获取、缓存、失效和提交边界，避免请求状态散落在页面组件中。
+
+## 流程
+
+1. 判断状态来源：来自服务端且需要缓存、去重、刷新、分页或 mutation 时使用请求缓存方案；纯本地 UI 状态用组件 state 或 store。
+2. 先沿用项目已有数据获取库；新增依赖时 React/Vue/Solid/Svelte 可考虑 TanStack Query，也可沿用 SWR、Nuxt/Nitro 数据获取或项目封装。
+3. 设计稳定 cache key/query key：结构包含实体、动作和所有影响结果的参数。
+4. API 函数保持纯请求函数，数据 hook/composable 负责缓存、select、loading/error/empty 状态。
+5. mutation 成功后 invalidation；需要即时反馈时使用 optimistic update 并在失败时回滚。
+
+## React 快速开始
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+export function UserList({ keyword }: { keyword: string }) {
+  const query = useQuery({
+    queryKey: ["users", "list", { keyword }],
+    queryFn: () => getUserList({ keyword, page: 1, pageSize: 20 }),
+    select: (response) => response.list,
+  });
+
+  if (query.isLoading) return <Skeleton />;
+  if (query.isError) return <ErrorFallback onRetry={() => query.refetch()} />;
+  if (!query.data?.length) return <EmptyState />;
+
+  return query.data.map((user) => <UserRow key={user.id} user={user} />);
+}
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: createUser,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["users"] }),
+  });
+}
+```
+
+## 详细参考
+
+涉及是否需要查询库、QueryClient 默认配置、Vue adapter、乐观更新、无限滚动查询、预取、SSR 水合和 API 层整合时，加载 [references/query-patterns.md](references/query-patterns.md)。
+
+## 约束
+
+- 相同数据必须复用相同 cache key/query key；参数缺失会造成缓存串读。
+- `staleTime` 过长会显示旧数据，过短会造成频繁请求。
+- 请求缓存库不管理本地 UI 状态；不要把 modal、输入框值放进 query cache。
+- 乐观更新必须保存快照并在失败时回滚。
+- SSR/SSG 场景必须使用框架支持的预取、水合或服务端数据边界。
+
+## 预期输出
+
+数据获取层具备 loading/error/empty/data 状态，重复请求自动去重，mutation 后缓存正确失效或回滚，API 层与 UI 层边界清晰。

package/localized/zh-CN/skills/fec-data-fetching/references/query-patterns.md

@@ -0,0 +1,103 @@
+# Server State 数据获取模式
+
+## 先判断是否需要查询库
+
+- 简单静态请求、一次性提交或已有框架 loader 足够表达的页面，不必默认引入查询库。
+- 需要跨组件缓存、去重、后台刷新、分页、乐观更新、预取或 SSR hydration 时，再使用 TanStack Query、SWR、Nuxt 数据获取或项目既有请求缓存方案。
+- 查询库只管理 server state，不替代本地 UI 状态、表单状态、权限判断或 Service Worker 缓存。
+
+## 选型参考
+
+先沿用仓库已有请求层和缓存方案；新增依赖时再按框架与复杂度选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| React server state | TanStack Query / SWR / 项目既有封装 | TanStack Query 适合 mutation、invalidation 和无限查询；SWR 适合轻量读取缓存。 |
+| Vue server state | TanStack Query Vue adapter / VueUse / Nuxt `useFetch` / 项目既有封装 | 不要让 Vue 项目照搬 React-only hook 示例。 |
+| Solid / Svelte / 跨框架 | TanStack Query 对应 adapter 或项目既有资源层 | cache key、staleTime、mutation 回滚原则保持一致。 |
+| 简单页面请求 | 框架 loader、组件内轻量请求或 API composable | 仍要处理 loading/error/empty 和取消或过期响应。 |
+| SSR / SSG | 框架预取、水合或服务端数据边界 | 确保服务端 key 与客户端 key 一致，避免重复请求和水合错配。 |
+
+## 通用边界
+
+- API 函数只负责请求、解析和错误归一化，不包含 UI toast、loading 或缓存逻辑。
+- cache key/query key 必须包含所有影响响应的参数。
+- mutation 成功后按实体或列表失效；乐观更新必须先保存快照，失败时回滚。
+- 无限查询只处理数据分页；DOM 虚拟化由列表虚拟化流程处理。
+- 预取要有明确用户路径或首屏收益，不为所有可能数据提前请求。
+
+## QueryClient 默认配置
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000,
+      gcTime: 30 * 60 * 1000,
+      retry: 2,
+      refetchOnWindowFocus: true,
+    },
+  },
+});
+```
+
+## Query Key 设计
+
+- 推荐：`["users", "list", { page, status }]`
+- 详情：`["users", "detail", userId]`
+- 所有影响请求结果的参数都必须进入 key。
+
+## 乐观更新
+
+```tsx
+const mutation = useMutation({
+  mutationFn: () => api.likePost(postId),
+  onMutate: async () => {
+    await queryClient.cancelQueries({ queryKey: ["post", postId] });
+    const previousPost = queryClient.getQueryData(["post", postId]);
+    queryClient.setQueryData(["post", postId], (old: Post) => ({
+      ...old,
+      likes: old.likes + 1,
+      liked: true,
+    }));
+    return { previousPost };
+  },
+  onError: (_error, _variables, context) => {
+    queryClient.setQueryData(["post", postId], context?.previousPost);
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ["post", postId] });
+  },
+});
+```
+
+## 无限查询
+
+```tsx
+const feed = useInfiniteQuery({
+  queryKey: ["feed"],
+  queryFn: ({ pageParam = 1 }) => api.fetchFeed({ page: pageParam, limit: 20 }),
+  getNextPageParam: (lastPage, pages) => (lastPage.hasMore ? pages.length + 1 : undefined),
+  initialPageParam: 1,
+});
+```
+
+虚拟列表场景将数据分页与 DOM 虚拟化分开设计。
+
+## API 层整合
+
+```ts
+export async function getUserList(params: GetUserListParams): Promise<GetUserListResponse> {
+  return request.get("/api/users", { params });
+}
+
+export function useUsers(params: GetUserListParams) {
+  return useQuery({
+    queryKey: ["users", "list", params],
+    queryFn: () => getUserList(params),
+    select: (response) => response.list,
+  });
+}
+```
+
+API 函数不包含 UI toast、loading 或缓存逻辑。