@bovinphang/frontend-craft 2.7.0 → 2.9.0

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

@@ -0,0 +1,265 @@
+# Smell-to-Refactoring Map
+
+Candidate techniques are advisory. Select by observed cause, preconditions, risk, and the smallest safe transformation; never reduce diagnosis to keyword lookup.
+
+## SMELL-MYSTERIOUS-NAME — Mysterious Name
+
+**Primary/Supporting Candidates**
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-RENAME-VARIABLE`
+- `RF-RENAME-FIELD`
+
+**Selection Note**
+- Confirm the diagnosed cause of Mysterious Name and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-DUPLICATED-CODE — Duplicated Code
+
+**Primary/Supporting Candidates**
+- `RF-EXTRACT-FUNCTION`
+- `RF-SLIDE-STATEMENTS`
+- `RF-PULL-UP-METHOD`
+
+**Selection Note**
+- Confirm the diagnosed cause of Duplicated Code and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-LONG-FUNCTION — Long Function
+
+**Primary/Supporting Candidates**
+- `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`
+
+**Selection Note**
+- Confirm the diagnosed cause of Long Function and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-LONG-PARAMETER-LIST — Long Parameter List
+
+**Primary/Supporting Candidates**
+- `RF-REPLACE-PARAMETER-WITH-QUERY`
+- `RF-PRESERVE-WHOLE-OBJECT`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-REMOVE-FLAG-ARGUMENT`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+
+**Selection Note**
+- Confirm the diagnosed cause of Long Parameter List and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-GLOBAL-DATA — Global Data
+
+**Primary/Supporting Candidates**
+- `RF-ENCAPSULATE-VARIABLE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Global Data and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-MUTABLE-DATA — Mutable Data
+
+**Primary/Supporting Candidates**
+- `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`
+
+**Selection Note**
+- Confirm the diagnosed cause of Mutable Data and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-DIVERGENT-CHANGE — Divergent Change
+
+**Primary/Supporting Candidates**
+- `RF-SPLIT-PHASE`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+- `RF-EXTRACT-CLASS`
+
+**Selection Note**
+- Confirm the diagnosed cause of Divergent Change and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-SHOTGUN-SURGERY — Shotgun Surgery
+
+**Primary/Supporting Candidates**
+- `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`
+
+**Selection Note**
+- Confirm the diagnosed cause of Shotgun Surgery and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-FEATURE-ENVY — Feature Envy
+
+**Primary/Supporting Candidates**
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+
+**Selection Note**
+- Confirm the diagnosed cause of Feature Envy and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-DATA-CLUMPS — Data Clumps
+
+**Primary/Supporting Candidates**
+- `RF-EXTRACT-CLASS`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-PRESERVE-WHOLE-OBJECT`
+
+**Selection Note**
+- Confirm the diagnosed cause of Data Clumps and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-PRIMITIVE-OBSESSION — Primitive Obsession
+
+**Primary/Supporting Candidates**
+- `RF-REPLACE-PRIMITIVE-WITH-OBJECT`
+- `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+- `RF-EXTRACT-CLASS`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+
+**Selection Note**
+- Confirm the diagnosed cause of Primitive Obsession and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-REPEATED-SWITCHES — Repeated Switches
+
+**Primary/Supporting Candidates**
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+
+**Selection Note**
+- Confirm the diagnosed cause of Repeated Switches and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-LOOPS — Loops
+
+**Primary/Supporting Candidates**
+- `RF-REPLACE-LOOP-WITH-PIPELINE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Loops and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-LAZY-ELEMENT — Lazy Element
+
+**Primary/Supporting Candidates**
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+- `RF-COLLAPSE-HIERARCHY`
+
+**Selection Note**
+- Confirm the diagnosed cause of Lazy Element and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-SPECULATIVE-GENERALITY — Speculative Generality
+
+**Primary/Supporting Candidates**
+- `RF-COLLAPSE-HIERARCHY`
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-REMOVE-DEAD-CODE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Speculative Generality and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-TEMPORARY-FIELD — Temporary Field
+
+**Primary/Supporting Candidates**
+- `RF-EXTRACT-CLASS`
+- `RF-MOVE-FUNCTION`
+- `RF-INTRODUCE-SPECIAL-CASE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Temporary Field and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-MESSAGE-CHAINS — Message Chains
+
+**Primary/Supporting Candidates**
+- `RF-HIDE-DELEGATE`
+- `RF-EXTRACT-FUNCTION`
+- `RF-MOVE-FUNCTION`
+
+**Selection Note**
+- Confirm the diagnosed cause of Message Chains and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-MIDDLE-MAN — Middle Man
+
+**Primary/Supporting Candidates**
+- `RF-REMOVE-MIDDLE-MAN`
+- `RF-INLINE-FUNCTION`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Middle Man and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-INSIDER-TRADING — Insider Trading
+
+**Primary/Supporting Candidates**
+- `RF-MOVE-FUNCTION`
+- `RF-MOVE-FIELD`
+- `RF-HIDE-DELEGATE`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Insider Trading and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-LARGE-CLASS — Large Class
+
+**Primary/Supporting Candidates**
+- `RF-EXTRACT-CLASS`
+- `RF-EXTRACT-SUPERCLASS`
+- `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`
+
+**Selection Note**
+- Confirm the diagnosed cause of Large Class and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-ALTERNATIVE-CLASSES-DIFFERENT-INTERFACES — Alternative Classes with Different Interfaces
+
+**Primary/Supporting Candidates**
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-SUPERCLASS`
+
+**Selection Note**
+- Confirm the diagnosed cause of Alternative Classes with Different Interfaces and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-DATA-CLASS — Data Class
+
+**Primary/Supporting Candidates**
+- `RF-ENCAPSULATE-RECORD`
+- `RF-REMOVE-SETTING-METHOD`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+- `RF-SPLIT-PHASE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Data Class and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-REFUSED-BEQUEST — Refused Bequest
+
+**Primary/Supporting Candidates**
+- `RF-PUSH-DOWN-METHOD`
+- `RF-PUSH-DOWN-FIELD`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+
+**Selection Note**
+- Confirm the diagnosed cause of Refused Bequest and choose only a technique whose preconditions fit the current ownership and behavior contract.
+
+## SMELL-COMMENTS — Comments
+
+**Primary/Supporting Candidates**
+- `RF-EXTRACT-FUNCTION`
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-INTRODUCE-ASSERTION`
+
+**Selection Note**
+- Confirm the diagnosed cause of Comments and choose only a technique whose preconditions fit the current ownership and behavior contract.

