front-end/.cursor/rules/coding-standards.mdc

---
alwaysApply: false
---
### 编码规范

#### 命名规范
**文件命名**
- 页面文件：使用 kebab-case，如 `order-list.vue`
- 组件文件：使用 PascalCase，如 `UserCard.vue`
- 工具文件：使用 camelCase，如 `dateUtils.js`

**变量命名**
- 常量：使用 SCREAMING_SNAKE_CASE，如 `API_BASE_URL`
- 变量和函数：使用 camelCase，如 `getUserInfo`
- 组件 props：使用 camelCase，如 `itemList`
- CSS 类名：使用 kebab-case，如 `.user-card`

#### 组件开发规范
**单文件组件结构顺序**
```vue
<template>
  <!-- 模板内容 -->
</template>

<script> // 或 <script setup lang="ts">
export default {
  // 组件选项
}
</script>

<style lang="scss" scoped>
/* 样式内容 */
</style>
```

**Props 定义**
```javascript
// Vue 2 Options API
props: {
  title: {
    type: String,
    required: true,
    default: ''
  },
  list: {
    type: Array,
    default: () => []
  }
}
```

#### API 请求规范
**统一请求处理**
```javascript
// 使用 uni.request 而不是 axios
const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      url: options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: {
        'Content-Type': 'application/json',
        ...options.header
      },
      success: (res) => {
        if (res.statusCode === 200) {
          resolve(res.data)
        } else {
          reject(res)
        }
      },
      fail: reject
    })
  })
}
```

**错误处理**
```javascript
try {
  const result = await apiCall()
  // 处理成功结果
} catch (error) {
  uni.showToast({
    title: error.message || '请求失败',
    icon: 'none'
  })
}
```

#### 状态管理规范
**Store 结构**
```javascript
// Vuex 或 Pinia
const store = {
  state: {
    user: null,
    loading: false
  },
  mutations: {
    SET_USER(state, user) {
      state.user = user
    },
    SET_LOADING(state, loading) {
      state.loading = loading
    }
  },
  actions: {
    async login({ commit }, params) {
      commit('SET_LOADING', true)
      try {
        const user = await loginApi(params)
        commit('SET_USER', user)
      } finally {
        commit('SET_LOADING', false)
      }
    }
  }
}
```

#### 样式规范
**使用 rpx 单位**
```scss
.container {
  padding: 32rpx;          // 推荐
  margin: 16rpx 24rpx;     // 推荐
  font-size: 28rpx;        // 推荐
  
  // 避免使用 px，除非是特殊需求
  border: 1px solid #ccc;  // 细边框可以使用 px
}
```

**响应式设计**
```scss
.grid {
  display: flex;
  flex-wrap: wrap;
  
  .item {
    width: 50%;
    
    // 条件编译样式
    /* #ifdef H5 */
    &:hover {
      background-color: #f5f5f5;
    }
    /* #endif */
  }
}
```

#### 性能优化规范
**列表渲染优化**
```vue
<template>
  <!-- 使用 key 提升渲染性能 -->
  <view v-for="item in list" :key="item.id">
    {{ item.name }}
  </view>
  
  <!-- 长列表使用虚拟滚动 -->
  <recycle-list :list="longList" :item-height="100">
    <template v-slot="{ item }">
      <ListItem :data="item" />
    </template>
  </recycle-list>
</template>
```

**图片优化**
```vue
<template>
  <!-- 使用 lazy-load 懒加载 -->
  <image 
    :src="imageUrl" 
    mode="aspectFill"
    lazy-load
    @error="handleImageError"
  />
</template>
```

#### 调试和测试
**调试信息**
```javascript
// 条件编译调试代码
// #ifdef APP-PLUS || H5
console.log('Debug info:', data)
// #endif

// 使用 uni.getSystemInfo 获取设备信息
uni.getSystemInfo({
  success: (res) => {
    console.log('Platform:', res.platform)
    console.log('Version:', res.version)
  }
})
```

**错误监控**
```javascript
// App.vue 中的全局错误处理
onError(err => {
  console.error('Global error:', err)
  // 上报错误到监控平台
})
```

