# free-test-wk

**Repository Path**: free_pan/free-test-wk

## Basic Information

- **Project Name**: free-test-wk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple UI WK

> 基于 pnpm monorepo 的 Vue 3 企业级脚手架 — 内置 vxe-table/vxe-pc-ui 数据驱动方案、Tailwind CSS 样式体系、MSW 请求模拟、多环境构建、VitePress 文档站及完整的 Git 提交规范。

## 项目概览

采用 **pnpm workspace** 组织多包结构，`apps/web` 为主应用，`packages/` 承载共享 UI 组件、工具函数和文档站。项目集成了现代前端工程化所需的完整工具链：

- **样式**：Tailwind CSS v3 + PostCSS
- **数据层**：vxe-pc-ui/vxe-table 数据驱动表单表格 + 图表
- **HTTP**：axios + @tanstack/vue-query（数据请求/缓存）
- **Mock**：MSW（浏览器开发环境 + Vitest 测试双模拦截）
- **构建**：开发/测试/生产三套环境变量，按 `--mode` 切换
- **代码质量**：ESLint + oxlint（双遍检查）+ oxfmt（格式化）
- **提交流程**：cz-git 交互式提交 → husky pre-commit(lint-staged) → commit-msg(commitlint)
- **国际化**：vue-i18n 11（集成 vxe-pc-ui 语言包）
- **文档**：VitePress + vitepress-demo-plugin 可交互 Demo

## 架构

```
simple-ui-wk/
├── apps/
│   └── web/                           # 主 Vue 3 单页应用
│       ├── .env.development            # 开发环境变量
│       ├── .env.test                   # 测试环境变量
│       ├── .env.production             # 生产环境变量
│       ├── src/
│       │   ├── main.ts                # 应用入口（MSW + Pinia + Router + i18n）
│       │   ├── App.vue                # 根组件
│       │   ├── i18n.ts                # vue-i18n（含 vxe-pc-ui 语言包）
│       │   ├── router/index.ts        # Vue Router（动态 import 懒加载）
│       │   ├── stores/counter.ts      # Pinia Composition API
│       │   ├── views/                 # 页面级组件
│       │   ├── components/            # 应用专有组件
│       │   │   └── __tests__/         # 组件单元测试
│       │   ├── assets/                # CSS（base.css + main.css）、图片
│       │   └── mocks/                 # MSW 请求模拟
│       │       ├── handlers.ts        #   共享请求处理器
│       │       ├── browser.ts         #   浏览器集成（开发环境）
│       │       └── node.ts            #   Node.js 集成（测试环境）
│       ├── public/
│       │   └── mockServiceWorker.js   # MSW Service Worker 脚本
│       ├── tailwind.config.js         # Tailwind CSS v3 配置
│       ├── postcss.config.mjs         # PostCSS（tailwindcss + autoprefixer）
│       ├── vite.config.ts             # Vite 配置（动态插件）
│       ├── vitest.config.ts           # Vitest 配置（含 MSW setup）
│       ├── vitest.setup.ts            # MSW 测试启动/重置/关闭
│       └── index.html                 # HTML 入口
├── packages/
│   ├── ui/                            # @simple-ui/ui — 共享 UI 组件
│   │   └── src/
│   │       ├── index.ts               # 统一导出入口
│   │       ├── helper/vxeHelper.ts    # vxe-pc-ui 全局注册
│   │       └── components/
│   │           ├── HelloWorld.vue
│   │           ├── TheWelcome.vue
│   │           ├── WelcomeItem.vue
│   │           ├── JsonForm.vue       # vxe-form 封装
│   │           ├── JsonTable.vue      # vxe-grid 封装
│   │           └── icons/             # SVG 图标组件
│   ├── shared/                        # @simple-ui/shared — 共享类型与工具
│   │   └── src/
│   │       ├── index.ts               # 导出入口
│   │       └── utils/
│   │           └── commBO.ts          # 通用业务对象类型（PageBO / BizResp / BizPageResp）
│   └── docs/                          # @simple-ui/docs — VitePress 文档站点
│       ├── articles/                  # 文档内容（按分类子目录组织）
│       │   ├── demo/                  #   Demo 展示页
│       │   ├── demos/                 #   Demo 源码（hello-world / counter / toast-demo）
│       │   ├── guide/                 #   指南
│       │   ├── ui/                    #   UI 组件文档
│       │   └── shared/                #   Shared 包文档
│       ├── .vitepress/
│       │   ├── config.ts              # VitePress 配置（含 vitepress-demo-plugin）
│       │   └── theme/
│       │       ├── index.ts           # 主题入口
│       │       ├── custom.css         # Tailwind 指令
│       │       └── css.d.ts           # TS 声明
│       ├── tailwind.config.js
│       └── postcss.config.mjs
├── .commitlintrc.cjs                  # commitlint + cz-git 共享配置
├── .lintstagedrc.cjs                  # lint-staged 预提交任务
├── .husky/
│   ├── pre-commit                     # npx lint-staged
│   └── commit-msg                     # npx commitlint --edit $1
├── .oxlintrc.json                     # oxlint correctness 规则
├── .oxfmtrc.json                      # oxfmt（semi: false, singleQuote: true）
├── eslint.config.ts                   # ESLint flat config
├── pnpm-workspace.yaml                # 工作空间定义
├── tsconfig.base.json                 # 共享 TypeScript 配置
└── playwright.config.ts               # Playwright E2E
```

