@dtt_siye/atool 1.3.0 → 1.4.0

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

@@ -2,377 +2,83 @@
 
 Vue 3 项目专属分析规则，与 `rules/web.md` 配合使用。本文件中的规则优先于 `web.md` 中的同名字段。
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `web-conventions` skill 作为规范约束。
 
-Vue 3 项目按 SFC（Single File Component）三段式 + Composition API 分层分析：
+## 模块发现策略
 
-```
-<template> — UI 结构层（el-* 组件引用、v-if/v-for、事件绑定）
-<script setup> — 逻辑层（defineProps、defineEmits、composables、生命周期）
-<style> — 样式层（scoped SCSS、CSS 变量、设计 Token）
-```
-
-## Vue SFC 三段式分析
-
-### Template 段分析
-
-**扫描文件**: `src/**/*.vue` 的 `<template>` 部分
-
-**提取内容**:
-- 使用的 UI 库组件（如 `el-table`, `el-form`）
-- 条件渲染（`v-if` / `v-show` 的条件变量）
-- 列表渲染（`v-for` 的数据源变量）
-- 事件绑定（`@click`, `@change` 等关联的方法）
-- 动态组件（`<component :is="...">`）
-- 插槽使用（`<slot name="...">`）
-
-**输出示例**:
-```
-### UserList — Template 分析
-- **UI 库组件**: el-table, el-table-column, el-pagination, el-dialog, el-form
-- **条件渲染**:
-  | 指令 | 条件变量 | 用途 |
-  |------|----------|------|
-  | v-if="loading" | loading | 显示加载遮罩 |
-  | v-if="dialogVisible" | dialogVisible | 显示编辑弹窗 |
-- **列表渲染**:
-  | 指令 | 数据源 | 迭代变量 |
-  |------|--------|----------|
-  | v-for="item in tableData" | tableData | item |
-- **事件绑定**:
-  | 事件 | 处理方法 | 说明 |
-  |------|----------|------|
-  | @selection-change="handleSelectionChange" | handleSelectionChange | 多选变更 |
-  | @size-change="handleSizeChange" | handleSizeChange | 切换每页条数 |
-```
-
-### Script Setup 段分析
-
-**扫描文件**: `src/**/*.vue` 的 `<script setup>` 部分
-
-**提取内容**:
-- `defineProps<T>()` — Props 类型定义
-- `defineEmits<T>()` — 事件定义
-- `ref()` / `reactive()` / `computed()` — 响应式变量
-- `onMounted()` / `watch()` / `watchEffect()` — 生命周期和监听
-- 引入的 composables（`useXxx()`）
-- 引入的 API 函数
-
-**输出示例**:
-```
-### UserForm — Script Setup 分析
-- **Props**:
-  ```typescript
-  defineProps<{
-    visible: boolean
-    userId?: string
-  }>()
-  ```
-- **Emits**:
-  ```typescript
-  defineEmits<{
-    (e: 'update:visible', val: boolean): void
-    (e: 'refresh'): void
-  }>()
-  ```
-- **响应式变量**:
-  | 名称 | 类型 | 初始值 | 说明 |
-  |------|------|--------|------|
-  | formRef | Ref<FormInstance> | null | 表单引用 |
-  | formData | Reactive<UserForm> | {...} | 表单数据 |
-  | rules | Reactive<FormRules> | {...} | 校验规则 |
-  | loading | Ref<boolean> | false | 提交加载状态 |
-- **生命周期**:
-  | Hook | 行为 |
-  |------|------|
-  | watch(() => props.visible) | 弹窗打开时重置表单 |
-  | watch(() => props.userId) | userId 变化时获取用户详情 |
-- **引入的 composables**: useDict('sys_normal_disable')
-- **引入的 API**: getUserDetail(), createUser(), updateUser()
-```
-
-### Style 段分析
-
-**扫描文件**: `src/**/*.vue` 的 `<style>` 部分 + 全局样式文件
-
-**提取内容**:
-- `scoped` / 非 scoped 标识
-- 使用的 CSS 预处理器（SCSS / Less）
-- 组件内的 CSS 变量引用
-- 全局样式覆盖
+Vue 项目按 SFC（Single File Component）三段式 + Composition API 发现模块边界：
 