### 编码规范

#### 命名规范
**文件命名**
- 页面文件：使用 kebab-case，如 `order-list.vue`
- 组件文件：使用 PascalCase，如 `UserCard.vue`
- 工具文件：使用 camelCase，如 `dateUtils.js`

**变量命名**
- 常量：使用 SCREAMING_SNAKE_CASE，如 `API_BASE_URL`
- 变量和函数：使用 camelCase，如 `getUserInfo`
- 组件 props：使用 camelCase，如 `itemList`
- CSS 类名：使用 kebab-case，如 `.user-card`

#### 组件开发规范
**单文件组件结构顺序**
```vue
<template>
  <!-- 模板内容 -->
</template>

<script>
// 或 <script setup lang="ts">
export default {
  // 组件选项
}
</script>

<style lang="scss" scoped>
/* 样式内容 */
</style>
```

**Props 定义**
```javascript
// Vue 2 Options API
props: {
  title: {
    type: String,
    required: true,
    default: ''
  },
  list: {
    type: Array,
    default: () => []
  }
}
```

#### API 请求规范
**统一请求处理**
```javascript
// 使用 uni.request 而不是 axios
const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      url: options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: {
        'Content-Type': 'application/json',
        ...options.header
      },
      success: (res) => {
        if (res.statusCode === 200) {
          resolve(res.data)
        } else {
          reject(res)
        }
      },
      fail: reject
    })
  })
}
```

**错误处理**
```javascript
try {
  const result = await apiCall()
  // 处理成功结果
} catch (error) {
  uni.showToast({
    title: error.message || '请求失败',
    icon: 'none'
  })
}
```

#### 状态管理规范
**Store 结构**
```javascript
// Vuex 或 Pinia
const store = {
  state: {
    user: null,
    loading: false
  },
  mutations: {
    SET_USER(state, user) {
      state.user = user
    },
    SET_LOADING(state, loading) {
      state.loading = loading
    }
  },
  actions: {
    async login({ commit }, params) {
      commit('SET_LOADING', true)
      try {
        const user = await loginApi(params)
        commit('SET_USER', user)
      } finally {
        commit('SET_LOADING', false)
      }
    }
  }
}
```

#### 样式规范
**使用 rpx 单位**
```scss
.container {
  padding: 32rpx;          // 推荐
  margin: 16rpx 24rpx;     // 推荐
  font-size: 28rpx;        // 推荐
  
  // 避免使用 px，除非是特殊需求
  border: 1px solid #ccc;  // 细边框可以使用 px
}
```

**响应式设计**
```scss
.grid {
  display: flex;
  flex-wrap: wrap;
  
  .item {
    width: 50%;
    
    // 条件编译样式
    /* #ifdef H5 */
    &:hover {
      background-color: #f5f5f5;
    }
    /* #endif */
  }
}
```

#### 性能优化规范
**列表渲染优化**
```vue
<template>
  <!-- 使用 key 提升渲染性能 -->
  <view v-for="item in list" :key="item.id">
    {{ item.name }}
  </view>
  
  <!-- 长列表使用虚拟滚动 -->
  <recycle-list :list="longList" :item-height="100">
    <template v-slot="{ item }">
      <ListItem :data="item" />
    </template>
  </recycle-list>
</template>
```

**图片优化**
```vue
<template>
  <!-- 使用 lazy-load 懒加载 -->
  <image 
    :src="imageUrl" 
    mode="aspectFill"
    lazy-load
    @error="handleImageError"
  />
</template>
```

#### 调试和测试
**调试信息**
```javascript
// 条件编译调试代码
// #ifdef APP-PLUS || H5
console.log('Debug info:', data)
// #endif

// 使用 uni.getSystemInfo 获取设备信息
uni.getSystemInfo({
  success: (res) => {
    console.log('Platform:', res.platform)
    console.log('Version:', res.version)
  }
})
```

**错误监控**
```javascript
// App.vue 中的全局错误处理
onError(err => {
  console.error('Global error:', err)
  // 上报错误到监控平台
})
```