@chenhui996/gg-cli 1.0.3 → 1.0.5

package/dist/template/operations-tem/docs//345/215/225/345/205/203/346/265/213/350/257/225/350/247/204/350/214/203.md

@@ -0,0 +1,131 @@
+# 前端单元测试开发规范
+
+单元测试是保障前端代码质量、支持安全重构的重要手段。本文档规定了团队内前端项目的测试工具选型、目录结构以及测试代码的编写规范。
+
+## 1. 测试工具选型
+
+在基于 Vite 的前端项目中，我们**全面弃用 Jest，转而使用 Vitest 作为核心测试框架**。
+
+### 为什么选择 Vitest？
+1. **与 Vite 完美融合**：Vitest 直接复用项目的 `vite.config.ts`（包括 alias、插件等），实现了零配置开箱即用，避免了在 Jest 中配置复杂的 Babel/TypeScript 转换器。
+2. **极速运行**：得益于 Vite 的原生 ESM 支持和底层的 esbuild/oxc，Vitest 的启动和运行速度远超 Jest。
+3. **API 兼容**：Vitest 提供了与 Jest 几乎 100% 兼容的 API（如 `describe`, `it`, `expect`），现有的 Jest 经验可以无缝迁移。
+
+### 核心测试栈：
+- **测试框架**: [Vitest](https://vitest.dev/) (替代 Jest)
+- **组件测试库**: [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) (用于渲染和交互测试)
+- **环境模拟**: `jsdom` 或 `happy-dom` (模拟浏览器 DOM 环境)
+
+---
+
+## 2. 测试文件命名与目录规范
+
+### 2.1 命名规范
+测试文件必须以 `.test.ts` 或 `.test.tsx` 结尾（如果包含 JSX 代码必须用 `.tsx`）。
+
+### 2.2 目录存放方式
+推荐**就近存放**原则。测试文件应与其被测试的代码文件放在同一目录下，方便查找和维护。
+
+```text
+src/
+├── utils/
+│   ├── math.ts
+│   └── math.test.ts         # 工具函数的测试文件
+├── components/
+│   └── Button/
+│       ├── index.tsx
+│       ├── index.less
+│       └── index.test.tsx   # UI 组件的测试文件
+```
+
+---
+
+## 3. 编写规范
+
+### 3.1 测试结构 (Arrange - Act - Assert)
+所有的测试用例都必须遵循著名的 **AAA 模式**：
+- **Arrange (准备)**：初始化测试数据、渲染组件、设置 Mock 函数。
+- **Act (执行)**：触发用户交互（点击、输入）或调用函数。
+- **Assert (断言)**：验证期望的结果（如：函数返回值、DOM 元素的变化）。
+
+### 3.2 纯函数测试规范
+纯函数（如工具类、数据转换逻辑）是最容易且最应该被测试的代码。
+
+```typescript
+// utils/math.test.ts
+import { describe, it, expect } from 'vitest';
+import { add } from './math';
+
+describe('math 工具函数', () => {
+  it('应当正确计算两个正数的和', () => {
+    // Arrange
+    const a = 1;
+    const b = 2;
+    
+    // Act
+    const result = add(a, b);
+    
+    // Assert
+    expect(result).toBe(3);
+  });
+});
+```
+
+### 3.3 React 组件测试规范 (React Testing Library)
+组件测试的原则是：**测试组件的行为，而不是其内部实现**。像真实用户一样去交互和断言，不要去测试组件的内部 state。
+
+```tsx
+// components/Button/index.test.tsx
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Button } from './index';
+
+describe('Button 组件', () => {
+  it('正常渲染标签文字', () => {
+    // Arrange
+    render(<Button label="提交" onClick={() => {}} />);
+    
+    // Act & Assert
+    // 像用户一样通过可见文本寻找元素
+    expect(screen.getByText('提交')).toBeInTheDocument();
+  });
+
+  it('点击时应触发 onClick 回调', () => {
+    // Arrange
+    // 使用 vi.fn() 创建一个 Mock 函数记录调用
+    const handleClick = vi.fn();
+    render(<Button label="提交" onClick={handleClick} />);
+    
+    // Act
+    fireEvent.click(screen.getByText('提交'));
+    
+    // Assert
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+---
+
+## 4. Mock 规范
+
+在前端测试中，经常需要 Mock 网络请求或复杂的第三方依赖。
+
+- **Mock 函数**：使用 `vi.fn()` 替代 `jest.fn()`。
+- **Mock 模块**：使用 `vi.mock('module-name')` 替代 `jest.mock()`。
+- **Mock 定时器**：使用 `vi.useFakeTimers()`。
+
+---
+
+## 5. 测试覆盖率 (Coverage) 要求
+
+虽然不强求 100% 的覆盖率（会带来过高的维护成本），但应遵守以下底线：
+
+1. **核心业务逻辑 (utils/store/hooks)**：包含大量计算、格式化、状态流转的纯函数，要求语句覆盖率达到 **80%** 以上。
+2. **公共 UI 组件 (components)**：要求进行基本的渲染测试和交互测试。
+3. **页面级组件 (pages)**：不强制要求编写详细的单元测试，推荐使用 E2E 测试工具（如 Cypress/Playwright）进行核心链路覆盖。
+
+运行覆盖率命令：
+```bash
+npm run test:coverage
+```

package/dist/template/operations-tem/docs//351/241/271/347/233/256/347/233/256/345/275/225/347/273/223/346/236/204/350/247/204/350/214/203.md

@@ -0,0 +1,93 @@
+# 项目目录结构规范
+
+本文档定义了前端工程的标准目录结构，旨在保持项目架构的清晰一致，降低新成员的理解成本，并为大型应用的扩展奠定基础。
+
+## 1. 根目录结构
+
+项目根目录存放工程化配置、环境变量文件以及源代码目录。
+
+```text
+├── .env.development      # 本地开发环境变量配置
+├── .env.test             # 测试环境变量配置
+├── .env.production       # 生产环境变量配置
+├── .eslintrc.cjs         # ESLint 逻辑检查配置
+├── .prettierrc           # Prettier 代码格式化配置
+├── .editorconfig         # 跨编辑器基础配置规范
+├── package.json          # 项目依赖及 npm scripts
+├── tsconfig.json         # TypeScript 基础配置
+├── tsconfig.app.json     # TypeScript 针对 src 目录的配置
+├── tsconfig.node.json    # TypeScript 针对 vite.config.ts 等 Node 环境的配置
+├── vite.config.ts        # Vite 构建工具配置
+├── index.html            # 应用挂载的 HTML 模板
+└── src/                  # 源代码主目录
+```
+
+## 2. `src/` 源代码主目录结构
+
+所有业务代码、静态资源和配置文件都应放置在 `src` 目录下，并严格按照功能模块进行划分。
+
+```text
+src/
+├── api/                # API 接口请求定义
+├── assets/             # 静态资源文件
+├── components/         # 业务无关的全局公共组件
+├── hooks/              # 全局自定义 React Hooks
+├── layouts/            # 页面布局组件
+├── pages/              # 页面级组件 (路由视图)
+├── router/             # 路由配置表
+├── store/              # 全局状态管理 (Zustand)
+├── types/              # 全局 TypeScript 类型定义
+├── utils/              # 全局公共工具函数
+├── App.tsx             # 根组件，承载路由等全局 Context
+├── main.tsx            # 应用入口文件，负责渲染 React 树
+├── index.css           # 全局样式文件
+└── vite-env.d.ts       # Vite 环境变量类型声明
+```
+
+---
+
+## 3. 详细目录说明与规范
+
+### 3.1 `api/` (接口定义层)
+- 存放所有的接口请求函数。
+- 按照业务模块或后端微服务划分文件，例如 `user.ts`、`order.ts`。
+- **规范**：接口函数的命名应见名知意（如 `getUserList`, `createOrder`），并且必须定义入参和返回值的 TypeScript 类型。
+
+### 3.2 `assets/` (静态资源)
+- 存放不需要经过 Webpack/Vite 编译的静态资源，如图片 (`images/`)、SVG 图标 (`icons/`)、字体文件等。
+- **规范**：较大的静态资源建议上传至 CDN，小图片或图标可以直接放在此处。
+
+### 3.3 `components/` (公共组件库)
+- 存放**跨页面复用**的、**业务无关**的 UI 组件或业务组件（如封装的通用图表组件 `Chart/`、通用的文件上传组件）。
+- **规范**：每个组件应拥有自己的文件夹，内部包含 `index.tsx` (组件逻辑) 和 `index.less` (组件样式)。
+
+### 3.4 `hooks/` (自定义 Hooks)
+- 存放全局复用的自定义 React Hooks，例如 `useDebounce.ts`、`useWindowSize.ts`。
+- **规范**：文件命名必须以 `use` 开头，采用 **camelCase (小驼峰)**。
+
+### 3.5 `layouts/` (布局组件)
+- 存放页面的整体布局组件，例如包含侧边栏、顶栏和底部版权信息的 `BasicLayout.tsx`，或者登录页专用的 `BlankLayout.tsx`。
+- 布局组件通常被用作路由配置中的父级路由组件 (`<Outlet />`)。
+
+### 3.6 `pages/` (页面级视图)
+- 存放与路由直接对应的页面组件。
+- 按照功能模块划分文件夹，如 `home/`、`dashboard/`、`about/`。
+- **规范**：
+  - 如果一个页面较复杂，可以在其文件夹下建立私有的 `components/` 目录存放仅该页面使用的子组件。
+  - 入口文件统一命名为 `index.tsx`，配合 `index.less` 使用。
+
+### 3.7 `router/` (路由配置)
+- 存放应用的路由配置表。
+- **规范**：基于 React Router v7 的 Data API 模式配置路由树。按业务模块拆分路由配置，避免单一文件过长。
+
+### 3.8 `store/` (全局状态管理)
+- 存放基于 Zustand 的全局状态。
+- **规范**：按业务领域拆分 Store 文件，如 `useUserStore.ts`、`useAppStore.ts`。不要将本应属于组件内部的局部状态放入全局 Store。
+
+### 3.9 `types/` (全局类型声明)
+- 存放全局公用的 TypeScript 接口 (`interface`) 和类型别名 (`type`)。
+- **规范**：例如定义后端的通用分页返回结构、全局共享的枚举值等。命名约定为 `*.d.ts` 或 `*.ts`。
+
+### 3.10 `utils/` (工具函数)
+- 存放纯 JavaScript/TypeScript 的工具函数，如日期格式化 (`date.ts`)、正则校验 (`regex.ts`)、本地存储封装 (`storage.ts`)。
+- **重点**：`request/` 目录用于存放 Axios 的二次封装，包括拦截器配置、错误统一处理等。

package/dist/template/operations-tem/package.json

@@ -4,9 +4,16 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
-    "build": "tsc -b && vite build",
+    "dev": "vite --mode development",
+    "build:test": "tsc -b && vite build --mode test",
+    "build:prod": "tsc -b && vite build --mode production",
+    "build": "npm run build:prod",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "analyze": "cross-env ANALYZE=true npm run build:prod",
     "lint": "eslint .",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,less,css,json,md}\"",
     "preview": "vite preview"
   },
   "dependencies": {
@@ -25,19 +32,29 @@
     "@babel/core": "^7.29.0",
     "@eslint/js": "^9.39.4",
     "@rolldown/plugin-babel": "^0.2.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/coverage-v8": "^4.1.4",
     "babel-plugin-react-compiler": "^1.0.0",
+    "cross-env": "^10.1.0",
     "eslint": "^9.39.4",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^17.4.0",
+    "jsdom": "^29.0.2",
     "less": "^4.6.4",
+    "prettier": "^3.8.1",
+    "rollup-plugin-visualizer": "^7.0.1",
+    "terser": "^5.46.1",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.56.1",
-    "vite": "^8.0.0"
+    "vite": "^8.0.0",
+    "vitest": "^4.1.4"
   }
 }

package/dist/template/operations-tem/src/api/user.ts

@@ -13,9 +13,9 @@ export const userService = {
   getUserInfo: (userId: number) => {
     return request.get<UserInfo>(`/users/${userId}`);
   },
-  
+
   // 更新用户信息
   updateUserInfo: (userId: number, data: Partial<UserInfo>) => {
     return request.put<UserInfo>(`/users/${userId}`, data);
-  }
+  },
 };

package/dist/template/operations-tem/src/components/ErrorBoundary/index.tsx

@@ -0,0 +1,82 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { Result, Button } from 'antd';
+
+interface Props {
+  children?: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error?: Error;
+}
+
+/**
+ * 全局错误边界组件 (Error Boundary)
+ * 用于捕获 React 组件树中的渲染错误，防止整个应用白屏崩溃
+ * 同时可在此处进行错误日志上报
+ */
+export class ErrorBoundary extends Component<Props, State> {
+  public state: State = {
+    hasError: false,
+  };
+
+  public static getDerivedStateFromError(error: Error): State {
+    // 更新 state 以致于下一次渲染能够显示降级后的 UI
+    return { hasError: true, error };
+  }
+
+  public componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // 在这里你可以将错误日志上报给服务器
+    console.error('Uncaught error in React component tree:', error, errorInfo);
+
+    // 示例：如果在生产环境，调用监控 SDK
+    // if (import.meta.env.PROD) {
+    //   logService.error('REACT_RENDER_ERROR', { error, errorInfo });
+    // }
+  }
+
+  private handleReset = () => {
+    // 重置错误状态，尝试恢复组件渲染
+    this.setState({ hasError: false, error: undefined });
+    // 也可以选择刷新整个页面
+    // window.location.reload();
+  };
+
+  public render() {
+    if (this.state.hasError) {
+      // 渲染自定义的降级 UI，或者使用默认的 500 页面
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      return (
+        <Result
+          status="500"
+          title="抱歉，页面加载出错了"
+          subTitle={
+            import.meta.env.DEV
+              ? this.state.error?.message
+              : "我们正在努力修复此问题，请稍后再试。"
+          }
+          extra={
+            <Button type="primary" onClick={this.handleReset}>
+              重试
+            </Button>
+          }
+          style={{
+            height: '100%',
+            display: 'flex',
+            flexDirection: 'column',
+            justifyContent: 'center',
+            background: '#fff',
+            borderRadius: 8,
+            margin: 24,
+          }}
+        />
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/dist/template/operations-tem/src/layouts/BasicLayout.tsx

@@ -1,13 +1,5 @@
-import { Outlet, Link, useLocation, useNavigate } from "react-router-dom";
-import {
-  Layout,
-  Menu,
-  Avatar,
-  Badge,
-  Space,
-  Typography,
-  Button,
-} from "antd";
+import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom';
+import { Layout, Menu, Avatar, Badge, Space, Typography, Button } from 'antd';
 import {
   MessageOutlined,
   AppstoreOutlined,
@@ -16,7 +8,7 @@ import {
   SettingOutlined,
   BellOutlined,
   UserOutlined,
-} from "@ant-design/icons";
+} from '@ant-design/icons';
 
 const { Header, Content, Sider } = Layout;
 const { Text } = Typography;
@@ -30,30 +22,30 @@ const { Text } = Typography;
  */
 const MENU_ITEMS = [
   {
-    key: "/",
+    key: '/',
     icon: <MessageOutlined />,
-    label: "聊天",
+    label: '聊天',
   },
   {
-    key: "/dashboard",
+    key: '/dashboard',
     icon: <AppstoreOutlined />,
-    label: "功能大厅",
+    label: '功能大厅',
   },
   {
-    key: "/workspace", // 暂未实现
+    key: '/workspace', // 暂未实现
     icon: <FolderOutlined />,
-    label: "工作空间",
+    label: '工作空间',
   },
   {
-    key: "/calendar", // 暂未实现
+    key: '/calendar', // 暂未实现
     icon: <CalendarOutlined />,
-    label: "日历",
+    label: '日历',
   },
 ];
 
 /**
  * 基础布局组件 (BasicLayout)
- * 
+ *
  * 整体布局结构：
  * - Sider (左侧侧边栏)
  *   - Logo
@@ -62,7 +54,7 @@ const MENU_ITEMS = [
  * - Layout (右侧主体)
  *   - Header (顶部导航)
  *   - Content (路由出口 Outlet)
- * 
+ *
  * @returns {JSX.Element} 布局组件
  */
 export default function BasicLayout() {
@@ -75,17 +67,14 @@ export default function BasicLayout() {
   const renderUserProfile = () => (
     <div
       style={{
-        padding: "16px",
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "space-between",
+        padding: '16px',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
       }}
     >
       <Space>
-        <Avatar
-          src="https://api.dicebear.com/7.x/miniavs/svg?seed=1"
-          icon={<UserOutlined />}
-        />
+        <Avatar src="https://api.dicebear.com/7.x/miniavs/svg?seed=1" icon={<UserOutlined />} />
         <Text strong style={{ fontSize: 14 }}>
           国泰海通-张三
         </Text>
@@ -95,37 +84,39 @@ export default function BasicLayout() {
   );
 
   return (
-    <Layout style={{ minHeight: "100vh", position: "relative" }}>
+    <Layout style={{ minHeight: '100vh', position: 'relative' }}>
       {/* 左侧侧边栏 */}
       <Sider
         width={240}
         theme="light"
         style={{
-          borderRight: "1px solid #f0f0f0",
+          borderRight: '1px solid #f0f0f0',
         }}
       >
-        <div style={{ display: "flex", flexDirection: "column", height: '100%', position: 'relative' }}>
+        <div
+          style={{ display: 'flex', flexDirection: 'column', height: '100%', position: 'relative' }}
+        >
           {/* Logo 区域 */}
           <div
             style={{
               height: 64,
-              display: "flex",
-              alignItems: "center",
+              display: 'flex',
+              alignItems: 'center',
               paddingLeft: 24,
               fontSize: 20,
-              fontWeight: "bold",
-              color: "#333",
+              fontWeight: 'bold',
+              color: '#333',
             }}
           >
             PILOTCORE
           </div>
 
           {/* 菜单区域 - flex: 1 撑满剩余空间 */}
-          <div style={{ flex: 1, overflowY: "auto" }}>
+          <div style={{ flex: 1, overflowY: 'auto' }}>
             <Menu
               mode="inline"
               selectedKeys={[location.pathname]}
-              style={{ borderRight: 0, paddingBottom: 16, borderBottom: "1px solid #f0f0f0" }}
+              style={{ borderRight: 0, paddingBottom: 16, borderBottom: '1px solid #f0f0f0' }}
               items={MENU_ITEMS.map((item) => ({
                 ...item,
                 label: <Link to={item.key}>{item.label}</Link>,
@@ -134,7 +125,7 @@ export default function BasicLayout() {
           </div>
 
           {/* 底部用户信息 */}
-          <div style={{ position: "absolute", bottom: 0, width: '100%' }}>
+          <div style={{ position: 'absolute', bottom: 0, width: '100%' }}>
             {renderUserProfile()}
           </div>
         </div>
@@ -145,11 +136,11 @@ export default function BasicLayout() {
         {/* 顶部导航栏 */}
         <Header
           style={{
-            padding: "0 24px",
-            display: "flex",
-            justifyContent: "flex-end",
-            alignItems: "center",
-            backgroundColor: "transparent", // 透明背景融入整体
+            padding: '0 24px',
+            display: 'flex',
+            justifyContent: 'flex-end',
+            alignItems: 'center',
+            backgroundColor: 'transparent', // 透明背景融入整体
           }}
         >
           <Space size={24}>
@@ -159,9 +150,9 @@ export default function BasicLayout() {
                 icon={<BellOutlined />}
                 shape="circle"
                 style={{
-                  border: "none",
-                  background: "#fff",
-                  boxShadow: "0 2px 8px rgba(0,0,0,0.05)",
+                  border: 'none',
+                  background: '#fff',
+                  boxShadow: '0 2px 8px rgba(0,0,0,0.05)',
                 }}
               />
             </Badge>
@@ -171,7 +162,7 @@ export default function BasicLayout() {
         {/* 内容区域 */}
         <Content
           style={{
-            margin: "0 24px 24px",
+            margin: '0 24px 24px',
             minHeight: 280,
           }}
         >

package/dist/template/operations-tem/src/main.tsx

@@ -1,14 +1,14 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import { RouterProvider } from 'react-router-dom'
-import { ConfigProvider } from 'antd'
-import zhCN from 'antd/locale/zh_CN'
-import { router } from './router'
-import 'antd/dist/reset.css'
-import './style.less'
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router-dom';
+import { ConfigProvider } from 'antd';
+import zhCN from 'antd/locale/zh_CN';
+import { router } from '@/router';
+import { ErrorBoundary } from '@/components/ErrorBoundary';
+import 'antd/dist/reset.css';
+import './style.less';
 
 createRoot(document.getElementById('root')!).render(
-  <StrictMode>
+  <ErrorBoundary>
     <ConfigProvider
       locale={zhCN}
       theme={{
@@ -34,5 +34,5 @@ createRoot(document.getElementById('root')!).render(
     >
       <RouterProvider router={router} />
     </ConfigProvider>
-  </StrictMode>,
-)
+  </ErrorBoundary>,
+);

package/dist/template/operations-tem/src/pages/404.test.tsx

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import NotFound from './404';
+import { BrowserRouter } from 'react-router-dom';
+
+describe('NotFound (404) 页面组件', () => {
+  it('应当正确渲染 404 状态码和提示信息', () => {
+    // Arrange: 渲染组件 (需要包裹在 Router 中因为内部使用了 useNavigate)
+    render(
+      <BrowserRouter>
+        <NotFound />
+      </BrowserRouter>
+    );
+
+    // Assert: 验证页面中是否出现了 404 和相关提示文字
+    expect(screen.getByText('404')).toBeInTheDocument();
+    expect(screen.getByText('抱歉，您访问的页面不存在。')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: '返回首页' })).toBeInTheDocument();
+  });
+});

package/dist/template/operations-tem/src/pages/dashboard/index.tsx

@@ -1,5 +1,5 @@
 import { Card, Row, Col } from 'antd';
-import Chart from '../../components/Chart';
+import Chart from '@/components/Chart';
 import type { EChartsOption } from 'echarts';
 
 export default function Dashboard() {