# Nuwax 应用开发平台模板接入规范

> **版本**: 1.0.0
> **更新日期**: 2026-04-24
> **适用模板**: `react-vite`、`vue3-vite`

---

## 目录

- [1. 概述](#1-概述)
- [2. 环境要求](#2-环境要求)
- [3. 模板目录结构](#3-模板目录结构)
- [4. 配置文件规范](#4-配置文件规范)
- [5. 样式规范 TailwindCSS](#5-样式规范-tailwindcss)
- [6. 路由规范 Hash 模式](#6-路由规范-hash-模式)
- [7. 核心模块约定](#7-核心模块约定)
- [8. UI 组件库](#8-ui-组件库)
- [9. 构建与质量门禁](#9-构建与质量门禁)
- [10. 交付物格式](#10-交付物格式)
- [11. 禁止事项](#11-禁止事项)
- [12. React / Vue 对照表](#12-react-vue-对照表)
- [13. 验收 Checklist](#13-验收-checklist)

---

## 1. 概述

本文档定义了接入 Nuwax 应用开发平台的前端模板必须遵循的结构、配置和代码规范。

接入方需按照本规范交付符合平台标准的模板项目，以确保：

- 模板可在 Nuwax 应用开发平台上正确运行（Hash 路由、静态托管兼容）
- 构建产物符合平台部署要求
- 开发体验与平台工具链一致

**本规范中每一项均标注**：

| 标记 | 含义 |
|------|------|
| **[必要]** | 不满足则无法通过验收，模板不可接入平台 |
| **[可选]** | 推荐采用，但可由接入方根据业务需求自行决定 |

---

## 2. 环境要求

**[必要]** 以下为模板开发和构建的最低环境要求：

| 工具 | 最低版本 |
|------|----------|
| Node.js | >= 18.0.0 |
| pnpm | >= 8.0.0 |

---

## 3. 模板目录结构

### 3.1 React + Vite 模板 **[必要]**

```
<project-root>/
├── index.html                  # [必要] 入口 HTML
├── package.json                # [必要] 包配置
├── meta.json                   # [必要] 模板元信息
├── vite.config.ts              # [必要] Vite 构建配置
├── tsconfig.json               # [必要] TypeScript 配置
├── tsconfig.node.json          # [必要] Node 环境 TS 配置
├── tailwind.config.js          # [必要] TailwindCSS 配置
├── postcss.config.js           # [必要] PostCSS 配置
├── components.json             # [可选] shadcn/ui 组件配置
├── AGENTS.md                   # [可选] AI Agent 规则文件
├── CLAUDE.md                   # [可选] AI Agent 规则文件（与 AGENTS.md 保持一致）
├── .prettierrc                 # [可选] Prettier 格式化配置
├── .eslintrc.json              # [可选] ESLint 配置
├── .editorconfig               # [可选] 编辑器配置
└── src/
    ├── main.tsx                # [必要] 应用入口
    ├── App.tsx                 # [必要] 根组件（RouterProvider）
    ├── index.css               # [必要] 全局样式（含 Tailwind 指令）
    ├── vite-env.d.ts           # [必要] Vite 类型声明
    ├── pages/                  # [必要] 页面组件目录
    │   ├── Home.tsx            # [必要] 首页
    │   └── NotFound.tsx        # [必要] 404 页面
    ├── components/             # [必要] 组件目录
    │   └── ui/                 # [可选] UI 基础组件（shadcn/ui）
    ├── lib/                    # [必要] 工具库目录
    │   ├── api.ts              # [可选] HTTP 客户端
    │   ├── services.ts         # [可选] 数据服务层
    │   └── utils.ts            # [必要] 工具函数（至少含 cn()）
    ├── router/                 # [必要] 路由配置目录
    │   └── index.tsx           # [必要] 路由注册
    └── examples/               # [可选] 示例页面
```

### 3.2 Vue 3 + Vite 模板 **[必要]**

```
<project-root>/
├── index.html                  # [必要] 入口 HTML
├── package.json                # [必要] 包配置
├── meta.json                   # [必要] 模板元信息
├── vite.config.ts              # [必要] Vite 构建配置
├── tsconfig.json               # [必要] TypeScript 配置
├── tsconfig.node.json          # [必要] Node 环境 TS 配置
├── tailwind.config.js          # [必要] TailwindCSS 配置
├── postcss.config.js           # [必要] PostCSS 配置
├── components.json             # [可选] shadcn-vue 组件配置
├── AGENTS.md                   # [可选] AI Agent 规则文件
├── CLAUDE.md                   # [可选] AI Agent 规则文件（与 AGENTS.md 保持一致）
├── .prettierrc                 # [可选] Prettier 格式化配置
├── .eslintrc.cjs               # [可选] ESLint 配置
├── .editorconfig               # [可选] 编辑器配置
└── src/
    ├── main.ts                 # [必要] 应用入口
    ├── App.vue                 # [必要] 根组件（<router-view />）
    ├── style.css               # [必要] 全局样式（含 Tailwind 指令）
    ├── pages/                  # [必要] 页面组件目录
    │   ├── Home.vue            # [必要] 首页
    │   └── NotFound.vue        # [必要] 404 页面
    ├── components/             # [必要] 组件目录
    │   └── ui/                 # [可选] UI 基础组件（shadcn-vue）
    ├── lib/                    # [必要] 工具库目录
    │   ├── api.ts              # [可选] HTTP 客户端
    │   ├── services.ts         # [可选] 数据服务层
    │   └── utils.ts            # [必要] 工具函数（至少含 cn()）
    ├── router/                 # [必要] 路由配置目录
    │   └── index.ts            # [必要] 路由注册
    └── examples/               # [可选] 示例页面
```

---

## 4. 配置文件规范

### 4.1 `package.json` **[必要]**

以下字段和 scripts 必须存在：

```jsonc
{
  "name": "@xagi-templates/<template-name>",  // [必要] 遵循 @xagi-templates 命名空间（可自定义 name，但须保持 scoped 格式）
  "version": "<version>",                       // [必要] 语义化版本，与 meta.json 保持一致
  "private": true,                             // [必要] 标记为私有包
  "type": "module",                            // [必要] ESM 模块系统
  "scripts": {
    "dev": "vite",                             // [必要] 启动开发服务器
    "build": "tsc && vite build",              // [必要] 生产构建（Vue: "vite build"）
    "type-check": "tsc --noEmit",              // [必要] 类型检查（Vue: "vue-tsc --noEmit"）
    "lint": "eslint src ...",                  // [必要] 代码规范检查
    "check": "pnpm run type-check && pnpm run lint" // [必要] 组合质量门禁
  },
  "engines": {
    "node": ">=18.0.0"                         // [必要] Node 版本约束
  }
}
```

**[可选]** 推荐包含的 scripts：

```jsonc
{
  "scripts": {
    "build:production": "NODE_ENV=production vite build",
    "preview": "vite preview",
    "lint:fix": "eslint src --fix",
    "clean": "rm -rf dist",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}
```

### 4.2 `vite.config.ts` **[必要]**

**[必要]** 必须配置 `@` 路径别名指向 `./src`：

```ts
// react-vite
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})
```

```ts
// vue3-vite
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})
```

### 4.3 `tsconfig.json` **[必要]**

**[必要]** 以下配置项必须包含：

```jsonc
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,                    // [必要] 严格模式
    "noUnusedLocals": true,            // [必要] 禁止未使用的局部变量
    "noUnusedParameters": true,        // [必要] 禁止未使用的参数
    "noFallthroughCasesInSwitch": true, // [必要] switch 禁止贯穿
    "skipLibCheck": true,
    "isolatedModules": true,
    "noEmit": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]               // [必要] 与 vite.config.ts 别名一致
    }
  }
}
```

React 模板额外需要：**[必要]**

```jsonc
{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
```

Vue 模板额外需要：**[必要]**

```jsonc
{
  "compilerOptions": {
    "jsx": "preserve"
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
}
```

### 4.4 `meta.json` **[必要]**

模板元信息，平台据此识别模板类型：

```jsonc
{
  "name": "React + Vite",           // 或 "Vue 3 + Vite"
  "description": "模板描述",
  "version": "<version>",               // [必要] 与 package.json 版本保持一致
  "author": "<author>",
  "framework": "react",             // [必要] "react" 或 "vue"
  "bundler": "vite",                // [必要] 固定为 "vite"
  "language": "typescript",          // [必要] 固定为 "typescript"
  "category": "frontend"
}
```

### 4.5 `index.html` **[必要]**

React 模板：

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>React Vite App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

Vue 模板：

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vue3 Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

**[必要]** 关键要求：
- React 挂载点 `id="root"`，Vue 挂载点 `id="app"`
- `<script type="module">` 入口指向对应 main 文件

### 4.6 `components.json` **[可选]**

仅在使用 shadcn/ui（React）或 shadcn-vue（Vue）时需要。

React（shadcn/ui）：

```jsonc
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}
```

Vue（shadcn-vue）：

```jsonc
{
  "$schema": "https://shadcn-vue.com/schema.json",
  "style": "new-york",
  "typescript": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/style.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib"
  },
  "iconLibrary": "lucide"
}
```

### 4.7 `AGENTS.md` / `CLAUDE.md` **[可选]**

AI Agent 规则文件，用于指导 AI 编码助手（如 Cursor、Claude Code 等）在模板中高效、一致地开发功能。两个文件内容应保持一致，以兼容不同 AI 工具链。

**[可选]** 但强烈推荐包含，可显著提升 AI 辅助开发的质量和一致性。

文件必须包含以下通用章节：

#### 必须包含的章节

```markdown
# <React|Vue> Vite 模板 — Agent 规则

## 目标

使用确定性规则指导 AI Agent 高效交付功能，减少猜测。

## 命令约定

仅使用 `pnpm`。

## 任务入口（始终遵循）

1. 用一句话确认目标模板和功能目标。
2. 定位对应模块区域（pages、components、lib、router）。
3. 复用 src/examples 和 src/components/ui 中的已有模式。
4. 使用框架原生风格实现（React 函数组件 + hooks / Vue Composition API + <script setup lang="ts">）。
5. 完成前运行 `pnpm check`。

## 同构结构映射

| 关注点     | 路径位置                    |
| ---------- | --------------------------- |
| 路由页面   | src/pages/*.<tsx|vue>       |
| 通用组件   | src/components/**           |
| API 客户端 | src/lib/api.ts              |
| 服务层     | src/lib/services.ts         |
| 工具函数   | src/lib/utils.ts            |
| 路由注册   | src/router/index.<tsx|ts>   |

## 最小交付路径

### 新建页面（5 步）
### 新建组件（4 步）
### 新建 API 流程（4 步）

## 允许的变更
## 禁止的变更
## 提交前检查清单
```

#### 关键要求

- **通用性**：文件中不得包含任何组织名称、品牌名称或内部系统代号
- **命令约定**：必须列出 `dev`、`build`、`type-check`、`lint`、`check` 五个命令
- **结构映射**：路径必须与模板实际目录结构一致
- **交付路径**：新建页面、组件、API 流程的步骤必须与实际约定一致
- **提交前检查清单**：必须要求 `pnpm check` 通过

---

## 5. 样式规范 TailwindCSS

### 5.1 基础配置 **[必要]**

**[必要]** 入口 CSS 必须包含 Tailwind 三指令：

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

**[必要]** `postcss.config.js` 必须包含 TailwindCSS + Autoprefixer：

```js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
```

### 5.2 `tailwind.config.js` Safelist **[必要]**

**[必要]** 由于平台需要通过类名字符串动态组合样式（如低代码设计模式场景），**必须将所有常用 Tailwind 工具类加入 safelist**，防止构建时被 tree-shake 误删。

需要覆盖的 safelist 类别：

| 类别 | 示例 | 覆盖范围 |
|------|------|----------|
| 颜色 | `text-blue-500`, `bg-primary-600` | 22 个默认色板 + `primary` 自定义色板 × 11 个色阶 × 15 个前缀 |
| 间距 | `p-4`, `m-8`, `px-6` | 0–96 全部间距值 × 14 个 padding/margin 前缀 |
| 边框宽度 | `border-2`, `border-t-4` | 5 个宽度值 × 7 个方向前缀 |
| 边框样式 | `border-solid`, `border-dashed` | 6 种样式 |
| 字重 | `font-bold`, `font-medium` | 9 个字重 |
| 字号 | `text-sm`, `text-2xl` | 13 个尺寸 |
| 行高 | `leading-normal`, `leading-6` | 14 个值 |
| 字距 | `tracking-tight`, `tracking-wide` | 6 个值 |
| 文本对齐 | `text-left`, `text-center` | 6 个值 |
| 透明度 | `opacity-50`, `opacity-100` | 15 个值 |
| 圆角 | `rounded-md`, `rounded-tl-sm` | 8 个值 × 9 个方向前缀 |
| 阴影 | `shadow-md`, `shadow-lg` | 7 个值 |

**[必要]** 参考实现结构（完整代码见标准模板 `tailwind.config.js`）：

```js
// 颜色 safelist 生成函数
const defaultColors = ['slate', 'gray', /* ...全部 22 个 */]
const customColors = ['primary']          // [必要] 自定义主色调
const colorShades = [50, 100, 200, /* ... */ 900, 950]
const colorPrefixes = ['text', 'bg', 'border', 'ring', /* ... */]

function generateColorSafelist() { /* ... */ }
function generateSpacingSafelist() { /* ... */ }
function generateBorderWidthSafelist() { /* ... */ }
function generateBorderRadiusSafelist() { /* ... */ }
function generateShadowSafelist() { /* ... */ }
// ... 其他 safelist 函数

export default {
  content: ['./index.html', './src/**/*.{vue,js,ts,jsx,tsx}'],
  safelist: [
    ...generateColorSafelist(),
    ...generateSpacingSafelist(),
    ...generateBorderWidthSafelist(),
    ...generateBorderStyleSafelist(),
    ...generateFontWeightSafelist(),
    ...generateFontSizeSafelist(),
    ...generateLineHeightSafelist(),
    ...generateLetterSpacingSafelist(),
    ...generateTextAlignSafelist(),
    ...generateOpacitySafelist(),
    ...generateBorderRadiusSafelist(),
    ...generateShadowSafelist(),
  ],
  // ...
}
```

> **重要**：标准模板中已包含完整的 safelist 生成函数，可直接复用 `tailwind.config.js`，无需自行编写。

### 5.3 自定义主题 **[必要]**

**[必要]** 必须包含 `primary` 自定义色板：

```js
theme: {
  extend: {
    colors: {
      primary: {
        50: '#eff6ff',
        100: '#dbeafe',
        200: '#bfdbfe',
        300: '#93c5fd',
        400: '#60a5fa',
        500: '#3b82f6',   // 主色
        600: '#2563eb',
        700: '#1d4ed8',
        800: '#1e40af',
        900: '#1e3a8a',
      },
    },
  },
},
```

**[必要]** `darkMode` 配置为 `'class'`：

```js
export default {
  // ...
  darkMode: 'class',
}
```

**[可选]** 推荐包含的扩展：

```js
theme: {
  extend: {
    fontFamily: {
      sans: ['Inter', 'system-ui', 'sans-serif'],
      mono: ['Fira Code', 'monospace'],
    },
    spacing: { 18: '4.5rem', 88: '22rem' },
    borderRadius: { '4xl': '2rem' },
    boxShadow: { soft: '0 2px 15px -3px rgba(0,0,0,0.07), ...' },
    animation: {
      'fade-in': 'fadeIn 0.5s ease-in-out',
      'slide-up': 'slideUp 0.3s ease-out',
      'accordion-down': 'accordion-down 0.2s ease-out',
      'accordion-up': 'accordion-up 0.2s ease-out',
    },
    keyframes: {
      fadeIn: { '0%': { opacity: '0' }, '100%': { opacity: '1' } },
      slideUp: { '0%': { transform: 'translateY(10px)', opacity: '0' }, '100%': { transform: 'translateY(0)', opacity: '1' } },
      'accordion-down': { from: { height: '0' }, to: { height: 'var(--radix-accordion-content-height)' } },
      'accordion-up': { from: { height: 'var(--radix-accordion-content-height)' }, to: { height: '0' } },
    },
  },
},
```

### 5.4 CSS 变量体系 **[可选]**

React 模板推荐使用 CSS 变量定义主题色（兼容 shadcn/ui）：

```css
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96%;
    --muted: 210 40% 96%;
    --destructive: 0 84.2% 60.2%;
    --border: 214.3 31.8% 91.4%;
    --ring: 221.2 83.2% 53.3%;
    --radius: 0.5rem;
  }
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode 变量覆盖 */
  }
}
```

### 5.5 `cn()` 样式合并函数 **[必要]**

**[必要]** `src/lib/utils.ts` 中必须提供 `cn()` 函数用于合并 Tailwind 类名：

```ts
import { type ClassValue, clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]): string {
  return twMerge(clsx(inputs))
}
```

**[必要]** 对应依赖：

```jsonc
{
  "dependencies": {
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.0"
  }
}
```

---

## 6. 路由规范 Hash 模式

### 6.1 为什么必须使用 Hash 路由 **[必要]**

Nuwax 应用开发平台使用静态文件托管，所有模板的构建产物以静态资源形式部署。Hash 路由（`/#/path`）的 URL fragment 不会被发送到服务器，因此**无需服务器端 URL 重写规则**，确保所有路由在任意静态托管环境均可正常工作。

### 6.2 React 模板路由 **[必要]**

**[必要]** 使用 `createHashRouter`（来自 `react-router-dom`）：

```tsx
// src/router/index.tsx
import { createHashRouter } from 'react-router-dom'
import Home from '@/pages/Home'
import NotFound from '@/pages/NotFound'

export const router = createHashRouter([
  { path: '/', element: <Home /> },
  { path: '*', element: <NotFound /> },
  // 业务路由在此添加
])
```

**[必要]** 根组件使用 `RouterProvider`：

```tsx
// src/App.tsx
import { RouterProvider } from 'react-router-dom'
import { router } from '@/router'

function App() {
  return <RouterProvider router={router} />
}

export default App
```

### 6.3 Vue 模板路由 **[必要]**

**[必要]** 使用 `createWebHashHistory`（来自 `vue-router`）：

```ts
// src/router/index.ts
import { createRouter, createWebHashHistory } from 'vue-router'
import Home from '@/pages/Home.vue'
import NotFound from '@/pages/NotFound.vue'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    { path: '/', name: 'home', component: Home },
    { path: '/:pathMatch(.*)*', name: 'not-found', component: NotFound },
    // 业务路由在此添加
  ],
})

export default router
```

**[必要]** 根组件使用 `<router-view />`：

```vue
<!-- src/App.vue -->
<template>
  <router-view />
</template>
```

### 6.4 路由依赖 **[必要]**

```jsonc
// React
{ "dependencies": { "react-router-dom": "7.9.5" } }

// Vue
{ "dependencies": { "vue-router": "^4.6.0" } }
```

---

## 7. 核心模块约定

### 7.1 `src/lib/utils.ts` **[必要]**

**[必要]** 至少包含 `cn()` 函数。

**[可选]** 推荐包含的工具函数：

| 函数 | 说明 |
|------|------|
| `cn(...inputs)` | Tailwind 类名合并 |
| `formatDate(date, options?)` | 日期格式化 |
| `debounce(fn, wait)` | 函数防抖 |
| `throttle(fn, limit)` | 函数节流 |
| `isMobile()` | 移动端检测 |
| `isDarkMode()` | 暗色模式检测 |
| `toggleDarkMode()` | 暗色模式切换 |
| `initDarkMode()` | 初始化暗色模式 |

### 7.2 `src/lib/api.ts` **[可选]**

如果项目需要 HTTP 请求能力，推荐遵循以下结构：

```
ApiClient 类
├── constructor(baseURL?)     — 创建 Axios 实例，60s 超时
├── setupInterceptors()       — 请求/响应拦截器
├── get/post/put/delete/patch — 标准 HTTP 方法
└── 导出
    ├── apiClient             — ApiClient 单例
    ├── api                   — 便捷方法集合 { get, post, put, delete, patch }
    └── extractApiData()      — 解包后端响应 { code, data, message } -> data
```

**[可选]** HTTP 客户端可自行选择（Axios、fetch 等），但如使用 Axios，建议保持与标准模板一致的接口设计。

### 7.3 `src/lib/services.ts` **[可选]**

**[可选]** 数据服务层，封装业务 API 调用。推荐模式：

React（useApi Hook）：

```tsx
export function useApi<T>(apiCall: () => Promise<T>, deps: any[] = []) {
  // 返回 { data, loading, error, refetch }
}
```

Vue（useApi 组合式函数）：

```ts
export function useApi<T>(apiCall: () => Promise<T>, options?: UseApiOptions) {
  // 返回 { data: Ref, loading: Ref, error: Ref, execute, refetch }
}
```

**[可选]** SSE 流式请求（`streamRequest`），用于对接 AI 流式输出等场景。

---

## 8. UI 组件库

### 8.1 组件库选择 **[可选]**

以下为平台标准模板使用的 UI 组件方案，接入方可自行选择其他方案：

| 模板 | 推荐方案 | 组件基元 | 图标库 |
|------|----------|----------|--------|
| react-vite | shadcn/ui (new-york) | Radix UI | Lucide React |
| vue3-vite | shadcn-vue (new-york) | radix-vue | Lucide Vue Next |

### 8.2 组件放置位置 **[必要]**

**[必要]** 无论选择哪种组件库，UI 基础组件必须放在 `src/components/ui/` 目录下：

```
src/components/ui/
├── button.tsx|vue
├── card.tsx|vue
├── dialog.tsx|vue
├── input.tsx|vue
├── ...
```

### 8.3 推荐可用的 UI 组件 **[可选]**

标准模板已内置以下 shadcn 组件，可按需使用：

| 组件 | React | Vue |
|------|-------|-----|
| Accordion | `accordion.tsx` | `accordion.vue` |
| Alert Dialog | `alert-dialog.tsx` | `alert-dialog.vue` |
| Avatar | `avatar.tsx` | `avatar.vue` |
| Button | `button.tsx` | `button.vue` |
| Card | `card.tsx` | `card.vue` |
| Checkbox | `checkbox.tsx` | `checkbox.vue` |
| Dialog | `dialog.tsx` | `dialog.vue` |
| Dropdown Menu | `dropdown-menu.tsx` | `dropdown-menu.vue` |
| Form | `form.tsx` | `form.ts` |
| Input | `input.tsx` | `input.vue` |
| Label | `label.tsx` | `label.vue` |
| Popover | `popover.tsx` | `popover.vue` |
| Progress | `progress.tsx` | `progress.vue` |
| Select | `select.tsx` | `select.vue` |
| Separator | `separator.tsx` | `separator.vue` |
| Switch | `switch.tsx` | `switch.vue` |
| Tabs | `tabs.tsx` | `tabs.vue` |
| Textarea | `textarea.tsx` | `textarea.vue` |
| Tooltip | `tooltip.tsx` | `tooltip.vue` |

### 8.4 样式工具依赖 **[可选]**

如果使用 shadcn/ui 风格组件，推荐包含：

```jsonc
{
  "dependencies": {
    "class-variance-authority": "^0.7.1",   // 组件变体管理
    "tailwindcss-animate": "^1.0.7"         // Tailwind 动画插件
  }
}
```

### 8.5 表单验证 **[可选]**

| 模板 | 推荐方案 |
|------|----------|
| react-vite | zod + react-hook-form + @hookform/resolvers |
| vue3-vite | zod + vee-validate + @vee-validate/zod |

---

## 9. 构建与质量门禁

### 9.1 必须通过的命令 **[必要]**

| 命令 | 说明 | 必要性 |
|------|------|--------|
| `pnpm type-check` | TypeScript 类型检查，零错误 | **[必要]** |
| `pnpm lint` | ESLint 代码规范检查，零警告 | **[必要]** |
| `pnpm check` | 等价于 `type-check` + `lint` | **[必要]** |
| `pnpm build` | 生产构建成功，产物输出到 `dist/` | **[必要]** |

### 9.2 构建产物 **[必要]**

**[必要]** Vite 构建产物必须输出到 `dist/` 目录，且包含至少：

```
dist/
├── index.html        # [必要] 入口页面
├── assets/           # [必要] 静态资源
│   ├── index-*.js    # JS bundle
│   └── index-*.css   # CSS bundle
```

### 9.3 版本一致性 **[必要]**

**[必要]** 以下三处版本号必须保持一致：

1. `package.json` 的 `version` 字段
2. `meta.json` 的 `version` 字段
3. `templates.json` 中对应模板的 `version` 字段（如在 monorepo 中）

### 9.4 完整验收脚本 **[可选]**

参考标准模板的 `test-templates.sh`，依次执行：

```bash
pnpm check:versions                          # 版本一致性
pnpm -C packages/react-vite run check        # React 质量门禁
pnpm -C packages/vue3-vite run check         # Vue 质量门禁
pnpm -C packages/react-vite run build        # React 构建
pnpm -C packages/vue3-vite run build         # Vue 构建
```

---

## 10. 交付物格式

### 10.1 打包方式 **[必要]**

接入方交付的模板以 zip 包形式提交，结构如下：

```
<template-name>-template_<version>_<timestamp>.zip
```

示例：`react-vite-template_<version>_2026_04_24_12_00_00.zip`

### 10.2 打包排除项 **[必要]**

**[必要]** zip 包中不得包含以下内容：

```
node_modules/
dist/
dist-ssr/
.cache/
.parcel-cache/
coverage/
.DS_Store
*.log
*.local
.env
.env.local
.env.*.local
.vscode/
.idea/
*.tgz
tmp/
temp/
playground/
```

### 10.3 打包包含项 **[必要]**

**[必要]** zip 包中必须包含：

```
index.html
package.json
meta.json
vite.config.ts
tsconfig.json
tsconfig.node.json
tailwind.config.js
postcss.config.js
src/                          # 完整源码目录
```

---

## 11. 禁止事项

| 编号 | 禁止项 | 原因 |
|------|--------|------|
| 1 | 禁止使用 `BrowserRouter` / `createWebHistory` | 静态托管不支持服务端 URL 重写 |
| 2 | 禁止使用 npm / yarn 作为包管理器 | 平台统一使用 pnpm |
| 3 | 禁止在代码中硬编码敏感信息（密钥、令牌等） | 安全风险 |
| 4 | 禁止移除 `tailwind.config.js` 中的 safelist | 动态类名会被 tree-shake 删除 |
| 5 | 禁止修改 `"type": "module"` 为其他值 | ESM 是统一模块标准 |
| 6 | 禁止修改 `"private": true` 为 `false` | 模板不可发布到 npm |
| 7 | 禁止修改构建输出目录（必须为 `dist/`） | 平台部署依赖此路径 |
| 8 | 禁止移除 `@` 路径别名配置 | 模板内广泛使用 `@/` 导入 |
| 9 | 禁止在 `node_modules` 或 `dist` 目录中修改代码 | 应修改源码后重新安装/构建 |
| 10 | 禁止引入需要 Node.js 运行时的库到客户端代码 | 模板为纯 SPA，无服务端 |

---

## 12. React / Vue 对照表

以下是两个模板在等价功能上的对照，方便跨框架参考：

| 关注点 | react-vite | vue3-vite |
|--------|-----------|-----------|
| 框架 | React 18 | Vue 3 |
| 入口文件 | `src/main.tsx` | `src/main.ts` |
| 根组件 | `src/App.tsx`（`<RouterProvider />`） | `src/App.vue`（`<router-view />`） |
| 全局样式 | `src/index.css` | `src/style.css` |
| Vite 插件 | `@vitejs/plugin-react` | `@vitejs/plugin-vue` |
| 路由库 | `react-router-dom` | `vue-router` |
| 路由模式 | `createHashRouter` | `createWebHashHistory` |
| 路由文件 | `src/router/index.tsx` | `src/router/index.ts` |
| 路由注册 | `{ path, element: <Component /> }` | `{ path, name, component: Component }` |
| 404 路由 | `path: '*'` | `path: '/:pathMatch(.*)*'` |
| 页面组件 | `src/pages/*.tsx` | `src/pages/*.vue` |
| UI 组件 | `src/components/ui/*.tsx` | `src/components/ui/*.vue` |
| UI 组件库 | shadcn/ui (Radix UI) | shadcn-vue (radix-vue) |
| 图标 | `lucide-react` | `lucide-vue-next` |
| 表单验证 | zod + react-hook-form | zod + vee-validate |
| 异步 Hook | `useApi<T>(apiCall, deps)` | `useApi<T>(apiCall, options?)` |
| 类型检查 | `tsc --noEmit` | `vue-tsc --noEmit` |
| TS JSX | `"jsx": "react-jsx"` | `"jsx": "preserve"` |
| 挂载点 | `<div id="root">` | `<div id="app">` |
| 类型声明 | `src/vite-env.d.ts` | 无（tsconfig include 覆盖） |
| ESConfig | `.eslintrc.json` | `.eslintrc.cjs` |
| Hooks 模式 | `useState` / `useEffect` / `useCallback` | `ref` / `onMounted` / `watch` |
| Props 类型 | interface + React.FC | `defineProps<T>()` |
| 样式类合并 | `cn()` from `@/lib/utils` | `cn()` from `@/lib/utils` |

---

## 13. 验收 Checklist

### 目录结构

- [ ] `index.html` 存在且挂载点正确
- [ ] `package.json` 含 `"type": "module"`, `"private": true`, 完整 scripts
- [ ] `meta.json` 含 `framework`, `bundler`, `language`, `version` 字段
- [ ] `vite.config.ts` 含 `@` 路径别名
- [ ] `tsconfig.json` 含 `strict: true`, `@/*` paths
- [ ] `tailwind.config.js` 含完整 safelist + `primary` 色板 + `darkMode: 'class'`
- [ ] `postcss.config.js` 含 `tailwindcss` + `autoprefixer`
- [ ] `.gitignore` 含 `node_modules/`, `dist/` 等必要排除（如适用）
- [ ] `src/main.ts(x)` 入口文件存在
- [ ] `src/App.tsx` / `src/App.vue` 根组件存在
- [ ] `src/router/` 路由目录及路由文件存在
- [ ] `src/pages/` 页面目录含 `Home` 和 `NotFound`
- [ ] `src/components/` 组件目录存在
- [ ] `src/lib/utils.ts` 含 `cn()` 函数
- [ ] `AGENTS.md` / `CLAUDE.md` 存在且内容通用（无组织/品牌特定名称）（如提供）

### 路由

- [ ] React: 使用 `createHashRouter`
- [ ] Vue: 使用 `createWebHashHistory`
- [ ] 存在 `/` 首页路由
- [ ] 存在 404 兜底路由

### 样式

- [ ] 入口 CSS 含 `@tailwind base/components/utilities`
- [ ] TailwindCSS safelist 覆盖：颜色、间距、边框、字重、字号、行高、透明度、圆角、阴影
- [ ] `primary` 自定义色板存在
- [ ] `darkMode: 'class'` 已配置
- [ ] `cn()` 函数可用（依赖 `clsx` + `tailwind-merge`）

### 构建与质量

- [ ] `pnpm type-check` 通过，零错误
- [ ] `pnpm lint` 通过，零警告
- [ ] `pnpm build` 成功，`dist/` 目录正常生成
- [ ] `package.json` / `meta.json` 版本号一致

### 交付物

- [ ] zip 包不含 `node_modules/`, `dist/`, `.DS_Store`
- [ ] zip 包含完整源码和所有必要配置文件
- [ ] 文件名格式：`<template>-template_<version>_<timestamp>.zip`

---

## 附录：标准模板获取

接入方将以 Nuwax 应用开发平台提供的标准模板（`react-vite` / `vue3-vite`）作为基线，在遵循本规范的前提下进行业务开发。

标准模板仓库：`https://github.com/nuwax-ai/xagi-frontend-templates`

- React Vite 模板路径：`packages/react-vite/`
- Vue 3 Vite 模板路径：`packages/vue3-vite/`