@dtt_siye/atool 1.3.0 → 1.4.0

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

@@ -1,52 +1,43 @@
 # Web 项目分析规则
 
-通用 Web 项目分析规则，适用于 React、Vue、Next.js、Svelte 等前端框架。如检测到具体框架（Vue 3 / React），会同时加载 `rules/web-vue.md` 或 `rules/web-react.md` 作为补充。
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `web-conventions` skill 作为规范约束。
 
-## 分析粒度
+## 模块发现策略
 
-按页面、组件目录和功能模块进行分析，分层结构为：
+按路由/视图目录识别模块边界：
 
-```
-用户界面 (UI)
-    ↓
-页面/路由 (Pages/Router)
-    ↓
-组件 (Components)
-    ↓
-Hooks/Composables (逻辑复用)
-    ↓
-状态管理 (Store/Context)
-    ↓
-服务/API (Services)
-    ↓
-工具/类型 (Utils/Types)
-```
+- **Next.js App Router**: `app/` 下每个一级路由目录（排除 `api/`、`layout.tsx`）为一个页面模块
+- **Next.js Pages Router**: `pages/` 下每个文件/目录为一个路由模块
+- **React SPA**: `src/pages/` 下每个文件为一个路由模块
+- **Vue 项目**: `src/views/` 下每个子目录为一个页面模块
+- **Feature-based 结构**: `src/features/{feature}/` 下的子目录
+- **组件层**: `src/components/{name}/` 下有 3+ 文件的子目录
 
-## 目录扫描策略
+不视为独立模块：单文件入口（`main.ts`, `App.vue`, `index.ts`）、纯导出桶文件、`utils/`/`helpers/` 目录（合并为一个模块）。
 
-### 1. 识别框架类型
+## 入口识别
 
 **信号文件检测：**
-- Next.js: `app/` 或 `pages/` 目录 + `next.config.js` / `next.config.mjs`
-- React SPA: `src/App.tsx` + `react-router` 依赖
-- Vue/Nuxt: `src/views/` + `vue-router` 依赖，或 Nuxt 的 `pages/` 目录
-- SvelteKit: `src/routes/` + `svelte.config.js`
-- Vite 项目: `vite.config.ts` / `vite.config.js`
+
+| 框架 | 信号文件 |
+|------|----------|
+| Next.js App Router | `app/layout.tsx` 或 `app/layout.js` |
+| Next.js Pages Router | `pages/_app.tsx` 或 `pages/_app.js` |
+| React SPA | `src/App.tsx` + `react-router` 依赖 |
+| Vue/Nuxt | `src/views/` + `vue-router` 依赖，或 Nuxt 的 `pages/` |
+| SvelteKit | `src/routes/` + `svelte.config.js` |
+| Vite 项目 | `vite.config.ts` / `vite.config.js` |
 
 **微前端检测：**
-- qiankun: `main.js` 中包含 `registerMicroApps`，子应用有 `vue.config.js` 中 `devServer.headers`
-- Module Federation: `webpack.config.js` 中包含 `ModuleFederationPlugin`
+- qiankun: `main.js` 含 `registerMicroApps`
+- Module Federation: `webpack.config.js` 含 `ModuleFederationPlugin`
 - single-spa: `import-map.json` 或 `single-spa` 依赖
 
-**Monorepo 检测：**
-- `pnpm-workspace.yaml` → pnpm workspace
-- `lerna.json` → Lerna monorepo
-- `nx.json` → Nx monorepo
-- `package.json` 中 `workspaces` 字段
+**Monorepo 检测：** `pnpm-workspace.yaml` / `lerna.json` / `nx.json` / `package.json workspaces`
 
-### 2. 依赖提取
+## 架构模式识别
 
-从 `package.json` 提取关键依赖并分类：
+从 `package.json` 提取依赖后判断架构：
 
 | 类别 | 依赖示例 |
 |------|----------|
@@ -54,337 +45,54 @@ Hooks/Composables (逻辑复用)
 | UI 库 | element-plus, antd, vuetify, shadcn/ui, tailwindcss |
 | 状态管理 | zustand, redux-toolkit, pinia, vuex, mobx |
 | 路由 | react-router, vue-router, @tanstack/router |
-| 请求库 | axios, fetch, swr, @tanstack/react-query |
-| 构建工具 | vite, webpack, turbopack, rollup |
-| CSS 方案 | tailwindcss, sass, styled-components, css-modules |
-| 测试 | vitest, jest, cypress, playwright |
-| 代码质量 | eslint, prettier, typescript, husky |
-
-### 3. 按层扫描路径
+| 请求库 | axios, swr, @tanstack/react-query |
+| 构建工具 | vite, webpack, turbopack |
 
