refactor: 替换项目中的"yudao"为"AIOTAGRO"，并清理相关配置文件
This commit is contained in:
562
docs/开发文档.md
Normal file
562
docs/开发文档.md
Normal file
@@ -0,0 +1,562 @@
|
||||
# 开发文档
|
||||
|
||||
## 开发环境搭建
|
||||
|
||||
### 环境要求
|
||||
|
||||
- **Node.js**: 18.0.0 或更高版本
|
||||
- **pnpm**: 8.0.0 或更高版本
|
||||
- **Git**: 2.0.0 或更高版本
|
||||
|
||||
### 安装步骤
|
||||
|
||||
1. **安装 Node.js**
|
||||
```bash
|
||||
# 下载并安装 Node.js 18+
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
2. **安装 pnpm**
|
||||
```bash
|
||||
# 使用 npm 安装 pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# 验证安装
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
3. **克隆项目**
|
||||
```bash
|
||||
git clone https://github.com/vbenjs/vue-vben-admin.git
|
||||
cd vue-vben-admin
|
||||
```
|
||||
|
||||
4. **安装依赖**
|
||||
```bash
|
||||
# 安装项目依赖
|
||||
pnpm install
|
||||
```
|
||||
|
||||
5. **启动开发服务器**
|
||||
```bash
|
||||
# 启动 Ant Design 版本
|
||||
pnpm dev:antd
|
||||
|
||||
# 启动 Element Plus 版本
|
||||
pnpm dev:ele
|
||||
|
||||
# 启动 Naive UI 版本
|
||||
pnpm dev:naive
|
||||
```
|
||||
|
||||
## 项目结构说明
|
||||
|
||||
### 目录结构详解
|
||||
|
||||
```
|
||||
yudao-ui-admin-vben/
|
||||
├── apps/ # 应用目录
|
||||
│ ├── web-antd/ # Ant Design 版本
|
||||
│ │ ├── src/ # 源代码
|
||||
│ │ │ ├── api/ # API 接口
|
||||
│ │ │ ├── components/ # 组件
|
||||
│ │ │ ├── layouts/ # 布局
|
||||
│ │ │ ├── router/ # 路由
|
||||
│ │ │ ├── store/ # 状态管理
|
||||
│ │ │ ├── utils/ # 工具函数
|
||||
│ │ │ └── views/ # 页面视图
|
||||
│ │ └── package.json # 应用配置
|
||||
│ ├── web-ele/ # Element Plus 版本
|
||||
│ ├── web-naive/ # Naive UI 版本
|
||||
│ └── backend-mock/ # 后端模拟服务
|
||||
├── packages/ # 共享包目录
|
||||
│ ├── @core/ # 核心功能
|
||||
│ ├── constants/ # 常量定义
|
||||
│ ├── effects/ # 副作用管理
|
||||
│ ├── icons/ # 图标库
|
||||
│ ├── locales/ # 国际化
|
||||
│ ├── stores/ # 状态管理
|
||||
│ ├── styles/ # 样式文件
|
||||
│ ├── types/ # 类型定义
|
||||
│ └── utils/ # 工具函数
|
||||
└── internal/ # 内部配置
|
||||
├── lint-configs/ # 代码规范
|
||||
├── tailwind-config/ # Tailwind 配置
|
||||
├── tsconfig/ # TypeScript 配置
|
||||
└── vite-config/ # Vite 配置
|
||||
```
|
||||
|
||||
### 核心包说明
|
||||
|
||||
#### @core 包
|
||||
- 基础组件封装
|
||||
- 工具函数集合
|
||||
- 类型定义扩展
|
||||
|
||||
#### stores 包
|
||||
- 全局状态管理
|
||||
- 用户信息存储
|
||||
- 应用配置管理
|
||||
|
||||
#### utils 包
|
||||
- 数据处理工具
|
||||
- 日期时间工具
|
||||
- 表单验证工具
|
||||
|
||||
## 开发规范
|
||||
|
||||
### 代码规范
|
||||
|
||||
#### 1. 命名规范
|
||||
- **文件命名**: 使用 kebab-case (例如: user-info.vue)
|
||||
- **组件命名**: 使用 PascalCase (例如: UserInfo)
|
||||
- **变量命名**: 使用 camelCase (例如: userName)
|
||||
- **常量命名**: 使用 UPPER_SNAKE_CASE (例如: API_BASE_URL)
|
||||
|
||||
#### 2. 组件规范
|
||||
```typescript
|
||||
// 组件结构示例
|
||||
<script setup lang="ts">
|
||||
// 导入
|
||||
import { ref, computed } from 'vue'
|
||||
import { useUserStore } from '@/stores/user'
|
||||
|
||||
// 类型定义
|
||||
interface Props {
|
||||
userId: number
|
||||
userName: string
|
||||
}
|
||||
|
||||
// Props 定义
|
||||
const props = defineProps<Props>()
|
||||
|
||||
// 状态管理
|
||||
const userStore = useUserStore()
|
||||
const loading = ref(false)
|
||||
|
||||
// 计算属性
|
||||
const fullName = computed(() => `${props.userName} (${props.userId})`)
|
||||
|
||||
// 方法
|
||||
const handleSubmit = async () => {
|
||||
loading.value = true
|
||||
try {
|
||||
await userStore.updateUser(props.userId, { name: props.userName })
|
||||
} finally {
|
||||
loading.value = false
|
||||
}
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="user-info">
|
||||
<h3>{{ fullName }}</h3>
|
||||
<button :disabled="loading" @click="handleSubmit">
|
||||
{{ loading ? '保存中...' : '保存' }}
|
||||
</button>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.user-info {
|
||||
padding: 16px;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
#### 3. API 调用规范
|
||||
```typescript
|
||||
// api/user.ts
|
||||
import { request } from '@/utils/request'
|
||||
|
||||
export interface User {
|
||||
id: number
|
||||
name: string
|
||||
email: string
|
||||
}
|
||||
|
||||
export const userApi = {
|
||||
// 获取用户列表
|
||||
getUsers: (params: { page: number; size: number }) => {
|
||||
return request.get<{ list: User[]; total: number }>('/api/users', { params })
|
||||
},
|
||||
|
||||
// 创建用户
|
||||
createUser: (data: Omit<User, 'id'>) => {
|
||||
return request.post<User>('/api/users', data)
|
||||
},
|
||||
|
||||
// 更新用户
|
||||
updateUser: (id: number, data: Partial<User>) => {
|
||||
return request.put<User>(`/api/users/${id}`, data)
|
||||
},
|
||||
|
||||
// 删除用户
|
||||
deleteUser: (id: number) => {
|
||||
return request.delete(`/api/users/${id}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 样式规范
|
||||
|
||||
#### 1. CSS 类命名
|
||||
- 使用 BEM 命名规范
|
||||
- 避免使用全局样式
|
||||
- 优先使用 Tailwind CSS
|
||||
|
||||
```css
|
||||
/* BEM 示例 */
|
||||
.user-list {}
|
||||
.user-list__item {}
|
||||
.user-list__item--active {}
|
||||
.user-list__item__avatar {}
|
||||
```
|
||||
|
||||
#### 2. Tailwind CSS 使用
|
||||
```vue
|
||||
<template>
|
||||
<div class="p-4 bg-white rounded-lg shadow-sm">
|
||||
<h3 class="text-lg font-semibold text-gray-900 mb-4">用户信息</h3>
|
||||
<div class="space-y-3">
|
||||
<div class="flex items-center space-x-3">
|
||||
<span class="text-sm text-gray-500 w-20">姓名:</span>
|
||||
<span class="text-sm text-gray-900">{{ user.name }}</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 功能开发指南
|
||||
|
||||
### 1. 新增页面
|
||||
|
||||
#### 步骤 1: 创建页面组件
|
||||
```bash
|
||||
# 在 apps/web-antd/src/views/ 下创建页面目录
|
||||
mkdir -p apps/web-antd/src/views/user-management
|
||||
```
|
||||
|
||||
#### 步骤 2: 创建页面组件
|
||||
```vue
|
||||
<!-- apps/web-antd/src/views/user-management/index.vue -->
|
||||
<script setup lang="ts">
|
||||
import { ref, onMounted } from 'vue'
|
||||
import { userApi } from '@/api/user'
|
||||
|
||||
interface User {
|
||||
id: number
|
||||
name: string
|
||||
email: string
|
||||
}
|
||||
|
||||
const users = ref<User[]>([])
|
||||
const loading = ref(false)
|
||||
|
||||
const loadUsers = async () => {
|
||||
loading.value = true
|
||||
try {
|
||||
const response = await userApi.getUsers({ page: 1, size: 10 })
|
||||
users.value = response.data.list
|
||||
} finally {
|
||||
loading.value = false
|
||||
}
|
||||
}
|
||||
|
||||
onMounted(() => {
|
||||
loadUsers()
|
||||
})
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="user-management">
|
||||
<h1>用户管理</h1>
|
||||
<div v-if="loading">加载中...</div>
|
||||
<div v-else>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>ID</th>
|
||||
<th>姓名</th>
|
||||
<th>邮箱</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr v-for="user in users" :key="user.id">
|
||||
<td>{{ user.id }}</td>
|
||||
<td>{{ user.name }}</td>
|
||||
<td>{{ user.email }}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.user-management {
|
||||
padding: 20px;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
#### 步骤 3: 配置路由
|
||||
```typescript
|
||||
// apps/web-antd/src/router/routes.ts
|
||||
import type { RouteRecordRaw } from 'vue-router'
|
||||
|
||||
export const routes: RouteRecordRaw[] = [
|
||||
// ... 其他路由
|
||||
{
|
||||
path: '/user-management',
|
||||
name: 'UserManagement',
|
||||
component: () => import('@/views/user-management/index.vue'),
|
||||
meta: {
|
||||
title: '用户管理',
|
||||
requiresAuth: true
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 2. 新增组件
|
||||
|
||||
#### 创建可复用组件
|
||||
```vue
|
||||
<!-- apps/web-antd/src/components/UserAvatar.vue -->
|
||||
<script setup lang="ts">
|
||||
interface Props {
|
||||
user: {
|
||||
name: string
|
||||
avatar?: string
|
||||
}
|
||||
size?: 'small' | 'medium' | 'large'
|
||||
}
|
||||
|
||||
const props = withDefaults(defineProps<Props>(), {
|
||||
size: 'medium'
|
||||
})
|
||||
|
||||
const sizeMap = {
|
||||
small: 'w-8 h-8',
|
||||
medium: 'w-12 h-12',
|
||||
large: 'w-16 h-16'
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="user-avatar flex items-center space-x-3">
|
||||
<img
|
||||
v-if="user.avatar"
|
||||
:src="user.avatar"
|
||||
:alt="user.name"
|
||||
:class="['rounded-full', sizeMap[size]]"
|
||||
/>
|
||||
<div
|
||||
v-else
|
||||
:class="['bg-gray-200 rounded-full flex items-center justify-center', sizeMap[size]]"
|
||||
>
|
||||
<span class="text-gray-600 font-medium">{{ user.name.charAt(0) }}</span>
|
||||
</div>
|
||||
<span class="text-gray-900 font-medium">{{ user.name }}</span>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.user-avatar {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
## 开发计划
|
||||
|
||||
### 第一阶段：基础功能开发 (1-2周)
|
||||
|
||||
#### 任务清单
|
||||
- [x] 项目环境搭建
|
||||
- [x] 基础架构配置
|
||||
- [x] 用户登录功能
|
||||
- [x] 权限管理系统
|
||||
- [x] 基础布局组件
|
||||
|
||||
#### 技术要点
|
||||
- Vue3 Composition API 使用
|
||||
- TypeScript 类型定义
|
||||
- Pinia 状态管理
|
||||
- Vue Router 路由配置
|
||||
|
||||
### 第二阶段：业务功能开发 (2-3周)
|
||||
|
||||
#### 任务清单
|
||||
- [x] 用户管理模块
|
||||
- [x] 角色管理模块
|
||||
- [x] 菜单管理模块
|
||||
- [x] 系统设置模块
|
||||
- [x] 数据表格组件
|
||||
|
||||
#### 技术要点
|
||||
- 表单验证处理
|
||||
- 表格数据展示
|
||||
- 分页查询优化
|
||||
- 文件上传下载
|
||||
|
||||
### 第三阶段：优化完善 (1周)
|
||||
|
||||
#### 任务清单
|
||||
- [x] 性能优化
|
||||
- [x] 代码重构
|
||||
- [x] 测试用例编写
|
||||
- [x] 文档完善
|
||||
|
||||
#### 技术要点
|
||||
- 代码分割优化
|
||||
- 懒加载实现
|
||||
- 单元测试覆盖
|
||||
- 文档自动生成
|
||||
|
||||
## 常见问题解决
|
||||
|
||||
### 1. 依赖安装问题
|
||||
|
||||
**问题**: pnpm install 失败
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 清理缓存
|
||||
pnpm store prune
|
||||
|
||||
# 重新安装
|
||||
pnpm install --force
|
||||
```
|
||||
|
||||
### 2. 类型检查错误
|
||||
|
||||
**问题**: TypeScript 类型错误
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 检查类型错误
|
||||
pnpm type-check
|
||||
|
||||
# 自动修复
|
||||
pnpm lint:fix
|
||||
```
|
||||
|
||||
### 3. 构建失败
|
||||
|
||||
**问题**: 生产构建失败
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 清理构建缓存
|
||||
pnpm clean
|
||||
|
||||
# 重新构建
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## 测试指南
|
||||
|
||||
### 单元测试
|
||||
|
||||
```typescript
|
||||
// __tests__/user.spec.ts
|
||||
import { describe, it, expect } from 'vitest'
|
||||
import { mount } from '@vue/test-utils'
|
||||
import UserInfo from '@/components/UserInfo.vue'
|
||||
|
||||
describe('UserInfo', () => {
|
||||
it('renders user name correctly', () => {
|
||||
const wrapper = mount(UserInfo, {
|
||||
props: {
|
||||
user: {
|
||||
name: '张三',
|
||||
email: 'zhangsan@example.com'
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
expect(wrapper.text()).toContain('张三')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### E2E 测试
|
||||
|
||||
```typescript
|
||||
// __tests__/e2e/user.spec.ts
|
||||
import { test, expect } from '@playwright/test'
|
||||
|
||||
test('user login flow', async ({ page }) => {
|
||||
await page.goto('/login')
|
||||
await page.fill('[data-testid="username"]', 'admin')
|
||||
await page.fill('[data-testid="password"]', '123456')
|
||||
await page.click('[data-testid="login-btn"]')
|
||||
|
||||
await expect(page).toHaveURL('/dashboard')
|
||||
})
|
||||
```
|
||||
|
||||
## 部署指南
|
||||
|
||||
### 开发环境部署
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
pnpm dev:antd
|
||||
|
||||
# 访问地址
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
### 生产环境部署
|
||||
```bash
|
||||
# 构建生产版本
|
||||
pnpm build:antd
|
||||
|
||||
# 部署到服务器
|
||||
# 将 dist 目录上传到 Web 服务器
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 构建优化
|
||||
- 代码分割
|
||||
- 树摇优化
|
||||
- 压缩资源
|
||||
- 缓存策略
|
||||
|
||||
### 运行时优化
|
||||
- 虚拟滚动
|
||||
- 图片懒加载
|
||||
- 组件懒加载
|
||||
- 防抖节流
|
||||
|
||||
## 安全指南
|
||||
|
||||
### 前端安全
|
||||
- XSS 防护
|
||||
- CSRF 防护
|
||||
- 输入验证
|
||||
- 权限控制
|
||||
|
||||
### 代码安全
|
||||
- 敏感信息加密
|
||||
- API 密钥保护
|
||||
- 代码混淆
|
||||
- 安全审计
|
||||
|
||||
## 维护指南
|
||||
|
||||
### 日常维护
|
||||
- 定期更新依赖
|
||||
- 监控系统性能
|
||||
- 备份重要数据
|
||||
- 安全漏洞修复
|
||||
|
||||
### 版本管理
|
||||
- 使用 Git 版本控制
|
||||
- 遵循语义化版本
|
||||
- 定期发布版本
|
||||
- 维护更新日志
|
||||
Reference in New Issue
Block a user