291 lines
6.7 KiB
Plaintext
291 lines
6.7 KiB
Plaintext
# 智能体平台前端项目开发规范
|
||
|
||
## 项目概述
|
||
这是一个基于 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 目录
|
||
|
||
---
|
||
|
||
遵循以上规范可以确保代码质量、提高开发效率、降低维护成本。如有疑问，请参考项目中的现有代码或咨询团队负责人。
|