6dac34e373
Major changes: - Migrate all handlers from Gin to Echo framework - Add new apperrors, echohelpers, and validator packages - Update middleware for Echo compatibility - Add ArchivedHandler to task categorization chain (archived tasks go to cancelled_tasks column) - Add 6 new integration tests: - RecurringTaskLifecycle: NextDueDate advancement for weekly/monthly tasks - MultiUserSharing: Complex sharing with user removal - TaskStateTransitions: All state transitions and kanban column changes - DateBoundaryEdgeCases: Threshold boundary testing - CascadeOperations: Residence deletion cascade effects - MultiUserOperations: Shared residence collaboration - Add single-purpose repository functions for kanban columns (GetOverdueTasks, GetDueSoonTasks, etc.) - Fix RemoveUser route param mismatch (userId -> user_id) - Fix determineExpectedColumn helper to correctly prioritize in_progress over overdue 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
191 lines
4.7 KiB
Markdown
191 lines
4.7 KiB
Markdown
# Casera API (Go)
|
|
|
|
Go implementation of the Casera property management API, built with Echo, GORM, and GoAdmin.
|
|
|
|
## Tech Stack
|
|
|
|
- **HTTP Framework**: [Echo v4](https://github.com/labstack/echo)
|
|
- **ORM**: [GORM](https://gorm.io/) with PostgreSQL
|
|
- **Push Notifications**: Direct APNs (via [apns2](https://github.com/sideshow/apns2)) + FCM HTTP API
|
|
- **Admin Panel**: [GoAdmin](https://github.com/GoAdminGroup/go-admin)
|
|
- **Background Jobs**: [Asynq](https://github.com/hibiken/asynq)
|
|
- **Caching**: Redis
|
|
- **Logging**: [zerolog](https://github.com/rs/zerolog)
|
|
- **Configuration**: [Viper](https://github.com/spf13/viper)
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.21+
|
|
- PostgreSQL 15+
|
|
- Redis 7+
|
|
|
|
### Development Setup
|
|
|
|
```bash
|
|
# Install dependencies
|
|
make deps
|
|
|
|
# Copy environment file
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
|
|
# Run the API server
|
|
make run
|
|
```
|
|
|
|
### Docker Setup
|
|
|
|
```bash
|
|
# Start all services
|
|
make docker-up
|
|
|
|
# View logs
|
|
make docker-logs
|
|
|
|
# Stop services
|
|
make docker-down
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
myCribAPI-go/
|
|
├── cmd/
|
|
│ ├── api/main.go # API server entry point
|
|
│ ├── worker/main.go # Background worker entry point
|
|
│ └── admin/main.go # GoAdmin server entry point
|
|
├── internal/
|
|
│ ├── config/ # Configuration management
|
|
│ ├── models/ # GORM models
|
|
│ ├── database/ # Database connection
|
|
│ ├── repositories/ # Data access layer
|
|
│ ├── services/ # Business logic
|
|
│ ├── handlers/ # HTTP handlers
|
|
│ ├── middleware/ # Gin middleware
|
|
│ ├── dto/ # Request/Response DTOs
|
|
│ ├── router/ # Route setup
|
|
│ ├── push/ # APNs/FCM push notifications
|
|
│ ├── worker/ # Asynq jobs
|
|
│ └── admin/ # GoAdmin tables
|
|
├── pkg/
|
|
│ ├── utils/ # Utilities
|
|
│ └── errors/ # Error types
|
|
├── migrations/ # SQL migrations
|
|
├── templates/emails/ # Email templates
|
|
├── docker/ # Docker files
|
|
├── go.mod
|
|
└── Makefile
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
The API maintains 100% compatibility with the Django version.
|
|
|
|
### Public Endpoints (No Auth)
|
|
|
|
- `GET /api/health/` - Health check
|
|
- `POST /api/auth/login/` - Login
|
|
- `POST /api/auth/register/` - Register
|
|
- `GET /api/static_data/` - Cached lookups
|
|
|
|
### Protected Endpoints (Token Auth)
|
|
|
|
- `GET /api/residences/` - List residences
|
|
- `GET /api/tasks/` - List tasks
|
|
- `GET /api/tasks/by-residence/:id/` - Kanban board
|
|
- See full API documentation in the Django project
|
|
|
|
## Configuration
|
|
|
|
Environment variables (see `.env.example`):
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `PORT` | Server port | 8000 |
|
|
| `DEBUG` | Debug mode | false |
|
|
| `SECRET_KEY` | JWT secret | required |
|
|
| `POSTGRES_*` | Database config | - |
|
|
| `REDIS_URL` | Redis URL | redis://localhost:6379/0 |
|
|
| `APNS_*` | iOS push config | - |
|
|
| `FCM_SERVER_KEY` | Android push key | - |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run tests
|
|
make test
|
|
|
|
# Run tests with coverage
|
|
make test-coverage
|
|
|
|
# Run linter
|
|
make lint
|
|
|
|
# Format code
|
|
make fmt
|
|
```
|
|
|
|
## Database
|
|
|
|
This Go version uses the same PostgreSQL database as the Django version. GORM models are mapped to Django's table names:
|
|
|
|
- `auth_user` - Django's User model
|
|
- `user_authtoken` - Auth tokens
|
|
- `residence_residence` - Residences
|
|
- `task_task` - Tasks
|
|
|
|
## Seeding Data
|
|
|
|
Seed files are located in `seeds/`:
|
|
- `001_lookups.sql` - Lookup tables (residence types, task categories, priorities, etc.)
|
|
- `002_test_data.sql` - Test users, residences, tasks, contractors, etc.
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Seed lookup tables
|
|
./dev.sh seed
|
|
|
|
# Seed test data
|
|
./dev.sh seed-test
|
|
```
|
|
|
|
### Production (Dokku)
|
|
|
|
```bash
|
|
# Seed lookup tables (required)
|
|
cat seeds/001_lookups.sql | dokku postgres:connect casera-db
|
|
|
|
# Seed test data
|
|
cat seeds/002_test_data.sql | dokku postgres:connect casera-db
|
|
```
|
|
|
|
### Test Users
|
|
|
|
All test users have password: `password123`
|
|
|
|
| Username | Email | Tier | Notes |
|
|
|----------|-------|------|-------|
|
|
| admin | admin@example.com | Pro | Admin user |
|
|
| john | john@example.com | Pro | Owns 2 residences |
|
|
| jane | jane@example.com | Free | Owns 1 residence, shared access to residence 1 |
|
|
| bob | bob@example.com | Free | Owns 1 residence |
|
|
|
|
### Test Data Includes
|
|
|
|
- 4 residences (house, beach house, apartment, condo)
|
|
- 4 contractors with specialties
|
|
- 10 tasks across residences
|
|
- Documents/warranties
|
|
- Notifications
|
|
|
|
## Migration from Django
|
|
|
|
This is a full rewrite that maintains API compatibility. The mobile clients (KMM) work with both versions without changes.
|
|
|
|
## License
|
|
|
|
Proprietary - Casera
|