FileCollect/项目规则文件.md

# 项目规则文件

## 1. 总则

本文档定义了图片收集小程序项目的核心开发规则、编码规范和工作流程，适合个人工作室开发环境使用。

## 2. 代码规范

### 2.1 开发工具与框架

- **开发工具**：HBuilderX
- **开发框架**：uni-app（Vue.js）
- **后台管理框架**：uni-admin
- **云开发平台**：uni-cloud
- **UI框架**：uView
- **uView版本**：建议使用最新稳定版

### 2.2 代码风格

- **缩进**：使用4个空格进行缩进，禁止使用Tab
- **行长度**：每行代码长度不超过120个字符
- **文件编码**：统一使用UTF-8编码
- **换行符**：使用LF（\n）作为换行符
- **注释**：
  - 函数/方法必须包含注释，说明功能、参数和返回值
  - 复杂逻辑必须添加注释说明
  - 避免不必要的注释，代码应当自解释
- **uView使用规范**：
  - 优先使用uView提供的组件，保持UI一致性
  - 遵循uView的主题配置机制进行样式定制
  - 组件属性值优先使用uView提供的常量或枚举值
  - 自定义样式时，避免直接覆盖uView组件的样式，应使用`custom-class`属性
  - 对于常用的uView组件配置，可封装为业务组件以提高复用性
- **uni-admin使用规范**：
  - 遵循uni-admin的目录结构和文件命名规范
  - 使用uni-admin提供的权限管理机制
  - 扩展uni-admin功能时，应遵循其插件机制
  - 后台页面开发时，复用uni-admin提供的基础组件
  - 遵循uni-admin的页面布局规范，确保后台管理界面风格统一
- **uni-cloud使用规范**：
  - 云函数命名应清晰表达其功能，使用小驼峰命名法
  - 数据库集合命名使用复数形式，全小写
  - 严格遵循uni-cloud权限控制规则
  - 避免在云函数中执行耗时操作，复杂业务逻辑应拆分处理
  - 使用云函数时，需要对入参进行严格校验
  - 云函数代码需进行模块化设计，提高复用性
  - 数据库查询应添加合理索引，优化查询性能
  - 云存储文件命名应包含时间戳或随机字符串，避免文件名冲突

### 2.3 命名规范

- **变量名**：使用小驼峰命名法（camelCase）
  - 示例：`userName`, `departmentList`, `imageCount`
- **常量名**：使用全大写，下划线分隔
  - 示例：`MAX_UPLOAD_SIZE`, `API_BASE_URL`
- **函数/方法名**：使用小驼峰命名法，动词开头
  - 示例：`uploadImage()`, `verifyUser()`, `getDepartmentList()`
- **组件名**：
  - 自定义组件：使用大驼峰命名法（PascalCase）或短横线命名法（kebab-case）
    - 示例：`UserManager.vue`, `image-uploader.vue`
  - uView组件：遵循uView官方命名规范，使用`u-`前缀
    - 示例：`u-button`, `u-upload`, `u-table`
- **文件名**：遵循uni-app命名规范，页面文件名建议与页面路由保持一致
  - 示例：`index.vue`, `upload.vue`, `user-detail.vue`
- **云函数命名**：使用小驼峰命名法，前缀表示模块
  - 示例：`userLogin`, `imageUpload`, `taskCreate`
- **数据库集合命名**：使用复数形式，全小写
  - 示例：`users`, `departments`, `images`, `tasks`, `logs`

### 2.4 目录结构规范（uni-app + uView + uni-admin）

- `/pages` - 页面文件目录
  - `/admin` - 后台管理页面目录（uni-admin相关）
- `/components` - 自定义组件目录
  - `/uview-ui` - uView UI组件目录（通过插件安装）
- `/static` - 静态资源目录
- `/common` - 公共资源目录
- `/api` - 网络请求接口目录
- `/utils` - 工具函数目录
- `/services` - 业务逻辑层目录
- `/config` - 配置文件目录
  - `/theme.scss` - uView主题变量配置文件