-## Pinia Store 分析
+- **页面模块**: `src/views/{module}/` 下每个子目录
+- **组件模块**: `src/components/{name}/` 下 3+ 文件的子目录
+- **状态模块**: `src/store/modules/` 或 `src/stores/` 下每个子目录
+- **Composables 模块**: `src/composables/` 下每个文件
 
-**扫描文件**: `src/stores/**/*.ts`, `src/store/**/*.ts`
-
-**提取内容**:
-- `defineStore` 的 ID 和配置模式（Setup Store / Options Store）
-- State 完整接口（所有字段 + 类型）
-- Getters（名称 + 返回类型 + 计算逻辑摘要）
-- Actions（签名 + 内部调用的 API + 修改的 state 字段）
-- 跨 Store 依赖（在 Action 中调用了其他 Store 的 Action/Getter）
-- `persist` 插件配置（存储 key、存储位置、需要持久化的字段）
-
-**输出示例**:
-```
-### useUserStore（Options Store）
-- **文件**: `src/stores/modules/user.ts`
-- **Store ID**: `'user'`
-- **State 接口**:
-  ```typescript
-  interface UserState {
-    token: string
-    userInfo: UserInfo | null
-    roles: string[]
-    permissions: string[]
-  }
-  ```
-  | 字段 | 类型 | 说明 |
-  |------|------|------|
-  | token | string | JWT token |
-  | userInfo | UserInfo \| null | 用户详情 |
-  | roles | string[] | 角色标识列表 |
-  | permissions | string[] | 权限标识列表（如 ['system:user:add']） |
+不视为独立模块：单文件入口（`main.ts`, `App.vue`, `index.ts`）、纯导出桶文件、`utils/`/`helpers/` 目录。
 
-- **Getters**:
-  | 名称 | 返回类型 | 计算逻辑 |
-  |------|----------|----------|
-  | isAdmin | boolean | roles.includes('admin') |
-  | userName | string | userInfo?.nickname ?? '' |
+## 入口识别
 
-- **Actions**:
-  | Action | 签名 | 调用 API | 修改的 State |
-  |--------|------|----------|--------------|
-  | login | (loginData: LoginForm) => Promise<void> | authApi.login() | token |
-  | getInfo | () => Promise<void> | userApi.getUserInfo() | userInfo, roles, permissions |
-  | logout | () => Promise<void> | - | 全部重置 |
+- 路由配置文件: `src/router/index.ts`，识别静态路由 vs 动态路由（`router.addRoute()`）
+- 组件映射: `import.meta.glob('../views/**/*.vue')` — 动态路由加载模式
+- 微前端检测: `main.ts` 含 `registerMicroApps`（qiankun），`vue.config.js` 含 `devServer.headers`
 
-- **跨 Store 依赖**:
-  - login 成功后调用 `usePermissionStore().generateRoutes(roles)`
-- **持久化**: pinia-plugin-persistedstate, key: 'user', pick: ['token']
-```
+## 架构模式识别
 
-## Vue Router 分析
+通过文件结构判断 Vue 2 vs Vue 3 及组织模式：
 
-**扫描文件**: `src/router/**/*.ts`
+| 特征 | 判断 |
+|------|------|
+| `<script setup>` + `defineProps` | Vue 3 Composition API |
+| `export default { data(), methods: {} }` | Vue 2 Options API |
+| `src/composables/` 目录 | Composition API 逻辑复用 |
+| `src/store/modules/` | Vuex 模块化 |
+| `src/stores/` + `defineStore` | Pinia |
+| `src/views/` + `src/api/` + `src/store/` 三层结构 | 标准后台管理系统架构 |
 