### 包依赖关系

```
root（编排脚本 + 共享运行时依赖 + 代码检查/格式化/Git 工具）
├── apps/web ───────┬── @simple-ui/ui, @simple-ui/shared (workspace:*)
│                    └── vue / pinia / vue-router / vue-i18n
│                        vxe-pc-ui / vxe-table / echarts / vue-echarts
│                        tailwindcss / postcss / autoprefixer
│                        @tanstack/vue-query / @vueuse/core / axios / big.js
├── packages/ui（peerDep: vue）— 源文件导入，vxe-pc-ui/vxe-table 全局注册
├── packages/shared（无运行时依赖）— PageBO / BizResp / BizPageResp 类型
└── packages/docs— vitepress / vitepress-demo-plugin / tailwindcss
```

## 技术栈

| 领域          | 技术                                                       |
| ------------- | ---------------------------------------------------------- |
| **框架**      | Vue 3（`<script setup lang="ts">` Composition API）        |
| **构建**      | Vite 8（函数式配置，动态加载插件）                         |
| **状态管理**  | Pinia（Composition API Store）                             |
| **路由**      | Vue Router 5（`createWebHistory`，动态 `import()` 懒加载） |
| **数据请求**  | axios + @tanstack/vue-query                                |
| **语言**      | TypeScript strict + `noUncheckedIndexedAccess`             |
| **包管理**    | pnpm 11 workspace（`apps/*` + `packages/*`）               |
| **样式**      | Tailwind CSS v3（PostCSS）+ Scoped CSS + CSS 变量          |
| **UI 组件库** | vxe-pc-ui + vxe-table（数据驱动表单/表格）                 |
| **图表**      | ECharts 6 + vue-echarts                                    |
| **国际化**    | vue-i18n 11（集成 vxe-pc-ui 语言包）                       |
| **Mock**      | MSW 2（浏览器 Service Worker + Node.js 双环境拦截）        |
| **单元测试**  | Vitest + jsdom + @vue/test-utils + MSW                     |
| **E2E**       | Playwright（Chromium / Firefox / WebKit）                  |
| **类型检查**  | vue-tsc --build（增量模式）                                |
| **代码检查**  | oxlint（correctness）+ ESLint（完整规则，双遍）            |
| **格式化**    | oxfmt（`semi: false, singleQuote: true`）                  |
| **开发工具**  | Vue DevTools（仅开发模式启用）                             |
| **打包分析**  | rollup-plugin-visualizer（`ANALYZE=true` 时生成）          |
| **文档站**    | VitePress 1.x + vitepress-demo-plugin（可交互 Demo）       |
| **提交规范**  | cz-git + commitlint + husky + lint-staged                  |

## 多环境构建

三套环境通过 `.env.{mode}` 文件和 `vite --mode` 切换：

| 环境            | 文件               | 脚本              | 命令                               |
| --------------- | ------------------ | ----------------- | ---------------------------------- |
| **development** | `.env.development` | `pnpm dev`        | 开发服务器（HMR + MSW + DevTools） |
| **test**        | `.env.test`        | `pnpm build:test` | 测试构建                           |
| **production**  | `.env.production`  | `pnpm build`      | 生产构建（type-check + build）     |

所有 `VITE_*` 前缀的变量通过 `import.meta.env` 在客户端代码中访问。

## Git 提交工作流

```
git commit
  │
  ├─→ [pre-commit]  lint-staged
  │     ├── *.{js,ts,tsx,vue}          → oxlint --fix → eslint --fix --cache
  │     └── *.{js,ts,tsx,vue,json,css,md,html}  → oxfmt
  │
  ├─→ [commit-msg]  commitlint
  │     └── @commitlint/config-conventional
  │
  └─→ 提交成功
```

```sh
# 交互式提交
pnpm commit
```

