# Vue2-Client 代码风格和约定

## 总体原则
- 编写简洁、技术性的JavaScript代码
- 提供准确的代码示例
- 优先迭代和模块化，避免代码重复
- 使用描述性变量名（如：isLoading, hasError）

## Vue组件开发规范

### 组件API风格
**优先使用**：
- Vue 2.7组合API + setup语法糖
- 声明式编程模式

**避免使用**（除非修改现有代码）：
- 选项API (Options API)
- 传统的setup标签形式

### 示例：推荐的组件结构
```vue
<script setup>
import { ref, computed } from 'vue'

// 使用组合API
const isLoading = ref(false)
const hasError = ref(false)

// 计算属性使用箭头函数
const displayText = computed(() => {
  return isLoading.value ? '加载中...' : '已完成'
})

// 方法使用箭头函数
const handleClick = () => {
  isLoading.value = true
}
</script>

<template>
  <div>{{ displayText }}</div>
</template>
```

## 命名约定

### 目录命名
- 使用kebab-case（小写带破折号）
- 示例：`components/auth-wizard`、`pages/user-manage`

### 文件命名
- **组件文件**：使用PascalCase
  - 示例：`AuthWizard.vue`、`UserTable.vue`
- **可组合函数**：使用camelCase
  - 示例：`useAuthState.js`、`useFormValidation.js`
- **工具函数**：使用camelCase
  - 示例：`formatDate.js`、`encryptData.js`

### 变量命名
- **布尔值**：使用助动词前缀
  - `isLoading`、`hasError`、`canEdit`、`shouldShow`
- **普通变量**：使用camelCase
  - `userData`、`pageTitle`、`apiResponse`
- **常量**：使用UPPER_SNAKE_CASE
  - `API_BASE_URL`、`MAX_RETRY_COUNT`

## 项目特定约定

### X组件命名规范
Base-client中的核心组件使用X前缀：
- `XForm`：表单组件
- `XTable`：表格组件
- `XCard`：卡片组件
- `XPageView`：页面视图组件

### 组件文件结构
```
src/
├── base-client/          # 基础组件（全局注册）
│   ├── components/       # X系列组件
│   └── plugins/          # 全局插件
├── components/           # 通用组件（按需引入）
├── pages/               # 页面组件
└── layouts/             # 布局组件
```

## 代码格式规范

### 语法和格式
- **箭头函数**：方法和计算属性统一使用箭头函数
- **简洁语法**：避免条件语句中不必要的花括号
  ```javascript
  // 推荐
  if (isValid) return true
  
  // 避免（简单语句）
  if (isValid) {
    return true
  }
  ```
- **模板语法**：使用声明式渲染，避免在模板中写复杂逻辑

### 导入顺序
文件导入按以下顺序组织：
1. Vue核心和第三方库
2. 组件导入
3. 可组合函数（composables）
4. 工具函数（helpers）
5. 静态内容（assets、styles）
6. 类型定义（如果有）

示例：
```javascript
// 1. 核心库
import { ref, computed } from 'vue'
import { message } from 'ant-design-vue'

// 2. 组件
import UserForm from '@/components/UserForm.vue'

// 3. 可组合函数
import { useAuth } from '@/composables/useAuth'

// 4. 工具
import { formatDate } from '@/utils/date'

// 5. 样式
import './styles.less'
```

## Less样式规范

### 样式组织
- 使用Less预处理器
- 主题变量定义在`src/theme/`
- 组件样式与组件文件共同放置
- 使用BEM命名规范（可选，但推荐）

### 示例
```less
.user-table {
  &__header {
    padding: 16px;
  }
  
  &__body {
    min-height: 400px;
  }
}
```

## 注释规范

### 注释语言
- **必须使用中文**编写注释
- 代码注释、文档、说明都使用中文

### 注释格式
```javascript
/**
 * 用户认证可组合函数
 * @returns {Object} 返回认证状态和方法
 */
const useAuth = () => {
  // 检查用户是否已登录
  const isLoggedIn = ref(false)
  
  return { isLoggedIn }
}
```

## 配置驱动开发规范

### JSON配置
项目采用配置驱动模式，组件行为通过JSON配置定义：
```javascript
// XForm配置示例
const formConfig = {
  columns: [
    {
      title: '用户名',
      key: 'username',
      type: 'input',
      required: true
    }
  ]
}
```

### 配置文件位置
- 系统配置：`src/config/`
- 默认配置：`src/config/default/`
- 配置替换器：`src/config/replacer/`

## ESLint规范
- 开发时默认禁用ESLint（--no-eslint）
- 提交前必须运行`npm run lint`检查
- 遵循Vue官方ESLint规则
- 标准JavaScript风格（@vue/eslint-config-standard）

## Git提交规范
虽然项目未强制要求，但推荐使用约定式提交：
- `feat:` 新功能
- `fix:` 修复bug
- `docs:` 文档更新
- `style:` 代码格式调整
- `refactor:` 重构
- `test:` 测试相关
- `chore:` 构建或工具变更

## 最佳实践
1. **组件复用**：优先使用base-client中的X组件
2. **配置优于编码**：能用配置实现的不写硬编码
3. **mixins使用**：表单验证等共享逻辑使用mixins
4. **响应式设计**：使用XFormCol栅格系统
5. **API调用**：统一使用`src/services/apiService.js`
6. **数据转换**：遵循DataModel模式
7. **错误处理**：使用axios拦截器统一处理