Manuale Sviluppatori
Guida completa per sviluppatori e ingegneri DevOps che vogliono installare, distribuire e gestire Jinbocho.
Sezioni
| # |
Sezione |
Contenuto |
| 1 |
Prerequisiti |
Docker, Python 3.12, Node.js 18, chiavi API |
| 2 |
Sviluppo locale |
Docker Compose, porte, variabili d’ambiente, verifica |
| 3 |
Servizi backend |
auth, catalog, gateway, ai — endpoint, env var, test |
| 4 |
Frontend |
Setup React, pattern TanStack Query, gotcha critici |
| 5 |
Database e migrazioni |
Alembic, schema PostgreSQL, reset locale |
| 6 |
CI/CD |
Workflow GitHub Actions pianificati per tutti i servizi |
| 7 |
Deploy in produzione |
Guida passo per passo su Render + Neon |
| 8 |
Monitoring e logging |
Log Render, health check, console Neon |
| 9 |
Troubleshooting |
Problemi comuni e soluzioni |
| 10 |
Architettura |
Diagramma di sistema, bounded context, flusso dati, sicurezza |
Percorsi rapidi
Voglio eseguire Jinbocho in locale
- Prerequisiti — installa Docker, Python, Node.js
- Sviluppo locale —
docker compose up --build -d e sei pronto
Voglio fare il deploy in produzione
- Prerequisiti — crea account Neon e Render
- Sviluppo locale — verifica che funzioni in locale prima
- Deploy in produzione — guida passo per passo su Render + Neon
Devo capire il codice
- Architettura — diagramma di sistema, bounded context, scelte progettuali
- Servizi backend — analisi servizio per servizio
- Frontend — architettura React e gotcha critici
Qualcosa non funziona
- Troubleshooting — raggruppato per area (database, CORS, JWT, cold start)
- Monitoring e logging — come leggere i log di Render
Stack tecnologico
| Livello |
Tecnologia |
| Backend |
Python 3.12, FastAPI, SQLAlchemy (async) |
| Database |
PostgreSQL 16 (Neon in produzione) |
| Migrazioni |
Alembic |
| Frontend |
React 18, TypeScript strict, Vite, TanStack Query, Zustand |
| HTTP client |
ky |
| Deploy |
Docker Compose (dev), Render + Neon (prod) |
| CI/CD |
GitHub Actions (pianificato) |
| Qualità del codice |
mypy (strict), ruff, pytest, vitest |
Prima di ogni commit
# Backend (esegui nella directory di ogni servizio modificato)
ruff check app tests
python -m mypy app --strict
pytest tests/ -v
# Frontend
cd jinbocho-fe
npm run typecheck && npm run test