package/skills/fec-component-testing/SKILL.md

@@ -1,27 +1,27 @@
 ---
 name: fec-component-testing
-description: Use when authoring or reviewing frontend unit, component, or light integration tests close to UI code, including React Testing Library, Vue Test Utils, hooks/composables, props/emits, callbacks, accessible queries, user-event interactions, mocks, loading/error/empty states, and regression coverage. For layer planning, real-browser journeys, or existing validation failures, choose the matching testing or validation workflow first; Chinese triggers include 组件测试, 组件单测, 单元测试, 轻量集成测试.
+description: Use when authoring or reviewing frontend unit, component, or light integration tests close to UI code, including React Testing Library, Vue Test Utils, hooks/composables, props/emits, callbacks, accessible queries, user-event interactions, mocks, loading/error/empty states, and regression coverage. For layer planning, real-browser journeys, or existing validation failures, choose the matching testing or validation workflow first; Chinese triggers include component testing, Component unit testing, unit testing, lightweight integration testing.
 ---
 
-# 组件测试
+#Component testing
 
 ## Purpose
 
-用贴近代码和用户行为的测试验证纯逻辑、组件契约与轻量模块协作，减少重构和 UI 交互回归。
+Use tests close to the code and user behavior to verify pure logic, component contracts, and lightweight module collaboration to reduce refactoring and UI interaction regression.
 
 ## Procedure
 
-### 1. 先确定测试层级
+### 1. First determine the test level
 
-- 单元测试：纯函数、hooks/composables、utils、状态逻辑、schema。
-- 组件测试：props/emits、回调、用户交互、loading/error/empty、mock 边界。
-- 轻量集成测试：表单 + API mock + Router/Store/Provider 上下文。
+- Unit testing: pure functions, hooks/composables, utils, state logic, schema.
+- Component testing: props/emis, callbacks, user interaction, loading/error/empty, mock boundaries.
+- Lightweight integration testing: form + API mock + Router/Store/Provider context.
 
-跨页面真实浏览器流程分流到 E2E workflow；测试层选择不清楚时先做测试分层规划。
+The cross-page real browser process is offloaded to the E2E workflow; if the test layer selection is unclear, do the test layering planning first.
 
-### 2. 优先按用户可感知行为测试
+### 2. Prioritize testing based on user-perceivable behavior
 
