BodyBalanceEvaluation/CONTRIBUTING.md

# 贡献指南

感谢您对身体平衡评估系统项目的关注！我们欢迎所有形式的贡献，包括但不限于代码、文档、测试、问题报告和功能建议。

## 目录

- [行为准则](#行为准则)
- [如何贡献](#如何贡献)
- [开发环境设置](#开发环境设置)
- [代码规范](#代码规范)
- [提交规范](#提交规范)
- [Pull Request 流程](#pull-request-流程)
- [问题报告](#问题报告)
- [功能请求](#功能请求)
- [文档贡献](#文档贡献)
- [测试指南](#测试指南)

## 行为准则

### 我们的承诺

为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺，无论年龄、体型、残疾、种族、性别认同和表达、经验水平、国籍、个人形象、种族、宗教或性取向如何，参与我们项目和社区的每个人都能获得无骚扰的体验。

### 我们的标准

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

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

不可接受的行为包括：

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

## 如何贡献

### 贡献类型

我们欢迎以下类型的贡献：

1. **代码贡献**
   - 新功能开发
   - Bug 修复
   - 性能优化
   - 代码重构

2. **文档贡献**
   - API 文档
   - 用户指南
   - 开发者文档
   - 代码注释

3. **测试贡献**
   - 单元测试
   - 集成测试
   - 端到端测试
   - 性能测试

4. **设计贡献**
   - UI/UX 设计
   - 图标设计
   - 用户体验改进

5. **其他贡献**
   - 问题报告
   - 功能建议
   - 社区支持
   - 翻译工作

## 开发环境设置

### 前置要求

- Python 3.8+
- Node.js 16.0+
- Git
- 代码编辑器（推荐 VS Code）

### 环境配置

1. **克隆仓库**
   ```bash
   git clone https://github.com/example/body-balance-evaluation.git
   cd body-balance-evaluation
   ```

2. **安装依赖**
   ```bash
   # Windows
   install.bat
   
   # 或手动安装
   python -m venv venv
   venv\Scripts\activate  # Windows
   # source venv/bin/activate  # macOS/Linux
   
   pip install -r backend/requirements.txt
   cd src/renderer && npm install
   ```

3. **配置开发环境**
   ```bash
   # 复制配置文件
   cp config.json config.local.json
   
   # 编辑本地配置（可选）
   # 修改 config.local.json 中的设置
   ```

4. **启动开发服务器**
   ```bash
   # Windows
   start_dev.bat
   
   # 或手动启动
   python main.py --mode development
   ```

### 开发工具推荐

#### VS Code 扩展
- Python
- Pylance
- Vue Language Features (Volar)
- TypeScript Vue Plugin (Volar)
- ESLint
- Prettier
- GitLens

#### 浏览器扩展
- Vue.js devtools
- React Developer Tools（如果使用）

## 代码规范

### Python 代码规范

我们遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 规范：

```python
# 好的示例
class PatientManager:
    """患者管理器类"""
    
    def __init__(self, database_path: str):
        self.db_path = database_path
        self.logger = logging.getLogger(__name__)
    
    def create_patient(self, patient_data: dict) -> int:
        """创建新患者
        
        Args:
            patient_data: 患者信息字典
            
        Returns:
            患者ID
            
        Raises:
            ValueError: 当患者数据无效时
        """
        if not self._validate_patient_data(patient_data):
            raise ValueError("Invalid patient data")
        
        # 实现逻辑...
        return patient_id
```

#### 代码格式化
使用 Black 进行代码格式化：
```bash
black . --line-length=88
```

#### 代码检查
使用 flake8 进行代码检查：
```bash
flake8 . --max-line-length=88 --exclude=venv,__pycache__
```

### JavaScript/Vue 代码规范

我们遵循 [Vue.js 风格指南](https://vuejs.org/style-guide/)：

```javascript
// 好的示例
export default {
  name: 'PatientList',
  
  props: {
    patients: {
      type: Array,
      required: true
    },
    loading: {
      type: Boolean,
      default: false
    }
  },
  
  emits: ['patient-selected', 'patient-deleted'],
  
  setup(props, { emit }) {
    const selectedPatient = ref(null)
    
    const handlePatientClick = (patient) => {
      selectedPatient.value = patient
      emit('patient-selected', patient)
    }
    
    return {
      selectedPatient,
      handlePatientClick
    }
  }
}
```

#### 代码格式化
使用 Prettier 进行代码格式化：
```bash
npm run format
```

#### 代码检查
使用 ESLint 进行代码检查：
```bash
npm run lint
```

### 通用规范

1. **命名规范**
   - 使用有意义的变量和函数名
   - Python: snake_case
   - JavaScript: camelCase
   - 常量: UPPER_CASE
   - 类名: PascalCase

2. **注释规范**
   - 为复杂逻辑添加注释
   - 使用文档字符串描述函数和类
   - 注释应该解释"为什么"而不是"是什么"

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 配置文件和脚本的变动
- `revert`: 回滚之前的提交

### 范围 (scope)

- `frontend`: 前端相关
- `backend`: 后端相关
- `database`: 数据库相关
- `device`: 设备管理相关
- `analysis`: 数据分析相关
- `ui`: 用户界面相关
- `api`: API 相关
- `config`: 配置相关
- `docs`: 文档相关
- `test`: 测试相关

### 示例

```bash
# 新功能
git commit -m "feat(frontend): add patient search functionality"

# Bug 修复
git commit -m "fix(backend): resolve database connection timeout issue"

# 文档更新
git commit -m "docs(api): update patient management API documentation"

# 重构
git commit -m "refactor(device): simplify camera initialization logic"
```

## Pull Request 流程

### 创建 Pull Request

1. **Fork 仓库**
   - 点击 GitHub 页面右上角的 "Fork" 按钮

2. **创建功能分支**
   ```bash
   git checkout -b feature/your-feature-name
   # 或
   git checkout -b fix/your-bug-fix
   ```

3. **进行开发**
   - 编写代码
   - 添加测试
   - 更新文档

4. **提交更改**
   ```bash
   git add .
   git commit -m "feat(scope): your commit message"
   ```

5. **推送分支**
   ```bash
   git push origin feature/your-feature-name
   ```

6. **创建 Pull Request**
   - 在 GitHub 上创建 Pull Request
   - 填写详细的描述

### Pull Request 模板

```markdown
## 描述
简要描述这个 PR 的目的和内容。

## 更改类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重构
- [ ] 文档更新
- [ ] 性能优化
- [ ] 其他（请说明）

## 测试
- [ ] 已添加单元测试
- [ ] 已添加集成测试
- [ ] 已手动测试
- [ ] 所有测试通过

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的注释
- [ ] 已更新相关文档
- [ ] 没有引入新的警告
- [ ] 已测试在不同环境下的兼容性

## 相关问题
关闭 #issue_number

## 截图（如适用）
添加截图来帮助解释你的更改。

## 额外说明
添加任何其他相关信息。
```

### 代码审查

所有 Pull Request 都需要经过代码审查：

1. **自动检查**
   - CI/CD 流水线检查
   - 代码格式检查
   - 测试覆盖率检查

2. **人工审查**
   - 代码质量
   - 设计合理性
   - 测试完整性
   - 文档完整性

3. **审查标准**
   - 代码可读性
   - 性能影响
   - 安全性考虑
   - 向后兼容性

## 问题报告

### 报告 Bug

使用 [Bug 报告模板](https://github.com/example/body-balance-evaluation/issues/new?template=bug_report.md)：

```markdown
**描述 Bug**
清晰简洁地描述 bug 是什么。

**重现步骤**
重现行为的步骤：
1. 转到 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误

**预期行为**
清晰简洁地描述你期望发生什么。

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

**环境信息**
 - 操作系统: [例如 Windows 10]
 - Python 版本: [例如 3.9.0]
 - Node.js 版本: [例如 16.14.0]
 - 应用版本: [例如 1.0.0]

**额外信息**
添加任何其他关于问题的信息。
```

### 报告安全问题

如果发现安全漏洞，请不要在公开的 issue 中报告。请发送邮件到 security@example.com。

## 功能请求

使用 [功能请求模板](https://github.com/example/body-balance-evaluation/issues/new?template=feature_request.md)：

```markdown
**功能描述**
清晰简洁地描述你想要的功能。

**问题描述**
清晰简洁地描述问题是什么。例如：我总是感到沫丧当 [...]

**解决方案**
清晰简洁地描述你想要发生什么。

**替代方案**
清晰简洁地描述你考虑过的任何替代解决方案或功能。

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

## 文档贡献

### 文档类型

1. **用户文档**
   - 安装指南
   - 使用教程
   - 常见问题
   - 故障排除

2. **开发者文档**
   - API 文档
   - 架构说明
   - 贡献指南
   - 代码注释

3. **项目文档**
   - README
   - CHANGELOG
   - LICENSE
   - 项目规划

### 文档规范

1. **Markdown 格式**
   - 使用标准 Markdown 语法
   - 保持一致的格式
   - 使用有意义的标题

2. **内容要求**
   - 清晰准确
   - 及时更新
   - 包含示例
   - 考虑不同用户水平

3. **图片和媒体**
   - 使用 SVG 格式（如可能）
   - 优化文件大小
   - 提供替代文本

## 测试指南

### 测试类型

1. **单元测试**
   - 测试单个函数或方法
   - 使用 pytest（Python）或 Jest（JavaScript）
   - 目标覆盖率 > 80%

2. **集成测试**
   - 测试模块间交互
   - 测试 API 端点
   - 测试数据库操作

3. **端到端测试**
   - 测试完整用户流程
   - 使用 Playwright 或 Cypress
   - 测试关键业务场景

### 测试规范

```python
# Python 测试示例
import pytest
from unittest.mock import Mock, patch

class TestPatientManager:
    """患者管理器测试类"""
    
    @pytest.fixture
    def patient_manager(self):
        """测试夹具"""
        return PatientManager(":memory:")
    
    def test_create_patient_success(self, patient_manager):
        """测试成功创建患者"""
        patient_data = {
            "name": "测试患者",
            "age": 30,
            "gender": "male"
        }
        
        patient_id = patient_manager.create_patient(patient_data)
        
        assert patient_id is not None
        assert isinstance(patient_id, int)
    
    def test_create_patient_invalid_data(self, patient_manager):
        """测试无效数据创建患者"""
        invalid_data = {"name": ""}
        
        with pytest.raises(ValueError):
            patient_manager.create_patient(invalid_data)
```

```javascript
// JavaScript 测试示例
import { describe, it, expect, vi } from 'vitest'
import { mount } from '@vue/test-utils'
import PatientList from '@/components/PatientList.vue'

describe('PatientList', () => {
  it('renders patient list correctly', () => {
    const patients = [
      { id: 1, name: '患者1', age: 30 },
      { id: 2, name: '患者2', age: 25 }
    ]
    
    const wrapper = mount(PatientList, {
      props: { patients }
    })
    
    expect(wrapper.findAll('.patient-item')).toHaveLength(2)
    expect(wrapper.text()).toContain('患者1')
    expect(wrapper.text()).toContain('患者2')
  })
  
  it('emits patient-selected event when patient is clicked', async () => {
    const patients = [{ id: 1, name: '患者1', age: 30 }]
    
    const wrapper = mount(PatientList, {
      props: { patients }
    })
    
    await wrapper.find('.patient-item').trigger('click')
    
    expect(wrapper.emitted('patient-selected')).toBeTruthy()
    expect(wrapper.emitted('patient-selected')[0]).toEqual([patients[0]])
  })
})
```

### 运行测试

```bash
# Python 测试
cd backend
python -m pytest tests/ -v --cov=.

# JavaScript 测试
cd src/renderer
npm run test

# 所有测试
npm run test
```

## 发布流程

### 版本管理

我们使用语义化版本控制：

- **主版本号**: 不兼容的 API 修改
- **次版本号**: 向下兼容的功能性新增
- **修订号**: 向下兼容的问题修正

### 发布步骤

1. **更新版本号**
   ```bash
   # 更新 package.json 中的版本号
   npm version patch|minor|major
   ```

2. **更新 CHANGELOG**
   - 记录所有重要更改
   - 按类型分组（新增、更改、修复等）

3. **创建发布标签**
   ```bash
   git tag -a v1.0.0 -m "Release version 1.0.0"
   git push origin v1.0.0
   ```

4. **构建和测试**
   ```bash
   npm run build
   npm run test
   ```

5. **发布**
   - 创建 GitHub Release
   - 上传构建产物
   - 发布到包管理器（如需要）

## 社区支持

### 获取帮助

- **GitHub Discussions**: 一般讨论和问题
- **GitHub Issues**: Bug 报告和功能请求
- **邮件**: dev@example.com
- **文档**: 项目 Wiki

### 参与社区

- 回答其他用户的问题
- 参与功能讨论
- 分享使用经验
- 推广项目

## 致谢

感谢所有为这个项目做出贡献的开发者！

### 贡献者

- [贡献者列表](https://github.com/example/body-balance-evaluation/contributors)

### 特别感谢

- 感谢所有提供反馈和建议的用户
- 感谢开源社区提供的优秀工具和库
- 感谢医疗专业人士提供的专业指导

---

再次感谢您的贡献！如果您有任何问题，请随时联系我们。