feat: 添加前端技术栈规范文档，包含React、Apollo、Chakra UI和MobX相关指南

Author: LessUp

rules/frontend/react/apollo-graphql/apollo-caching.mdc

@@ -1,5 +1,10 @@
 ---
-description: 利用 Apollo Client 的缓存功能来提高性能。
+description: "利用 Apollo Client 的缓存功能来提高性能"
 globs: src/**/*.js
 ---
-- 利用 Apollo Client 的缓存功能
+- **利用 Apollo Client 的缓存功能**：
+  - 优先使用 Apollo Client 的规范化缓存（Normalized Cache）来存储和管理数据，减少不必要的网络请求。
+  - 理解并配置 `fetchPolicy`，以优化数据获取策略，例如 `cache-first`、`network-only`、`cache-and-network` 等。
+  - 针对频繁变动的数据，考虑使用 `no-cache` 或 `cache-and-network` 策略，并结合订阅（Subscriptions）或轮询（Polling）实现实时更新。
+  - 对于列表数据，合理使用 `offsetLimitPagination` 或 `cursorPagination` 等策略来处理分页和无限滚动，确保缓存的有效性。
+  - 在进行数据修改（如 Mutations）后，通过 `update` 函数或 `refetchQueries` 来及时更新缓存，保持UI与后端数据的一致性。

rules/frontend/react/apollo-graphql/apollo-custom-hooks.mdc

@@ -1,5 +1,32 @@
 ---
-description: 指导为 Apollo 操作实现自定义 hooks。
+description: "指导为 Apollo 操作实现自定义 hooks"
 globs: src/hooks/**/*.js
 ---
