@dtt_siye/atool 1.2.1 → 1.3.1

package/skills/project-analyze/rules/web-react.md

@@ -2,297 +2,75 @@
 
 React 项目专属分析规则，与 `rules/web.md` 配合使用。本文件中的规则优先于 `web.md` 中的同名字段。适用于 React SPA、Next.js（App Router / Pages Router）。
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `web-conventions` skill 作为规范约束。
 
-React 项目按组件树 + Hooks + 状态管理分层分析：
+## 模块发现策略
 
-```
-React 组件树
-    ├── Pages（路由级组件）
-    ├── Components（UI 组件）
-    │   ├── UI 组件（纯展示）
-    │   └── Container 组件（含逻辑）
-    ├── Hooks（自定义 Hook）
-    ├── Context / Store（全局状态）
-    ├── Services（API 调用）
-    ├── Types（TypeScript 类型）
-    └── Styles（CSS Modules / Tailwind）
-```
+React 项目按组件树 + Hooks + 状态管理分层发现模块边界：
 
-## JSX 组件分析
+- **页面模块**: `src/pages/` 或 `src/app/` 下每个子目录
+- **组件模块**: `src/components/{name}/` 下 3+ 文件的子目录
+- **状态模块**: `src/store/slices/` 或 `src/stores/` 下每个子目录
+- **Hooks 模块**: `src/hooks/` 下每个文件
 
-**扫描文件**: `src/**/*.tsx`, `app/**/*.tsx`
+不视为独立模块：单文件入口（`main.tsx`, `App.tsx`）、纯导出桶文件、`utils/`/`helpers/` 目录。
 
-**提取内容**:
-- 组件名 + 文件路径
-- Props TypeScript interface（完整字段定义）
-- Children 类型
-- 使用的自定义 Hooks（`useXxx()`）
-- JSX Element Tree（子组件结构，1-2 层深度）
-- 条件渲染逻辑
-- `key` 使用模式
+## 入口识别
 
-**输出示例**:
-```
-### UserList（Container 组件）
-- **路径**: `src/pages/system/UserList.tsx`
-- **Props Interface**:
-  ```typescript
-  interface UserListProps {
-    /** 筛选的角色 ID */
-    roleId?: string;
-    /** 是否为只读模式 */
-    readonly?: boolean;
-  }
-  ```
-- **使用的 Hooks**:
-  | Hook | 来源 | 用途 |
-  |------|------|------|
-  | useUserStore | stores/userStore | 获取用户列表和操作方法 |
-  | usePagination | hooks/usePagination | 分页逻辑 |
-  | useDebounce | hooks/useDebounce | 搜索输入防抖 |
-- **JSX 结构**（1 层）:
-  <PageHeader title="用户管理" />
-  <SearchForm onSearch={handleSearch} />
-  {loading ? <Spin /> : <UserTable data={users} onSelect={handleSelect} />}
-  <Pagination {...paginationProps} />
-  <UserFormDialog visible={dialogVisible} onClose={handleClose} />
-- **条件渲染**:
-  | 条件 | 渲染内容 |
-  |------|----------|
-  | loading | <Spin /> 加载动画 |
-  | users.length === 0 | <Empty description="暂无数据" /> |
-```
+- React Router: `src/App.tsx` 中的 `<BrowserRouter>` / `<Routes>` 结构，或 `src/routes/` 目录
+- React.lazy + Suspense: 代码分割入口，说明哪些路由是异步加载
+- Protected Route 模式: `<ProtectedRoute>` 或 `<RequireAuth>` 包裹的路由段
+- Context Provider 嵌套: `_app.tsx` 或根组件中的 Provider 树（状态、主题、认证）
 
-## 状态管理分析
+## 架构模式识别
 
-### Redux Toolkit
+通过文件结构判断组织模式：
 
-**扫描文件**: `src/store/**/*.ts`, `src/stores/**/*.ts`
+| 特征 | 架构模式 |
+|------|----------|
+| `src/pages/` + `src/components/` + `src/hooks/` | 传统分层 |
+| `src/features/{name}/{components,hooks,store}/` | Feature-based |
+| `src/domain/` + `src/infrastructure/` | Domain-driven |
+| `atoms/`, `molecules/`, `organisms/` | Atomic Design |
 
-**提取内容**:
-- Slice 名称 + Reducer 路径
-- State 接口（所有字段 + 类型 + 初始值）
-- Reducers（名称 + 参数 + 修改的 state）
-- ExtraReducers（异步 Thunk 的 pending/fulfilled/rejected）
-- Selectors（名称 + 返回类型）
+## 数据流模式
 
