Cloudsis项目前端开发规范

参考来源: Vue 官方风格指南、Element Plus 最佳实践 主要作用：基于 Vue 3 + TypeScript + Element Plus + 麦杰公司框架的技术栈，配合 create-maguscloud-app 的 sis 脚手架进行 cloudsis 项目开发。

适用范围

• 适用项目：使用 create-maguscloud-app 的 sis 脚手架、集成麦杰公司 Framework 5.x 的 cloudsis 项目。
• 主要文件类型：.vue / .ts / .tsx / .js / .css / .scss / .less / package.json / vite.config.*。

🚀 项目初始化

使用 create-maguscloud-app 脚手架

# 使用 npx 创建 cloudsis 项目
npx create-maguscloud-app@latest my-cloudsis-app --template sis

# 或使用特定版本
npx create-maguscloud-app@1.1.6 my-cloudsis-app --template sis

# 进入项目目录
cd my-cloudsis-app

# 安装依赖
pnpm i

CloudSis依赖自定义插件一览

📁 项目结构 (sis 脚手架)

src/
├── api/                 # API 请求
├── components/          # 通用组件
├── common
│   ├── authCode         # 授权编码对照表
│   ├── charts           # echarts Json
│   ├── dicts            # 系统字典对照表
│   ├── pinia            # Pinia stores
│   └── websocket        # 实时请求
├── lang                 # 国际化
│   ├── index.ts
│   └── locale           # 国际化配置文件
├── composables/         # 组合式函数
├── router/              # 路由配置
├── utils/               # 自定义工具函数
├── types/               # TypeScript 类型
├── utils/               # 工具函数
├── mock/                # 本地测试数据
├── views/               # 页面组件
├── App.vue
└── main.ts

[!tip] 提示 项目中使用的@代表的是src文件夹，在vite.config.ts有配置 resolve: { alias: { '@': resolve('./src'), }, },

UI 风格约束

严格禁止（常见 AI 风格）

• ❌ 蓝紫色霓虹渐变、发光描边、玻璃拟态
• ❌ 大面积渐变、过多装饰性几何图形
• ❌ 赛博风、暗黑科技风、AI 风格 UI
• ❌ UI 文案中使用 emoji

后台系统（默认风格）

技术栈

Vue 编码规范

组件基础

<template>
  <div class="user-card">
    <h3>{{ displayName }}</h3>
  </div>
</template>

<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import type { User } from '@/types'

// Props & Emits
const props = defineProps<{ userId: number }>()
const emit = defineEmits<{ (e: 'update', value: string): void }>()

// 响应式状态
const loading = ref(false)
const user = ref<User | null>(null)

// 计算属性
const displayName = computed(() => user.value?.name ?? '未知用户')

// 生命周期
onMounted(async () => { await fetchUser() })

// 方法
async function fetchUser() {
  loading.value = true
  try {
    user.value = await api.getUser(props.userId)
  } finally {
    loading.value = false
  }
}
</script>

<style scoped>
.user-card { padding: 16px; }
</style>

命名约定

Vue Router路由规范

// src/router/index.ts
import { createRouter } from '@magustek/framework-core'
import { createMainRouter } from '@magustek/framework-wujie'

const routes = [
	{
		path: '/',
	    component: () => import('@/***/views/index.vue'),
	    name: 'SisCommonIndex',
	    children: []
	}
]


const router = createRouter({
  base: import.meta.env.BASE_URL,
  routes: routes,
})

const mainRouter = createMainRouter(router)

export { router, mainRouter }

// src/main.ts
import { router, mainRouter } from './router/index'
app.use(router).use(mainRouter)

通过@magustek/framework-core创建路由，路由文件使用异步引入

状态管理（Pinia）

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const user = ref<User | null>(null)
  const token = ref<string>('')

  const isLoggedIn = computed(() => !!token.value)

  async function login(username: string, password: string) {
    const res = await api.login(username, password)
    token.value = res.token
    user.value = res.user
  }

  return { user, token, isLoggedIn, login }
})

交互状态处理

必须处理的状态: loading、empty、error、disabled、submitting

<template>
  <el-skeleton v-if="loading" :rows="5" animated />
  <el-result v-else-if="error" icon="error" :title="error">
    <template #extra>
      <el-button @click="fetchData">重试</el-button>
    </template>
  </el-result>
  <el-empty v-else-if="list.length === 0" description="暂无数据" />
  <template v-else>
    <!-- 正常内容 -->
  </template>
</template>

TypeScript 规范

// types/user.ts
export interface User {
  id: number
  username: string
  role: 'admin' | 'user'
}

export interface ApiResponse<T = unknown> {
  code: number
  message: string
  data: T
}

性能优化

// 路由懒加载
const routes = [
  { path: '/dashboard', component: () => import('@/views/Dashboard.vue') }
]

// 请求防抖
import { useDebounceFn } from '@vueuse/core'
const debouncedSearch = useDebounceFn((keyword) => api.search(keyword), 300)

代码质量检查

• ESLint：eslint-plugin-vue(flat/recommended) + @stylistic/eslint-plugin + Prettier 集成
• Prettier：单引号、分号、尾逗号 all、100 字符宽度、2 空格缩进、arrowParens: 'always'
• 完整 ESLint/Prettier 配置案例

📚 相关文档

references/（按需加载）

• Framework-Core 文档
• Framework-UI 文档
• Framework-Utils 文档
• CloudSIS 插件库

assets/（案例与模板）

• 后端 API 文档读取与代码生成规范
• API 接口定义案例
• 按钮权限配置案例
• 组件使用案例
• 字典配置案例
• 国际化配置案例
• 路由配置案例
• 类型配置案例
• 自定义Hooks使用案例
• TypeScript 标准

外部文档

• Vue 3 官方文档
• Element Plus 文档
• TypeScript 文档

📋 本 Skill 遵循：cloudsis-components - 基于麦杰公司 Framework 5.x 的 cloudsis 项目开发规范

适用场景：

• 使用 create-maguscloud-app 的 sis 脚手架初始化项目
• 集成麦杰公司框架进行 cloudsis 项目开发
• 遵循统一的编码规范和最佳实践