-- 为 Apollo 操作实现自定义 hooks
+- **为 Apollo 操作实现自定义 hooks**：
+  - **封装复杂逻辑**：将重复的 Apollo Client 操作（如查询、变更、订阅）和相关逻辑封装到自定义 hooks 中，提高代码复用性。
+  - **统一错误处理和加载状态**：在自定义 hooks 中统一处理加载（`loading`）、错误（`error`）状态和数据（`data`），简化组件层的逻辑。
+  - **类型安全**：结合 TypeScript 为自定义 hooks 定义清晰的输入（变量）和输出（数据、状态）类型，确保类型安全。
+  - **可测试性**：设计易于测试的自定义 hooks，方便进行单元测试和集成测试。
+  - **示例**：
+    ```typescript
+    // hooks/useUser.ts
+    import { useQuery, gql } from '@apollo/client';
+
+    const GET_USER_QUERY = gql`
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    export const useUser = (id: string) => {
+      const { data, loading, error } = useQuery(GET_USER_QUERY, {
+        variables: { id },
+      });
+
+      return { user: data?.user, loading, error };
+    };
+    ```

rules/frontend/react/apollo-graphql/apollo-devtools.mdc

@@ -1,5 +1,11 @@
 ---
-description: 建议使用 Apollo Client DevTools 进行调试。
+description: "建议使用 Apollo Client DevTools 进行调试"
 globs: src/**/*.js
 ---
-- 使用 Apollo Client DevTools 进行调试
+- **使用 Apollo Client DevTools 进行调试**：
+  - **安装与集成**：在开发环境中安装并集成 Apollo Client DevTools 浏览器扩展，以便于调试 Apollo Client 的操作和缓存状态。
+  - **查询与变更监控**：利用 DevTools 监控所有 GraphQL 查询（Queries）、变更（Mutations）和订阅（Subscriptions）的请求与响应，包括变量、操作名称和返回数据。
+  - **缓存检查**：检查 Apollo Client 的规范化缓存（Normalized Cache）内容，理解数据如何存储、更新和失效，有助于排查数据不一致问题。
+  - **性能分析**：分析 GraphQL 请求的性能，识别潜在的瓶颈，例如慢查询或过多的网络请求。
+  - **错误诊断**：查看 GraphQL 错误信息，快速定位后端或前端数据处理中的问题。
+  - **状态管理**：观察组件如何与 Apollo Client 交互，以及数据流如何在应用中传递。

rules/frontend/react/apollo-graphql/apollo-provider-setup.mdc

@@ -1,5 +1,29 @@
 ---
-description: 要求在应用程序根部使用 Apollo Provider。
+description: "要求在应用程序根部使用 Apollo Provider"
 globs: src/App.jsx
 ---
-- 在应用程序根部使用 Apollo Provider
+- **在应用程序根部使用 Apollo Provider**：
+  - **全局可用性**：确保在 React 应用程序的根组件（例如 `App.js` 或 `index.js`）中使用 `ApolloProvider` 包裹整个应用，以便所有子组件都能访问 Apollo Client 实例。
+  - **Client 实例配置**：在 `ApolloProvider` 中传入已配置好的 `ApolloClient` 实例，该实例应包含 `uri`（GraphQL 服务器地址）和 `cache`（缓存策略，通常是 `InMemoryCache`）等必要配置。
+  - **示例**：
+    ```javascript
+    // index.js 或 App.js
+    import React from 'react';
+    import ReactDOM from 'react-dom/client';
+    import { ApolloClient, InMemoryCache, ApolloProvider, gql } from '@apollo/client';
+    import App from './App';
+
+    const client = new ApolloClient({
+      uri: 'YOUR_GRAPHQL_ENDPOINT',
+      cache: new InMemoryCache(),
+    });
+
+    ReactDOM.createRoot(document.getElementById('root')).render(
+      <React.StrictMode>
+        <ApolloProvider client={client}>
+          <App />
+        </ApolloProvider>
+      </React.StrictMode>,
+    );
+    ```
+  - **中间件与错误处理**：在 `ApolloClient` 配置中，可以添加 `link` 来处理认证、错误重试、文件上传等高级功能，例如使用 `HttpLink`、`AuthLink`、`ErrorLink` 等。

rules/frontend/react/apollo-graphql/graphql-apollo-client-usage.mdc

@@ -1,9 +1,62 @@
 ---
-description: 应用 GraphQL 和 Apollo Client 使用的最佳实践，包括状态管理、数据获取和错误处理。
+description: "应用 GraphQL 和 Apollo Client 使用的最佳实践，包括状态管理、数据获取和错误处理"
 globs: src/graphql/**/*.js
 ---
-- 使用 Apollo Client 进行状态管理和数据获取
-- 实现查询组件进行数据获取
-- 利用变更操作进行数据修改
-- 使用片段创建可重用的查询部分
-- 实现适当的错误处理和加载状态
+- **使用 Apollo Client 进行状态管理和数据获取**：
+  - 利用 `useQuery` Hook 进行数据查询，处理加载状态、错误和数据。
+  - 使用 `useMutation` Hook 执行数据修改操作，并在成功后更新缓存或重新获取相关数据。
+  - 结合 `useSubscription` Hook 实现实时数据更新。
+- **实现查询组件进行数据获取**：
+  - 推荐使用基于 Hook 的方式（如 `useQuery`）而非旧版 `Query` 组件，以更好地利用 React Hooks 的特性。
+  - 示例：
+    ```typescript
+    import { useQuery, gql } from '@apollo/client';
+
+    const GET_TODOS = gql`
+      query GetTodos {
+        todos {
+          id
+          text
+          completed
+        }
+      }
+    `;
+
+    function TodosList() {
+      const { loading, error, data } = useQuery(GET_TODOS);
+
+      if (loading) return <p>Loading...</p>;
+      if (error) return <p>Error :({error.message}</p>;
+
+      return (
+        <ul>
+          {data.todos.map(({ id, text, completed }) => (
+            <li key={id} style={{ textDecoration: completed ? 'line-through' : 'none' }}>
+              {text}
+            </li>
+          ))}
+        </ul>
+      );
+    }
+    ```
+- **利用变更操作进行数据修改**：
+  - 使用 `useMutation` Hook 发送变更请求，并利用 `update` 函数或 `refetchQueries` 选项在变更成功后更新 Apollo 缓存，确保 UI 状态与后端数据同步。
+- **使用片段创建可重用的查询部分**：
+  - 定义 GraphQL 片段（Fragments）来封装可重用的字段集，提高查询的可维护性和复用性。
+  - 示例：
+    ```graphql
+    fragment UserFields on User {
+      id
+      name
+      email
+    }
+
+    query GetUserDetails($id: ID!) {
+      user(id: $id) {
+        ...UserFields
+      }
+    }
+    ```
+- **实现适当的错误处理和加载状态**：
+  - 在组件中处理 `loading` 和 `error` 状态，向用户提供友好的加载指示和错误反馈。
+  - 可以结合 `ErrorLink` 或自定义错误边界（Error Boundaries）来集中处理 GraphQL 错误。

rules/frontend/react/apollo-graphql/graphql-error-boundaries.mdc

@@ -1,5 +1,58 @@
 ---
-description: 要求为 GraphQL 错误实现适当的错误边界。
+description: "要求为 GraphQL 错误实现适当的错误边界"
 globs: src/**/*.jsx
----
-- 为 GraphQL 错误实现适当的错误边界
+--- 
+- **为 GraphQL 错误实现适当的错误边界**：
+  - **使用 React 错误边界**：利用 React 的错误边界（Error Boundaries）来捕获组件树中由 GraphQL 操作（查询、变更、订阅）引起的 JavaScript 错误，防止整个应用崩溃。
+  - **集中错误处理**：在错误边界组件中集中处理和展示友好的错误信息，而不是让每个组件单独处理错误状态。
+  - **错误日志记录**：在错误边界中实现错误日志记录机制（例如，发送到 Sentry、Bugsnag 等错误监控服务），以便于跟踪和诊断生产环境中的问题。
+  - **用户体验**：当发生错误时，向用户显示一个回退 UI，提供重试选项或引导用户进行下一步操作，提升用户体验。
+  - **示例**：
+    ```javascript
+    // ErrorBoundary.js
+    import React from 'react';
+
+    class ErrorBoundary extends React.Component {
+      constructor(props) {
+        super(props);
+        this.state = { hasError: false, error: null, errorInfo: null };
+      }
+
+      static getDerivedStateFromError(error) {
+        // 更新 state 使下一次渲染能够显示降级后的 UI
+        return { hasError: true };
+      }
+
+      componentDidCatch(error, errorInfo) {
+        // 你同样可以将错误日志上报给服务器
+        console.error("Uncaught error:", error, errorInfo);
+        this.setState({ error, errorInfo });
+      }
+
+      render() {
+        if (this.state.hasError) {
+          // 你可以自定义降级后的 UI 并渲染
+          return (
+            <div style={{ padding: '20px', border: '1px solid red', color: 'red' }}>
+              <h2>Something went wrong.</h2>
+              <details style={{ whiteSpace: 'pre-wrap' }}>
+                {this.state.error && this.state.error.toString()}
+                <br />
+                {this.state.errorInfo.componentStack}
+              </details>
+            </div>
+          );
+        }
+
+        return this.props.children;
+      }
+    }
+
+    export default ErrorBoundary;
+
+    // 在应用中使用
+    // <ErrorBoundary>
+    //   <MyGraphQLComponent />
+    // </ErrorBoundary>
+    ```
+  - **与 Apollo Link 结合**：对于 GraphQL 网络层面的错误（如 HTTP 错误、GraphQL 格式错误），可以结合 Apollo Client 的 `ErrorLink` 进行处理，并在 `ErrorLink` 中抛出错误，使其能被 React 错误边界捕获。

rules/frontend/react/apollo-graphql/graphql-naming-conventions.mdc

@@ -1,5 +1,30 @@
 ---
-description: 要求遵循查询、变更和片段的命名约定。
+description: "要求遵循查询、变更和片段的命名约定"
 globs: src/graphql/**/*.js
 ---
-- 遵循查询、变更和片段的命名约定
+- **遵循查询、变更和片段的命名约定**：
+  - **查询（Queries）**：
+    - 使用 `get` 或 `fetch` 前缀，后跟实体名称和可选的复数形式。
+    - 示例：`getUsers`、`getUserById`、`fetchProductDetails`。
+  - **变更（Mutations）**：
+    - 使用动词前缀表示操作类型，后跟实体名称。
+    - 示例：`createUser`、`updateProduct`、`deleteComment`。
+  - **订阅（Subscriptions）**：
+    - 使用 `on` 前缀，后跟事件名称。
+    - 示例：`onNewMessage`、`onUserUpdated`。
+  - **片段（Fragments）**：
+    - 使用实体名称，后跟 `Fields` 或 `Details` 后缀。
+    - 示例：`UserFields`、`ProductDetails`。
+  - **类型（Types）和字段（Fields）**：
+    - 类型名称使用 PascalCase（大驼峰命名法）。
+    - 字段名称使用 camelCase（小驼峰命名法）。
+    - 示例：`User` 类型中的 `firstName` 字段。
+  - **枚举（Enums）**：
+    - 枚举类型名称使用 PascalCase，枚举值使用 ALL_CAPS（全大写）。
+    - 示例：`OrderStatus` 枚举中的 `PENDING`、`COMPLETED`。
+  - **变量（Variables）**：
+    - 变量名称使用 camelCase。
+    - 示例：`$userId`、`$input`。
+  - **通用原则**：
+    - 保持命名清晰、简洁、一致，能够直观地表达其用途和所操作的数据。
+    - 避免缩写，除非是广为人知的缩写（如 `ID`）。

rules/frontend/react/apollo-graphql/graphql-typescript-integration.mdc

@@ -1,5 +1,79 @@
 ---
-description: 强制使用 TypeScript 确保 GraphQL 操作的类型安全。
+description: "强制使用 TypeScript 确保 GraphQL 操作的类型安全"
 globs: src/graphql/**/*.ts
 ---
-- 对 GraphQL 操作使用 TypeScript 确保类型安全
+- **对 GraphQL 操作使用 TypeScript 确保类型安全**：
+  - **代码生成**：利用 GraphQL Code Generator 或类似工具，根据 GraphQL schema 和操作（Queries, Mutations, Subscriptions）自动生成 TypeScript 类型定义。
+  - **类型推断**：确保 `useQuery`、`useMutation` 和 `useSubscription` Hooks 的返回值（`data`, `loading`, `error`）和变量（`variables`）都具有正确的类型推断。
+  - **端到端类型安全**：从 GraphQL API 到前端组件，实现端到端的类型安全，减少运行时错误。
+  - **示例**：
+    ```typescript
+    // graphql.schema.json (部分)
+    {
+      "data": {
+        "__schema": {
+          "types": [
+            {
+              "kind": "OBJECT",
+              "name": "User",
+              "fields": [
+                { "name": "id", "type": { "kind": "NON_NULL", "ofType": { "kind": "SCALAR", "name": "ID" } } },
+                { "name": "name", "type": { "kind": "SCALAR", "name": "String" } }
+              ]
+            }
+          ]
+        }
+      }
+    }
+
+    // query.graphql
+    query GetUser($id: ID!) {
+      user(id: $id) {
+        id
+        name
+      }
+    }
+
+    // generated.ts (通过工具生成)
+    export type GetUserQueryVariables = {
+      id: string;
+    };
+
+    export type GetUserQuery = {
+      user?:  {
+        __typename?: "User";
+        id: string;
+        name?: string | null;
+      } | null;
+    };
+
+    // component.tsx
+    import { useQuery } from '@apollo/client';
+    import { GetUserQuery, GetUserQueryVariables } from './generated'; // 假设类型已生成
+
+    const GET_USER_QUERY = gql`
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    function UserProfile({ userId }: { userId: string }) {
+      const { data, loading, error } = useQuery<GetUserQuery, GetUserQueryVariables>(GET_USER_QUERY, {
+        variables: { id: userId },
+      });
+
+      if (loading) return <p>Loading...</p>;
+      if (error) return <p>Error: {error.message}</p>;
+
+      return (
+        <div>
+          <h1>{data?.user?.name}</h1>
+          <p>ID: {data?.user?.id}</p>
+        </div>
+      );
+    }
+    ```
+  - **手动类型定义（不推荐）**：在无法使用代码生成工具的情况下，可以手动定义 GraphQL 响应的 TypeScript 接口，但这容易出错且难以维护。

rules/frontend/react/apollo-graphql/react-functional-components-preference.mdc

@@ -1,5 +1,33 @@
 ---
-description: 在 React 组件中强制使用带有 hooks 的函数式组件。
+description: "在 React 组件中强制使用带有 hooks 的函数式组件"
 globs: src/components/**/*.jsx
 ---
-- 始终使用带有 hooks 的函数式组件而不是类组件。
+- **始终使用带有 hooks 的函数式组件而不是类组件**：
+  - **现代化开发**：优先使用 React Hooks（如 `useState`, `useEffect`, `useContext`, `useReducer`, `useCallback`, `useMemo` 等）进行状态管理和副作用处理，以符合 React 官方推荐的现代化开发范式。
+  - **代码简洁性**：函数式组件通常比类组件更简洁，更易于阅读和理解，尤其是在处理逻辑复用时。
+  - **逻辑复用**：通过自定义 Hooks，可以方便地在不同组件之间共享状态逻辑，避免了高阶组件（HOCs）和渲染属性（Render Props）带来的嵌套问题。
+  - **性能优化**：结合 `useCallback` 和 `useMemo` 等 Hooks，可以有效地进行性能优化，避免不必要的渲染。
+  - **可测试性**：函数式组件和 Hooks 更容易进行单元测试。
+  - **示例**：
+    ```javascript
+    // 函数式组件示例
+    import React, { useState, useEffect } from 'react';
+
+    function Counter() {
+      const [count, setCount] = useState(0);
+
+      useEffect(() => {
+        document.title = `You clicked ${count} times`;
+      }, [count]);
+
+      return (
+        <div>
+          <p>You clicked {count} times</p>
+          <button onClick={() => setCount(count + 1)}>
+            Click me
+          </button>
+        </div>
+      );
+    }
+    ```
+  - **特殊情况**：仅在极少数需要使用 `getSnapshotBeforeUpdate` 或 `componentDidCatch` 等生命周期方法时，才考虑使用类组件，但大多数场景下 Hooks 都能提供替代方案（如错误边界）。