# 智能体平台前端项目开发规范

## 项目概述
这是一个基于 uni-app-x 框架开发的智能体平台前端项目，支持多端部署（H5、小程序、App）。

## 技术栈
- **框架**: uni-app-x (Vue 3 + TypeScript)
- **语言**: UTS (UniApp TypeScript)
- **样式**: SCSS
- **状态管理**: Vue 3 Composition API
- **构建工具**: uni-app 官方构建工具
- **UI组件**: 自定义组件 + uni-ui 组件库

## 代码规范

### 1. 文件命名规范
- **页面文件**: 使用 kebab-case，如 `agent-detail.uvue`
- **组件文件**: 使用 kebab-case，如 `custom-nav-bar.uvue`
- **工具文件**: 使用 camelCase，如 `chatService.uts`
- **常量文件**: 使用 camelCase + .constants.uts 后缀，如 `api.constants.uts`
- **类型文件**: 使用 camelCase + .uts 后缀，如 `agent.uts`
- **枚举文件**: 使用 camelCase + .uts 后缀，如 `agent.uts`

### 2. 目录结构规范
```
├── components/          # 公共组件
│   └── component-name/  # 组件目录（kebab-case）
│       └── component-name.uvue
├── pages/              # 页面文件
│   └── page-name/      # 页面目录（kebab-case）
│       ├── page-name.uvue
│       ├── components/ # 页面私有组件
│       └── layers/     # 页面逻辑层
├── types/              # 类型定义
│   ├── interfaces/     # 接口定义
│   └── enums/         # 枚举定义
├── constants/          # 常量定义
├── servers/           # API 服务层
├── utils/             # 工具函数
├── static/            # 静态资源
└── styles/            # 全局样式
```

### 3. 代码风格规范

#### UTS 代码规范
- 使用 TypeScript 严格模式
- 优先使用 `interface` 定义对象类型
- 使用 `type` 定义联合类型和复杂类型
- 枚举使用 `enum` 关键字定义
- 函数参数和返回值必须明确类型注解
- 使用 `export default` 导出默认值
- 使用命名导出导出多个值

```uts
// ✅ 推荐
interface UserInfo {
  id: string;
  name: string;
  avatar?: string;
}

type Status = 'loading' | 'success' | 'error';

enum UserRole {
  ADMIN = 'admin',
  USER = 'user'
}

export default function getUserInfo(id: string): Promise<UserInfo> {
  // 实现
}

export { UserInfo, Status, UserRole };
```

#### Vue 组件规范
- 使用 `<script setup lang="uts">` 语法
- 组件名使用 PascalCase
- Props 使用 TypeScript 接口定义
- 事件名使用 kebab-case
- 使用 Composition API 而非 Options API

```uvue
<template>
  <view class="component-name">
    <text>{{ title }}</text>
  </view>
</template>

<script setup lang="uts">
interface Props {
  title: string;
  count?: number;
}

const props = withDefaults(defineProps<Props>(), {
  count: 0
});

const emit = defineEmits<{
  click: [id: string];
  change: [value: number];
}>();
</script>
```

#### SCSS 样式规范
- 使用 BEM 命名规范
- 优先使用全局工具类（定义在 global.scss 中）
- 组件样式使用 scoped
- 使用 rpx 单位适配不同屏幕
- 颜色使用 CSS 变量

```scss
.component-name {
  &__header {
    display: flex;
    align-items: center;
  }
  
  &__content {
    padding: 16rpx;
  }
  
  &--active {
    background-color: var(--primary-color);
  }
}
```

### 4. 注释规范
- 所有公共函数必须添加 JSDoc 注释
- 复杂逻辑必须添加行内注释
- 组件 Props 和 Events 必须添加注释
- 接口和类型定义必须添加注释

```uts
/**
 * 获取用户信息
 * @param userId 用户ID
 * @param includeAvatar 是否包含头像信息
 * @returns Promise<UserInfo> 用户信息
 */
export async function getUserInfo(
  userId: string, 
  includeAvatar: boolean = false
): Promise<UserInfo> {
  // 实现逻辑
}
```

### 5. 错误处理规范
- 使用 try-catch 处理异步操作
- 统一使用 uni.showToast 显示错误信息
- API 调用必须处理错误情况
- 使用类型守卫检查数据有效性

```uts
try {
  const result = await apiCall();
  if (result.code === SUCCESS_CODE) {
    // 处理成功
  } else {
    uni.showToast({
      title: result.message || '操作失败',
      icon: 'none'
    });
  }
} catch (error) {
  console.error('API调用失败:', error);
  uni.showToast({
    title: '网络错误，请重试',
    icon: 'none'
  });
}
```

### 6. 性能优化规范
- 使用 `v-if` 而非 `v-show` 控制大组件显示
- 长列表使用虚拟滚动
- 图片使用懒加载
- 合理使用 `computed` 和 `watch`
- 避免在模板中使用复杂计算

### 7. 多端适配规范
- 使用条件编译处理平台差异
- 样式使用 rpx 单位
- 使用 uni-app 提供的 API 而非原生 API
- 测试不同平台的兼容性

```uvue
<template>
  <!-- #ifdef H5 -->
  <div class="h5-specific">H5 特定内容</div>
  <!-- #endif -->
  
  <!-- #ifdef MP-WEIXIN -->
  <view class="wechat-specific">微信小程序特定内容</view>
  <!-- #endif -->
</template>
```

### 8. 状态管理规范
- 使用 Pinia 进行状态管理
- 状态按模块划分
- 使用 TypeScript 定义状态类型
- 避免直接修改状态，使用 actions

### 9. API 调用规范
- 统一使用 servers 目录下的服务文件
- 使用 TypeScript 定义请求和响应类型
- 统一错误处理
- 使用拦截器处理通用逻辑

```uts
// servers/user.uts
export interface LoginRequest {
  username: string;
  password: string;
}

export interface LoginResponse {
  token: string;
  userInfo: UserInfo;
}

export async function login(data: LoginRequest): Promise<LoginResponse> {
  return await request.post('/api/login', data);
}
```

### 10. 测试规范
- 关键业务逻辑必须编写单元测试
- 使用 Jest 进行测试
- 测试覆盖率不低于 80%
- 测试文件使用 `.test.uts` 后缀

## 提交规范

### Git 提交信息格式
```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型:**
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建过程或辅助工具的变动

**示例:**
```
feat(chat): 添加语音输入功能

- 集成语音识别 API
- 添加录音按钮组件
- 处理音频文件上传

Closes #123
```

## 部署规范
- 使用环境变量管理不同环境的配置
- 生产环境必须开启代码压缩
- 使用 CDN 加速静态资源
- 配置适当的缓存策略

## 安全规范
- 敏感信息不得硬编码
- 使用 HTTPS 进行网络请求
- 对用户输入进行验证和过滤
- 定期更新依赖包

## 文档规范
- 每个模块必须包含 README 文档
- API 接口必须提供文档
- 组件必须提供使用示例
- 重要决策必须记录在 docs 目录

---

遵循以上规范可以确保代码质量、提高开发效率、降低维护成本。如有疑问，请参考项目中的现有代码或咨询团队负责人。