-每个测试保持 Arrange / Act / Assert 清晰分段：准备数据和渲染、执行用户动作、断言用户可见结果或公开契约。
+Each test keeps Arrange / Act / Assert clearly segmented: preparing data and rendering, performing user actions, asserting user-visible results or exposing contracts.
 
 ```tsx
 import { render, screen } from "@testing-library/react";
@@ -41,7 +41,7 @@ test("submits the entered keyword", async () => {
 });
 ```
 
-### 3. Vue 组件使用可访问查询或明确文本断言
+### 3. Vue components use accessible queries or explicit text assertions
 
 ```ts
 import { mount } from "@vue/test-utils";
@@ -58,9 +58,9 @@ test("emits logout when the logout item is clicked", async () => {
 });
 ```
 
-优先使用角色、标签和可见文本；仅在没有稳定语义时使用 `data-testid`。
+Prefer roles, labels, and visible text; only use `data-testid` when there is no stable semantics.
 
-### 4. 控制 mock 边界
+### 4. Control mock boundaries
 
 ```ts
 vi.mock("../api/users", () => ({
@@ -68,24 +68,24 @@ vi.mock("../api/users", () => ({
 }));
 ```
 
-- mock 网络、时间、路由和浏览器 API。
-- 不 mock 被测组件的内部函数。
-- 对设计系统基础组件只做轻量 mock，保留可访问行为。
-- mock 数据应表达业务场景，不使用只有测试作者能理解的随意字符串。
-- 共享 fixture 应保持可读，复杂对象用 builder 补默认值；每个测试只覆盖与场景相关的字段。
-- mock 网络时优先模拟用户可见结果和错误形状，不复制后端实现细节。
+- Mock network, time, routing and browser APIs.
+- Do not mock the internal functions of the component under test.
+- Only make light mocks of the basic components of the design system to retain accessible behaviors.
+- Mock data should express the business scenario and not use arbitrary strings that only the test author can understand.
+- Shared fixtures should remain readable, and complex objects should use builders to fill in default values; each test only covers the fields relevant to the scenario.
+- When mocking the network, give priority to simulating user-visible results and error shapes, and do not copy back-end implementation details.
 
-### 5. 覆盖关键状态
+### 5. Override key status
 
-每个复杂组件至少覆盖：
+Each complex component covers at least:
 
-- 默认渲染。
-- 用户交互和回调。
+- Default rendering.
+- User interaction and callbacks.
 - loading / empty / error。
-- 权限或禁用态。
-- 键盘交互和焦点行为（适用时）。
+- Permission or disabled status.
+- Keyboard interaction and focus behavior (when applicable).
 
-### 6. 保持测试可维护
+### 6. Keep tests maintainable
 
 ```ts
 function setup() {
@@ -96,24 +96,24 @@ function setup() {
 }
 ```
 
-将重复渲染逻辑放入 `setup`，但不要隐藏测试的核心操作和断言。
+Put the repetitive rendering logic into `setup`, but don't hide the core actions and assertions of the test.
 
-### 7. 回归测试先证明问题
+### 7. Regression testing proves the problem first
 
-- Bug 修复先写能复现失败的最小测试。
-- 失败原因应指向用户行为或公开契约，而不是导入错误、测试环境或等待方式。
-- 修复后保留回归测试，避免把验证只留在手工步骤里。
+- Bug fixes should be written first to create the smallest test that can reproduce the failure.
+- Reasons for failure should point to user behavior or public contracts, not import errors, test environments, or wait methods.
+- Keep regression testing after fixing to avoid leaving verification only in manual steps.
 
 ## Constraints
 
-- 避免测试实现细节，例如内部 state 名称、私有函数调用、DOM 层级快照。
-- 不把 snapshot 作为交互组件的主要断言；它只能辅助检查稳定静态输出。
-- 异步断言使用 `findBy*` 或 `waitFor`，不要用固定延迟。
-- 测试名称应描述用户场景，而不是函数名。
-- 组件测试不能替代 E2E；路由、真实浏览器兼容和跨页流程仍需 E2E。
-- 不在测试里复制组件实现逻辑；否则测试会和错误实现一起通过。
-- 不在测试间共享可变 fixture、全局 store 或 fake timer 状态；每个用例独立 setup 和 cleanup。
+- Avoid testing implementation details such as internal state names, private function calls, DOM hierarchy snapshots.
+- Do not use snapshot as the main assertion for interactive components; it can only assist in checking stable static output.
+- Use `findBy*` or `waitFor` for asynchronous assertions, do not use fixed delays.
+- Test names should describe user scenarios, not function names.
+- Component testing is not a replacement for E2E; routing, real-browser compatibility, and cross-page flows still require E2E.
+- Do not copy component implementation logic in tests; otherwise the test will pass with the wrong implementation.
+- No mutable fixtures, global store or fake timer state shared between tests; each use case has independent setup and cleanup.
 
 ## Expected Output
 
