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年
编制：个人工作室