-**提取内容**:
-- 静态路由 vs 动态路由（从后端获取的菜单路由）
-- 路由 meta 字段规范（title, icon, roles, hidden, keepAlive 等）
-- 路由守卫（beforeEach 链路）
-- 动态路由加载方式（`router.addRoute()` vs 组件映射）
-- keep-alive 缓存策略
+**qiankun 微前端识别**：主应用 `registerMicroApps` 列表（name, entry, activeRule），子应用生命周期钩子（bootstrap/mount/unmount），共享状态方案（initGlobalState/props 传递）。
 
-**输出示例**:
-```
-### 路由配置
-- **模式**: createWebHistory()
-- **静态路由**:
-  | 路径 | 组件 | Meta.title | Meta.hidden | 权限 |
-  |------|------|------------|-------------|------|
-  | /login | LoginPage | '登录' | true | 公开 |
-  | /redirect/:path(.*) | RedirectPage | - | true | 公开 |
-  | /404 | NotFoundPage | '404' | true | 公开 |
+## 数据流模式
 
-- **动态路由**: 通过 `router.addRoute()` 从后端菜单数据动态生成
-  - 数据源: `usePermissionStore().menuRoutes`
-  - 组件映射: `import.meta.glob('../views/**/*.vue')`
+**Pinia 检测**：扫描 `src/stores/**/*.ts`，识别：
+- defineStore 配置模式（Options Store / Setup Store）
+- State 接口完整字段 + 类型
+- Actions 调用的 API 函数
+- 跨 Store 依赖（Action 中调用其他 Store）
+- pinia-plugin-persistedstate 配置（key、pick 字段）
 
-- **路由 Meta 规范**:
-  ```typescript
-  interface RouteMeta {
-    title: string        // 页面标题
-    icon?: string        // 菜单图标
-    roles?: string[]     // 允许访问的角色
-    hidden?: boolean     // 是否在菜单中隐藏
-    keepAlive?: boolean  // 是否缓存
-    affix?: boolean      // 是否固定在标签栏
-  }
-  ```
+**Vuex 检测**：扫描 `src/store/modules/**/*.ts`，识别模块命名空间、mutations/actions/getters。
 
-- **路由守卫链路**:
-  beforeEach → NProgress.start()
-    → 白名单检查（无需 token 的页面直接放行）
-    → 有 token → 已获取用户信息？→ 放行 : 调用 getInfo()
-    → 无 token → 白名单？→ 放行 : 跳转 /login?redirect={原路径}
-```
+**Vue Router 数据流**：
+- 静态路由 vs 动态路由（后端菜单 → `router.addRoute()`）
+- 路由 meta 规范（title/icon/roles/hidden/keepAlive/affix）
+- 路由守卫 beforeEach 链路（NProgress → 白名单 → token 检查 → 权限检查）
 
-## qiankun 微前端分析（如适用）
+## 分析关注点
 
-**扫描文件**: 主应用 `main.ts`, 子应用 `main.ts`, `vue.config.js`
+- **Vue 版本检测**: Vue 2（`vue: ^2.x`）vs Vue 3（`vue: ^3.x`），Composition API 使用比例
+- **响应式系统**: `ref()` vs `reactive()` 使用模式，`computed()` 依赖关系，`watch` vs `watchEffect`
+- **SFC 三段式分析**: `<template>` 中的 UI 库组件引用、`<script setup>` 中的 composables、`<style scoped>` 中的 CSS 变量引用
+- **keep-alive 缓存策略**: 哪些路由/组件配置了 keepAlive，缓存边界
+- **Axios 封装**: 请求/响应拦截器逻辑，token 注入方式，错误码映射
 
-**提取内容**:
-- 主应用注册的子应用列表（name + entry + activeRule）
-- 子应用的生命周期钩子（bootstrap, mount, unmount）
-- 共享状态方案（initGlobalState / props 传递）
-- 子应用间通信方式
+## 输出示例
 
