chore: initialize qiming workspace repository
This commit is contained in:
Codex
290
qiming-mobile/.cursorrules
Normal file
290
qiming-mobile/.cursorrules
Normal file
@@ -0,0 +1,290 @@
|
||||
# 智能体平台前端项目开发规范
|
||||
|
||||
## 项目概述
|
||||
这是一个基于 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 目录
|
||||
|
||||
---
|
||||
|
||||
遵循以上规范可以确保代码质量、提高开发效率、降低维护成本。如有疑问，请参考项目中的现有代码或咨询团队负责人。
|
||||
Reference in New Issue
Block a user