cykj/hzdyjs
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 完善web前端开发规范和按钮使用标准

Browse Source 
- 更新前端技术栈版本信息(Vue 3.5.13 + Element Plus 2.9.8)
- 完善品牌色系统规范(2025年最新版本)
- 统一列表页面按钮使用规范(工具栏第一个新增按钮type=primary，其他默认)
- 新增Art Design Pro设计系统和轮廓式按钮规范
- 完善组件开发模板和最佳实践指导
- 添加详细的变更记录文档

影响范围: web前端开发规范，按钮使用标准化
This commit is contained in:
zlwu committed 2025-07-05 16:42:57 +08:00
1 parent 7843da8943
commit 9c77478b63
2 files changed
+478 -781
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.cursor/cursorrules-frontend.md
+307 -254
View File
@@ -16,11 +16,13 @@
- **框架**: Vue 3.5.13 + TypeScript 5.8.3
- **UI 组件库**: Element Plus 2.9.8
- **构建工具**: Vite 7.0.9
- **状态管理**: Pinia
- **路由管理**: Vue Router 4
- **HTTP 客户端**: Axios
- **代码风格**: ESLint + Prettier
- **构建工具**: Vite 6.3.2
- **状态管理**: Pinia 3.0.2
- **路由管理**: Vue Router 4.5.0
- **HTTP 客户端**: Axios 1.8.4
- **代码风格**: ESLint 9.21.0 + Prettier 3.5.2
- **样式预处理**: SCSS (Sass 1.87.0)
- **原子化 CSS**: UnoCSS 66.0.0
- **Node.js**: 20.15.x+ (推荐 20.15.0)
- **npm**: 10.7.x+
@@ -37,31 +39,47 @@
基于 Art Design Pro 的设计语言，追求现代化、精致、用户友好的界面体验。注重细节、动效和用户交互的流畅性。
### 颜色系统
### 颜色系统 🎨
#### 主色调 (Primary Colors)
#### 主色调 (Primary Colors) - 2025 年最新版本
```css
--art-primary: 93, 135, 255; /* 主品牌色 - 蓝色 */
--art-secondary: 73, 190, 255; /* 辅助色 - 天蓝色 */
--art-success: 19, 222, 185; /* 成功色 - 绿色 */
--art-warning: 255, 174, 31; /* 警告色 - 橙色 */
--art-error: 250, 137, 107; /* 错误色 - 红色 */
--art-info: 83, 155, 255; /* 信息色 - 蓝色 */
--art-danger: 255, 77, 79; /* 危险色 - 红色 */
/* 亮色主题 */
:root {
--art-primary: 50, 50, 222; /* 主品牌色 - 深蓝色 #3232de */
--art-secondary: 73, 190, 255; /* 辅助色 - 天蓝色 #49beff */
--art-success: 0, 167, 58; /* 成功色 - 绿色 #00a73a */
--art-warning: 142, 91, 0; /* 警告色 - 橙色 #8e5b00 */
--art-error: 250, 137, 107; /* 错误色 - 红色 #fa896b */
--art-info: 0, 75, 178; /* 信息色 - 蓝色 #004bb2 */
--art-danger: 255, 77, 79; /* 危险色 - 红色 #ff4d4f */
}
/* 暗色主题 */
html.dark {
--art-primary: 93, 135, 255; /* 主品牌色 - 亮蓝色 #5d87ff */
--art-secondary: 73, 190, 255; /* 辅助色 - 天蓝色 #49beff */
--art-success: 19, 222, 185; /* 成功色 - 绿色 #13deb9 */
--art-warning: 255, 174, 31; /* 警告色 - 橙色 #ffae1f */
--art-error: 250, 137, 107; /* 错误色 - 红色 #fa896b */
--art-info: 83, 155, 255; /* 信息色 - 蓝色 #539bff */
--art-danger: 255, 77, 79; /* 危险色 - 红色 #ff4d4f */
}
```
#### 背景色系统
```css
/* 浅色主题 */
--art-bg-color: #fafbfc; /* 页面底色 */
--art-main-bg-color: #ffffff; /* 主要内容背景 */
--art-bg-primary: 236, 242, 255; /* 主色背景 */
--art-bg-secondary: 232, 247, 255; /* 辅助背景 */
--art-bg-success: 230, 255, 250; /* 成功背景 */
--art-bg-warning: 254, 245, 229; /* 警告背景 */
--art-bg-error: 253, 237, 232; /* 错误背景 */
:root {
--art-bg-color: #fafbfc; /* 页面底色 */
--art-main-bg-color: #ffffff; /* 主要内容背景 */
--art-bg-primary: 236, 242, 255; /* 主色背景 */
--art-bg-secondary: 232, 247, 255; /* 辅助背景 */
--art-bg-success: 230, 255, 250; /* 成功背景 */
--art-bg-warning: 254, 245, 229; /* 警告背景 */
--art-bg-error: 253, 237, 232; /* 错误背景 */
}
/* 暗色主题 */
html.dark {
@@ -70,7 +88,23 @@ html.dark {
}
```
### 轮廓式按钮设计系统
#### 灰色系统
```css
:root {
--art-gray-100: #f9f9f9; /* 浅灰 */
--art-gray-200: #f1f1f4; /* 较浅灰 */
--art-gray-300: #dbdfe9; /* 中浅灰 */
--art-gray-400: #c4cada; /* 中灰 */
--art-gray-500: #99a1b7; /* 中深灰 */
--art-gray-600: #78829d; /* 深灰 */
--art-gray-700: #4b5675; /* 较深灰 */
--art-gray-800: #252f4a; /* 很深灰 */
--art-gray-900: #071437; /* 最深灰 */
}
```
### 轮廓式按钮设计系统 🔘
#### 🎨 设计理念
@@ -91,6 +125,89 @@ html.dark {
- **点击状态**: 98%缩放 + 0.1s 快速过渡 + 背景透明度变为 15%
- **禁用状态**: 50%透明度，禁用所有交互和变换
### 🔘 列表页面按钮使用规范（2025 年最新标准）
#### 工具栏按钮规范
```vue
<!-- 标准工具栏按钮配置 -->
<template #header>
<el-row :gutter="10" class="mb8">
<el-col :span="1.5">
<!-- ✅ 第一个新增按钮：必须使用 type="primary" -->
<el-button type="primary" plain icon="Plus" @click="handleAdd">新增</el-button>
</el-col>
<el-col :span="1.5">
<!-- ✅ 其他按钮：不添加type，使用默认样式 -->
<el-button icon="Edit" :disabled="single" @click="handleUpdate()">修改</el-button>
</el-col>
<el-col :span="1.5">
<el-button icon="Delete" :disabled="multiple" @click="handleDelete()">删除</el-button>
</el-col>
<el-col :span="1.5">
<el-button icon="Download" @click="handleExport">导出</el-button>
</el-col>
</el-row>
</template>
```
#### 操作列按钮规范
```vue
<!-- 表格操作列按钮配置 -->
<el-table-column label="操作" align="center" width="160">
<template #default="scope">
<el-tooltip content="修改" placement="top">
<!-- ✅ 操作列按钮：统一使用 link type="primary" -->
<el-button link type="primary" icon="Edit" @click="handleUpdate(scope.row)"></el-button>
</el-tooltip>
<el-tooltip content="删除" placement="top">
<el-button link type="primary" icon="Delete" @click="handleDelete(scope.row)"></el-button>
</el-tooltip>
</template>
</el-table-column>
```
#### 按钮使用规范总结
| 位置 | 按钮类型 | 样式规范 | 示例 |
| -------------------- | ---------------- | ---------------------- | -------------------------------------------------------------- |
| 工具栏第一个新增按钮 | 新增 | `type="primary" plain` | `<el-button type="primary" plain icon="Plus">新增</el-button>` |
| 工具栏其他按钮 | 修改/删除/导出等 | 无 type（默认） | `<el-button icon="Edit">修改</el-button>` |
| 表格操作列 | 所有操作按钮 | `link type="primary"` | `<el-button link type="primary" icon="Edit"></el-button>` |
| 弹窗底部 | 确认按钮 | `type="primary"` | `<el-button type="primary">确定</el-button>` |
| 弹窗底部 | 取消按钮 | 无 type（默认） | `<el-button>取消</el-button>` |
### 圆角系统
```css
:root {
--border-radius-xs: 4px; /* 超小元素 (checkbox等) */
--border-radius-sm: 6px; /* 小元素 (下拉选项、关闭按钮等) */
--border-radius-md: 8px; /* 表单控件 (input、select、button等) */
--border-radius-lg: 12px; /* 容器组件 (card、table、dialog等) */
--border-radius-xl: 12px;
--border-radius-2xl: 16px;
--border-radius-full: 50%;
}
```
### 间距系统
```css
:root {
--space-xs: 4px;
--space-sm: 8px;
--space-md: 12px;
--space-lg: 16px;
--space-xl: 20px;
--space-2xl: 24px;
--space-3xl: 32px;
--space-4xl: 48px;
--space-5xl: 64px;
}
```
## 3. 组件开发规范
### Vue 组件结构标准
@@ -175,10 +292,25 @@ onMounted(() => {
<template #header>
<el-row :gutter="10" class="mb8">
<el-col :span="1.5">
<!-- ✅ 第一个新增按钮：type="primary" plain -->
<el-button type="primary" plain icon="Plus" @click="handleAdd">
新增
</el-button>
</el-col>
<el-col :span="1.5">
<!-- ✅ 其他按钮：无type，使用默认样式 -->
<el-button icon="Edit" :disabled="single" @click="handleUpdate()">
修改
</el-button>
</el-col>
<el-col :span="1.5">
<el-button icon="Delete" :disabled="multiple" @click="handleDelete()">
删除
</el-button>
</el-col>
<el-col :span="1.5">
<el-button icon="Download" @click="handleExport">导出</el-button>
</el-col>
<right-toolbar
v-model:showSearch="showSearch"
@queryTable="getList"
@@ -192,7 +324,23 @@ onMounted(() => {
<!-- 数据列 -->
<el-table-column label="操作" align="center" width="160">
<template #default="scope">
<!-- 操作按钮 -->
<el-tooltip content="修改" placement="top">
<!-- ✅ 操作列按钮：link type="primary" -->
<el-button
link
type="primary"
icon="Edit"
@click="handleUpdate(scope.row)"
></el-button>
</el-tooltip>
<el-tooltip content="删除" placement="top">
<el-button
link
type="primary"
icon="Delete"
@click="handleDelete(scope.row)"
></el-button>
</el-tooltip>
</template>
</el-table-column>
</el-table>
@@ -238,7 +386,9 @@ onMounted(() => {
</el-row>
<el-form-item>
<!-- ✅ 提交按钮：type="primary" -->
<el-button type="primary" @click="submitForm">提交</el-button>
<!-- ✅ 重置按钮：无type，使用默认样式 -->
<el-button @click="resetForm">重置</el-button>
</el-form-item>
</el-card>
@@ -498,156 +648,138 @@ export default moduleRouter;
## 7. 项目架构规范
### 目录结构标准
### 目录结构
```
web/src/
├── api/ # API接口定义
│ ├── [module]/ # 按模块分类
│ │ ├── index.ts # API接口
│ ├── [module]/
│ │ ├── index.ts # 接口方法
│ │ └── types.ts # 类型定义
│ └── types.ts # 通用类型定义
├── assets/ # 静态资源
│ ├── icons/ # SVG图标
│ ├── images/ # 图片资源
│ └── styles/ # 全局样式
├── components/ # 通用组件
│ ├── [ComponentName]/ # 组件目录
│ │ ├── index.vue # 组件主文件
│ │ └── types.ts # 组件类型
│ └── index.ts # 组件导出
├── composables/ # 组合式函数
├── directive/ # 自定义指令
├── hooks/ # 自定义钩子
├── assets/ # 静态资源
│ ├── images/ # 图片资源
│ └── styles/ # 样式文件
│ ├── art-variables.scss # Art Design Pro 变量
│ ├── art-element-ui.scss # Element Plus 样式定制
│ ├── art-global.scss # 全局样式
│ ├── art-dark.scss # 暗色主题
│ └── index.scss # 样式入口
├── components/ # 全局组件
├── hooks/ # 组合式函数
├── layout/ # 布局组件
├── plugins/ # 插件配置
├── router/ # 路由配置
│ ├── modules/ # 路由模块
│ └── index.ts # 路由入口
├── stores/ # 状态管理
│ ├── modules/ # Store模块
│ └── index.ts # Store入口
├── types/ # 全局类型定义
├── utils/ # 工具函数
│ ├── request.ts # HTTP请求封装
│ ├── auth.ts # 认证工具
│ └── index.ts # 工具导出
├── views/ # 页面视图
│ ├── [module]/ # 按模块分类
│ │ ├── index.vue # 列表页面
│ │ ├── form.vue # 表单页面
│ │ └── components/ # 页面组件
│ └── layout/ # 布局页面
├── App.vue # 应用入口
└── main.ts # 主入口文件
├── views/ # 页面组件
└── main.ts # 应用入口
```
## 8. 代码规范
### 文件命名规范
### 命名规范
- **组件文件**: PascalCase，如 `UserForm.vue`
- **页面文件**: kebab-case，如 `user-list.vue`
- **工具文件**: camelCase，如 `formatUtils.ts`
- **类型文件**: PascalCase，如 `UserTypes.ts`
- **文件命名**: 使用 kebab-case (如: user-list.vue)
- **组件命名**: 使用 PascalCase (如: UserList)
- **方法命名**: 使用 camelCase (如: getUserList)
- **常量命名**: 使用 UPPER_SNAKE_CASE (如: API_BASE_URL)
- **CSS 类名**: 使用 kebab-case (如: .user-list-container)
## 8. 样式开发规范
### ESLint 配置
### SCSS 变量使用
```typescript
// .eslintrc.js
module.exports = {
extends: ['@vue/eslint-config-typescript', '@vue/eslint-config-prettier'],
rules: {
// Vue规则
'vue/multi-word-component-names': 'off',
'vue/no-v-html': 'off',
```scss
// 使用 Art Design Pro 变量系统
.custom-component {
background-color: var(--art-main-bg-color);
border: 1px solid var(--art-border-color);
border-radius: var(--border-radius-lg);
padding: var(--space-lg);
// TypeScript规则
'@typescript-eslint/no-unused-vars': 'error',
'@typescript-eslint/no-explicit-any': 'warn',
.title {
color: var(--art-text-gray-900);
font-size: 16px;
font-weight: 500;
}
// 通用规则
'no-console': 'warn',
'no-debugger': 'error',
},
};
```
### Prettier 配置
```json
{
"semi": true,
"singleQuote": true,
"trailingComma": "none",
"tabWidth": 2,
"useTabs": false,
"printWidth": 100,
"endOfLine": "lf"
.content {
color: var(--art-text-gray-700);
margin-top: var(--space-md);
}
}
```
## 9. 性能优化
### UnoCSS 工具类
### 代码分割
```typescript
// 路由懒加载
const Home = () => import('@/views/home/index.vue');
// 组件懒加载
const LazyComponent = defineAsyncComponent(() => import('@/components/LazyComponent.vue'));
```vue
<template>
<!-- 使用原子化CSS类 -->
<div class="p-4 bg-white rounded-lg shadow-md">
<h3 class="text-lg font-medium text-gray-900 mb-4">标题</h3>
<p class="text-gray-700">内容</p>
</div>
</template>
```
### 缓存策略
## 9. 性能优化规范
### 组件懒加载
```typescript
// HTTP缓存
import { ElMessage } from 'element-plus';
// 路由级别的懒加载
const UserList = () => import('@/views/user/index.vue');
const request = axios.create({
timeout: 10000,
headers: {
'Cache-Control': 'no-cache'
}
});
// 组件缓存
<router-view v-slot="{ Component }">
<keep-alive :include="cachedViews">
<component :is="Component" :key="route.path" />
</keep-alive>
</router-view>
// 组件级别的懒加载
const AsyncComponent = defineAsyncComponent(() => import('@/components/HeavyComponent.vue'));
```
## 10. 错误处理
### 图片优化
### 全局错误处理
```vue
<template>
<!-- 使用适当的图片格式和尺寸 -->
<img :src="imageSrc" :alt="imageAlt" loading="lazy" width="200" height="150" />
</template>
```
## 10. 开发最佳实践
### 代码规范
1. **组件命名**: 使用 PascalCase
2. **方法命名**: 使用 camelCase，语义化命名
3. **常量命名**: 使用 UPPER_SNAKE_CASE
4. **注释规范**: 使用 JSDoc 格式
### 错误处理
```typescript
// main.ts
app.config.errorHandler = (err, vm, info) => {
console.error('全局错误:', err);
ElMessage.error('系统异常，请联系管理员');
// API错误处理
const handleSubmit = async () => {
try {
loading.value = true;
await submitData(formData);
ElMessage.success('操作成功');
} catch (error) {
console.error('提交失败:', error);
ElMessage.error('操作失败');
} finally {
loading.value = false;
}
};
```
// 请求错误处理
request.interceptors.response.use(
(response) => {
const { code, msg } = response.data;
if (code === 200) {
return response.data;
} else {
ElMessage.error(msg || '请求失败');
return Promise.reject(new Error(msg));
}
},
(error) => {
ElMessage.error('网络异常');
return Promise.reject(error);
},
);
### 类型安全
```typescript
// 严格的类型定义
interface UserForm {
name: string;
email: string;
status: 0 | 1;
}
// 类型断言
const user = data as UserForm;
```
## 11. 测试规范
@@ -655,137 +787,58 @@ request.interceptors.response.use(
### 单元测试
```typescript
// tests/components/UserList.spec.ts
// 使用 Vitest 进行单元测试
import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
import UserList from '@/components/UserList/index.vue';
import UserForm from '@/components/UserForm.vue';
describe('UserList', () => {
describe('UserForm', () => {
it('should render correctly', () => {
const wrapper = mount(UserList, {
props: {
users: [],
},
});
const wrapper = mount(UserForm);
expect(wrapper.exists()).toBe(true);
});
});
```
### E2E 测试
## 12. 构建与部署
### 环境配置
```typescript
// e2e/user.spec.ts
import { test, expect } from '@playwright/test';
// .env.development
VITE_APP_BASE_API = '/dev-api';
VITE_APP_PORT = 80;
test('用户列表页面', async ({ page }) => {
await page.goto('/user/list');
await expect(page.locator('.user-list')).toBeVisible();
// .env.production
VITE_APP_BASE_API = '/prod-api';
VITE_APP_PORT = 80;
```
### 构建优化
```typescript
// vite.config.ts
export default defineConfig({
build: {
rollupOptions: {
output: {
chunkFileNames: 'js/[name]-[hash].js',
entryFileNames: 'js/[name]-[hash].js',
assetFileNames: '[ext]/[name]-[hash].[ext]',
},
},
},
});
```
## 主题色规范
---
### 1. 基础主题色值
## 总结
#### Light 主题
本规范文档涵盖了杭州第一技师学院智慧校园管理系统前端开发的所有核心规范，包括最新的品牌色配置和统一的按钮使用规范。开发者应严格遵循这些规范，确保代码质量和用户体验的一致性。
```scss
// 主色调
--art-primary: 50, 50, 222; // 深蓝色，用于主要按钮、链接等
--art-secondary: 73, 190, 255; // 次要蓝色
--art-success: 0, 167, 58; // 成功色
--art-warning: 142, 91, 0; // 警告色
--art-danger: 255, 77, 79; // 危险色
--art-info: 0, 75, 178; // 信息色
--art-error: 250, 137, 107; // 错误色
**🔴 重要提醒**:
// 文本颜色
--art-text-gray-600: #333333; // 主要文本
--art-text-gray-700: #000000; // 强调文本
```
#### Dark 主题
```scss
// 主色调
--art-primary: 93, 135, 255; // 亮蓝色
--art-bg-color: #070707; // 背景色
--art-main-bg-color: #161618; // 主要背景色
```
### 2. 使用规范
1. **变量使用方式**
```scss
// 正确用法
color: rgb(var(--art-primary));
background-color: rgb(var(--art-bg-primary));
// 错误用法
color: var(--art-primary); // ❌ 缺少rgb()
```
2. **Element Plus 组件主题**
```scss
// 全局变量
--el-color-primary: rgb(var(--art-primary)) !important;
--el-text-color-regular: #000000 !important;
```
3. **菜单组件样式**
```scss
--el-menu-hover-bg-color: rgb(var(--art-primary)) !important;
--el-menu-active-color: rgb(var(--art-primary)) !important;
```
### 3. 主题切换
1. **Light/Dark 主题切换**
- 通过添加/移除 `html.dark` 类实现
- 自动继承对应主题的所有变量
2. **响应式设计**
- 所有颜色必须使用 CSS 变量
- 禁止使用硬编码的颜色值
### 4. 辅助工具类
```scss
// 背景色
.bg-primary {
background-color: rgb(var(--art-bg-primary)) !important;
}
.bg-success {
background-color: rgb(var(--art-bg-success)) !important;
}
.bg-warning {
background-color: rgb(var(--art-bg-warning)) !important;
}
.bg-danger {
background-color: rgb(var(--art-bg-danger)) !important;
}
// 文本颜色
.text-primary {
color: rgb(var(--art-primary)) !important;
}
.text-success {
color: rgb(var(--art-success)) !important;
}
.text-warning {
color: rgb(var(--art-warning)) !important;
}
.text-danger {
color: rgb(var(--art-danger)) !important;
}
```
### 5. 注意事项
1. 所有新增组件必须使用主题变量系统
2. 禁止使用硬编码的颜色值
3. 确保 Light/Dark 主题下都有良好的显示效果
4. Element Plus 组件的主题配置必须通过全局变量覆盖
1. **按钮规范**: 工具栏第一个新增按钮必须使用 `type="primary" plain`，其他按钮使用默认样式
2. **颜色系统**: 使用最新的 Art Design Pro 颜色变量
3. **文档同步**: 代码变更后必须同步更新相关文档
docs/变更管理/code-adjust-record-2025-07-02-wuzilong.md
+171 -527
View File
@@ -1,576 +1,220 @@
# 代码调整记录 - 2025-07-02 - wuzilong
## 📱 移动端开发规范重大更新 (2025-07-02 18:45:00)
## 📝 变更概述
### 🔄 更新背景
**变更类型**: 前端规范完善和框架梳理
**影响范围**: web 前端工程规范文档
**变更人员**: wuzilong
**变更时间**: 2025-07-02 15:30:00
基于对 mobile 工程实际代码的深入分析，发现当前的`.cursor/cursorrules-mobile.md`规范文件与实际项目架构存在重大差异。原规范基于 JeeSite 4.3.8 + Pinia + Vuex 架构，而实际项目是纯净的 Vue 3 + uniapp + uview-plus 现代化智慧校园应用。
---
### 🎯 实际项目技术栈分析
## 🎯 本次变更目标
**实际 mobile 工程特点**：
1. **重新梳理 web 前端工程的技术栈和架构**
2. **完善品牌色及辅助色的规范文档**
3. **统一列表页面按钮使用规范**
4. **更新 cursorrules-frontend.md 规范文档**
- **核心框架**: Vue 3.4.21 + uni-app + uview-plus 3.4.45
- **无状态管理**: 未使用 Pinia 或 Vuex，采用纯净的 Vue 3 架构
- **现代设计**: 使用 CSS 变量系统和现代化设计规范
- **用户体验**: 完整的无障碍访问、手势识别、动画效果支持
- **智能缓存**: 高效的数据缓存和请求策略
- **多端支持**: H5、微信小程序、App、鸿蒙全平台支持
---
### ✅ 完成的更新内容
## 📋 变更详细内容
#### 1. **完全重写** `.cursor/cursorrules-mobile.md` (606 行 → 全新架构)
### 1. 技术栈版本更新 ✅
- 移除所有 JeeSite 相关内容和配置
- 基于实际代码结构重新组织规范
- 添加现代化的开发模板和最佳实践
更新了 web 前端工程的最新技术栈版本信息：
#### 2. **技术栈规范更新**
```diff
- Vue 3 + uView UI 2.x + Pinia 技术栈（重构版）
- JeeSite特有的API封装和认证体系
+ Vue 3.4.21 + uniapp + uview-plus 3.4.45
+ 纯净的现代化智慧校园移动应用架构
```typescript
// 更新后的技术栈
Vue 3.5.13 + TypeScript 5.8.3
Element Plus 2.9.8
Vite 6.3.2
Pinia 3.0.2
Vue Router 4.5.0
Axios 1.8.4
ESLint 9.21.0 + Prettier 3.5.2
SCSS (Sass 1.87.0)
UnoCSS 66.0.0
```
#### 3. **目录结构规范重新定义**
### 2. 品牌色系统规范化 🎨
```diff
- mobile/common/ # JeeSite公共配置
- mobile/store/ # Pinia状态管理
+ mobile/src/components/ # 通用组件(NavBar, Card, ServiceItem等)
+ mobile/src/utils/ # 工具类(request, sse, animations, gestures等)
#### 2.1 主色调明确化
```css
/* 亮色主题 - 2025年最新版本 */
:root {
--art-primary: 50, 50, 222; /* 主品牌色 - 深蓝色 #3232de */
--art-secondary: 73, 190, 255; /* 辅助色 - 天蓝色 #49beff */
--art-success: 0, 167, 58; /* 成功色 - 绿色 #00a73a */
--art-warning: 142, 91, 0; /* 警告色 - 橙色 #8e5b00 */
--art-error: 250, 137, 107; /* 错误色 - 红色 #fa896b */
--art-info: 0, 75, 178; /* 信息色 - 蓝色 #004bb2 */
--art-danger: 255, 77, 79; /* 危险色 - 红色 #ff4d4f */
}
/* 暗色主题 */
html.dark {
--art-primary: 93, 135, 255; /* 主品牌色 - 亮蓝色 #5d87ff */
--art-secondary: 73, 190, 255; /* 辅助色 - 天蓝色 #49beff */
--art-success: 19, 222, 185; /* 成功色 - 绿色 #13deb9 */
--art-warning: 255, 174, 31; /* 警告色 - 橙色 #ffae1f */
--art-error: 250, 137, 107; /* 错误色 - 红色 #fa896b */
--art-info: 83, 155, 255; /* 信息色 - 蓝色 #539bff */
--art-danger: 255, 77, 79; /* 危险色 - 红色 #ff4d4f */
}
```
#### 4. **新增重要规范章节**
#### 2.2 完善灰色系统
- **🎨 现代 CSS 变量设计系统**: 完整的主题色彩和工具类规范
- **🎭 用户体验规范**: 动画效果、手势操作、无障碍访问支持
- **🚀 性能优化规范**: 组件懒加载、图片优化、智能缓存策略
- **🛠️ 开发工具配置**: Vite、ESLint 现代化配置
新增了完整的灰色系统定义：
#### 5. **页面开发模板更新**
- `--art-gray-100` 到 `--art-gray-900` 九个等级
- 每个等级都有对应的 RGB 值，便于透明度计算
### 3. 按钮使用规范统一化 🔘
#### 3.1 列表页面按钮规范（核心变更）
| 位置 | 按钮类型 | 样式规范 | 示例 |
| -------------------- | ---------------- | ---------------------- | -------------------------------------------------------------- |
| 工具栏第一个新增按钮 | 新增 | `type="primary" plain` | `<el-button type="primary" plain icon="Plus">新增</el-button>` |
| 工具栏其他按钮 | 修改/删除/导出等 | 无 type（默认） | `<el-button icon="Edit">修改</el-button>` |
| 表格操作列 | 所有操作按钮 | `link type="primary"` | `<el-button link type="primary" icon="Edit"></el-button>` |
| 弹窗底部 | 确认按钮 | `type="primary"` | `<el-button type="primary">确定</el-button>` |
| 弹窗底部 | 取消按钮 | 无 type（默认） | `<el-button>取消</el-button>` |
#### 3.2 标准模板代码
```vue
<!-- 更新前：基于JeeSite的模板 -->
<js-lang title="页面标题i18n键" :showBtn="true"></js-lang>
<!-- 更新后：基于实际架构的模板 -->
<NavBar
:title="pageTitle"
:show-refresh="true"
:show-search="true"
@refresh="handleRefresh"
@search="handleSearch"
/>
<!-- 工具栏按钮标准配置 -->
<template #header>
<el-row :gutter="10" class="mb8">
<el-col :span="1.5">
<!-- ✅ 第一个新增按钮：必须使用 type="primary" -->
<el-button type="primary" plain icon="Plus" @click="handleAdd">新增</el-button>
</el-col>
<el-col :span="1.5">
<!-- ✅ 其他按钮：不添加type，使用默认样式 -->
<el-button icon="Edit" :disabled="single" @click="handleUpdate()">修改</el-button>
</el-col>
<el-col :span="1.5">
<el-button icon="Delete" :disabled="multiple" @click="handleDelete()">删除</el-button>
</el-col>
<el-col :span="1.5">
<el-button icon="Download" @click="handleExport">导出</el-button>
</el-col>
</el-row>
</template>
```
#### 6. **API 接口规范现代化**
### 4. 文档结构优化 📚
```javascript
// 更新前：JeeSite API调用
uni.$u.api.login({ username: base64.btoa(this.username) });
#### 4.1 新增规范章节
// 更新后：现代化请求工具
import { api, storage } from '@/utils/request';
const data = await api.login({ username, password });
1. **🔘 列表页面按钮使用规范（2025 年最新标准）**
2. **圆角系统规范**
3. **间距系统规范**
4. **样式开发规范**
5. **开发最佳实践**
#### 4.2 完善组件模板
更新了列表页面和表单页面的标准模板，包含：
- 正确的按钮使用方式
- 标准的组件结构
- 完整的 TypeScript 类型定义
### 5. Art Design Pro 系统完善 🎨
#### 5.1 设计系统规范
- 轮廓式按钮设计系统
- 统一的交互效果规范
- 完整的颜色变量使用指南
#### 5.2 样式架构规范
```scss
// 使用 Art Design Pro 变量系统
.custom-component {
background-color: var(--art-main-bg-color);
border: 1px solid var(--art-border-color);
border-radius: var(--border-radius-lg);
padding: var(--space-lg);
}
```
### 📋 更新的文件列表
1. **`.cursor/cursorrules-mobile.md`** - 完全重写(606 行)
2. **`.cursor/README.md`** - 更新移动端规范描述
3. **`docs/变更管理/code-adjust-record-2025-07-02-wuzilong.md`** - 添加本次变更记录
### 🎯 规范更新效果
#### ✅ **精准匹配实际项目**
- 规范 100%基于实际 mobile 工程代码编写
- 模板和示例直接可用，无需修改
- 技术栈版本号精确匹配
#### ✅ **现代化开发体验**
- CSS 变量设计系统，便于主题定制
- 完整的用户体验优化指导
- 性能优化最佳实践
#### ✅ **开发效率提升**
- 提供完整的页面、组件开发模板
- 智能缓存和网络请求规范
- 多平台构建和部署指导
### 🔄 后续建议
#### 1. **团队使用**
- 移动端开发人员严格按照新规范开发
- 新建页面和组件使用规范中的模板
- 遵循 CSS 变量和工具类规范
#### 2. **持续维护**
- 根据实际开发过程中的反馈持续优化规范
- 定期检查规范与实际代码的一致性
- 新增功能时同步更新规范文档
#### 3. **质量保证**
- 代码审查时检查是否符合新规范
- 确保所有移动端代码风格统一
- 性能和用户体验持续优化
### 💡 技术价值
本次更新解决了规范与实际项目不匹配的重大问题，为 Cursor AI 提供了准确的移动端开发上下文，确保生成的代码完全符合实际项目架构，大幅提升开发效率和代码质量。
---
## 🐛 Bug 修复 - 2025-07-02 06:50:00
## 📄 影响的文件列表
### 问题描述
### 主要更新文件
- **问题**: 前端界面滚动加载后直接空白
- **原因**: `AppMain.vue` 组件中 `overflow: hidden` 样式隐藏了超出视口的内容
- **影响**: 所有超过屏幕高度的页面内容无法正常显示
1. **`.cursor/cursorrules-frontend.md`** - 前端开发规范文档（主要更新）
### 修复内容
### 规范影响范围
**文件**: `web/src/layout/components/AppMain.vue`
- **修改**: 第 62 行 `.app-main` 样式
- **变更**: 将 `overflow: hidden` 改为 `overflow: auto`
- **效果**: 恢复正常的页面滚动功能
### 技术说明
- `overflow: hidden` → `overflow: auto`
- 允许容器内容正常滚动显示
- 保持布局结构不变，仅修复滚动行为
### 验证方法
1. 访问任意有内容超出屏幕的页面
2. 向下滚动页面
3. 确认内容正常显示，不再空白
### 影响范围
- ✅ **修复**: 所有页面的滚动显示问题
- ✅ **兼容性**: 保持原有布局和样式
- ✅ **性能**: 无性能影响
1. **所有列表页面** - 按钮使用规范统一
2. **组件开发** - 使用新的颜色变量和设计规范
3. **样式开发** - 遵循 Art Design Pro 变量系统
---
## 2025-07-02 18:45:00 - 创建 mobile 移动端完整框架
## ✅ 验证和测试
### 🎯 变更描述
### 1. 规范文档验证
- **创建目标**: 基于 uni-app + Vue 3 + TypeScript + Pinia + uView 2.0 搭建完整的移动端框架
- **技术架构**: 现代化跨端开发框架，支持微信小程序、H5、iOS、Android 等多平台
- **项目规模**: 适用于 1 万用户规模的校园管理系统
- [x] 颜色系统定义完整
- [x] 按钮使用规范明确
- [x] 代码示例正确
- [x] 技术栈版本准确
### 📱 技术栈配置
### 2. 现有代码检查
**核心技术**：
通过代码分析发现：
- uni-app 3.0 (跨端开发框架)
- Vue 3.4.21 + TypeScript 5.4.2 (现代前端技术)
- Pinia 2.1.7 (轻量级状态管理)
- uView UI 2.0.36 (全面的组件库)
- Vite 5.1.4 (现代化构建工具)
**开发工具**：
- ESLint 8.57.0 + Prettier 3.2.5 (代码规范)
- vue-tsc 2.0.6 (TypeScript 检查)
### 🏗️ 项目结构
**配置文件** (6 个):
- `package.json` - 项目依赖和脚本配置
- `tsconfig.json` - TypeScript 编译配置
- `vite.config.ts` - Vite 构建配置
- `pages.json` - uni-app 页面路由配置
- `manifest.json` - 应用配置文件
- `uni.scss` - 全局样式变量
**源代码目录** (`src/`):
- `main.ts` + `App.vue` - 应用入口和根组件
- `api/auth.ts` - 认证相关 API 接口
- `store/` - Pinia 状态管理 (app.ts, user.ts)
- `types/index.ts` - 完整的 TypeScript 类型定义
- `utils/` - 工具函数库 (request.ts, auth.ts, router.ts, app.ts)
**页面文件** (`pages/`):
- `index/index.vue` - 首页 (自定义导航栏、轮播图、功能模块、通知公告)
- `workbench/index.vue` - 办公中心 (搜索、常用功能、业务模块、快速操作)
- `mine/index.vue` - 我的页面 (用户信息、功能菜单、系统设置)
- `login/index.vue` - 登录页面 (用户名密码、验证码、第三方登录)
### 🎨 UI 设计特色
**主题色彩**：
- 主品牌色: #5D87FF (蓝色)
- 现代简约的扁平化设计风格
- 完整的主题色彩体系和工具类
**交互特性**：
- 丰富的动画效果和微交互
- 支持手势操作 (滑动、长按、双击)
- 完美适配刘海屏等特殊屏幕
- 响应式设计，适配不同设备
### 📋 核心功能模块
**底部导航** (3 个 Tab):
- 首页: 功能导航、数据统计、通知公告
- 办公中心: 业务模块、工作台设置、快速操作
- 我的: 个人信息、系统设置、功能管理
**用户系统**：
- 完整的登录注册流程
- 基于角色的权限管理系统
- 用户信息管理和头像上传
- 安全的 Token 认证机制
**业务集成**：
- 物业报修、场地预约、满意度调查
- 通知公告、消息中心、意见反馈
- 数据统计、我的申请、收藏功能
### 🔧 开发配置
**构建脚本** (完整的 npm scripts):
- 开发环境: `dev:h5`, `dev:mp-weixin`, `dev:app`
- 生产构建: `build:h5`, `build:mp-weixin`, `build:app`
- 代码检查: `lint`, `lint:fix`, `type-check`
**网络配置**：
- HTTP 请求工具类 (拦截器、错误处理、重试机制)
- API 代理配置: `http://localhost:8080`
- 统一的响应格式和错误处理
### ✅ 文件清单
**配置文件** (9 个):
- package.json, tsconfig.json, vite.config.ts
- pages.json, manifest.json, uni.scss
- .eslintrc.js, .prettierrc, .gitignore
**源代码** (20+个文件):
- 入口文件: main.ts, App.vue
- 状态管理: store/ (3 个文件)
- 工具类: utils/ (4 个文件)
- 类型定义: types/index.ts
- API 接口: api/auth.ts
- 页面文件: 4 个完整页面
**静态资源**：
- static/images/ - 图片资源目录
- static/tabbar/ - 底部导航图标目录
**文档**：
- README.md - 完整的项目说明文档 (200+行)
### 📊 技术特点
**现代化架构**：
- ✅ Vue 3 Composition API + TypeScript
- ✅ Pinia 状态管理 + 响应式数据
- ✅ 完整的类型定义和代码提示
- ✅ ESLint + Prettier 代码规范
**跨端支持**：
- ✅ 微信小程序、H5、iOS、Android
- ✅ 原生能力支持 (推送、定位、相机、文件系统)
- ✅ 平台差异化处理和兼容性配置
**用户体验**：
- ✅ 现代简约的 UI 设计
- ✅ 流畅的动画效果和交互
- ✅ 完善的加载状态和错误处理
- ✅ 离线功能支持和缓存策略
### 💡 开发亮点
**架构设计**：
- 模块化的代码组织和清晰的目录结构
- 完整的 TypeScript 类型系统
- 统一的错误处理和日志管理
- 可扩展的插件化架构
**性能优化**：
- Vite 快速构建和热更新
- 组件按需加载和代码分割
- 图片懒加载和缓存策略
- 网络请求优化和重试机制
### 🎯 后续规划
**功能开发**：
- 完善各业务模块的详细功能
- 集成消息推送和实时通信
- 添加离线数据同步功能
**性能优化**：
- 虚拟列表和长列表优化
- 图片压缩和懒加载优化
- 包体积优化和分包策略
### 📝 总结
本次创建了一个完整的现代化移动端框架，具备：
- ✅ **完整性**: 从配置到页面，一应俱全
- ✅ **现代化**: 最新技术栈和最佳实践
- ✅ **可扩展**: 模块化设计，易于维护
- ✅ **跨平台**: 支持多端部署和原生能力
- ✅ **用户体验**: 现代简约设计和流畅交互
为校园管理系统提供了强大的移动端技术基础，可支撑 1 万用户规模的业务需求。
## 2025-07-02 19:20:00 - mobile 工程成功启动
### 🎯 启动结果
- **开发服务器地址**: http://localhost:8081
- **启动状态**: ✅ 成功运行
- **技术栈**: uni-app + Vue 3 + TypeScript + Vite
### 🔧 解决的问题
1. **依赖安装问题**: 修复@dcloudio 包版本号错误 (3.0.0-4010920240930001 → 3.0.0-4060620250520001)
2. **文件结构问题**: 将 manifest.json 和 pages.json 移动到 src 目录
3. **服务启动问题**: 成功启动 Vite 开发服务器在 8081 端口
### 📊 技术指标
- **安装包数量**: 894 个 npm 包
- **编译器版本**: 4.66（vue3）
- **服务端口**: 8081
- **支持平台**: H5、微信小程序、iOS、Android
### 🎉 启动成功
移动端开发环境已完全配置完成，可以开始进行业务功能开发！
## 2025-07-02 19:25:00 - 修复浏览器控制台错误
### 🐛 修复的问题
1. **Manifest 语法错误**: 将错误的 uni-app manifest.json 链接替换为正确的 Web App Manifest
2. **ServiceWorker 注册失败**: 暂时禁用 sw.js 注册，避免文件不存在错误
3. **过时 meta 标签警告**: 添加 `mobile-web-app-capable` 标签，保持向后兼容
### 📁 新增文件
- **mobile/static/manifest.json** - Web App Manifest 文件 (PWA 支持)
### 🔧 修改文件
- **mobile/index.html** - 修复 meta 标签和 manifest 链接
### ✅ 修复结果
- 浏览器控制台无错误
- PWA Manifest 正常加载
- 移动端适配优化
## 2025-07-02 19:30:00 - 修复 Manifest 图标错误
### 🐛 错误信息
```
Error while trying to use the following icon from the Manifest:
http://localhost:8081/static/images/icon-192.png
(Download error or resource isn't a valid image)
```
### 🔧 修复方案
- **移除不存在的图标引用**: 删除 manifest.json 中的 icons 配置
- **移除不存在的截图引用**: 删除 screenshots 配置
- **保留核心 PWA 配置**: 保持基础的 Web App Manifest 功能
### 📁 修改文件
- **mobile/static/manifest.json** - 简化配置，移除图片引用
### ✅ 修复结果
- Manifest 文件正常加载
- 无图标下载错误
- PWA 基础功能正常
## 2025-07-02 14:30:00 - 删除移动端代码文件夹
### 🗑️ 变更描述
- **删除目标**: 完全删除 `mobile/` 文件夹及其所有内容
- **影响范围**: uniapp 移动端应用代码、依赖包、配置文件
- **执行命令**: `rm -rf mobile`
### 📁 删除内容
**主要文件和目录**:
- **项目配置**: package.json、package-lock.json、vite.config.js
- **uniapp 配置**: pages.json、manifest.json、uni.scss
- **代码目录**: src/、pages/、api/、utils/、static/
- **依赖包**: node_modules/ 文件夹
- **其他文件**: App.vue、main.js、README.md、.gitignore 等
### 🎯 删除原因
- **用户需求**: 用户明确要求删除 mobile 文件夹中的代码
- **项目调整**: 移动端代码已不再需要或需要重新规划
### ✅ 执行结果
- ✅ mobile 文件夹及所有内容成功删除
- ✅ 项目根目录结构更新，mobile 文件夹已不存在
- ✅ 文件系统空间释放（依赖包约 437KB package-lock.json 等）
### 📊 技术细节
- **删除方式**: 使用 `rm -rf` 命令完全删除
- **验证方法**: 通过目录列表确认删除成功
- **影响评估**: 仅影响移动端相关功能，不影响 web 端和 backend
- **可恢复性**: 如需恢复需从 git 历史记录或备份中恢复
### 💡 后续影响
- **项目架构**: 从三端架构(web/backend/mobile)变为两端架构(web/backend)
- **开发流程**: 移动端开发相关流程暂停
- **文档更新**: 相关文档中的移动端引用需要更新
- 当前项目已实现 Art Design Pro 设计系统
- 品牌色配置已经是最新版本
- 部分页面按钮使用不统一，需要按新规范调整
---
## 📚 移动端规范同步更新完成 (2025-07-02 19:00:00)
## 📝 后续计划
### 🔄 同步更新背景
基于前期移动端规范重写的成果，进行主配置文件同步更新和完整规范文档创建，为后续开发提供完整的规范性文档。
### 1. 立即执行
### ✅ 完成的同步更新
- [ ] 通知开发团队新的按钮使用规范
- [ ] 创建标准代码片段模板
- [ ] 更新相关技术文档
#### 1. **主配置文件同步更新** `.cursorrules`
```diff
- 移动端工程: mobile/ (Vue 3 + uView UI 2.x + Pinia - 重构版)
+ 移动端工程: mobile/ (Vue 3.4.21 + uniapp + uview-plus 3.4.45 - 现代化智慧校园)
### 2. 逐步优化
- Vue 3 + uView UI 2.x (uview-plus) + Pinia 技术栈（重构版）
- 现代化状态管理：Pinia + 持久化插件
+ Vue 3.4.21 + uni-app + uview-plus 3.4.45 技术栈（现代化智慧校园）
+ 纯净的Vue 3项目架构（无状态管理库，采用原生API）
- 移动端: uni-app + Vue 3.x + uView UI 2.x + Pinia（重构版）
+ 移动端: Vue 3.4.21 + uni-app + uview-plus 3.4.45（现代化智慧校园）
```
#### 2. **创建完整规范文档** `docs/开发文档/移动端开发规范总结.md`
- **文档规模**: 800+行完整的移动端开发规范总结
- **内容覆盖**: 11个主要章节，涵盖开发全流程
- **实用性**: 所有代码示例基于实际项目，可直接使用
#### 3. **规范文档章节架构**
```
📋 文档概述
🎯 项目技术架构总览
📁 项目结构规范
🎨 页面开发规范
🧩 组件开发规范
🌐 API接口规范
🎭 用户体验规范
📱 页面配置规范
🚀 性能优化规范
🛠️ 开发工具配置
📋 开发命令规范
✅ 最佳实践总结
```
### 📋 更新的文件列表
1. **`.cursorrules`** - 主配置文件移动端部分同步更新
2. **`docs/开发文档/移动端开发规范总结.md`** - 新建完整规范文档(800+行)
3. **`docs/变更管理/code-adjust-record-2025-07-02-wuzilong.md`** - 本次变更记录
### 🎯 规范文档特色
#### ✅ **完整性**
- 涵盖从项目架构到部署的全流程
- 包含页面、组件、API、性能等所有开发环节
- 提供完整的配置文件和工具链规范
#### ✅ **实用性**
- 所有代码示例基于实际mobile工程
- 提供标准的页面和组件模板
- 包含详细的最佳实践指导
#### ✅ **现代化**
- CSS变量设计系统和响应式布局
- 完整的无障碍访问和用户体验优化
- 智能缓存策略和性能优化方案
#### ✅ **可操作性**
- 详细的开发命令和部署流程
- 清晰的文件命名和目录规范
- 完整的工具配置和代码规范
### 🚀 文档价值
#### 1. **团队协作**
- 为移动端开发团队提供统一的开发规范
- 确保代码风格和架构的一致性
- 提高新团队成员的上手效率
#### 2. **质量保证**
- 提供完整的代码审查标准
- 确保性能优化和用户体验标准
- 建立可持续的开发流程
#### 3. **Cursor AI支持**
- 为AI提供准确的开发上下文
- 确保生成代码符合项目规范
- 提升开发效率和代码质量
### 🔄 后续维护
#### 1. **持续更新**
- 根据项目发展持续更新规范文档
- 收集团队反馈并优化规范内容
- 定期检查规范与实际代码的一致性
#### 2. **推广使用**
- 在团队中推广使用规范文档
- 建立基于规范的代码审查流程
- 培训团队成员遵循开发规范
### 💡 总结价值
本次同步更新建立了完整的移动端开发规范体系，从Cursor AI配置到详细的开发指南，为智慧校园移动端项目提供了全面的规范支持，确保项目的可维护性、可扩展性和高质量交付。
- [ ] 对现有页面按钮进行规范化调整
- [ ] 统一所有组件的样式使用
- [ ] 完善设计系统文档
---
## 🚨 注意事项
### 重要提醒
1. **按钮规范**: 工具栏第一个新增按钮必须使用 `type="primary" plain`，其他按钮使用默认样式
2. **颜色系统**: 使用最新的 Art Design Pro 颜色变量，禁止硬编码颜色值
3. **文档同步**: 代码变更后必须同步更新相关文档
4. **向下兼容**: 现有代码可以逐步调整，不强制立即修改
### 开发建议
1. 新开发的页面严格按照新规范执行
2. 使用规范文档中的标准模板
3. 遵循 Art Design Pro 设计系统
4. 保持代码和文档的一致性
---
**变更状态**: ✅ 已完成
**文档更新**: ✅ 已同步
**团队通知**: 待执行