Add File

CONTRIBUTING.md

@@ -0,0 +1,419 @@
+# 贡献指南 / Contributing Guide
+
+[English](#english) | [中文](#中文)
+
+---
+
+## 中文
+
+感谢您对 LandPPT 项目的关注！我们欢迎所有形式的贡献，包括但不限于：
+
+### 🤝 贡献方式
+
+- 🐛 **Bug 报告**：发现问题并报告
+- 💡 **功能建议**：提出新功能想法
+- 📝 **代码贡献**：修复bug或实现新功能
+- 📚 **文档改进**：完善文档和示例
+- 🌐 **翻译工作**：帮助翻译界面和文档
+- 🧪 **测试用例**：编写和改进测试
+
+### 🚀 开始贡献
+
+#### 1. 准备开发环境
+
+```bash
+# Fork 并克隆仓库
+git clone https://github.com/your-username/LandPPT.git
+cd LandPPT
+
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# 或
+.venv\Scripts\activate     # Windows
+
+# 安装依赖
+pip install uv
+uv pip install -e ".[dev]"
+
+# 配置环境变量
+cp .env.example .env
+# 编辑 .env 文件配置必要的API密钥
+
+# 初始化数据库
+python setup_database.py
+
+# 运行项目
+python run.py
+```
+
+#### 2. 开发流程
+
+1. **创建分支**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # 或
+   git checkout -b fix/your-bug-fix
+   ```
+
+2. **编写代码**
+   - 遵循现有的代码风格
+   - 添加必要的注释和文档字符串
+   - 确保代码通过所有测试
+
+3. **运行测试**
+   ```bash
+   # 运行所有测试
+   pytest
+
+   # 运行特定测试
+   pytest tests/test_specific.py
+
+   # 生成覆盖率报告
+   pytest --cov=src/landppt
+   ```
+
+4. **代码格式化**
+   ```bash
+   # 格式化代码
+   black src/
+   isort src/
+
+   # 检查代码质量
+   flake8 src/
+   mypy src/
+   ```
+
+5. **提交更改**
+   ```bash
+   git add .
+   git commit -m "feat: add new feature description"
+   # 或
+   git commit -m "fix: fix bug description"
+   ```
+
+6. **推送并创建PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+   然后在GitHub上创建Pull Request
+
+### 📝 代码规范
+
+#### 提交信息格式
+使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+类型包括：
+- `feat`: 新功能
+- `fix`: Bug修复
+- `docs`: 文档更新
+- `style`: 代码格式化
+- `refactor`: 代码重构
+- `test`: 测试相关
+- `chore`: 构建过程或辅助工具的变动
+
+#### Python代码规范
+- 遵循 [PEP 8](https://pep8.org/) 规范
+- 使用类型提示 (Type Hints)
+- 编写清晰的文档字符串
+- 保持函数和类的单一职责
+
+#### 示例代码风格
+```python
+from typing import Optional, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+class PPTGenerator:
+    """PPT生成器类
+    
+    负责根据输入内容生成PPT演示文稿
+    """
+    
+    def __init__(self, config: Dict[str, Any]) -> None:
+        """初始化PPT生成器
+        
+        Args:
+            config: 配置字典
+        """
+        self.config = config
+        
+    async def generate_ppt(
+        self, 
+        content: str, 
+        template_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """生成PPT
+        
+        Args:
+            content: 输入内容
+            template_id: 模板ID，可选
+            
+        Returns:
+            生成的PPT数据
+            
+        Raises:
+            ValueError: 当输入内容为空时
+        """
+        if not content.strip():
+            raise ValueError("内容不能为空")
+            
+        logger.info(f"开始生成PPT，内容长度: {len(content)}")
+        
+        # 实现逻辑...
+        return {"status": "success", "data": {}}
+```
+
+### 🧪 测试指南
+
+#### 编写测试
+- 为新功能编写单元测试
+- 确保测试覆盖率不低于80%
+- 使用有意义的测试名称
+- 测试边界条件和异常情况
+
+#### 测试示例
+```python
+import pytest
+from unittest.mock import Mock, patch
+from src.landppt.core.ppt_generator import PPTGenerator
+
+class TestPPTGenerator:
+    """PPT生成器测试类"""
+    
+    @pytest.fixture
+    def generator(self):
+        """创建PPT生成器实例"""
+        config = {"template_dir": "/tmp/templates"}
+        return PPTGenerator(config)
+    
+    async def test_generate_ppt_success(self, generator):
+        """测试成功生成PPT"""
+        content = "这是测试内容"
+        result = await generator.generate_ppt(content)
+        
+        assert result["status"] == "success"
+        assert "data" in result
+    
+    async def test_generate_ppt_empty_content(self, generator):
+        """测试空内容异常"""
+        with pytest.raises(ValueError, match="内容不能为空"):
+            await generator.generate_ppt("")
+```
+
+### 📋 Issue 和 PR 模板
+
+#### Bug 报告
+报告bug时请包含：
+- 问题描述
+- 复现步骤
+- 期望行为
+- 实际行为
+- 环境信息（操作系统、Python版本等）
+- 相关日志或截图
+
+#### 功能请求
+提出新功能时请包含：
+- 功能描述
+- 使用场景
+- 预期收益
+- 可能的实现方案
+
+### 🎯 开发重点
+
+当前项目重点关注以下方面：
+
+1. **AI集成优化**
+   - 支持更多AI提供商
+   - 优化AI调用性能
+   - 改进错误处理
+
+2. **模板系统**
+   - 丰富模板库
+   - 改进模板编辑器
+   - 支持自定义模板
+
+3. **用户体验**
+   - 优化Web界面
+   - 改进响应速度
+   - 增强错误提示
+
+4. **文档和测试**
+   - 完善API文档
+   - 增加测试覆盖率
+   - 改进用户指南
+
+### 📞 联系方式
+
+如有疑问，可以通过以下方式联系：
+- 创建 [GitHub Issue](https://github.com/your-username/LandPPT/issues)
+- 参与 [GitHub Discussions](https://github.com/your-username/LandPPT/discussions)
+
+---
+
+## English
+
+Thank you for your interest in the LandPPT project! We welcome all forms of contributions, including but not limited to:
+
+### 🤝 Ways to Contribute
+
+- 🐛 **Bug Reports**: Find and report issues
+- 💡 **Feature Suggestions**: Propose new feature ideas
+- 📝 **Code Contributions**: Fix bugs or implement new features
+- 📚 **Documentation**: Improve docs and examples
+- 🌐 **Translation**: Help translate interface and documentation
+- 🧪 **Testing**: Write and improve test cases
+
+### 🚀 Getting Started
+
+#### 1. Development Environment Setup
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/your-username/LandPPT.git
+cd LandPPT
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# or
+.venv\Scripts\activate     # Windows
+
+# Install dependencies
+pip install uv
+uv pip install -e ".[dev]"
+
+# Configure environment variables
+cp .env.example .env
+# Edit .env file to configure necessary API keys
+
+# Initialize database
+python setup_database.py
+
+# Run the project
+python run.py
+```
+
+#### 2. Development Workflow
+
+1. **Create Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+2. **Write Code**
+   - Follow existing code style
+   - Add necessary comments and docstrings
+   - Ensure code passes all tests
+
+3. **Run Tests**
+   ```bash
+   # Run all tests
+   pytest
+
+   # Run specific tests
+   pytest tests/test_specific.py
+
+   # Generate coverage report
+   pytest --cov=src/landppt
+   ```
+
+4. **Code Formatting**
+   ```bash
+   # Format code
+   black src/
+   isort src/
+
+   # Check code quality
+   flake8 src/
+   mypy src/
+   ```
+
+5. **Commit Changes**
+   ```bash
+   git add .
+   git commit -m "feat: add new feature description"
+   # or
+   git commit -m "fix: fix bug description"
+   ```
+
+6. **Push and Create PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+   Then create a Pull Request on GitHub
+
+### 📝 Code Standards
+
+#### Commit Message Format
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Types include:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation update
+- `style`: Code formatting
+- `refactor`: Code refactoring
+- `test`: Test related
+- `chore`: Build process or auxiliary tool changes
+
+#### Python Code Standards
+- Follow [PEP 8](https://pep8.org/) guidelines
+- Use Type Hints
+- Write clear docstrings
+- Maintain single responsibility for functions and classes
+
+### 🧪 Testing Guidelines
+
+#### Writing Tests
+- Write unit tests for new features
+- Ensure test coverage is not less than 80%
+- Use meaningful test names
+- Test boundary conditions and exceptions
+
+### 📋 Issue and PR Templates
+
+#### Bug Reports
+When reporting bugs, please include:
+- Problem description
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Environment info (OS, Python version, etc.)
+- Relevant logs or screenshots
+
+#### Feature Requests
+When proposing new features, please include:
+- Feature description
+- Use cases
+- Expected benefits
+- Possible implementation approaches
+
+### 📞 Contact
+
+If you have questions, you can contact us through:
+- Create a [GitHub Issue](https://github.com/your-username/LandPPT/issues)
+- Join [GitHub Discussions](https://github.com/your-username/LandPPT/discussions)
+
+---
+
+Thank you for contributing to LandPPT! 🎉