What a mess
This commit is contained in:
Joan
167
docs/API_REFACTOR_V2.md
Normal file
167
docs/API_REFACTOR_V2.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# API Refactor v2.0 - Complete Redesign
|
||||
|
||||
## Overview
|
||||
|
||||
The API has been completely refactored to be **standalone and independent**. It no longer depends on bot modules and contains all necessary code within the `api/` directory.
|
||||
|
||||
## Changes
|
||||
|
||||
### ✅ Completed
|
||||
|
||||
1. **Cleaned root directory**:
|
||||
- Moved all `.md` documentation files to `docs/archive/`
|
||||
- Moved migration scripts to `scripts/`
|
||||
- Root is now clean with only essential config files
|
||||
|
||||
2. **Created standalone API modules**:
|
||||
- `api/database.py` - Complete database operations (no bot dependency)
|
||||
- `api/world_loader.py` - Game world loader with data models
|
||||
- `api/items.py` - Items manager
|
||||
- `api/game_logic.py` - All game mechanics
|
||||
- `api/main_new.py` - New standalone FastAPI application
|
||||
|
||||
3. **New database schema**:
|
||||
- `players.id` is now the primary key (auto-increment)
|
||||
- `telegram_id` is optional (nullable) for Telegram users
|
||||
- `username`/`password_hash` for web users
|
||||
- All foreign keys now reference `players.id` instead of `telegram_id`
|
||||
|
||||
4. **Simplified deployment**:
|
||||
- Removed unnecessary nginx complexity
|
||||
- Traefik handles all routing
|
||||
- PWA serves static files via nginx (efficient for static content)
|
||||
- API is completely standalone
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Option 1: Fresh Start (Recommended)
|
||||
|
||||
**Pros**: Clean database, no migration issues
|
||||
**Cons**: Loses existing Telegram user data
|
||||
|
||||
```bash
|
||||
# 1. Stop all containers
|
||||
docker compose down
|
||||
|
||||
# 2. Remove old database
|
||||
docker volume rm echoes-of-the-ashes-postgres-data
|
||||
|
||||
# 3. Update files
|
||||
mv api/main_new.py api/main.py
|
||||
mv api/requirements_new.txt api/requirements.txt
|
||||
mv Dockerfile.api.new Dockerfile.api
|
||||
|
||||
# 4. Rebuild and start
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### Option 2: Migrate Existing Data
|
||||
|
||||
**Pros**: Keeps Telegram user data
|
||||
**Cons**: Requires running migration script
|
||||
|
||||
```bash
|
||||
# 1. Create migration script to:
|
||||
# - Add `id` column as primary key
|
||||
# - Make `telegram_id` nullable
|
||||
# - Update all foreign keys
|
||||
# - Backfill `id` values
|
||||
|
||||
# 2. Run migration
|
||||
docker exec -it echoes_of_the_ashes_api python scripts/migrate_to_v2.py
|
||||
|
||||
# 3. Update files and rebuild
|
||||
# (same as Option 1 steps 3-4)
|
||||
```
|
||||
|
||||
## New API Structure
|
||||
|
||||
```
|
||||
api/
|
||||
├── main_new.py # Standalone FastAPI app
|
||||
├── database.py # All database operations
|
||||
├── world_loader.py # World data loading
|
||||
├── items.py # Items management
|
||||
├── game_logic.py # Game mechanics
|
||||
├── internal.py # (deprecated - logic moved to main)
|
||||
└── requirements_new.txt # Minimal dependencies
|
||||
```
|
||||
|
||||
## Bot Integration
|
||||
|
||||
The bot will now call the API for all operations instead of directly accessing the database.
|
||||
|
||||
### Bot Changes Needed:
|
||||
|
||||
1. **Replace direct database calls** with API calls using `httpx`:
|
||||
```python
|
||||
# Old:
|
||||
player = await get_player(telegram_id)
|
||||
|
||||
# New:
|
||||
response = await http_client.get(
|
||||
f"{API_URL}/api/internal/player/{telegram_id}",
|
||||
headers={"Authorization": f"Bearer {INTERNAL_KEY}"}
|
||||
)
|
||||
player = response.json()
|
||||
```
|
||||
|
||||
2. **Use internal endpoints** (protected by API key):
|
||||
- `GET /api/internal/player/{telegram_id}` - Get player
|
||||
- `POST /api/internal/player` - Create player
|
||||
- All other game operations use public endpoints with JWT
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```env
|
||||
# Database
|
||||
POSTGRES_USER=your_user
|
||||
POSTGRES_PASSWORD=your_password
|
||||
POSTGRES_DB=echoes_db
|
||||
POSTGRES_HOST=echoes_of_the_ashes_db
|
||||
POSTGRES_PORT=5432
|
||||
|
||||
# API
|
||||
JWT_SECRET_KEY=your-jwt-secret-key
|
||||
API_INTERNAL_KEY=your-internal-api-key
|
||||
|
||||
# Bot (if using)
|
||||
TELEGRAM_BOT_TOKEN=your-bot-token
|
||||
```
|
||||
|
||||
## Testing the New API
|
||||
|
||||
1. **Health check**:
|
||||
```bash
|
||||
curl https://your-domain.com/health
|
||||
```
|
||||
|
||||
2. **Register web user**:
|
||||
```bash
|
||||
curl -X POST https://your-domain.com/api/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"testuser","password":"testpass"}'
|
||||
```
|
||||
|
||||
3. **Get location**:
|
||||
```bash
|
||||
curl https://your-domain.com/api/game/location \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Standalone** - API has zero bot dependencies
|
||||
2. **Clean** - All logic in one place
|
||||
3. **Testable** - Easy to test without bot infrastructure
|
||||
4. **Maintainable** - Clear separation of concerns
|
||||
5. **Scalable** - API and bot can scale independently
|
||||
6. **Flexible** - Easy to add new clients (mobile app, etc.)
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Choose migration path (fresh start vs migrate)
|
||||
2. Update and rebuild containers
|
||||
3. Test web interface
|
||||
4. Refactor bot to use API endpoints
|
||||
5. Remove old `api/main.py` and `api/internal.py`
|
||||
Reference in New Issue
Block a user