提交类型：`feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `chore`

影响范围：`web` / `ui` / `shared` / `docs` / `root`

## MSW 请求模拟

开发模式和单元测试中自动拦截 HTTP 请求，返回模拟数据。

### 浏览器端（开发环境）

`main.ts` 检测 `import.meta.env.DEV` 后动态加载 Service Worker，注册 `public/mockServiceWorker.js`，拦截浏览器发出的请求。

### Node.js 端（Vitest 测试）

`vitest.setup.ts` 在测试前调用 `server.listen()`，每个测试后 `resetHandlers()`，全部结束后 `close()`。

### 添加模拟接口

编辑 `apps/web/src/mocks/handlers.ts`：

```ts
import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('https://api.example.com/user', () => {
    return HttpResponse.json({ id: 'abc-123', firstName: 'John' })
  }),
]
```

## 打包体积分析

```sh
pnpm build:analyze
```

设置 `ANALYZE=true` 环境变量，触发 `rollup-plugin-visualizer` 在构建完成后生成 `stats.html`（交互式 treemap），展示各模块 gzip/brotli 压缩后体积占比。

## 快速开始

### 前置依赖

- **Node.js**：`^22.18.0 || >=24.12.0`
- **pnpm**：11.x
- **Playwright 浏览器**（E2E 时）：`npx playwright install`

### 安装

```sh
pnpm install
```

### 开发

```sh
pnpm dev           # Web 应用（HMR + MSW + DevTools）
pnpm docs:dev      # 文档站
```

### 构建

```sh
pnpm build         # 生产构建（type-check + vite build --mode production）
pnpm build:test    # 测试环境构建（vite build --mode test）
pnpm build:analyze # 生产构建 + 打包分析报告
pnpm docs:build    # 文档站构建
```

### 测试

```sh
pnpm test:unit     # Vitest（含 MSW 自动拦截）
pnpm test:e2e      # Playwright
```

### 代码检查与格式化

```sh
pnpm lint          # oxlint → ESLint 双遍
pnpm format        # oxfmt
```

## Tailwind CSS 使用说明

- `apps/web`：`tailwind.config.js` → 扫描 `src/` + `packages/ui/src/`
- `packages/docs`：`tailwind.config.js` → 扫描 `articles/` + `packages/ui/src/`
- 在 `@simple-ui/ui` 组件 `<template>` 中可直接使用 Tailwind 类

## 包开发说明

### `@simple-ui/ui`

- 组件使用 `<script setup lang="ts">`，引入的是源文件，由 Vite 编译
- 包装组件参照 `JsonForm`/`JsonTable` 模式：透传 Props/Slots/Events + `defineOptions` 命名
- **子包内部不支持 `@/` 别名**，使用相对路径导入

### `@simple-ui/shared`

- 存放跨包类型定义和工具函数
- 当前提供：`PageBO`（分页对象）、`BizResp`（通用响应）、`BizPageResp`（分页响应）

## VS Code 扩展推荐

- **Vue (Official)** — 语言支持（禁用 Vetur）
- **oxlint** — 编辑器反馈
- **ESLint** — 编辑器反馈
- **Playwright Test for VSCode** — E2E 运行器

## 配置文件索引

| 文件                               | 说明                                                 |
| ---------------------------------- | ---------------------------------------------------- |
| `eslint.config.ts`                 | ESLint flat config（Vue + TS + Playwright + Vitest） |
| `.oxlintrc.json`                   | oxlint correctness 规则                              |
| `.oxfmtrc.json`                    | oxfmt（无分号、单引号）                              |
| `.commitlintrc.cjs`                | commitlint + cz-git 共享配置                         |
| `.lintstagedrc.cjs`                | lint-staged 预提交任务                               |
| `.husky/pre-commit`                | 提交前触发 lint-staged                               |
| `.husky/commit-msg`                | 提交时触发 commitlint                                |
| `tsconfig.base.json`               | 共享 TypeScript 严格模式                             |
| `apps/web/vite.config.ts`          | Vite 函数式配置（动态插件）                          |
| `apps/web/vitest.config.ts`        | Vitest + MSW setup                                   |
| `apps/web/vitest.setup.ts`         | MSW 测试生命周期                                     |
| `apps/web/postcss.config.mjs`      | PostCSS（tailwindcss + autoprefixer）                |
| `apps/web/tailwind.config.js`      | Web 应用 Tailwind                                    |
| `apps/web/.env.*`                  | 开发/测试/生产 三套环境变量                          |
| `packages/docs/postcss.config.mjs` | 文档站 PostCSS                                       |
| `packages/docs/tailwind.config.js` | 文档站 Tailwind                                      |