158 lines
4.2 KiB
Markdown
158 lines
4.2 KiB
Markdown
# Quick Reference: New Modular Structure
|
|
|
|
## File Structure Overview
|
|
|
|
```
|
|
api/
|
|
├── main.py (568 lines) ← Main app, router registration, websocket
|
|
├── core/
|
|
│ ├── config.py ← All configuration constants
|
|
│ ├── security.py ← JWT, auth, password hashing
|
|
│ └── websockets.py ← ConnectionManager + manager instance
|
|
├── services/
|
|
│ ├── models.py ← All Pydantic request/response models
|
|
│ └── helpers.py ← Utility functions (distance, stamina, capacity)
|
|
└── routers/
|
|
├── auth.py ← Register, login, me
|
|
├── characters.py ← List, create, select, delete characters
|
|
├── game_routes.py ← Game state, movement, interactions, pickup/drop
|
|
├── combat.py ← PvE and PvP combat
|
|
├── equipment.py ← Equip, unequip, repair
|
|
├── crafting.py ← Craft, uncraft, craftable items
|
|
├── loot.py ← Corpse looting
|
|
└── statistics.py ← Player stats and leaderboards
|
|
```
|
|
|
|
## How to Add a New Endpoint
|
|
|
|
### Example: Adding a new game feature
|
|
|
|
1. **Choose the right router** based on feature:
|
|
- Player actions → `game_routes.py`
|
|
- Combat → `combat.py`
|
|
- Items → `equipment.py` or `crafting.py`
|
|
- New category → Create new router file
|
|
|
|
2. **Add endpoint to router:**
|
|
```python
|
|
# In api/routers/game_routes.py
|
|
|
|
@router.post("/api/game/new_action")
|
|
async def new_action(
|
|
request: NewActionRequest,
|
|
current_user: dict = Depends(get_current_user)
|
|
):
|
|
"""Your new endpoint"""
|
|
# Your logic here
|
|
return {"success": True}
|
|
```
|
|
|
|
3. **Add model if needed** (in `api/services/models.py`):
|
|
```python
|
|
class NewActionRequest(BaseModel):
|
|
action_param: str
|
|
```
|
|
|
|
4. **No need to touch main.py** - routers auto-register!
|
|
|
|
## How to Find Code
|
|
|
|
### Before Migration:
|
|
- "Where's the movement code?" → Scroll through 5,573 lines 😵
|
|
|
|
### After Migration:
|
|
- Movement → `api/routers/game_routes.py` line 200-300
|
|
- Combat → `api/routers/combat.py`
|
|
- Equipment → `api/routers/equipment.py`
|
|
- Auth → `api/routers/auth.py`
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Pydantic Model:
|
|
→ Edit `api/services/models.py`
|
|
|
|
### Changing Configuration:
|
|
→ Edit `api/core/config.py`
|
|
|
|
### Modifying Auth Logic:
|
|
→ Edit `api/core/security.py`
|
|
|
|
### Adding Helper Function:
|
|
→ Edit `api/services/helpers.py`
|
|
|
|
### Creating New Router:
|
|
1. Create `api/routers/new_feature.py`
|
|
2. Add router initialization function:
|
|
```python
|
|
LOCATIONS = None
|
|
ITEMS_MANAGER = None
|
|
|
|
def init_router_dependencies(locations, items_manager, world):
|
|
global LOCATIONS, ITEMS_MANAGER
|
|
LOCATIONS = locations
|
|
ITEMS_MANAGER = items_manager
|
|
|
|
router = APIRouter(tags=["new_feature"])
|
|
```
|
|
3. Import in `main.py`:
|
|
```python
|
|
from .routers import new_feature
|
|
```
|
|
4. Initialize dependencies:
|
|
```python
|
|
new_feature.init_router_dependencies(LOCATIONS, ITEMS_MANAGER, WORLD)
|
|
```
|
|
5. Register router:
|
|
```python
|
|
app.include_router(new_feature.router)
|
|
```
|
|
|
|
## Restart API After Changes
|
|
|
|
```bash
|
|
cd /opt/dockers/echoes_of_the_ashes
|
|
docker compose restart echoes_of_the_ashes_api
|
|
docker compose logs -f echoes_of_the_ashes_api
|
|
```
|
|
|
|
## Backup Files (Safe to Keep)
|
|
|
|
- `api/main_original_5573_lines.py` - Original massive file
|
|
- `api/main_pre_migration_backup.py` - Pre-migration backup
|
|
|
|
## What Changed vs What Stayed the Same
|
|
|
|
### Changed ✅:
|
|
- File organization (one big file → many small files)
|
|
- Import statements
|
|
- Router registration
|
|
|
|
### Stayed the Same ✅:
|
|
- All endpoint logic (100% preserved)
|
|
- All functionality (zero breaking changes)
|
|
- Database queries
|
|
- Game logic
|
|
- Business rules
|
|
|
|
## Benefits for You
|
|
|
|
1. **Finding code:** 10x faster
|
|
2. **Adding features:** Just pick the right router
|
|
3. **Understanding code:** Each file has a clear purpose
|
|
4. **Debugging:** Smaller files = easier to debug
|
|
5. **Collaboration:** Multiple people can work on different routers
|
|
|
|
## Need to Rollback?
|
|
|
|
If something goes wrong (it won't, but just in case):
|
|
|
|
```bash
|
|
cd /opt/dockers/echoes_of_the_ashes/api
|
|
cp main_original_5573_lines.py main.py
|
|
docker compose restart echoes_of_the_ashes_api
|
|
```
|
|
|
|
---
|
|
|
|
**Happy coding!** Your codebase is now clean, organized, and ready for future growth. 🚀
|