-**输出示例**:
-```
-### 微前端架构（qiankun）
-- **主应用**: locode-front (port: 3000)
-- **子应用列表**:
-  | 名称 | 入口 | 激活规则 | 端口 |
-  |------|------|----------|------|
-  | sub-app-a | //localhost:3001 | /sub-a | 3001 |
-  | sub-app-b | //localhost:3002 | /sub-b | 3002 |
-- **共享状态**: 主应用通过 props 传递 token、userInfo
-- **通信方式**: CustomEvent + initGlobalState
 ```
+### useUserStore（Pinia Options Store）
+- Store ID: 'user'
+- State: token (string), userInfo (UserInfo|null), roles (string[]), permissions (string[])
+- Getters: isAdmin → roles.includes('admin')
+- Actions: login(loginData) → authApi.login() → 修改 token；getInfo() → userApi.getUserInfo() → 修改 userInfo/roles/permissions
+- 跨 Store: login 成功后调用 usePermissionStore().generateRoutes(roles)
+- 持久化: pinia-plugin-persistedstate, key: 'user', pick: ['token']
 
-**微前端文档交叉引用提取**：
+### 路由守卫链路
+beforeEach → NProgress.start() → 白名单检查（放行）
+  → 有 token → 已获取用户信息？→ 放行 : 调用 getInfo()
+  → 无 token → 白名单？→ 放行 : 跳转 /login?redirect={原路径}
 
-当检测到 qiankun 微前端架构时，额外提取以下信息用于根目录文档交叉引用：
-- 主应用注册的每个子应用的 **docs/ 路径映射**
-- 子应用间的 **共享组件/工具**（标注是否重复实现）
-- 共享依赖 **版本对比表**
-
-输出到 `.atool-docs/micro-frontend-map.json`：
-```json
-{
-  "main_app": {
-    "name": "locode-front-master-vue3",
-    "docs_path": "./docs/"
-  },
-  "sub_apps": [
-    {
-      "name": "system",
-      "entry": "//localhost:10010/system/",
-      "docs_path": "../locode-front-system-vue3/docs/",
-      "shared_with_main": ["utils/", "hooks/", "directives/", "config/axios/"]
-    }
-  ],
-  "shared_code_analysis": {
-    "identical_dirs": ["src/utils/", "src/hooks/", "src/directives/", "src/plugins/"],
-    "version_conflicts": {
-      "vue": { "main": "3.4.20", "sub_apps": "3.3.8" },
-      "element-plus": { "main": "2.5.3", "sub_apps": "2.4.2" }
-    }
-  }
-}
+### 微前端架构（qiankun，如适用）
+- 主应用: locode-front (port: 3000)
+- 子应用: [{ name, entry, activeRule, port }]
+- 共享状态: 主应用通过 props 传递 token、userInfo
+- 通信方式: CustomEvent + initGlobalState
 ```
