first commit

2026-03-17 14:52:07 +08:00
parent a23b829323
commit ec25e6e617
104 changed files with 35840 additions and 0 deletions
--- a/docs/开发规范.md
+++ b/docs/开发规范.md
@@ -0,0 +1,300 @@
+# 开发规范文档
+
+## 一、命名规范
+
+### 1.1 文件命名
+- **页面文件**：使用小写字母，多个单词用短横线连接，如 `user-profile.vue`
+- **组件文件**：使用大驼峰命名，如 `UserCard.vue`、`LoadingView.vue`
+- **工具类文件**：使用小写字母，多个单词用短横线连接，如 `request.js`、`storage.js`
+- **常量文件**：使用小写字母，如 `constants.js`、`env.js`
+
+### 1.2 变量命名
+- **普通变量**：使用小驼峰命名，如 `userName`、`userInfo`
+- **常量**：使用全大写字母，单词间用下划线连接，如 `API_BASE_URL`、`MAX_RETRY_COUNT`
+- **私有变量**：以下划线开头，如 `_privateMethod`
+- **布尔值**：以 `is`、`has`、`can` 等开头，如 `isLogin`、`hasPermission`
+
+### 1.3 函数命名
+- **普通函数**：使用小驼峰命名，动词开头，如 `getUserInfo`、`handleClick`
+- **事件处理函数**：以 `handle` 或 `on` 开头，如 `handleSubmit`、`onLoad`
+- **工具函数**：使用动词开头，如 `formatDate`、`validatePhone`
+
+### 1.4 组件命名
+- **全局组件**：使用大驼峰命名，至少两个单词，如 `LoadingView`、`EmptyView`
+- **页面组件**：使用大驼峰命名，如 `LoginPage`、`UserProfile`
+- **业务组件**：使用大驼峰命名，体现业务含义，如 `UserCard`、`OrderList`
+
+## 二、代码注释规范
+
+### 2.1 文件注释
+每个文件开头必须包含文件说明注释：
+
+```javascript
+/**
+ * 用户相关接口
+ * @author 张三
+ * @date 2024-01-01
+ */
+```
+
+### 2.2 函数注释
+关键函数必须添加注释，说明功能、参数、返回值：
+
+```javascript
+/**
+ * 用户登录
+ * @param {object} data 登录数据
+ * @param {string} data.phone 手机号
+ * @param {string} data.password 密码
+ * @returns {Promise<object>} 登录结果
+ */
+export const login = (data) => {
+  return request.post('/auth/login', data)
+}
+```
+
+### 2.3 复杂逻辑注释
+对于复杂的业务逻辑，必须添加行内注释：
+
+```javascript
+// 检查Token是否过期
+if (tokenExpireTime < Date.now()) {
+  // Token已过期，刷新Token
+  await refreshToken()
+}
+```
+
+### 2.4 TODO注释
+待完成的功能使用 TODO 标记：
+
+```javascript
+// TODO: 添加图片压缩功能
+// FIXME: 修复在iOS端的兼容性问题
+```
+
+## 三、代码风格规范
+
+### 3.1 缩进与空格
+- 使用 2 个空格缩进
+- 运算符前后加空格
+- 逗号后加空格
+- 对象属性冒号后加空格
+
+### 3.2 引号使用
+- JavaScript 统一使用单引号
+- HTML 属性统一使用双引号
+
+### 3.3 分号使用
+- 语句结尾不使用分号（根据 Prettier 配置）
+
+### 3.4 代码长度
+- 单行代码不超过 100 个字符
+- 函数代码行数不超过 50 行
+- 文件代码行数不超过 500 行
+
+## 四、Vue 组件规范
+
+### 4.1 组件结构顺序
+```vue
+<template>
+  <!-- 模板内容 -->
+</template>
+
+<script>
+// 1. 导入
+import { ref } from 'vue'
+
+// 2. 组件定义
+export default {
+  name: 'ComponentName',
+  components: {},
+  props: {},
+  emits: [],
+  setup() {
+    // 3. 响应式数据
+    // 4. 计算属性
+    // 5. 方法
+    // 6. 生命周期
+    // 7. 返回
+  }
+}
+</script>
+
+<style lang="scss" scoped>
+/* 样式内容 */
+</style>
+```
+
+### 4.2 Props 定义
+Props 必须定义类型、默认值和校验：
+
+```javascript
+props: {
+  title: {
+    type: String,
+    required: true
+  },
+  count: {
+    type: Number,
+    default: 0,
+    validator: (value) => value >= 0
+  }
+}
+```
+
+### 4.3 事件命名
+- 使用短横线命名：`@update-value`
+- 使用动词开头：`@click`、`@change`、`@submit`
+
+## 五、Git 提交规范
+
+### 5.1 提交信息格式
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 5.2 Type 类型
+- `feat`: 新功能
+- `fix`: 修复 Bug
+- `docs`: 文档更新
+- `style`: 代码格式调整
+- `refactor`: 重构代码
+- `perf`: 性能优化
+- `test`: 测试相关
+- `chore`: 构建/工具链相关
+
+### 5.3 提交示例
+```
+feat(login): 添加手机号验证码登录功能
+
+- 实现验证码发送接口
+- 添加验证码输入组件
+- 完成登录逻辑
+
+Closes #123
+```
+
+## 六、API 接口规范
+
+### 6.1 接口文件组织
+按业务模块划分接口文件：
+```
+api/
+├── modules/
+│   ├── auth.js      # 认证相关
+│   ├── user.js      # 用户相关
+│   └── order.js     # 订单相关
+└── index.js         # 统一导出
+```
+
+### 6.2 接口命名
+- 使用动词开头：`getUserInfo`、`updateUserInfo`
+- RESTful 风格：`getList`、`getDetail`、`create`、`update`、`delete`
+
+### 6.3 接口注释
+每个接口必须添加注释说明：
+
+```javascript
+/**
+ * 获取用户信息
+ * @param {string} userId 用户ID
+ * @returns {Promise<object>} 用户信息
+ */
+export const getUserInfo = (userId) => {
+  return request.get(`/user/${userId}`)
+}
+```
+
+## 七、样式规范
+
+### 7.1 选择器命名
+- 使用短横线命名：`.user-card`、`.login-form`
+- 避免使用 ID 选择器
+- 避免使用标签选择器
+
+### 7.2 样式组织
+```scss
+.component-name {
+  // 1. 定位属性
+  position: relative;
+  
+  // 2. 盒模型属性
+  display: flex;
+  width: 100%;
+  padding: 20rpx;
+  
+  // 3. 文本属性
+  font-size: 28rpx;
+  color: #333;
+  
+  // 4. 其他属性
+  background-color: #fff;
+  
+  // 5. 嵌套选择器
+  .child-element {
+    // ...
+  }
+}
+```
+
+### 7.3 单位使用
+- 小程序端：使用 `rpx`
+- H5 端：使用 `rem` 或 `vw`
+- 固定尺寸：使用 `px`
+
+## 八、性能优化规范
+
+### 8.1 图片优化
+- 使用合适的图片格式（WebP、JPEG、PNG）
+- 压缩图片大小
+- 使用图片懒加载
+- 使用雪碧图合并小图标
+
+### 8.2 代码优化
+- 避免在循环中进行复杂计算
+- 使用防抖和节流
+- 合理使用计算属性和侦听器
+- 及时清理定时器和事件监听
+
+### 8.3 网络优化
+- 合并接口请求
+- 使用请求缓存
+- 实现请求重试机制
+- 避免重复请求
+
+## 九、安全规范
+
+### 9.1 数据安全
+- 敏感信息加密存储
+- Token 定期刷新
+- 防止 XSS 攻击
+- 防止 CSRF 攻击
+
+### 9.2 权限控制
+- 实现路由权限控制
+- 实现接口权限控制
+- 实现按钮级权限控制
+
+## 十、测试规范
+
+### 10.1 单元测试
+- 工具函数必须编写单元测试
+- 测试覆盖率不低于 80%
+- 使用 Jest 测试框架
+
+### 10.2 集成测试
+- 关键业务流程必须编写集成测试
+- 使用 uni-automator 进行自动化测试
+
+### 10.3 测试命名
+```javascript
+describe('工具函数测试', () => {
+  test('应该正确验证手机号', () => {
+    expect(isPhone('13800138000')).toBe(true)
+  })
+})
+```