aiotagro/nxxmdata

Fork 0

Files

ylweng 6b4e0c227f 修改文件结构，统一文档格式

2025-09-02 23:22:10 +08:00

13 KiB

Raw Blame History

贡献指南

欢迎贡献

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

开始之前

阅读项目文档

在开始贡献之前，请确保您已经阅读并理解了以下文档：

README.md - 项目概述
DEVELOPMENT.md - 开发指南
API.md - API 文档
架构文档 - 系统架构

了解项目状态

查看 Issues 了解当前需要解决的问题
查看 Projects 了解项目路线图
查看 CHANGELOG.md 了解最新变更

如何贡献

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

🐛 报告 Bug

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

💡 提出功能建议

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

📝 改进文档

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

💻 贡献代码

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

🎨 设计贡献

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

开发环境搭建

前置要求

Node.js 18.0+
npm 8.0+ 或 yarn 1.22+
MySQL 8.0+
Git 2.25+

克隆项目

# 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

安装依赖

# 后端依赖
cd backend
npm install

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

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

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

配置环境

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

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

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

初始化数据库

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

启动开发服务器

# 启动后端服务
cd backend
npm run dev

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

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

代码贡献流程

1. 选择或创建 Issue

查看现有的 Issues
选择标记为 good first issue 的问题（适合新手）
如果是新功能，请先创建 Issue 讨论

2. 创建分支

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

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

3. 开发代码

编写代码
添加或更新测试
更新相关文档
确保代码符合项目规范

4. 测试代码

# 运行单元测试
npm test

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

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

# 检查代码风格
npm run lint

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

5. 提交代码

# 添加变更文件
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 规范

命名约定

// 变量和函数使用 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

代码风格

// 使用 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];

错误处理

// 使用 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 组件规范

<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 规范

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

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

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

提交规范

我们使用 Conventional Commits 规范：

提交消息格式

<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: 配置相关

示例

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

破坏性变更

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 描述模板

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
- [ ] 其他: ____________

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

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

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

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

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

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

代码审查

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

问题报告

Bug 报告

使用 Bug 报告模板创建 Issue：

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

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

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

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

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

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

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

功能请求

**功能描述**
简要描述您想要的功能。

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

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

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

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

文档贡献

文档类型

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

文档写作规范

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

文档更新流程

识别需要更新的文档
创建文档分支 docs/update-api-guide
更新文档内容
提交并创建 PR
经过审查后合并

社区行为准则

我们的承诺

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

我们的标准

有助于创造积极环境的行为包括：

使用受欢迎和包容性的语言
尊重不同的观点和经验
优雅地接受建设性批评
关注对社区最有利的事情
对其他社区成员表示同情

不可接受的行为包括：

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

报告

如果您遇到不当行为，请联系项目团队：

邮箱: conduct@nxxmdata.com
我们将认真对待所有报告并进行调查

获得帮助

联系方式

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

社区资源

认可贡献者

我们感谢所有为项目做出贡献的人！贡献者将被列在：

CONTRIBUTORS.md 文件中
项目的 README 中
每次发布的致谢中

贡献类型

我们认可以下类型的贡献：

💻 代码贡献
📖 文档贡献
🎨 设计贡献
🐛 Bug 报告
💡 想法和建议
🤔 答疑解惑
📢 推广项目

许可证

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

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

最后更新: 2025年1月

13 KiB Raw Blame History Unescape Escape