-
-## Axios 封装分析
-
-**扫描文件**: `src/utils/request.ts`, `src/api/**/*.ts`
-
-**提取内容**:
-- Axios 实例配置（baseURL, timeout, headers）
-- 请求拦截器（token 注入、loading 管理）
-- 响应拦截器（错误码映射、token 刷新、消息提示）
-- API 模块化组织方式
-
-**输出示例**:
-```
-### Axios 配置
-- **文件**: `src/utils/request.ts`
-- **baseURL**: import.meta.env.VITE_API_BASE_URL || '/api'
-- **timeout**: 15000ms
-- **请求拦截器**:
-  1. 从 useUserStore().token 读取 token
-  2. 添加 `Authorization: Bearer ${token}`
-  3. NProgress.start()
-- **响应拦截器**:
-  | 状态码 | 处理方式 |
-  |--------|----------|
-  | 200 | 返回 data.data |
-  | 401 | 调用 refreshToken() → 成功则重发请求 → 失败则跳转 /login |
-  | 403 | ElMessage.error('没有操作权限') |
-  | 500 | ElMessage.error('服务器内部错误') |
-  | 默认 | ElMessage.error(msg) |
-```
-
-## Element Plus 设计 Token 提取
-
-**扫描文件**: `src/styles/**/*.scss`, `src/styles/**/*.css`, `tailwind.config.*`
-
-**提取内容**:
-- `:root` CSS 变量（Element Plus 主题色）
-- `.dark` 暗色模式覆盖变量
-- SCSS 变量（`$--color-primary` 等）
-- 布局变量（侧边栏宽度、头部高度）
-- Element Plus 自定义主题配置
-
-**输出示例**:
-```
-### Element Plus 主题 Token
-**来源**: `src/styles/element-variables.scss`
-| 变量 | 值 | 用途 |
-|------|------|------|
-| --el-color-primary | #00a3e0 | 主色调 |
-| --el-color-primary-light-3 | #33b7e9 | 主色浅 3 |
-| --el-color-primary-light-5 | #80cdef | 主色浅 5 |
-| --el-color-primary-light-7 | #b3e4f5 | 主色浅 7 |
-| --el-color-primary-light-9 | #e6f6fb | 主色浅 9 |
-| --el-color-success | #67c23a | 成功 |
-| --el-color-warning | #e6a23c | 警告 |
-| --el-color-danger | #f56c6c | 危险 |
-| --el-color-info | #909399 | 信息 |
-| --el-bg-color | #ffffff | 背景色 |
-| --el-text-color-primary | #303133 | 主文本色 |
-
-### 布局变量
-**来源**: `src/styles/variables.module.scss`
-| 变量 | 值 | 用途 |
-|------|------|------|
-| $sideBarWidth | 210px | 侧边栏展开宽度 |
-| $sideBarCollapsedWidth | 64px | 侧边栏折叠宽度 |
-| $navbarHeight | 50px | 顶部导航栏高度 |
-| $tagsViewHeight | 34px | 标签栏高度 |
-
-### 暗色模式
-**切换方式**: `<el-switch>` 切换 `html.dark` class
-**覆盖文件**: `src/styles/dark.scss`
-```
-
-## 输出模板
-
-### COMPONENT.md 章节结构（Vue 特有）
-
-```markdown
-# 组件文档
-
-## 页面组件（Views）
-按路由分组的页面组件，每个包含:
-- 路径 + 对应路由
-- Template 分析（使用的 UI 组件、条件/列表渲染）
-- Script Setup 分析（Props、Emits、响应式变量、生命周期）
-- 使用的 composables / store / API
-
-## 通用组件（Components）
-按功能分组的可复用组件
-
-## Composables
-可复用的组合式函数
-
-## Store 详解
-每个 Store 的完整文档（State/Getters/Actions/依赖关系）
-
-## 路由详解
-路由结构 + 守卫 + 动态加载机制
-```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 页面/视图层 | `src/views/{module}/` | 每个子目录 | 目录名 kebab-case |
-| API/服务层 | `src/api/{module}/` | 每个子目录 | 目录名 kebab-case |
-| 状态管理层 | `src/store/modules/` | 每个子目录 | 目录名 kebab-case |
-| 组件层 | `src/components/{name}/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| Composables 层 | `src/composables/` | 每个文件 | 文件名去后缀 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `main.ts`, `App.vue`, `index.ts`）
-- 纯导出桶文件（`index.ts` 仅有 re-export）
-- 工具函数目录（`utils/`, `helpers/`）— 合并为一个模块
-
-## Token 管理
-
-- 每个子任务分析 ≤10 个 `.vue` 文件
-- `.vue` 文件同时分析 template + script + style 三段
-- Store 文件单独分组分析
-- API 模块单独分组分析
-- 样式文件单独分组分析