-产出与组件同目录或项目约定目录下的测试文件，覆盖核心交互、状态和回归场景。验证时运行项目现有 test 命令，确认失败信息能定位到用户行为或组件契约。
+Produce test files in the same directory as the component or in the directory agreed upon by the project, covering core interactions, status and regression scenarios. During verification, run the existing test command of the project to confirm that the failure information can be located to user behavior or component contract.

package/skills/fec-data-fetching/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: fec-data-fetching
-description: Use when implementing or reviewing frontend server-state flows: typed queries, request caching, invalidation, mutations, optimistic updates, infinite queries, prefetch, SSR hydration, or API-layer integration. Do not use for local UI state or Service Worker caching; Chinese triggers include 数据获取, 缓存, 乐观更新.
+description: "Use when implementing or reviewing frontend server-state flows: typed queries, request caching, invalidation, mutations, optimistic updates, infinite queries, prefetch, SSR hydration, or API-layer integration. Do not use for local UI state or Service Worker caching; Chinese triggers include data fetch, cache, optimistic updates."
 ---
 
-# Server State 数据获取
+# Server State data acquisition
 
 ## Purpose
 
-为前端 server state 建立清晰的数据获取、缓存、失效和提交边界，避免请求状态散落在页面组件中。
+Establish clear data acquisition, caching, invalidation and submission boundaries for front-end server state to avoid request state being scattered among page components.
 
 ## Procedure
 
-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 并在失败时回滚。
+1. Determine the source of the state: use the request caching scheme when it comes from the server and needs caching, deduplication, refreshing, paging or mutation; use component state or store for purely local UI state.
+2. First use the existing data acquisition library of the project; when adding dependencies, you can consider TanStack Query for React/Vue/Solid/Svelte, or you can also use SWR, Nuxt/Nitro data acquisition or project encapsulation.
+3. Stable design cache key/query key: The structure contains entities, actions and all parameters that affect the results.
+4. The API function remains a pure request function, and the data hook/composable is responsible for cache, select, loading/error/empty status.
+5. Invalidation after mutation succeeds; use optimistic update when immediate feedback is needed and rollback when failure occurs.
 
 ## React Quick Start
 