-**输出示例**:
-```
-### userSlice
-- **文件**: `src/store/slices/userSlice.ts`
-- **Reducer Path**: `'user'`
-- **State 接口**:
-  ```typescript
-  interface UserState {
-    list: UserVO[];
-    total: number;
-    current: UserVO | null;
-    loading: boolean;
-    error: string | null;
-  }
-  ```
-- **Reducers**:
-  | Reducer | 参数 | 说明 |
-  |---------|------|------|
-  | setCurrentUser | (state, action: PayloadAction<UserVO>) | 设置当前用户 |
-  | clearError | (state) | 清除错误信息 |
-- **ExtraReducers**:
-  | Action | State 变更 |
-  |--------|-----------|
-  | fetchUsers.pending | loading = true |
-  | fetchUsers.fulfilled | list = payload.list, total = payload.total, loading = false |
-  | fetchUsers.rejected | error = payload, loading = false |
-- **Selectors**:
-  | 名称 | 返回类型 | 说明 |
-  |------|----------|------|
-  | selectUserList | UserVO[] | 用户列表 |
-  | selectCurrentUser | UserVO \| null | 当前选中用户 |
-```
+**Redux Toolkit 检测**：扫描 `src/store/slices/`，识别 Slice 名称、State 接口、ExtraReducers（Thunk 异步）、Selectors。
 
-### Zustand
+**Zustand 检测**：扫描 `src/stores/*.ts`，识别 Store 名称、State 字段、Actions、persist/devtools 中间件。
 
-**扫描文件**: `src/stores/**/*.ts`
+**React Query / SWR 检测**：识别 `useQuery`/`useMutation`/`useSWR` 的 Query Key 和数据源。
 
-**提取内容**:
-- Store 名称 + 创建方式（`create`）
-- State 字段（名称 + 类型）
-- Actions（签名 + 说明）
-- 中间件配置（persist, devtools, immer）
+**Context API 检测**：扫描 `src/context/*.tsx`，识别 Provider 嵌套层级和 Consumer 使用位置。
 
-**输出示例**:
-```
-### useAuthStore
-- **文件**: `src/stores/authStore.ts`
-- **State**:
-  | 字段 | 类型 | 说明 |
-  |------|------|------|
-  | token | string \| null | JWT token |
-  | user | User \| null | 当前用户 |
-  | isAuthenticated | boolean | 是否已认证 |
-- **Actions**:
-  | Action | 签名 | 说明 |
-  |--------|------|------|
-  | login | (credentials: LoginForm) => Promise<void> | 登录 |
-  | logout | () => void | 登出 |
-  | setUser | (user: User) => void | 设置用户信息 |
-- **中间件**: persist (key: 'auth-store', storage: localStorage)
-```
-
-## React Router 分析
+## 分析关注点
 
-**扫描文件**: `src/routes/**/*.tsx`, `src/App.tsx`, `app/**/page.tsx`, `app/**/layout.tsx`
+- **版本检测**: React 18（Concurrent Mode/Suspense）vs React 19（Server Components/Actions）
+- **Hooks 依赖图**: `useEffect` 依赖数组问题（过度/缺少依赖），自定义 Hook 调用链
+- **Server vs Client 边界**: `'use client'` 边界在何处，哪些组件是纯 Server Component
+- **Code Splitting**: `React.lazy` 入口数量及是否按路由分割
+- **状态提升位置**: Context Provider 范围是否合理（全局 vs 局部）
 
-**提取内容**:
-- 路由配置（path + element + loader）
-- 嵌套布局（Layout + Outlet）
-- 路由参数（useParams, useSearchParams）
-- 受保护路由（ProtectedRoute 模式）
-- 代码分割（React.lazy + Suspense）
+## 输出示例
 
-**输出示例**:
 ```
-### 路由结构
-**App Router (Next.js)**:
+### 路由结构（App Router）
 app/
-├── layout.tsx              → RootLayout (全局)
-├── page.tsx                → /
+├── layout.tsx          → RootLayout（全局 Provider）
 ├── (auth)/
-│   ├── layout.tsx          → AuthLayout (居中卡片)
-│   ├── login/page.tsx      → /login
-│   └── register/page.tsx   → /register
-├── (dashboard)/
-│   ├── layout.tsx          → DashboardLayout (侧边栏+顶栏)
-│   ├── dashboard/page.tsx  → /dashboard
-│   └── settings/page.tsx   → /settings
-└── admin/
-    ├── layout.tsx          → AdminLayout
-    └── users/
-        ├── page.tsx        → /admin/users
-        └── [id]/page.tsx   → /admin/users/:id
-
-### 受保护路由
-- **组件**: `<ProtectedRoute fallback={<Redirect to="/login" />} />`
-- **检查逻辑**: useAuthStore().isAuthenticated → false → 重定向
-- **角色检查**: `<RoleGate roles={['admin']}><AdminPanel /></RoleGate>`
+│   ├── login/page.tsx  → /login（Client Component，表单交互）
+│   └── register/page.tsx → /register
+└── (dashboard)/
+    ├── layout.tsx      → DashboardLayout（侧边栏+顶栏）
+    └── dashboard/page.tsx → /dashboard（Server Component，数据预取）
+
+### useAuthStore（Zustand）
+- State: token (string|null), user (User|null), isAuthenticated (boolean)
+- Actions: login(credentials), logout(), setUser(user)
+- 中间件: persist(key: 'auth-store', storage: localStorage)
+
+### useFetch（自定义 Hook）
+- 签名: useFetch<T>(url, options?) → { data, loading, error, refetch }
+- 内部依赖: axios 实例, useAuthStore (获取 token)
+- 副作用: enabled 参数控制是否自动请求
 ```
