jsharness 1.0.0

package/.harness/rules/project/frontend-vue3.md

@@ -0,0 +1,293 @@
+# Vue3 + TypeScript 前端编码规范 (frontend-vue3)
+
+> **级别**: 项目级强制 | **适用范围**: 前端 Vue3 项目
+> **来源**: `files/frontend-project-conventions/SKILL.md` (v1.0.0)
+> **归档日期**: 2026-05-21
+> **技术栈**: Vue 3 + TypeScript + Vite + Pinia + Vue Router + Element Plus
+
+---
+
+## 1. Composition API 强制使用
+
+所有 Vue 组件 **必须** 使用 `<script setup>` 语法的 Composition API。
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 组件语法 | 必须使用 `<script setup lang="ts">` | Code Review FAIL |
+| 禁止 Options API | 禁止出现 `export default { data(), methods(), mounted() }` | Code Review FAIL |
+| 禁止 this 关键字 | 生成的代码中不得出现 `this.` | Code Review WARNING |
+
+**正确示例**:
+```vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue';
+
+interface Props {
+  userId: string;
+  userName?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  userName: '',
+});
+
+const isLoading = ref(false);
+const userInfo = ref<UserInfo | null>(null);
+
+const displayName = computed(() => props.userName || '匿名用户');
+
+onMounted(() => {
+  fetchUserInfo();
+});
+</script>
+```
+
+---
+
+## 2. TypeScript 类型安全约束
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| Props 定义 | 必须使用 TS `interface` 或 `defineProps<T>()` 泛型 | Code Review WARNING |
+| 禁止裸 any | 禁止无注释说明的 `any` 类型 | Code Review WARNING |
+| Pinia 类型 | State 字段必须有明确类型，Getters/Actions 参数和返回值必须标注类型 | Code Review WARNING |
+
+**类型定义规范**:
+
+```typescript
+// ✅ 正确：Props 使用 interface
+interface UserProfileProps {
+  id: string;
+  name: string;
+  avatar?: string;
+  onUpdate?: (id: string) => void;
+}
+
+const props = defineProps<UserProfileProps>();
+
+// ✅ 正确：Emits 使用类型
+const emit = defineEmits<{
+  update: [id: string];
+  delete: [id: string];
+}>();
+
+// ⚠️ 允许但有条件：必须注释说明 why
+const legacyData: any = parseLegacyFormat(raw); // Legacy API, 待重构
+
+// ❌ 错误：禁止裸 any
+const data: any = fetchData();
+```
+
+---
+
+## 3. 文件命名与目录结构
+
+### 3.1 命名约定
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| Vue 组件文件 | PascalCase | `UserProfile.vue` |
+| 目录名 | kebab-case | `user-profile/` |
+| 工具函数文件 | camelCase | `formatDate.ts` |
+| 类型定义文件 | camelCase + types | `user.types.ts` |
+| 常量文件 | UPPER_SNAKE_CASE | `API_ENDPOINTS.ts` |
+| Hook 文件 | use + PascalCase | `useUserProfile.ts` |
+
+### 3.2 标准目录结构
+
+```
+src/
+├── api/              # API 接口封装（axios 实例、拦截器、类型定义）
+├── assets/           # 静态资源（全局样式、图片、字体）
+├── components/       # 可复用组件
+│   ├── ui/          # 通用 UI 组件（Button、Modal 等）
+│   └── business/    # 业务组件
+├── pages/            # 页面级组件（路由对应）
+├── router/           # 路由配置（路由定义、守卫、菜单结构）
+├── store/            # Pinia Store（按模块拆分）
+│   ├── modules/     # 各业务模块 store
+│   └── index.ts     # Store 入口
+├── types/            # 全局 TypeScript 类型定义
+├── utils/            # 工具函数
+└── composables/      # 组合式函数（Vue3 Hooks）
+```
+
+---
+
+## 4. 变量命名约定
+
+| 标识符类型 | 规范 | 示例 |
+|-----------|------|------|
+| 普通变量/函数 | camelCase | `userName`, `fetchUserData` |
+| 常量/配置项 | UPPER_SNAKE_CASE | `API_BASE_URL`, `MAX_RETRY_COUNT` |
+| 布尔变量 | `is`/`has`/`can`/`should`/`will` 前缀 | `isLoading`, `hasPermission`, `canEdit` |
+| 事件处理函数 | `handle` 前缀 | `handleSubmit`, `handleClick`, `handleChange` |
+| 计算属性 | 形容词/名词短语 | `displayName`, `filteredItems` |
+| Store action | 动词短语 | `fetchUsers`, `createOrder`, `toggleSidebar` |
+
+```typescript
+// ✅ 正确示例
+const isLoading = ref(false);
+const hasPermission = computed(() => user.role === 'admin');
+const MAX_RETRY_COUNT = 3;
+const handleClick = () => { /* ... */ };
+const handleSubmit = async () => { /* ... */ };
+```
+
+---
+
+## 5. Element Plus 组件使用规范
+
+| 场景 | 要求 | 说明 |
+|------|------|------|
+| 消息提示 | 使用 `ElMessage.success/warning/error/info` | 轻量反馈，自动消失 |
+| 确认操作 | 使用 `ElMessageBox.confirm` | 删除/提交等需二次确认的操作 |
+| 加载状态 | 使用 `v-loading` 指令 | 禁止手动控制 loading 变量实现 |
+| 图标使用 | 图标组件包裹在容器标签中 | 避免直接暴露图标组件 |
+| 表单校验 | 使用 ElForm + rules | 统一校验逻辑和提示样式 |
+| 数据表格 | 使用 el-table + 分页组件 | 配合 Pagination 组件使用 |
+
+**标准用法示例**:
+```vue
+<template>
+  <!-- 加载状态 -->
+  <div v-loading="isLoading">
+    <el-table :data="tableData" border>
+      <el-table-column prop="name" label="名称" />
+      <el-table-column prop="status" label="状态" />
+    </el-table>
+    <el-pagination
+      :current-page="pagination.page"
+      :page-size="pagination.pageSize"
+      :total="pagination.total"
+      @current-change="handlePageChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ElMessage, ElMessageBox } from 'element-plus';
+
+const handleDelete = async (row: TableRow) => {
+  try {
+    await ElMessageBox.confirm('确定要删除该记录吗？', '提示', {
+      confirmButtonText: '确定',
+      cancelButtonText: '取消',
+      type: 'warning',
+    });
+    await deleteRecord(row.id);
+    ElMessage.success('删除成功');
+  } catch {
+    // 用户取消操作
+  }
+};
+</script>
+```
+
+---
+
+## 6. 响应式数据管理规范
+
+### 6.1 分层原则
+
+| 数据范围 | 管理方式 | 示例 |
+|---------|----------|------|
+| 组件内部局部状态 | `ref()` / `reactive()` | 表单输入、弹窗开关 |
+| 跨组件共享状态 | Pinia Store | 用户信息、权限列表 |
+| 服务端状态缓存 | Pinia Plugin / `keepAlive` | 列表数据缓存 |
+
+### 6.2 禁止事项
+
+| 行为 | 原因 | 替代方案 |
+|------|------|----------|
+| prop drilling 超过两层 | 维护困难 | 使用 Pinia Store |
+| event bus 方式通信 | Vue3 已移除 `$on`/`$off` | 使用 Pinia 或 provide/inject |
+| 直接修改 props | 单向数据流破坏 | emit 事件或 computed |
+
+### 6.3 Pinia Store 组织规范
+
+```typescript
+// stores/modules/user.ts
+import { defineStore } from 'pinia';
+import type { UserInfo } from '@/types/user';
+
+export const useUserStore = defineStore('user', {
+  state: (): UserState => ({
+    userInfo: null,
+    token: '',
+    permissions: [],
+  }),
+
+  getters: {
+    isLoggedIn: (state): boolean => !!state.token,
+    isAdmin: (state): boolean => state.permissions.includes('admin'),
+  },
+
+  actions: {
+    async login(credentials: LoginCredentials) {
+      // ...
+    },
+    logout() {
+      // ...
+    },
+  },
+});
+```
+
+---
+
+## 7. 注释和文档规范
+
+### 7.1 JSDoc 标准
+
+**组件级注释** — 文件顶部必须包含：
+```typescript
+/**
+ * UserProfile.vue — 用户信息展示卡片
+ *
+ * @description 展示用户基本信息，支持编辑和删除操作
+ * @props id (string) - 用户唯一标识
+ * @props name (string, optional) - 用户显示名
+ * @emits update - 编辑时触发，参数为用户 ID
+ * @emits delete - 删除确认后触发，参数为用户 ID
+ * @author frontend-team
+ */
+```
+
+**函数级注释**:
+```typescript
+/**
+ * 根据用户 ID 批量获取用户详情
+ *
+ * @param ids - 用户 ID 数组
+ * @returns Promise<UserInfo[]> 用户信息数组，不存在的 ID 对应位置为 null
+ * @throws {NetworkError} 当网络请求失败时抛出
+ *
+ * @example
+ * const users = await batchGetUserIds(['id1', 'id2']);
+ */
+async function batchGetUserIds(ids: string[]): Promise<(UserInfo | null)[]> {
+  // ...
+}
+```
+
+### 7.2 注释要求
+
+- 所有公开 API 必须有 JSDoc
+- 复杂逻辑必须有行内注释解释「**为什么**」而非「是什么」
+- TODO/FIXME 必须附带场景说明：`// TODO: [场景描述] - 待[具体动作]`
+- 注释与代码必须同步更新
+
+---
+
+## 8. 禁止事项清单
+
+| # | 禁止行为 | 触发条件 | 后果 |
+|---|---------|---------|------|
+| FV-01 | Options API | 出现 `data()`, `methods()`, `mounted()` 等 Options API 写法 | **Code Review FAIL** |
+| FV-02 | 裸 any 类型 | `const x: any` 无注释说明原因 | **Code Review WARNING** |
+| FV-03 | 直接操作 DOM | 使用 `document.getElementById` 等 DOM 操作 | **Code Review FAIL** |
+| FV-04 | jQuery 引入 | package.json 中出现 jquery 依赖 | **Gate BLOCK** |
+| FV-05 | 内联样式字符串 | `style="color: red"` 非绑定形式（动态计算值除外） | **Lint ERROR** |
+| FV-06 | console.log 残留 | 生产代码中出现 console.log/debugger | **Gate A 类 WARNING** |
+| FV-07 | 魔法数字 | 无命名常量的数字字面量（除 0/1/-1） | **Code Review WARNING** |