- `/store` - Vuex状态管理目录（可选）
- `/uniCloud` - uni-cloud云开发目录
  - `/database` - 数据库相关配置
  - `/functions` - 云函数目录
  - `/cloud-storage` - 云存储相关文件
- `/uni_modules` - uni-modules插件目录（包含uni-admin等）

## 3. 开发流程

### 3.1 分支管理（简化）

- **main**：主分支，存放稳定版本代码
- **feature**：功能开发分支
- **bugfix**：bug修复分支（可选）

### 3.2 代码提交规范

提交信息建议使用简洁格式：
```
<类型>: <描述>
```

常用类型：
- **feat**: 新功能
- **fix**: 修复bug
- **docs**: 文档更新
- **refactor**: 代码重构

## 4. 安全规范

### 4.1 数据安全

- 敏感数据必须加密存储
- API接口必须进行权限验证
- 防止SQL注入、XSS攻击等常见安全问题
- 文件上传必须验证文件类型和大小
- 使用uniCloud的环境变量存储敏感配置信息，避免硬编码
- 云函数中避免打印敏感信息到日志

### 4.2 权限管理

- 严格按照用户角色分配权限（管理员、信息员、部门负责人、普通用户）
- 确保部门负责人只能访问其负责的部门数据
- 实现细粒度的权限控制
- 在uniCloud数据库中设置合理的权限规则
- 所有数据查询操作必须包含权限过滤条件
- 对关键操作（如删除、修改权限）添加二次确认机制

## 5. 测试规范

### 5.1 测试要求

- 核心功能建议编写基本测试用例
- 确保主要业务流程正常运行
- 重要接口进行必要的测试验证
- 云函数测试：使用uniCloud提供的本地调试工具进行云函数测试
- 权限测试：验证不同角色用户的权限控制是否正确

### 5.2 测试环境

- 开发环境：本地开发环境
- 测试环境：uniCloud测试环境
- 生产环境：uniCloud正式运行环境

## 6. 文档规范

### 6.1 代码文档

- 复杂函数和关键逻辑添加注释说明
- 保持代码自解释性

### 6.2 项目文档

- 维护基础需求文档
- 记录主要技术决策
- 编写简明部署说明

## 7. 性能优化

### 7.1 前端性能优化

- 图片适当压缩和懒加载
- 避免明显的性能瓶颈
- 优化关键操作的响应速度
- 减少网络请求次数，合理使用缓存
- 页面组件按需加载，避免一次性加载过多内容
- 使用uni-app提供的性能优化API

### 7.2 uni-cloud性能优化

- 云函数保持轻量化，避免不必要的计算
- 合理设置数据库索引，优化查询性能
- 使用事务处理复杂的数据库操作
- 云存储文件进行合理分类和命名
- 利用云函数缓存机制减少重复计算
- 定期清理无效数据，优化存储使用效率

## 8. 版本号规范

采用语义化版本号（Semantic Versioning）：

`主版本号.次版本号.修订号`

- **主版本号**：不兼容的API变更
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

## 9. 多部门管理特殊规则

### 9.1 数据访问控制

- 确保部门负责人只能访问和管理其负责的所有部门数据
- 在数据查询时必须包含部门权限过滤条件

### 9.2 用户界面

- 为管理多个部门的用户提供部门切换功能
- 显示数据时必须明确标识所属部门

## 10. 部署规范

### 10.1 部署流程

- 使用HBuilderX提供的uniCloud部署功能
- 遵循环境分离原则，开发、测试、生产环境严格隔离
- 正式发布前进行完整的回归测试

### 10.2 环境配置

- 使用uniCloud环境变量管理不同环境的配置
- 敏感配置信息通过环境变量注入，不硬编码到代码中
- 定期备份数据库和云存储中的重要数据

### 10.3 版本管理

- 每次发布需记录详细的版本说明
- 重要版本进行数据库备份
- 建立回滚机制，确保问题出现时可快速恢复

## 11. 附则

- 本规则根据个人工作室实际情况可灵活调整
- 核心规范建议严格遵守以保证代码质量
- 随着项目发展可逐步完善规则

---

**文档版本**：v1.0.0  
**发布日期**：2024年  
**编制**：个人工作室