蝉印

主题

贡献指南 ​

感谢您考虑为蝉印诊所管家做出贡献！本指南将帮助您了解如何参与项目开发。

🎯 贡献方式 ​

我们欢迎以下形式的贡献：

  • 🐛 报告 Bug
  • 💡 提出新功能建议
  • 📝 改进文档
  • 🔧 修复 Bug
  • ✨ 开发新功能
  • 🎨 优化 UI/UX
  • ⚡ 性能优化
  • ✅ 添加测试

📋 开始之前 ​

行为准则 ​

请阅读并遵守我们的 行为准则。我们致力于营造一个友好、包容的社区环境。

技术要求 ​

确保您的开发环境满足以下要求：

  • PHP: 8.4+
  • Composer: 2.x
  • Node.js: 18.x LTS 或 20.x LTS
  • npm: 9.x+
  • MySQL: 8.0+
  • Redis: 7.0+
  • Git: 2.30+

🚀 快速开始 ​

1. Fork 仓库 ​

点击页面右上角的 "Fork" 按钮，将仓库 fork 到您的账号下。

2. 克隆仓库 ​

bash
# 克隆您 fork 的仓库
git clone https://GitHub.com/YOUR_USERNAME/yiliaocrm-api.git

# 或使用 Gitee
git clone https://gitee.com/YOUR_USERNAME/yiliaocrm-api.git

# 进入项目目录
cd yiliaocrm-api

3. 添加上游仓库 ​

bash
# 添加原始仓库为上游
git remote add upstream https://GitHub.com/yiliaocrm/api.git

# 验证远程仓库
git remote -v

4. 安装依赖 ​

bash
# 安装 PHP 依赖
composer install

# 安装前端依赖
npm install

# 复制环境配置
cp .env.example .env

# 生成应用密钥
PHP artisan key:generate

# 运行数据库迁移
PHP artisan migrate

# 启动开发服务器
PHP artisan serve

🔀 工作流程 ​

1. 创建分支 ​

bash
# 更新主分支
git checkout main
git pull upstream main

# 创建功能分支
git checkout -b feature/your-feature-name

# 或修复 bug 分支
git checkout -b fix/bug-description

2. 开发代码 ​

  • 遵循项目代码风格
  • 编写清晰的注释
  • 添加必要的测试
  • 确保所有测试通过

3. 提交代码 ​

bash
# 添加修改的文件
git add .

# 提交代码 (使用规范的提交信息)
git commit -m "feat: 添加客户标签功能"

# 推送到您的 fork 仓库
git push origin feature/your-feature-name

4. 创建 Pull Request ​

  1. 访问您的 fork 仓库页面
  2. 点击 "New Pull Request" 按钮
  3. 选择您的分支
  4. 填写 PR 标题和描述
  5. 提交 PR

📝 提交信息规范 ​

我们使用 Conventional Commits 规范:

<type>(<scope>): <subject>

<body>

<footer>

Type 类型 ​

  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档更新
  • style: 代码格式 (不影响功能)
  • refactor: 重构
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建 / 工具相关

示例 ​

bash
# 新功能
git commit -m "feat(customer): 添加客户标签批量管理功能"

# Bug 修复
git commit -m "fix(appointment): 修复预约时间冲突检测 bug"

# 文档
git commit -m "docs(api): 更新客户管理 API 文档"

# 性能优化
git commit -m "perf(query): 优化客户列表查询性能"

🧪 测试要求 ​

运行测试 ​

bash
# 运行所有测试
PHP artisan test

# 运行特定测试
PHP artisan test --filter CustomerTest

# 生成代码覆盖率报告
PHP artisan test --coverage

测试要求 ​

  • 新功能必须包含单元测试
  • 测试覆盖率不低于 80%
  • 所有测试必须通过
  • 关键功能需要集成测试

🎨 代码风格 ​

PHP 代码风格 ​

我们使用 PSR-12 编码规范:

bash
# 检查代码风格
composer run lint

# 自动修复代码风格
composer run lint:fix

JavaScript 代码风格 ​

使用 ESLint 和 Prettier:

bash
# 检查代码风格
npm run lint

# 自动修复
npm run lint:fix

📦 Pull Request 检查清单 ​

提交 PR 前，请确保:

  • [ ] 代码遵循项目规范
  • [ ] 添加了必要的测试
  • [ ] 所有测试通过
  • [ ] 更新了相关文档
  • [ ] 提交信息符合规范
  • [ ] 没有合并冲突
  • [ ] CI/CD 检查通过

🔍 代码审查流程 ​

  1. 提交 PR: 您提交 Pull Request
  2. 自动检查: CI/CD 运行测试和代码检查
  3. 人工审查：维护者审查您的代码
  4. 反馈改进：根据反馈进行修改
  5. 批准合并：审查通过后合并到主分支

审查时间 ​

  • 一般 PR: 1-3 个工作日
  • 重要 PR: 3-7 个工作日
  • 紧急修复：24 小时内

🐛 报告 Bug ​

在提交 Bug 前 ​

  1. 搜索现有 Issues，确认是否已有人报告
  2. 确认问题可以复现
  3. 收集必要的信息

Bug 报告模板 ​

markdown
## Bug 描述
简洁清晰地描述 bug。

## 复现步骤
1. 进入 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误

## 预期行为
描述您期望发生什么。

## 实际行为
描述实际发生了什么。

## 环境信息
- 操作系统：[e.g. Ubuntu 22.04]
- PHP 版本：[e.g. 8.4.1]
- Laravel 版本：[e.g. 12.0]
- 浏览器：[e.g. Chrome 120]

## 截图
如果适用，添加截图帮助解释问题。

## 附加信息
添加其他相关信息。

💡 功能建议 ​

建议模板 ​

markdown
## 功能描述
清晰简洁地描述您希望的功能。

## 使用场景
描述这个功能的使用场景。

## 解决的问题
这个功能解决了什么问题？

## 替代方案
您是否考虑过其他替代方案？

## 附加信息
添加其他相关信息或设计草图。

📚 文档贡献 ​

文档同样重要！您可以:

  • 修正拼写 / 语法错误
  • 改进措辞和表达
  • 添加示例代码
  • 翻译文档
  • 添加教程

文档仓库：yiliaocrm/docs

🏆 贡献者权益 ​

认可 ​

  • 在贡献者列表中展示
  • 获得社区徽章
  • 优先体验新功能

成长 ​

  • 参与项目决策
  • 提升技术能力
  • 建立个人品牌

晋升路径 ​

  1. 贡献者 (Contributor): 提交过 PR
  2. 活跃贡献者 (Active Contributor): 持续贡献 3 个月 +
  3. 协作者 (Collaborator): 获得写权限
  4. 维护者 (Maintainer): 核心团队成员

💬 获取帮助 ​

如果您有任何问题:

📜 开源协议 ​

本项目基于 MIT License 开源。

贡献代码即表示您同意将您的贡献按照 MIT 协议授权。

再次感谢您的贡献！让我们一起打造更好的医疗 CRM 系统！ 🎉

最后更新于: