nxxmdata/docs/CONTRIBUTING.md

# 贡献指南

## 欢迎贡献

我们热烈欢迎社区开发者为宁夏智慧养殖监管平台做出贡献！无论您是想修复bug、添加新功能、改进文档，还是提供反馈建议，我们都非常感谢您的参与。

## 目录

- [开始之前](#开始之前)
- [如何贡献](#如何贡献)
- [开发环境搭建](#开发环境搭建)
- [代码贡献流程](#代码贡献流程)
- [代码规范](#代码规范)
- [提交规范](#提交规范)
- [Pull Request 指南](#pull-request-指南)
- [问题报告](#问题报告)
- [文档贡献](#文档贡献)
- [社区行为准则](#社区行为准则)

## 开始之前

### 阅读项目文档
在开始贡献之前，请确保您已经阅读并理解了以下文档：
- [README.md](README.md) - 项目概述
- [DEVELOPMENT.md](DEVELOPMENT.md) - 开发指南
- [API.md](API.md) - API 文档
- [架构文档](arch.md) - 系统架构

### 了解项目状态
- 查看 [Issues](https://github.com/your-org/nxxmdata/issues) 了解当前需要解决的问题
- 查看 [Projects](https://github.com/your-org/nxxmdata/projects) 了解项目路线图
- 查看 [CHANGELOG.md](CHANGELOG.md) 了解最新变更

## 如何贡献

您可以通过以下方式为项目做出贡献：

### 🐛 报告 Bug
- 发现了系统错误或异常行为
- 遇到了文档中的错误或不清楚的地方
- 发现了安全漏洞（请通过私密渠道报告）

### 💡 提出功能建议
- 提出新的功能想法
- 建议改进现有功能
- 提出用户体验优化建议

### 📝 改进文档
- 修复文档中的错误
- 添加缺失的文档
- 改进文档的清晰度和准确性
- 翻译文档到其他语言

### 💻 贡献代码
- 修复已知的 bug
- 实现新功能
- 优化性能
- 重构代码
- 添加测试用例

### 🎨 设计贡献
- 改进用户界面设计
- 提供图标和图片资源
- 优化用户体验

## 开发环境搭建

### 前置要求
- Node.js 18.0+
- npm 8.0+ 或 yarn 1.22+
- MySQL 8.0+
- Git 2.25+

### 克隆项目
```bash
# 1. Fork 项目到您的 GitHub 账户
# 2. 克隆您的 fork
git clone https://github.com/YOUR_USERNAME/nxxmdata.git
cd nxxmdata

# 3. 添加上游仓库
git remote add upstream https://github.com/original-org/nxxmdata.git
```

### 安装依赖
```bash
# 后端依赖
cd backend
npm install

# 前端依赖
cd ../admin-system/frontend
npm install

cd ../../website/data-screen
npm install

# 微信小程序依赖（可选）
cd ../../mini_program/farm-monitor-dashboard
npm install
```

### 配置环境
```bash
# 复制环境配置文件
cd backend
cp .env.example .env

cd ../admin-system/frontend
cp .env.example .env

# 编辑配置文件，设置数据库连接等信息
```

### 初始化数据库
```bash
cd backend
# 创建数据库
mysql -u root -p -e "CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 运行迁移
npm run db:migrate

# 填充种子数据
npm run db:seed
```

### 启动开发服务器
```bash
# 启动后端服务
cd backend
npm run dev

# 启动前端服务（新终端）
cd admin-system/frontend
npm run dev

# 启动官网大屏（新终端）
cd website/data-screen
npm run dev
```

## 代码贡献流程

### 1. 选择或创建 Issue
- 查看现有的 [Issues](https://github.com/your-org/nxxmdata/issues)
- 选择标记为 `good first issue` 的问题（适合新手）
- 如果是新功能，请先创建 Issue 讨论

### 2. 创建分支
```bash
# 更新主分支
git checkout main
git pull upstream main

# 创建功能分支
git checkout -b feature/your-feature-name
# 或者修复分支
git checkout -b fix/bug-description
```

### 3. 开发代码
- 编写代码
- 添加或更新测试
- 更新相关文档
- 确保代码符合项目规范

### 4. 测试代码
```bash
# 运行单元测试
npm test

# 运行集成测试
npm run test:integration

# 运行端到端测试
npm run test:e2e

# 检查代码风格
npm run lint

# 修复代码风格问题
npm run lint:fix
```

### 5. 提交代码
```bash
# 添加变更文件
git add .

# 提交代码（遵循提交信息规范）
git commit -m "feat: add user profile management feature"

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

### 6. 创建 Pull Request
- 在 GitHub 上创建 Pull Request
- 填写 PR 模板中的所有必要信息
- 等待代码审查

## 代码规范

### JavaScript/TypeScript 规范

#### 命名约定
```javascript
// 变量和函数使用 camelCase
const userName = 'john_doe';
function getUserInfo() {}

// 常量使用 UPPER_SNAKE_CASE
const API_BASE_URL = 'http://localhost:5350';

// 类名使用 PascalCase
class UserService {}

// 文件名使用 kebab-case
// user-service.js, farm-detail.vue
```

#### 代码风格
```javascript
// 使用 const/let，避免 var
const config = {...};
let mutableData = [];

// 使用箭头函数
const processData = (data) => {
  return data.map(item => item.value);
};

// 使用模板字符串
const message = `Hello, ${userName}!`;

// 使用对象解构
const { name, email } = user;

// 使用扩展运算符
const newArray = [...oldArray, newItem];
```

#### 错误处理
```javascript
// 使用 try-catch 处理异步错误
try {
  const result = await api.fetchData();
  return result;
} catch (error) {
  logger.error('Failed to fetch data:', error);
  throw new Error('Data fetch failed');
}

// 返回 Promise 的函数应该处理所有可能的错误
async function createUser(userData) {
  try {
    const user = await User.create(userData);
    return { success: true, data: user };
  } catch (error) {
    return { success: false, error: error.message };
  }
}
```

### Vue.js 组件规范

```vue
<template>
  <div class="component-name">
    <!-- 使用语义化的 HTML 标签 -->
    <header class="component-header">
      <h1>{{ title }}</h1>
    </header>
    
    <!-- 事件处理使用 handle 前缀 -->
    <button @click="handleSubmit">提交</button>
  </div>
</template>

<script>
import { ref, computed, onMounted } from 'vue'

export default {
  name: 'ComponentName', // 组件名使用 PascalCase
  
  props: {
    title: {
      type: String,
      required: true,
      default: ''
    }
  },
  
  emits: ['submit'],
  
  setup(props, { emit }) {
    // 响应式数据
    const isLoading = ref(false)
    
    // 计算属性
    const displayTitle = computed(() => {
      return props.title.toUpperCase()
    })
    
    // 方法
    const handleSubmit = () => {
      emit('submit')
    }
    
    // 生命周期
    onMounted(() => {
      // 初始化逻辑
    })
    
    return {
      isLoading,
      displayTitle,
      handleSubmit
    }
  }
}
</script>

<style scoped>
.component-name {
  /* 使用 BEM 命名法 */
}

.component-header {
  /* 样式规则 */
}
</style>
```

### CSS/SCSS 规范

```css
/* 使用 BEM 命名法 */
.block {}
.block__element {}
.block--modifier {}

/* 使用语义化的类名 */
.button--primary {}
.form__input--error {}

/* 避免深层嵌套 */
.component {
  .header {} /* 最多 3 层嵌套 */
}
```

## 提交规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

### 提交消息格式
```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

### 类型 (type)
- `feat`: 新增功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整（不影响代码逻辑）
- `refactor`: 重构（既不是新增功能也不是修复 bug）
- `perf`: 性能优化
- `test`: 添加或修改测试
- `chore`: 构建过程或辅助工具的变动
- `ci`: CI/CD 相关变更

### 范围 (scope)
- `api`: API 相关
- `ui`: 用户界面
- `auth`: 认证相关
- `db`: 数据库相关
- `config`: 配置相关

### 示例
```bash
feat(api): add user profile update endpoint
fix(ui): resolve map display issue on mobile devices
docs(readme): update installation instructions
style(frontend): format code with prettier
refactor(auth): simplify token validation logic
perf(db): optimize farm data query performance
test(api): add unit tests for user controller
chore(deps): update vue to version 3.4.0
```

### 破坏性变更
```bash
feat(api)!: change user authentication method

BREAKING CHANGE: JWT token format has changed
```

## Pull Request 指南

### PR 标题
PR 标题应该简洁明了地描述变更内容，遵循提交信息规范：
```
feat(user): add profile management feature
fix(map): resolve coordinate display issue
docs: update API documentation
```

### PR 描述模板
```markdown
## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
- [ ] 其他: ____________

## 变更描述
<!-- 简要描述这个 PR 的变更内容 -->

## 相关 Issue
<!-- 如果有相关的 Issue，请在此链接 -->
Closes #123

## 测试
- [ ] 我已经测试了我的代码
- [ ] 我已经添加了测试用例
- [ ] 所有测试都通过了

## 检查清单
- [ ] 我的代码遵循项目的代码规范
- [ ] 我已经进行了自我代码审查
- [ ] 我已经添加了必要的注释
- [ ] 我已经更新了相关文档
- [ ] 我的变更不会产生新的警告
- [ ] 我已经添加了适当的测试
- [ ] 新功能和修复都有对应的测试

## 截图（如果适用）
<!-- 如果是 UI 相关的变更，请添加截图 -->

## 额外说明
<!-- 任何其他需要说明的内容 -->
```

### 代码审查
- 所有 PR 都需要至少一个审查者的批准
- 解决所有审查意见后才能合并
- 保持代码变更的原子性和逻辑性
- 确保 CI/CD 检查通过

## 问题报告

### Bug 报告
使用 Bug 报告模板创建 Issue：

```markdown
**问题描述**
简要描述遇到的问题。

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

**预期行为**
描述您期望发生的行为。

**实际行为**
描述实际发生的行为。

**截图**
如果适用，添加截图来帮助解释您的问题。

**环境信息:**
 - 操作系统: [例如 macOS 12.0]
 - 浏览器: [例如 Chrome 95.0]
 - Node.js 版本: [例如 18.12.0]
 - 项目版本: [例如 1.2.0]

**附加信息**
添加任何其他有关问题的信息。
```

### 功能请求
```markdown
**功能描述**
简要描述您想要的功能。

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

**解决方案**
描述您想要的解决方案。

**备选方案**
描述您考虑过的任何备选解决方案或功能。

**附加信息**
添加任何其他关于功能请求的信息或截图。
```

## 文档贡献

### 文档类型
- **用户文档**: README, 安装指南, 使用教程
- **开发者文档**: API 文档, 开发指南, 架构文档
- **运维文档**: 部署指南, 故障排除, 监控指南

### 文档写作规范
- 使用清晰、简洁的语言
- 提供具体的示例和代码片段
- 包含必要的截图和图表
- 保持文档的时效性
- 使用统一的格式和风格

### 文档更新流程
1. 识别需要更新的文档
2. 创建文档分支 `docs/update-api-guide`
3. 更新文档内容
4. 提交并创建 PR
5. 经过审查后合并

## 社区行为准则

### 我们的承诺
为了营造一个开放和受欢迎的环境，我们作为贡献者和维护者承诺：无论年龄、体型、身体健全或残疾、民族、性别特征、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何，参与我们项目和社区的每个人都享有无骚扰的体验。

### 我们的标准
有助于创造积极环境的行为包括：
- 使用受欢迎和包容性的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同情

不可接受的行为包括：
- 使用性化的语言或图像以及不受欢迎的性关注或求爱
- 捣乱、侮辱/贬损评论以及个人或政治攻击
- 公开或私下骚扰
- 未经明确许可发布他人的私人信息
- 在专业环境中可能被合理认为不适当的其他行为

### 报告
如果您遇到不当行为，请联系项目团队：
- 邮箱: conduct@nxxmdata.com
- 我们将认真对待所有报告并进行调查

## 获得帮助

### 联系方式
- **技术问题**: 在 GitHub Issues 中提问
- **功能讨论**: 在 GitHub Discussions 中讨论
- **安全问题**: 发送邮件到 security@nxxmdata.com
- **其他问题**: 发送邮件到 hello@nxxmdata.com

### 社区资源
- [GitHub 仓库](https://github.com/your-org/nxxmdata)
- [项目文档](https://docs.nxxmdata.com)
- [API 文档](https://api.nxxmdata.com/docs)

## 认可贡献者

我们感谢所有为项目做出贡献的人！贡献者将被列在：
- [CONTRIBUTORS.md](CONTRIBUTORS.md) 文件中
- 项目的 README 中
- 每次发布的致谢中

### 贡献类型
我们认可以下类型的贡献：
- 💻 代码贡献
- 📖 文档贡献
- 🎨 设计贡献
- 🐛 Bug 报告
- 💡 想法和建议
- 🤔 答疑解惑
- 📢 推广项目

## 许可证

通过向此项目贡献代码，您同意您的贡献将在与项目相同的许可证下被许可。

---

再次感谢您对宁夏智慧养殖监管平台的关注和贡献！我们期待与您一起构建更好的系统。

*最后更新: 2025年1月*