jsharness 1.0.0

package/.harness/dev-map/frontend/components.md

@@ -0,0 +1,178 @@
+# 前端分区 — 组件库与复用模式
+
+## 通用 UI 组件库 (`components/ui/`) — Element Plus 二次封装
+
+本项目基于 **Element Plus** 进行二次封装，确保全局风格统一和便捷使用。
+
+### 已有组件清单
+
+| 组件名 | 文件路径 | Props | 用途 | 基于 |
+|--------|----------|-------|------|------|
+| `AppButton` | `ui/button/AppButton.vue` | variant, size, loading, disabled | 按钮 | ElButton |
+| `AppInput` | `ui/input/AppInput.vue` | type, error, prefix, suffix | 输入框 | ElInput |
+| `AppModal` | `ui/modal/AppModal.vue` | v-model:visible, title, size | 弹窗 | ElDialog |
+| `AppTable` | `ui/table/AppTable.vue` | columns, data, pagination | 数据表格 | ElTable |
+| `AppCard` | `ui/card/AppCard.vue` | title, actions | 卡片容器 | 自定义 |
+| `AppEmptyState` | `ui/empty-state/AppEmptyState.vue` | icon, title, description | 空状态占位 | 自定义 |
+| `AppConfirmDialog` | `ui/confirm-dialog/AppConfirmDialog.vue` | title, message, onConfirm | 确认对话框 | ElMessageBox |
+| `AppAvatar` | `ui/avatar/AppAvatar.vue` | src, name, size | 用户头像 | 自定义 |
+
+### 组件设计规范
+
+```vue
+<!-- ✅ 正确：组件接口清晰，支持多态 -->
+<script setup lang="ts">
+interface AppButtonProps {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger'
+  size?: 'sm' | 'md' | 'lg'
+  loading?: boolean
+  disabled?: boolean
+}
+
+const props = withDefaults(defineProps<AppButtonProps>(), {
+  variant: 'primary',
+  size: 'md',
+})
+
+const emit = defineEmits<{
+  click: [event: MouseEvent]
+}>()
+
+const handleClick = (e: MouseEvent) => {
+  if (!props.disabled && !props.loading) {
+    emit('click', e)
+  }
+}
+</script>
+
+<template>
+  <ElButton
+    :type="variant"
+    :size="size"
+    :loading="loading"
+    :disabled="disabled"
+    @click="handleClick"
+  >
+    <slot />
+  </ElButton>
+</template>
+```
+
+```typescript
+// ✅ 正确：统一导出模式
+// components/ui/button/index.ts
+export { default as AppButton } from './AppButton.vue'
+export type { AppButtonProps } from './AppButton.vue'
+```
+
+## 业务功能组件 (`components/features/`)
+
+### 组织方式
+
+按**功能域**组织，每个功能域一个文件夹：
+
+```
+features/
+├── user-management/          # 用户管理相关
+│   ├── UserList.vue          # 用户列表
+│   ├── UserDetail.vue        # 用户详情
+│   ├── UserForm.vue          # 新建/编辑表单
+│   ├── UserAvatar.vue        # 头像组件
+│   └── index.ts
+├── data-dashboard/           # 数据看板相关
+│   ├── StatsCard.vue         # 统计卡片
+│   ├── TrendChart.vue        # 趋势图表
+│   └── DataTable.vue         # 数据表格
+└── notification/             # 通知相关
+    ├── NotificationList.vue
+    └── NotificationBadge.vue
+```
+
+## 复用模式
+
+### 1. 组合模式（Composition / Slots）
+
+```vue
+<!-- 将复杂 UI 拆分为原子组件的组合 -->
+<template>
+  <AppDataTable>
+    <AppDataTable.Header>
+      <AppDataTable.Column id="name" sortable>姓名</AppDataTable.Column>
+      <AppDataTable.Column id="email">邮箱</AppDataTable.Column>
+    </AppDataTable.Header>
+    <AppDataTable.Body>
+      <!-- 内容由 slot 注入 -->
+    </AppDataTable.Body>
+  </AppDataTable>
+</template>
+```
+
+### 2. Slots / Scoped Slots 模式
+
+```vue
+<!-- 让父组件控制内部渲染逻辑 -->
+<template>
+  <AppCard>
+    <template #header>
+      <AppCard.Title>标题</AppCard.Title>
+    </template>
+
+    <!-- 子内容由使用者决定 -->
+    <slot />
+
+    <template #footer>
+      <AppButton @click="$emit('save')">保存</AppButton>
+    </template>
+  </AppCard>
+</template>
+```
+
+### 3. Composable + 组件分离（逻辑复用）
+
+```vue
+<!-- 逻辑抽离为 Composable，组件只负责渲染 -->
+<script setup lang="ts">
+// composables/useUserList.ts
+function useUserList() {
+  const { data: users, loading, error, refresh } = useFetch('/api/users')
+  
+  if (loading.value) return { isLoading: true }
+  if (error.value) return { isError: true, error, retry: refresh }
+
+  return { users, isLoading: false, isError: false, refresh }
+}
+</script>
+
+<template>
+  <!-- UserList.vue 只负责展示 -->
+  <div v-loading="isLoading">
+    <AppEmptyState v-if="isError" :title="'加载失败'" @retry="retry" />
+    <template v-else>
+      <UserCard v-for="user in users" :key="user.id" :user="user" />
+    </template>
+  </div>
+</template>
+```
+
+## 禁止的反模式
+
+```vue
+<!-- ❌ 禁止：在组件中直接 fetch（应使用 Composable） -->
+<script setup lang="ts">
+const userId = defineProp<string>('id')
+const user = ref(null)
+
+onMounted(async () => {
+  const res = await fetch(`/api/users/${userId}`)
+  user.value = await res.json()
+}) // 应使用 useUser(id) Composable
+</script>
+
+<!-- ❌ 禁止：硬编码中文字符串（应使用 i18n） -->
+<template>
+  <h1>用户信息</h1><!-- 应使用 {{ t('user.profile') }} -->
+</template>
+
+<!-- ❌ 禁止：巨型单文件组件 (>300 行) -->
+<!-- 应拆分为子组件或提取 Composable -->
+```