+按层扫描路径：
 - **页面层**: `src/pages/`, `app/`, `src/views/`, `src/routes/`
 - **组件层**: `src/components/`, `src/ui/`, `src/shared/`
-- **逻辑层**: `src/hooks/`, `src/composables/`, `src/directives/`
+- **逻辑层**: `src/hooks/`, `src/composables/`
 - **状态层**: `src/stores/`, `src/store/`, `src/context/`, `src/redux/`
-- **服务层**: `src/services/`, `src/api/`, `src/request/`, `src/http/`
-- **工具层**: `src/utils/`, `src/lib/`, `src/helpers/`, `src/constants/`
-- **类型层**: `src/types/`, `src/interfaces/`, `src/schemas/`
-- **样式层**: `src/styles/`, `src/assets/css/`, `src/themes/`
-- **国际化**: `src/locales/`, `src/i18n/`, `src/lang/`
+- **服务层**: `src/services/`, `src/api/`, `src/request/`
 - **权限**: `src/permission/`, `src/auth/`, `src/guards/`
+- **国际化**: `src/locales/`, `src/i18n/`
 
-### 4. 模块发现规则
+## 数据流模式
 
-- Next.js App Router: `app/` 下的每个一级目录（排除 `api/`, `layout.tsx`）为一个页面模块
-- Next.js Pages Router: `pages/` 下的每个文件/目录为一个路由模块
-- React SPA: `src/pages/` 下的每个文件为一个路由模块
-- Vue 项目: `src/views/` 下的每个子目录为一个页面模块
-- Feature-based 结构: `src/features/{feature}/` 下的子目录
-- 组件目录按子目录分组（如 `components/ui/`, `components/business/`）
+识别状态管理方案并记录跨 Store 依赖关系：
+- **Redux Toolkit**: `src/store/slices/` — Slice → Selector → ExtraReducer (Thunk)
+- **Zustand**: `src/stores/*.ts` — Store → persist middleware
+- **Pinia**: `src/stores/modules/` — defineStore Options/Setup → 跨 Store 依赖
+- **Context API**: `src/context/*.tsx` — Provider 嵌套层级
 
-## 各层提取规则
+权限认证数据流：登录 → token 存储 → 请求拦截器注入 → 401 刷新链路
 
-### 层 1: 路由/入口层
+## 分析关注点
 
-**扫描文件**: `src/router/index.ts`, `src/routes.ts`, `app/**/page.tsx`, `app/**/layout.tsx`
+- **路由守卫**: `beforeEach` / `ProtectedRoute` 链路，权限模型（RBAC/ABAC）
+- **版本检测**: React 18 vs 19（并发特性）、Vue 2 vs 3（Options vs Composition API）
+- **构建工具**: Vite（`vite.config.ts`）vs Webpack vs Turbopack
+- **国际化**: 支持的语言列表、i18n 框架（vue-i18n / react-i18next / next-intl）
+- **微前端**: 主/子应用关系、共享状态方案、共享代码重复度
 
-**提取内容**:
-- 路由配置（路径 + 对应组件 + 路由 meta）
-- 嵌套路由结构
-- 路由守卫（权限检查、登录拦截）
-- 布局组件层级
+## 输出示例
 
-**输出示例**:
 ```
 ### 路由结构
-
 / (Layout: DefaultLayout)
-├── /login                          → LoginPage         [公开]
-├── /dashboard                      → DashboardPage     [需认证]
-├── /system
-│   ├── /system/user                → UserPage          [admin]
-│   ├── /system/role                → RolePage          [admin]
-│   └── /system/menu                → MenuPage          [admin]
-└── /404                            → NotFoundPage      [公开]
+├── /login              → LoginPage         [公开]
+├── /dashboard          → DashboardPage     [需认证]
+└── /system
+    ├── /system/user    → UserPage          [admin]
+    └── /system/role    → RolePage          [admin]
 
 ### 路由守卫链路
 router.beforeEach → 检查 token → 无 token → 跳转 /login
-                                  → 有 token → 检查权限 → 放行 / 403
-```
-
-### 层 2: 状态管理层
-
-**扫描文件**: `src/stores/**/*.ts`, `src/store/**/*.ts`, `src/context/**/*.tsx`
-
-**提取内容**:
-- Store ID / 名称
-- State 接口（所有字段的类型和初始值）
-- Getters / 计算属性
-- Actions（参数 + 调用的 API + 修改的 state）
-- 跨 Store 依赖
-- 持久化配置
+                                → 有 token → 检查权限 → 放行 / 403
 
