Initial project setup with Python version 3.12, main script for backtesting trading strategies, and configuration files for project management. Added necessary dependencies and documentation structure.

2025-08-05 12:08:59 +08:00
parent cac0629dcd
commit 56dca05a3e
17 changed files with 1871 additions and 0 deletions
--- a/.cursor/rules/documentation.mdc
+++ b/.cursor/rules/documentation.mdc
@@ -0,0 +1,244 @@
+---
+description: Documentation standards for code, architecture, and development decisions
+globs: 
+alwaysApply: false
+---
+
+# Rule: Documentation Standards
+
+## Goal
+Maintain comprehensive, up-to-date documentation that supports development, onboarding, and long-term maintenance of the codebase.
+
+## Documentation Hierarchy
+
+### 1. Project Level Documentation (in ./docs/)
+- **README.md**: Project overview, setup instructions, basic usage
+- **CONTEXT.md**: Current project state, architecture decisions, patterns
+- **CHANGELOG.md**: Version history and significant changes
+- **CONTRIBUTING.md**: Development guidelines and processes
+- **API.md**: API endpoints, request/response formats, authentication
+
+### 2. Module Level Documentation (in ./docs/modules/)
+- **[module-name].md**: Purpose, public interfaces, usage examples
+- **dependencies.md**: External dependencies and their purposes
+- **architecture.md**: Module relationships and data flow
+
+### 3. Code Level Documentation
+- **Docstrings**: Function and class documentation
+- **Inline comments**: Complex logic explanations
+- **Type hints**: Clear parameter and return types
+- **README files**: Directory-specific instructions
+
+## Documentation Standards
+
+### Code Documentation
+```python
+def process_user_data(user_id: str, data: dict) -> UserResult:
+    """
+    Process and validate user data before storage.
+    
+    Args:
+        user_id: Unique identifier for the user
+        data: Dictionary containing user information to process
+        
+    Returns:
+        UserResult: Processed user data with validation status
+        
+    Raises:
+        ValidationError: When user data fails validation
+        DatabaseError: When storage operation fails
+        
+    Example:
+        >>> result = process_user_data("123", {"name": "John", "email": "john@example.com"})
+        >>> print(result.status)
+        'valid'
+    """
+```
+
+### API Documentation Format
+```markdown
+### POST /api/users
+
+Create a new user account.
+
+**Request:**
+```json
+{
+    "name": "string (required)",
+    "email": "string (required, valid email)",
+    "age": "number (optional, min: 13)"
+}
+```
+
+**Response (201):**
+```json
+{
+    "id": "uuid",
+    "name": "string",
+    "email": "string", 
+    "created_at": "iso_datetime"
+}
+```
+
+**Errors:**
+- 400: Invalid input data
+- 409: Email already exists
+```
+
+### Architecture Decision Records (ADRs)
+Document significant architecture decisions in `./docs/decisions/`:
+
+```markdown
+# ADR-001: Database Choice - PostgreSQL
+
+## Status
+Accepted
+
+## Context
+We need to choose a database for storing user data and application state.
+
+## Decision
+We will use PostgreSQL as our primary database.
+
+## Consequences
+**Positive:**
+- ACID compliance ensures data integrity
+- Rich query capabilities with SQL
+- Good performance for our expected load
+
+**Negative:**
+- More complex setup than simpler alternatives
+- Requires SQL knowledge from team members
+
+## Alternatives Considered
+- MongoDB: Rejected due to consistency requirements
+- SQLite: Rejected due to scalability needs
+```
+
+## Documentation Maintenance
+
+### When to Update Documentation
+
+#### Always Update:
+- **API changes**: Any modification to public interfaces
+- **Architecture changes**: New patterns, data structures, or workflows  
+- **Configuration changes**: Environment variables, deployment settings
+- **Dependencies**: Adding, removing, or upgrading packages
+- **Business logic changes**: Core functionality modifications
+
+#### Update Weekly:
+- **CONTEXT.md**: Current development status and priorities
+- **Known issues**: Bug reports and workarounds
+- **Performance notes**: Bottlenecks and optimization opportunities
+
+#### Update per Release:
+- **CHANGELOG.md**: User-facing changes and improvements
+- **Version documentation**: Breaking changes and migration guides
+- **Examples and tutorials**: Keep sample code current
+
+### Documentation Quality Checklist
+
+#### Completeness
+- [ ] Purpose and scope clearly explained
+- [ ] All public interfaces documented
+- [ ] Examples provided for complex usage
+- [ ] Error conditions and handling described
+- [ ] Dependencies and requirements listed
+
+#### Accuracy
+- [ ] Code examples are tested and working
+- [ ] Links point to correct locations
+- [ ] Version numbers are current
+- [ ] Screenshots reflect current UI
+
+#### Clarity
+- [ ] Written for the intended audience
+- [ ] Technical jargon is explained
+- [ ] Step-by-step instructions are clear
+- [ ] Visual aids used where helpful
+
+## Documentation Automation
+
+### Auto-Generated Documentation
+- **API docs**: Generate from code annotations
+- **Type documentation**: Extract from type hints
+- **Module dependencies**: Auto-update from imports
+- **Test coverage**: Include coverage reports
+
+### Documentation Testing
+```python
+# Test that code examples in documentation work
+def test_documentation_examples():
+    """Verify code examples in docs actually work."""
+    # Test examples from README.md
+    # Test API examples from docs/API.md
+    # Test configuration examples
+```
+
+## Documentation Templates
+
+### New Module Documentation Template
+```markdown
+# Module: [Name]
+
+## Purpose
+Brief description of what this module does and why it exists.
+
+## Public Interface
+### Functions
+- `function_name(params)`: Description and example
+
+### Classes  
+- `ClassName`: Purpose and basic usage
+
+## Usage Examples
+```python
+# Basic usage example
+```
+
+## Dependencies
+- Internal: List of internal modules this depends on
+- External: List of external packages required
+
+## Testing
+How to run tests for this module.
+
+## Known Issues
+Current limitations or bugs.
+```
+
+### API Endpoint Template
+```markdown
+### [METHOD] /api/endpoint
+
+Brief description of what this endpoint does.
+
+**Authentication:** Required/Optional
+**Rate Limiting:** X requests per minute
+
+**Request:**
+- Headers required
+- Body schema
+- Query parameters
+
+**Response:**
+- Success response format
+- Error response format
+- Status codes
+
+**Example:**
+Working request/response example
+```
+
+## Review and Maintenance Process
+
+### Documentation Review
+- Include documentation updates in code reviews
+- Verify examples still work with code changes
+- Check for broken links and outdated information
+- Ensure consistency with current implementation
+
+### Regular Audits
+- Monthly review of documentation accuracy
+- Quarterly assessment of documentation completeness
+- Annual review of documentation structure and organization