删除废弃的API和架构文档
This commit is contained in:
ylweng
594
docs/development/CONTRIBUTING.md
Normal file
594
docs/development/CONTRIBUTING.md
Normal file
@@ -0,0 +1,594 @@
|
||||
# 贡献指南
|
||||
|
||||
## 欢迎贡献
|
||||
|
||||
我们热烈欢迎社区开发者为宁夏智慧养殖监管平台做出贡献！无论您是想修复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月*
|
||||
Reference in New Issue
Block a user