package/.harness/dev-map/frontend/conventions.md

@@ -0,0 +1,416 @@
+# 前端分区 — 编码惯例 (Vue3 增强)
+
+> **来源**: `files/frontend-project-conventions/SKILL.md` (v1.0.0)
+> **归档日期**: 2026-05-21
+> **技术栈**: Vue 3 + TypeScript + Vite + Pinia + Vue Router + Element Plus
+
+## 技术栈版本速查
+
+| 组件 | 推荐版本 | 说明 |
+|------|---------|------|
+| Vue | ^3.4.x | Composition API 正式稳定版 |
+| TypeScript | ^5.3.x | strict mode 强制 |
+| Vite | ^5.x | 构建工具 |
+| Pinia | ^2.x | 官方状态管理 |
+| Vue Router | ^4.x | 路由管理 |
+| Element Plus | ^2.x | UI 组件库 |
+| Axios | ^1.x | HTTP 客户端 |
+| Vitest | ^1.x | 测试框架 |
+
+---
+
+## 文件命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| Vue 单文件组件 | PascalCase | `UserProfile.vue` |
+| Hook / 组合式函数 | camelCase + `use` 前缀 | `useUserProfile.ts` |
+| 工具函数 | camelCase | `formatDate.ts` |
+| 全局类型定义 | camelCase + types | `user.types.ts` |
+| 常量/枚举 | UPPER_SNAKE_CASE | `API_ENDPOINTS.ts` |
+| 样式文件 | 与组件同名 | `UserProfile.styles.ts` |
+| 测试文件 | 组件名 + `.test/.spec` | `UserProfile.test.tsx` |
+
+---
+
+## 标准目录结构详解
+
+```
+src/
+├── api/                      # API 接口封装层
+│   ├── client.ts            #   Axios 实例创建、拦截器配置
+│   ├── modules/             #   按业务模块拆分的 API 调用
+│   │   └── user.ts          #     用户相关 API（list/create/update/delete）
+│   └── types/               #   API 请求和响应的 TS 类型定义
+│       └── user.d.ts        #     UserAPI 的 ReqVO/RespVO 类型
+│
+├── assets/                   # 静态资源
+│   ├── styles/              #   全局样式（variables.css / reset.css / global.css）
+│   └── images/              #   图片资源（logo / icons / illustrations）
+│
+├── components/               # 可复用组件
+│   ├── ui/                  #   通用 UI 组件（无业务逻辑）
+│   │   ├── Button/
+│   │   │   ├── Button.vue
+│   │   │   ├── Button.test.ts
+│   │   │   └── index.ts
+│   │   └── Modal/
+│   └── business/            #   业务组件（含业务逻辑）
+│       └── UserProfileCard/
+│
+├── pages/                    # 页面级组件（路由对应）
+│   ├── user/
+│   │   ├── UserList.vue      #   列表页
+│   │   ├── UserDetail.vue    #   详情页
+│   │   └── UserCreate.vue    #   创建/编辑页
+│   └── dashboard/
+│
+├── router/                   # 路由配置
+│   ├── index.ts             #   路由实例 + 首屏路由
+│   ├── routes/              #   按模块拆分的路由定义
+│   │   ├── user.ts
+│   │   └── dashboard.ts
+│   └── guards/              #   导航守卫（权限校验 / 登录拦截）
+│       └── auth.ts
+│
+├── store/                    # Pinia Store
+│   ├── index.ts             #   Store 入口
+│   └── modules/             #   按业务模块拆分
+│       ├── user.ts          #     用户状态（登录信息 / 权限列表）
+│       └── app.ts           #     应用全局状态（侧边栏 / 主题）
+│
+├── types/                    # 全局共享类型定义
+│   ├── user.d.ts            #   用户相关类型接口
+│   ├── api.d.ts             #   通用 API 类型（PaginatedResult / CommonResult）
+│   └── env.d.ts             #   环境变量类型声明
+│
+├── utils/                    # 工具函数
+│   ├── format.ts            #   格式化（日期/金额/手机号脱敏）
+│   ├── request.ts           #   封装请求方法（get/post/put/delete）
+│   └── storage.ts           #   localStorage 封装
+│
+├── composables/              # Vue3 组合式函数（可复用逻辑）
+│   ├── useAuth.ts           #   认证状态管理
+│   ├── usePagination.ts     #   分页逻辑封装
+│   └── usePermission.ts     #   权限判断
+│
+├── layouts/                  # 布局组件
+│   ├── DefaultLayout.vue    #   默认布局（Header + Sidebar + Content）
+│   └── BlankLayout.vue      #   空白布局（登录页等）
+│
+└── App.vue                   # 根组件
+```
+
+---
+
+## 标准组件模板
+
+```vue
+<!--
+ * ComponentName.vue — {功能描述}
+ *
+ * @description {详细说明组件的功能和使用场景}
+ * @props {Type} propName - prop 说明
+ * @emits eventName - 触发时机和参数
+ * @author frontend-team
+-->
+<script setup lang="ts">
+/**
+ * 外部依赖
+ */
+import { ref, computed, onMounted } from 'vue';
+import { useRouter } from 'vue-router';
+import { ElMessage } from 'element-plus';
+
+/**
+ * 类型定义
+ */
+interface Props {
+  id: string;
+  title: string;
+  loading?: boolean;
+}
+
+interface Emits {
+  (e: 'update', value: string): void;
+  (e: 'delete', id: string): void;
+}
+
+/**
+ * Props & Emits
+ */
+const props = withDefaults(defineProps<Props>(), {
+  loading: false,
+});
+const emit = defineEmits<Emits>();
+
+/**
+ * 响应式状态
+ */
+const isLoading = ref(false);
+const dataList = ref<Item[]>([]);
+
+/**
+ * 计算属性
+ */
+const hasData = computed(() => dataList.value.length > 0);
+
+/**
+ * 方法
+ */
+const handleFetch = async () => {
+  isLoading.value = true;
+  try {
+    // 业务逻辑
+  } catch (error) {
+    ElMessage.error('操作失败');
+  } finally {
+    isLoading.value = false;
+  }
+};
+
+const handleClick = () => {
+  emit('update', props.id);
+};
+
+/**
+ * 生命周期
+ */
+onMounted(() => {
+  handleFetch();
+});
+</script>
+
+<template>
+  <div class="component-name">
+    <div v-loading="isLoading">
+      <!-- 内容区域 -->
+    </div>
+  </div>
+</template>
+
+<style scoped lang="scss">
+.component-name {
+  /* 样式 */
+}
+</style>
+```
+
+---
+
+## API 封装模式
+
+```typescript
+// api/client.ts — Axios 实例配置
+import axios from 'axios';
+import { ElMessage } from 'element-plus';
+import type { AxiosRequestConfig } from 'axios';
+
+// 创建实例
+const client = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 15000,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// 请求拦截器：自动附加 Token
+client.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token');
+  if (token && config.headers) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// 响应拦截器：统一错误处理
+client.interceptors.response.use(
+  (response) => response.data,
+  (error) => {
+    const message = error.response?.data?.message || '网络异常';
+    ElMessage.error(message);
+    return Promise.reject(error);
+  },
+);
+
+export default client;
+
+// api/modules/user.ts — 具体模块 API
+import client from '../client';
+import type { UserPageReqVO, UserRespVO, PageResult } from './types/user';
+
+export const UserAPI = {
+  /** 分页查询用户 */
+  page(params: UserPageReqVO) {
+    return client.post<CommonResult<PageResult<UserRespVO>>>('/user/page', params);
+  },
+  /** 创建用户 */
+  create(data: UserCreateReqVO) {
+    return client.post<CommonResult<Long>>('/user/create', data);
+  },
+};
+```
+
+---
+
+## Router 配置约定
+
+```typescript
+// router/routes/user.ts — 懒加载路由
+import type { RouteRecordRaw } from 'vue-router';
+
+const userRoutes: RouteRecordRaw[] = [
+  {
+    path: '/user',
+    component: () => import('@/layouts/DefaultLayout.vue'),
+    meta: { title: '用户管理', requiresAuth: true },
+    children: [
+      {
+        path: '',
+        name: 'UserList',
+        component: () => import('@/pages/user/UserList.vue'),
+        meta: { title: '用户列表' },
+      },
+      {
+        path: ':id',
+        name: 'UserDetail',
+        component: () => import('@/pages/user/UserDetail.vue'),
+        meta: { title: '用户详情' },
+      },
+    ],
+  },
+];
+
+export default userRoutes;
+```
+
+**路由规范**:
+- 所有页面组件必须 **懒加载** (`() => import(...)`)
+- 路由元数据 `meta` 包含 `title` 和 `requiresAuth`
+- 权限控制通过路由守卫统一处理
+- 菜单结构与路由结构保持一致
+
+---
+
+## Store 组织方式
+
+```typescript
+// store/modules/user.ts — 标准 Store 结构
+import { defineStore } from 'pinia';
+import type { UserInfo } from '@/types/user';
+
+interface UserState {
+  userInfo: UserInfo | null;
+  token: string;
+  permissions: string[];
+}
+
+export const useUserStore = defineStore('user', {
+  state: (): UserState => ({
+    userInfo: null,
+    token: localStorage.getItem('token') || '',
+    permissions: [],
+  }),
+
+  getters: {
+    isLoggedIn: (state) => !!state.token,
+    isAdmin: (state) => state.permissions.includes('admin'),
+    displayName: (state) => state.userInfo?.name || '未登录',
+  },
+
+  actions: {
+    async login(credentials: LoginCredentials) {
+      // ...
+    },
+    logout() {
+      this.$reset();
+      localStorage.removeItem('token');
+    },
+  },
+});
+```
+
+**Store 规范**:
+- State 字段必须有明确 TS 类型
+- Getters 用于派生计算数据
+- Actions 用于异步操作或批量修改
+- 禁止在组件外直接修改 Store state
+
+---
+
+## Import 排序
+
+```tsx
+// 1. Vue 相关
+import { ref, computed, onMounted } from 'vue';
+import { useRouter } from 'vue-router';
+
+// 2. UI 库
+import { ElMessage, ElMessageBox } from 'element-plus';
+
+// 3. 外部库（按字母序）
+import axios from 'axios';
+
+// 4. 内部共享模块（@/ 别名）
+import { useUserStore } from '@/store/modules/user';
+import { UserAPI } from '@/api/modules/user';
+import type { User, UserRole } from '@/types/user';
+
+// 5. 相对路径导入
+import { Avatar } from './Avatar';
+import type { UserProfileProps } from './types';
+```
+
+---
+
+## 组件编写惯例
+
+### 函数组件 + 解构 Props
+（见上方「标准组件模板」）
+
+### 条件渲染
+
+```tsx
+// ✅ 推荐：提前返回
+function UserDetail({ user }: { user: User | null }) {
+  if (!user) return <EmptyState />;
+  if (user.isBanned) return <BannedNotice />;
+  
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      {/* 主要内容 */}
+    </div>
+  );
+}
+```
+
+### 列表渲染
+
+```tsx
+// ✅ 推荐：带 key + 空状态处理
+function UserList({ users }: { users: User[] }) {
+  if (users.length === 0) {
+    return <EmptyState title="暂无用户" description="点击上方按钮添加" />;
+  }
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.id}>
+          <UserCard user={user} />
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## 注释与文档规范
+
+- **组件级注释**: 文件顶部 JSDoc，含名称、描述、props、events
+- **函数级注释**: 复杂逻辑函数前加 JSDoc（@param / @returns / @throws）
+- **行内注释**: 关键步骤解释"为什么"，关注 why 而非 what
+- **TODO 格式**: `// TODO: [场景] - 待[动作]`
+- **禁止注释与代码不一致**