-**输出示例**:
-```
 ### useUserStore
-- **文件**: `src/stores/modules/user.ts`
-- **State 接口**:
-  | 字段 | 类型 | 初始值 | 说明 |
-  |------|------|--------|------|
-  | token | string | '' | JWT token |
-  | userInfo | UserInfo \| null | null | 当前用户信息 |
-  | roles | string[] | [] | 角色列表 |
-- **Getters**:
-  | 名称 | 返回类型 | 说明 |
-  |------|----------|------|
-  | isAdmin | boolean | 是否管理员 |
-  | avatar | string | 用户头像 URL |
-- **Actions**:
-  | Action | 参数 | 调用的 API | 说明 |
-  |--------|------|-----------|------|
-  | login | (data: LoginForm) | authApi.login() | 登录并存储 token |
-  | getUserInfo | () | userApi.getInfo() | 获取用户信息 |
-  | logout | () | - | 清空状态并跳转 |
-- **跨 Store 依赖**: usePermissionStore（登录后同步权限）
-- **持久化**: localStorage, key: 'user-store'
-```
-
-### 层 3: 服务/API 层
-
-**扫描文件**: `src/api/**/*.ts`, `src/services/**/*.ts`, `src/request/**/*.ts`
-
-**提取内容**:
-- API 基础配置（baseURL、超时、拦截器）
-- API 函数列表（路径 + 方法 + 参数 + 返回类型）
-- Token 注入方式
-- 错误处理策略
-- 请求/响应拦截器逻辑
-
-**输出示例**:
-```
-### API 基础配置
-- **实例文件**: `src/utils/request.ts`
-- **baseURL**: `/api/v1`
-- **超时**: 15000ms
-- **Token 注入**: 请求拦截器从 localStorage 读取 token，添加 `Authorization: Bearer {token}` header
-- **错误处理**: 401 → 跳转登录；403 → 提示无权限；500 → 提示服务器错误
-
-### 用户模块 API
-| 函数 | 方法 | 路径 | 参数 | 返回类型 |
-|------|------|------|------|----------|
-| getUserPage | GET | /system/user/list | { pageNum, pageSize, ...query } | PageResult<UserVO> |
-| getUserDetail | GET | /system/user/:id | { id: string } | R<UserVO> |
-| createUser | POST | /system/user | CreateUserDTO | R<void> |
-| updateUser | PUT | /system/user | UpdateUserDTO | R<void> |
-| deleteUser | DELETE | /system/user/:id | { id: string } | R<void> |
-```
-
-### 层 4: 组件层
-
-**扫描文件**: `src/components/**/*.vue`, `src/components/**/*.tsx`
-
-**提取内容**:
-- 组件名称 + 路径
-- Props/参数定义（类型 + 是否必填 + 默认值）
-- Events/Emits（事件名 + 载荷类型）
-- Slots（插槽名 + 用途）
-- 依赖的 Store / API / 其他组件
-- 组件分类（基础组件 / 业务组件 / 页面组件）
-
-**输出示例**:
-```
-### UserList（业务组件）
-- **路径**: `src/views/system/user/index.vue`
-- **Props**:
-  | Prop | Type | Required | Default | Description |
-  |------|------|----------|---------|-------------|
-  | loading | boolean | No | false | 加载状态 |
-- **Emits**:
-  | Event | Payload | Description |
-  |-------|---------|-------------|
-  | refresh | () => void | 刷新列表 |
-  | edit | (row: UserVO) => void | 编辑用户 |
-- **使用的 Store**: useUserStore
-- **使用的 API**: getUserPage(), deleteUser()
-- **依赖组件**: UserForm, DictTag, Pagination
-```
-
-### 层 5: Hooks/Composables 层
-
-**扫描文件**: `src/hooks/**/*.ts`, `src/composables/**/*.ts`
-
-**提取内容**:
-- Hook 名称 + 路径
-- 参数签名
-- 返回值签名
-- 内部使用的 API / Store
-- 副作用说明
-
-**输出示例**:
+- State: token (string), userInfo (UserInfo|null), roles (string[])
+- Actions: login() → authApi.login(), logout() → 清空状态
+- 跨 Store 依赖: usePermissionStore（登录后同步权限）
+- 持久化: localStorage, key: 'user-store'
 ```
-### useTable
-- **路径**: `src/hooks/useTable.ts`
-- **签名**: `useTable<T>(fetchFn: (params) => Promise<PageResult<T>>, initialParams?)`
-- **返回值**:
-  | 字段 | 类型 | 说明 |
-  |------|------|------|
-  | tableData | Ref<T[]> | 表格数据 |
-  | loading | Ref<boolean> | 加载状态 |
-  | pagination | Reactive<PageParams> | 分页参数 |
-  | search | (params?) => void | 搜索方法 |
-  | refresh | () => void | 刷新当前页 |
-```
-
-### 层 6: 权限/认证层
-
-**扫描文件**: `src/permission/**/*.ts`, `src/auth/**/*.ts`, `src/directives/**/*.ts`
-
-**提取内容**:
-- 认证流程（登录 → token 存储 → token 刷新）
-- 权限模型（RBAC / ABAC）
-- 权限指令（如 `v-permission`）
-- 路由守卫逻辑
-
-**输出示例**:
-```
-### 认证流程
-用户登录 → POST /auth/login → 获取 token + refreshToken
-  → 存储 localStorage → 设置 Axios header
-  → 请求 401 → 使用 refreshToken 刷新 → 刷新失败 → 跳转登录页
-
-### 权限模型
-RBAC（基于角色的访问控制）
-- 用户 → 角色 → 菜单/按钮权限
-- 权限存储在 usePermissionStore.permissions: string[]（如 ['system:user:add']）
-- 指令 v-permission="['system:user:add']" 控制按钮显示
-```
-
-### 层 7: 国际化层
-
-**扫描文件**: `src/locales/**/*.ts`, `src/i18n/**/*.json`
-
-**提取内容**:
-- 支持的语言列表
-- i18n 框架（vue-i18n / react-i18next / next-intl）
-- 语言切换机制
-- 翻译文件结构
-
-### 层 8: 样式/设计系统层
-
-**扫描文件**: `src/styles/**`, `src/assets/css/**`, `tailwind.config.*`, `theme.ts`
-
-**提取内容**:
-- CSS 变量定义（`:root` / `.dark`）
-- SCSS 变量（`$color-primary`）
-- Tailwind 配置（`theme.extend`）
-- UI 库主题定制
-- 暗色模式实现方式
-- 响应式断点
-
-**输出示例**:
-```
-### 颜色系统（从 styles/variables.scss 提取）
-| 变量名 | 值 | 用途 |
-|--------|------|------|
-| --el-color-primary | #00a3e0 | 主色调 |
-| --el-color-primary-light-3 | #33b7e9 | 主色调浅色 |
-| --el-color-success | #67c23a | 成功状态 |
-| --el-color-warning | #e6a23c | 警告状态 |
-| --el-color-danger | #f56c6c | 危险状态 |
-
-### 暗色模式
-通过 html.dark class 切换，CSS 变量在 `styles/dark.scss` 中覆盖
-
-### 响应式断点
-| 名称 | 宽度 | 用途 |
-|------|------|------|
-| sm | ≥640px | 手机横屏 |
-| md | ≥768px | 平板 |
-| lg | ≥1024px | 桌面 |
-| xl | ≥1280px | 大屏 |
-```
-
-## 输出模板
-
-### README.md 章节结构
-
-```markdown
-# {项目名}
-
-## 项目概述
-业务描述 + 项目目标
-
-## 技术栈
-| 技术 | 版本 | 用途 |
-|------|------|------|
-
-## 架构设计
-### 架构图（ASCII）
-### 数据流图
-用户操作 → 事件处理 → Store → API → 响应 → UI 更新
-
-## 目录结构
-带注释的文件树
-
-## 路由结构
-路由树 + 权限标注
-
-## 状态管理
-Store 关系图 + 核心 Store 说明
-
-## API 接口
-按模块分组的 API 端点表
-
-## 认证与权限
-登录流程 + 权限模型
-
-## 构建 & 部署
-构建命令 + 环境变量 + 部署方式
-
-## 开发指南
-新增页面/组件/API 的步骤
-```
-
-### COMPONENT.md 章节结构
-
-```markdown
-# 组件文档
-
-## 基础组件
-项目内封装的通用组件（不含第三方 UI 库）
-
-## 业务组件
-按功能模块分组的业务组件
-
-## Hooks / Composables
-可复用的逻辑 Hook
-
-## 跨模块依赖关系
-模块间调用关系的 ASCII 图
-```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 页面/视图层 | `src/views/`, `src/pages/` | 每个子目录 | 目录名 kebab-case |
-| API/服务层 | `src/api/`, `src/services/` | 每个子目录 | 目录名 kebab-case |
-| 状态管理层 | `src/store/modules/`, `src/stores/` | 每个子目录 | 目录名 kebab-case |
-| 组件层 | `src/components/{name}/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| Hooks 层 | `src/hooks/` | 每个文件 | 文件名去后缀 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `main.ts`, `App.vue`, `index.ts`）
-- 纯导出桶文件（`index.ts` 仅有 re-export）
-- 工具函数目录（`utils/`, `helpers/`）— 合并为一个模块
-
-## Token 管理
-
-- 大组件目录（>15 文件）拆分为子任务
-- 每个子任务分析 ≤10 文件
-- `package.json` 分析单独一个子任务
-- 样式相关文件（CSS/Theme）单独一个子任务
-- 微前端项目：每个子应用作为独立分析单元
-- Monorepo 项目：每个 workspace 子包作为独立分析单元