-
-## 自定义 Hooks 分析
-
-**扫描文件**: `src/hooks/**/*.ts`, `src/hooks/**/*.tsx`
-
-**提取内容**:
-- Hook 名称 + 路径
-- 参数签名（TypeScript 类型）
-- 返回值签名（TypeScript 类型）
-- 内部依赖（API 调用、其他 Hook、Context）
-- 副作用（useEffect 中的逻辑）
-
-**输出示例**:
-```
-### useFetch
-- **路径**: `src/hooks/useFetch.ts`
-- **签名**:
-  ```typescript
-  function useFetch<T>(
-    url: string,
-    options?: {
-      params?: Record<string, string>;
-      enabled?: boolean;
-      retry?: number;
-    }
-  ): {
-    data: T | null;
-    loading: boolean;
-    error: Error | null;
-    refetch: () => void;
-  }
-  ```
-- **内部依赖**: axios 实例, useAuthStore (获取 token)
-- **副作用**: 组件挂载时自动请求；`enabled` 参数控制是否自动请求
-```
-
-## 样式分析
-
-### CSS Modules
-
-**扫描文件**: `src/**/*.module.css`, `src/**/*.module.scss`
-
-**提取内容**:
-- CSS Module 文件列表
-- 导出的 class 名称
-
-### Tailwind CSS
-
-**扫描文件**: `tailwind.config.*`, `src/**/*.tsx` 中的 Tailwind 类名
-
-**提取内容**:
-- 自定义颜色（`theme.extend.colors`）
-- 自定义间距（`theme.extend.spacing`）
-- 自定义断点（`theme.extend.screens`）
-- 常用组件的 Tailwind 类模式
-
-**输出示例**:
-```
-### Tailwind 自定义配置
-**来源**: `tailwind.config.ts`
-| Token | 值 | 用途 |
-|-------|------|------|
-| colors.primary | '#3B82F6' | 主色调 |
-| colors.secondary | '#8B5CF6' | 辅助色 |
-| screens.xl | '1440px' | 超大屏 |
-| spacing.sidebar | '280px' | 侧边栏宽度 |
-```
-
-## 输出模板
-
-### COMPONENT.md 章节结构（React 特有）
-
-```markdown
-# 组件文档
-
-## Pages（页面组件）
-按路由分组，每个页面包含:
-- 路径 + 布局组件
-- Props Interface
-- 使用的 Hooks
-- JSX 结构（1-2 层）
-- 路由参数 / Query 参数
-
-## Components（UI 组件）
-### Container 组件（含业务逻辑）
-### UI 组件（纯展示）
-
-## Hooks
-自定义 Hook 列表及文档
-
-## Store 详解
-Redux Slices / Zustand Stores 完整文档
-
-## 路由详解
-路由结构 + 保护逻辑 + 代码分割
-```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 页面/视图层 | `src/pages/`, `src/app/` | 每个子目录 | 目录名 kebab-case |
-| API/服务层 | `src/services/`, `src/api/` | 每个子目录 | 目录名 kebab-case |
-| 状态管理层 | `src/store/`, `src/stores/` | 每个子目录 | 目录名 kebab-case |
-| 组件层 | `src/components/{name}/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| Hooks 层 | `src/hooks/` | 每个文件 | 文件名去后缀 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `main.tsx`, `App.tsx`, `index.ts`）
-- 纯导出桶文件（`index.ts` 仅有 re-export）
-- 工具函数目录（`utils/`, `helpers/`）— 合并为一个模块
-
-## Token 管理
-
-- 每个子任务分析 ≤10 个 `.tsx` 文件
-- Store / Slice 文件单独分组
-- 自定义 Hook 文件单独分组
-- Context Provider 文件单独分组