262 lines
11 KiB
Markdown
262 lines
11 KiB
Markdown
# Backend MVP Implementation Plan
|
|
|
|
## Overview
|
|
This plan details the concrete implementation steps for the Captain's Log backend MVP using Rust + Axum + SQLx with comprehensive testing infrastructure.
|
|
|
|
## Project Structure (Actual Implementation)
|
|
```
|
|
captains-log/
|
|
├── justfile # Task runner for development commands
|
|
├── CLAUDE.md # Claude Code guidance
|
|
├── plan/ # Implementation plans and documentation
|
|
│ ├── 01_CORE_MVP/
|
|
│ │ ├── backend.md # This file
|
|
│ │ └── plan.md # Overall MVP plan
|
|
│ └── future_improvements.md # Architectural improvement opportunities
|
|
└── backend/
|
|
├── Cargo.toml # Rust project manifest
|
|
├── src/
|
|
│ ├── main.rs # Application entry point with health endpoint
|
|
│ ├── database/
|
|
│ │ ├── mod.rs # Database module exports
|
|
│ │ └── connection.rs # Database connection utilities
|
|
│ ├── models/
|
|
│ │ ├── mod.rs # Models module
|
|
│ │ └── task.rs # TaskModel with CRUD methods (Active Record)
|
|
│ └── services/
|
|
│ ├── mod.rs # Error handling and exports
|
|
│ └── tasks.rs # HTTP handlers for task endpoints
|
|
├── tests/api/ # Hurl API integration tests
|
|
│ ├── tasks.hurl # Main task API tests
|
|
│ ├── list_tasks.hurl # Task listing tests
|
|
│ ├── update_tasks.hurl # Task update tests
|
|
│ └── delete_tasks.hurl # Task deletion tests
|
|
└── migrations/
|
|
├── 20250823023643_create_tasks.up.sql # Create tasks table
|
|
└── 20250823023643_create_tasks.down.sql # Drop tasks table
|
|
```
|
|
|
|
## Phase 1: Project Foundation (Days 1-2)
|
|
|
|
### Task 1.1: Initialize Rust Project
|
|
- [x] **File**: `backend/Cargo.toml`
|
|
- Create new Rust binary project
|
|
- Add core dependencies: axum, sqlx, tokio, serde, uuid, chrono, anyhow
|
|
- Add dev dependencies: tarpaulin for coverage
|
|
- Configure SQLx features for SQLite and runtime
|
|
- **Expected outcome**: `cargo build` succeeds
|
|
|
|
### Task 1.2: Create Hello World Axum Server
|
|
- [x] **Files**: `backend/src/main.rs`, `backend/src/lib.rs`
|
|
- Create basic Axum application with health check endpoint
|
|
- Set up tokio runtime and basic error handling
|
|
- Configure server to listen on localhost:3000
|
|
- Add basic logging with tracing
|
|
- Set up lib.rs with public module exports for testing
|
|
- **Expected outcome**: `cargo run` starts server responding to GET /health
|
|
|
|
### Task 1.3: Create Development Justfile
|
|
- [x] **File**: `justfile`
|
|
- Initial commands: 'dev', 'build', 'test-unit', 'fmt', 'lint', 'clean'
|
|
- As Needed: `test-api`, `test-coverage`
|
|
- **Expected outcome**: `just --list` shows all commands
|
|
|
|
## Phase 2: Core Database Layer (Days 3-4)
|
|
|
|
### Task 2.0: Create Initial Database Migration
|
|
- [x] **File**: `backend/migrations/001_create_tasks.sql`
|
|
- Create tasks table with all required fields
|
|
- Add proper indexes and constraints
|
|
- Include created_at, updated_at triggers if needed
|
|
- Add database justfile commands: `migrate`, `reset-db`
|
|
- **Expected outcome**: `sqlx migrate run` creates table successfully
|
|
|
|
### Task 2.1: Define Task Model
|
|
- [x] **File**: `backend/src/models/task.rs`
|
|
- Create TaskModel struct with SQLx derives
|
|
- Add TaskStatus enum (Todo, Done, Backlog)
|
|
- Implement proper serialization/deserialization
|
|
- Add CRUD methods using Active Record pattern
|
|
- **Expected outcome**: Models compile without errors
|
|
|
|
### Task 2.2: Database Connection Pool
|
|
- [x] **File**: `backend/src/database/connection.rs`
|
|
- Set up SQLx connection pool configuration
|
|
- Add connection health checks
|
|
- Create database initialization functions
|
|
- Handle connection errors gracefully
|
|
- **Expected outcome**: Connection pool starts successfully
|
|
|
|
### Task 2.3: Task Repository Layer
|
|
- [x] **File**: `backend/src/models/task.rs` (Active Record Pattern)
|
|
- Implement CRUD operations directly on TaskModel
|
|
- Add SQLx queries for all operations (insert, get_by_id, update, delete, list_all)
|
|
- Include proper error handling
|
|
- Add comprehensive unit tests
|
|
- **Expected outcome**: All CRUD operations work against database
|
|
|
|
### Task 2.4: Unit Tests for Database Layer
|
|
- [x] **File**: `backend/src/models/task.rs` (integrated tests)
|
|
- Test all CRUD operations
|
|
- Test error conditions (not found, constraint violations)
|
|
- Use in-memory SQLite for fast tests
|
|
- Create test fixtures and utilities
|
|
- **Expected outcome**: `cargo test` passes with comprehensive model testing
|
|
|
|
### Task 2.5: Test Database Utilities
|
|
- [x] **File**: `backend/src/database/connection.rs` (create_test_pool function)
|
|
- Create test database setup/teardown functions
|
|
- Add test data seeding utilities
|
|
- Implement database reset between tests
|
|
- Create assertion helpers for database state
|
|
- **Expected outcome**: Test utilities work reliably across test runs
|
|
|
|
## Phase 3: Business Logic & Services (Day 5)
|
|
|
|
### Task 3.1: Task Service Implementation
|
|
- [x] **File**: `backend/src/services/tasks.rs` (HTTP handlers with business logic)
|
|
- Implement HTTP handlers with integrated business logic
|
|
- Add input validation and sanitization
|
|
- Handle business rules (e.g., completed_at when status changes)
|
|
- Include proper error types and handling
|
|
- **Expected outcome**: HTTP layer handles all business logic correctly
|
|
|
|
### Task 3.2: Input Validation
|
|
- [x] **Files**: `backend/src/services/tasks.rs`, `backend/src/models/task.rs`
|
|
- Add comprehensive input validation in handlers and model methods
|
|
- Validate required fields, field lengths
|
|
- Create custom error types for validation failures
|
|
- Add validation for business rules
|
|
- **Expected outcome**: Invalid inputs are rejected with clear error messages
|
|
|
|
### Task 3.3: Service Unit Tests
|
|
- [x] **File**: `backend/src/models/task.rs` (comprehensive unit tests)
|
|
- Test all model methods with valid/invalid inputs
|
|
- Test business rule enforcement
|
|
- Use in-memory database for testing
|
|
- Test error handling scenarios
|
|
- **Expected outcome**: Model tests provide comprehensive coverage
|
|
|
|
## Phase 4: HTTP Layer (Days 6-7)
|
|
|
|
### Task 4.1: Axum Server Setup
|
|
- [x] **File**: `backend/src/main.rs`
|
|
- Configure Axum application with middleware
|
|
- Set up logging with tracing
|
|
- Configure graceful shutdown
|
|
- Add application state management
|
|
- **Expected outcome**: Server starts and responds to basic requests
|
|
|
|
### Task 4.2: Health Check Endpoint
|
|
- [x] **File**: `backend/src/main.rs` (health function)
|
|
- Implement GET /health endpoint
|
|
- Return basic health status
|
|
- Return proper HTTP status codes
|
|
- **Expected outcome**: Health endpoint returns 200 OK when system is healthy
|
|
|
|
### Task 4.3: Task HTTP Handlers
|
|
- [x] **File**: `backend/src/services/tasks.rs`
|
|
- Implement all task CRUD endpoints:
|
|
- `POST /api/tasks` - Create task
|
|
- `GET /api/tasks` - List tasks
|
|
- `GET /api/tasks/{id}` - Get single task
|
|
- `PUT /api/tasks/{id}` - Update task
|
|
- `DELETE /api/tasks/{id}` - Delete task
|
|
- **Expected outcome**: All endpoints handle requests and return proper responses
|
|
|
|
### Task 4.4: Error Handling and Middleware
|
|
- [x] **Files**: `backend/src/services/mod.rs`
|
|
- Implement global error handler (AppError)
|
|
- Add proper HTTP error responses
|
|
- Create error conversion traits
|
|
- Handle validation and database errors
|
|
- **Expected outcome**: Errors are handled gracefully with proper HTTP status codes
|
|
|
|
### Task 4.5: Integration Tests for HTTP Layer
|
|
- [x] **File**: `backend/tests/api/*.hurl`
|
|
- Test all endpoints with real HTTP requests using Hurl
|
|
- Use running server for integration tests
|
|
- Test success and error scenarios
|
|
- Comprehensive API contract validation
|
|
- **Expected outcome**: All integration tests pass
|
|
|
|
## Phase 5: Testing Infrastructure (Day 8)
|
|
|
|
### Task 5.1: Hurl API Tests
|
|
- [x] **Files**: `backend/tests/api/*.hurl`
|
|
- Create comprehensive API tests using Hurl
|
|
- Test all endpoints with various inputs
|
|
- Include negative test cases
|
|
- Test API response formats and status codes
|
|
- **Expected outcome**: `just test-integration` passes all tests
|
|
|
|
### Task 5.2: Test Server Orchestration
|
|
- [x] **Files**: Update `justfile`
|
|
- Add commands to start/stop test server
|
|
- Implement server startup detection
|
|
- Add test runner that manages server lifecycle
|
|
- Create test environment isolation
|
|
- **Expected outcome**: Tests can run against live server reliably
|
|
|
|
### Task 5.3: Coverage Reporting
|
|
- [x] **Files**: Update `justfile`, `backend/Cargo.toml`
|
|
- Configure tarpaulin for coverage reporting
|
|
- Set up HTML coverage reports
|
|
- Add coverage command to justfile
|
|
- Current coverage: 32.41% (35/108 lines)
|
|
- **Expected outcome**: `just test-coverage` generates comprehensive coverage report
|
|
|
|
### Task 5.4: Test Documentation
|
|
- [x] **File**: Available in `CLAUDE.md` and this plan
|
|
- Document how to run different test types
|
|
- Explain test database setup and management
|
|
- Document Hurl test structure and conventions
|
|
- Add troubleshooting guide for common test issues
|
|
- **Expected outcome**: New developers can run all tests successfully
|
|
|
|
## Dependencies and Key Technologies
|
|
|
|
### Core Dependencies (Cargo.toml)
|
|
```toml
|
|
[dependencies]
|
|
axum = "0.7"
|
|
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "sqlite", "uuid", "chrono"] }
|
|
tokio = { version = "1.0", features = ["full"] }
|
|
serde = { version = "1.0", features = ["derive"] }
|
|
uuid = { version = "1.0", features = ["v4", "serde"] }
|
|
chrono = { version = "0.4", features = ["serde"] }
|
|
anyhow = "1.0"
|
|
tower = "0.4"
|
|
tower-http = { version = "0.5", features = ["cors", "trace"] }
|
|
tracing = "0.1"
|
|
tracing-subscriber = "0.3"
|
|
|
|
[dev-dependencies]
|
|
tarpaulin = "0.27"
|
|
```
|
|
|
|
### Testing Tools
|
|
- **Unit Tests**: Standard Rust `cargo test`
|
|
- **Integration Tests**: Axum test utilities
|
|
- **API Tests**: Hurl for external API testing
|
|
- **Coverage**: Tarpaulin for code coverage reporting
|
|
- **Database**: In-memory SQLite for fast unit tests, file-based SQLite for integration tests
|
|
|
|
## Success Criteria
|
|
- [ ] All CRUD operations work correctly
|
|
- [ ] >80% backend code coverage achieved
|
|
- [ ] Integration tests cover all API endpoints
|
|
- [ ] Hurl tests validate API contracts
|
|
- [ ] Database migrations work correctly
|
|
- [ ] Error handling is comprehensive
|
|
- [ ] Performance is acceptable for MVP usage
|
|
- [ ] Documentation is complete and accurate
|
|
|
|
## Testing Strategy Summary
|
|
1. **Unit Tests**: Fast, isolated tests using in-memory database
|
|
2. **Integration Tests**: Full request-response cycle with test database
|
|
3. **Hurl Tests**: External API validation against running server
|
|
4. **Coverage**: Automated coverage reporting with tarpaulin
|
|
5. **CI Ready**: All tests can run in automated environment
|
|
|
|
This plan provides a comprehensive roadmap for implementing a robust, well-tested backend MVP that meets the requirements outlined in the original plan.md.
|