@@ -45,18 +45,18 @@ export function useCreateUser() {
 }
 ```
 
-## 详细参考
+## Detailed reference
 
-涉及是否需要查询库、QueryClient 默认配置、Vue adapter、乐观更新、无限滚动查询、预取、SSR 水合和 API 层整合时，加载 [references/query-patterns.md](references/query-patterns.md)。
+Load [references/query-patterns.md](references/query-patterns.md) when it comes to whether you need a query library, QueryClient default configuration, Vue adapter, optimistic updates, infinite scroll queries, prefetching, SSR hydration, and API layer integration.
 
 ## Constraints
 
-- 相同数据必须复用相同 cache key/query key；参数缺失会造成缓存串读。
-- `staleTime` 过长会显示旧数据，过短会造成频繁请求。
-- 请求缓存库不管理本地 UI 状态；不要把 modal、输入框值放进 query cache。
-- 乐观更新必须保存快照并在失败时回滚。
-- SSR/SSG 场景必须使用框架支持的预取、水合或服务端数据边界。
+- The same data must reuse the same cache key/query key; missing parameters will cause cache string reading.
+- If `staleTime` is too long, old data will be displayed, and if it is too short, it will cause frequent requests.
+- The request cache library does not manage local UI state; do not put modal and input box values into the query cache.
+- Optimistic updates must save snapshots and rollback on failure.
+- SSR/SSG scenarios must use framework-supported prefetching, hydration, or server-side data boundaries.
 
 ## Expected Output
 
-数据获取层具备 loading/error/empty/data 状态，重复请求自动去重，mutation 后缓存正确失效或回滚，API 层与 UI 层边界清晰。
+The data acquisition layer has loading/error/empty/data status, repeated requests are automatically deduplicated, the cache is correctly invalidated or rolled back after mutation, and the boundary between the API layer and the UI layer is clear.

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

@@ -1,32 +1,32 @@
-# Server State 数据获取模式
+# Server State data acquisition mode
 
-## 先判断是否需要查询库
+## First determine whether a query library is needed
 
-- 简单静态请求、一次性提交或已有框架 loader 足够表达的页面，不必默认引入查询库。
-- 需要跨组件缓存、去重、后台刷新、分页、乐观更新、预取或 SSR hydration 时，再使用 TanStack Query、SWR、Nuxt 数据获取或项目既有请求缓存方案。
-- 查询库只管理 server state，不替代本地 UI 状态、表单状态、权限判断或 Service Worker 缓存。
+- Simple static requests, one-time submissions, or pages with sufficient expression in the existing framework loader do not need to introduce the query library by default.
+- When cross-component caching, deduplication, background refresh, paging, optimistic updates, prefetching or SSR hydration are required, use TanStack Query, SWR, Nuxt data acquisition or the project's existing request caching solution.
+- The query library only manages server state and does not replace local UI state, form state, permission judgment or Service Worker cache.
 
-## 选型参考
+## Selection reference
 
-先沿用仓库已有请求层和缓存方案；新增依赖时再按框架与复杂度选择。
+First, use the existing request layer and caching solution in the warehouse; when adding new dependencies, choose based on the framework and complexity.
 
-| 场景 | 候选方案 | 注意点 |
+| Scenarios | Alternative solutions | Notes |
 | --- | --- | --- |
-| 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 一致，避免重复请求和水合错配。 |
+| React server state | TanStack Query / SWR / Project existing package | TanStack Query is suitable for mutation, invalidation and infinite queries; SWR is suitable for lightweight read caching. |
+| Vue server state | TanStack Query Vue adapter / VueUse / Nuxt `useFetch` / Project existing package | Don’t let Vue projects copy React-only hook examples. |
+| Solid / Svelte / Cross-framework | TanStack Query corresponds to the existing resource layer of the adapter or project | The cache key, staleTime, and mutation rollback principles are consistent. |
+| Simple page requests | Framework loaders, lightweight requests within components, or API composable | Still have to handle loading/error/empty and cancellation or expiration responses. |
+| SSR / SSG | Framework prefetching, hydration or server-side data boundaries | Ensure that the server key is consistent with the client key to avoid repeated requests and hydration mismatches. |
 
-## 通用边界
+## Universal Boundary
 
-- API 函数只负责请求、解析和错误归一化，不包含 UI toast、loading 或缓存逻辑。
-- cache key/query key 必须包含所有影响响应的参数。
-- mutation 成功后按实体或列表失效；乐观更新必须先保存快照，失败时回滚。
-- 无限查询只处理数据分页；DOM 虚拟化由列表虚拟化流程处理。
-- 预取要有明确用户路径或首屏收益，不为所有可能数据提前请求。
+- API functions are only responsible for requesting, parsing and error normalization, and do not include UI toast, loading or caching logic.
+- The cache key/query key must contain all parameters that affect the response.
+- Mutation fails by entity or list after success; optimistic update must save the snapshot first and roll back when it fails.
+- Infinite queries only handle data paging; DOM virtualization is handled by the list virtualization process.
+- Prefetching must have a clear user path or above-the-fold revenue, and do not request all possible data in advance.
 
-## QueryClient 默认配置
+## QueryClient default configuration
 
 ```tsx
 const queryClient = new QueryClient({
@@ -43,11 +43,11 @@ const queryClient = new QueryClient({
 
 ## Query Key
 
-- 推荐：`["users", "list", { page, status }]`
-- 详情：`["users", "detail", userId]`
-- 所有影响请求结果的参数都必须进入 key。
+- Recommended: `["users", "list", { page, status }]`
+- Details: `["users", "detail", userId]`
+- All parameters that affect the request result must enter key.
 
-## 乐观更新
+## Optimistic update
 
 ```tsx
 const mutation = useMutation({
@@ -82,9 +82,9 @@ const feed = useInfiniteQuery({
 });
 ```
 
-虚拟列表场景将数据分页与 DOM 虚拟化分开设计。
+The virtual list scenario is designed to separate data paging and DOM virtualization.
 
-## API 层整合
+## API layer integration
 
 ```ts
 export async function getUserList(params: GetUserListParams): Promise<GetUserListResponse> {
@@ -100,4 +100,4 @@ export function useUsers(params: GetUserListParams) {
 }
 ```
 
-API 函数不包含 UI toast、loading 或缓存逻辑。
+API functions do not contain UI toast, loading or caching logic.