Introduzione al nostro motore di oroscopi¶

Il nostro motore di oroscopi è un runtime astrologico deterministico progettato per prodotti reali, non solo per la generazione di testo sperimentale. Combina il calcolo di Swiss Ephemeris, l'attivazione rigorosa dei fattori e la rendering editoriale, in modo che la tua app riceva output di report stabili, spiegabili e di alta qualità.

Su Cosa Stai Costruendo¶

Al runtime, il motore calcola lo stato celeste reale e assembla significati dai fattori astrologici attivati. Per payload identici, gli output rimangono byte per byte stabili. Quando vengono forniti input di personalizzazione, i vettori a livello di casa e contesto di nascita si attivano per produrre differenze specifiche per l'utente.

Questo offre al tuo team:

• Risultati prevedibili per test, QA e caching: le richieste identiche restituiscono sempre lo stesso JSON.
• Composizione del report spiegabile tramite tracciamenti factor_details in ogni sezione.
• Un percorso pulito dai semplici rapporti di firma ai rapporti personalizzati premium.
• Profondità consapevole del periodo: stack giornalieri (5-6 fattori), settimanali (10), mensili (11) e annuali (13) con pesi espliciti.

Panoramica dell'Architettura¶

Architettura del Motore Completo¶

Architettura Richiesta-Risposta¶

Pipeline Deterministico¶

1. Gateway verifica l'autenticazione, i limiti e le politiche di richiesta.
2. Validazione del contratto di richiesta applica lo schema e le opzioni accettate.
3. Motore risolve la fonte del segno, la finestra temporale e la configurazione dell'ephemeride.
4. Swiss Ephemeris calcola posizioni, aspetti e case (quando è disponibile).
5. Livello di aggregazione campiona il periodo, estrae eventi (aspetti, ingressi, stazioni, lunazioni, eclissi) e classifica i driver.
6. Motore di interpretazione mappa le specifiche dei fattori al contenuto editoriale utilizzando un ordine fisso, pesi espliciti e la selezione stabile della variante hash.
7. Motore editoriale genera narrazioni di sezione dal contenuto V2 con composizione dell'arco specifica per il periodo (apertura → spostamento → risultato).
8. Gateway restituisce il payload del motore più wrapper aziendali (_enterprise, _api_metadata_) per i metadati di integrazione.

Garanzie di Determinismo¶

Il determinismo non è un caso — viene applicato a ogni livello:

Questo significa che è possibile creare un hash per due richieste indipendenti con lo stesso corpo e ottenere lo stesso risultato, consentendo una memorizzazione efficace, test di regressione QA e debug riproducibile.

Report Pubblici vs Personalizzati¶

Entrambi sono modalità valide per la produzione. La differenza non riguarda la qualità; riguarda la profondità di attivazione.

Modalità Pubblica (Basata sul segno zodiacale)¶

Fornire solo il segno zodiacale e la data. Il motore produce una lettura stabile e condivisa per tutti gli utenti con quel segno in quel periodo.

• Ottimo per feed di pubblico ampio ed efficiente dal punto di vista dei costi (12 segni × 4 periodi × 365 giorni = circa 17.520 cache uniche giornaliere)
• Nessun calcolo delle case — l'assegnazione di rising_sign, house_cusps e del corpo house è gestita da null
• Ideale per un rapido lancio, oroscopi di stile rivista e livelli freemium

Modalità Personalizzata (Basata sulla Data di Nascita)¶

Fornire il contesto di nascita (birth_time, coordinate, fuso orario) per attivare vettori più approfonditi. Due utenti con lo stesso segno zodiacale possono ricevere editoriali diversi a causa della posizione delle case e del segno solare, che modificano i punteggi dei fattori.

• Campi obbligatori: birth_time (HH:MM) + birth_latitude + birth_longitude
• Sblocca: segno solare, cuspidi delle 12 case, assegnazioni pianeti-case e fattori di focus per le case (daily_house_focus, weekly_house_focus, monthly_house_focus, yearly_house_focus)
• Ideale per abbonamenti premium e esperienze di fidelizzazione elevate
• Supporta moduli dell'app più ricchi e funnel di personalizzazione

Modello Editoriale Basato sui Fattori¶

Il motore è alimentato da stack di fattori espliciti — driver di interpretazione deterministici calcolati da istantanee celesti e aggregazione periodica. Ogni periodo ha un ordine di fattori definito e pesi espliciti.

Stack di Fattori per Periodo¶

Strati aggiuntivi di fattori dedicati: - Pianeta: planet_core_archetypes, planet_condition_archetypes, planet_house_focus, planet_sign_archetypes - Data di Nascita: solar_return_tone, birthday_year_reset, natal_sun_house_year_theme - Aspetto: Strati basati sull'aspetto con aspetto dominante calcolato o sovrascritto - Transito: Strati basati sul transito con archetipo di transito dominante calcolato o sovrascritto

Ogni fattore ha un peso esplicito (ad esempio, moon_in_sign: 1.15 giornaliero, yearly_theme_archetypes: 1.30 annuale) che influenza il punteggio della sezione e la derivazione dell'intensità.

Questo modello evita derive casuali nel testo e mantiene il tono editoriale legato ai driver calcolati con piena tracciabilità in factor_details.

Statistiche App Personalizzate Giornaliere (Horoscopo Principale)¶

Per la modalità giornaliera personalizzata, il motore restituisce blocchi di statistiche app-ready a data.daily_personalized_stats. Questi sono ideali per schede e widget di riepilogo.

Trigger di attivazione: period=daily e la richiesta di nascita personalizzata include sia birth_time che coordinates.

Blocchi chiave:

• overall_pulse — punteggio composito della vitalità giornaliera
• archetype_scores — scomposizione a otto dimensioni (wisdom, creativity, confidence, intuition, allure, romance, career, emotions)
• harmony_discord — i 4 segni più armoniosi e i 4 segni più discordanti
• elemental_balance — distribuzione fuoco/terra/aria/acqua
• momentum_channels — segnali di momentum planetario

Controllo della densità del payload:

• daily_stats_detail: "full" per dati completi del grafico con livelli di confidenza per blocco
• daily_stats_detail: "compact" per payload client più leggeri (ideale per widget mobili)

Punti salienti nella progettazione della richiesta¶

Il motore supporta controlli chiari e tipizzati per la configurazione astrologica e il comportamento di rendering. Le opzioni comuni includono:

Garanzie sulla forma della risposta nel Gateway¶

Le risposte del gateway passano i dati del motore e aggiungono wrapper:

• _enterprise — informazioni sul livello, la quota e il limite di velocità
• _api_metadata_ — informazioni sull'endpoint, le lingue supportate e il contesto della richiesta

Per gli endpoint del motore per i report, _api_metadata_.supported_languages è solo in inglese:

{
  "_api_metadata_": {
    "supported_languages": ["en"]
  }
}

Politica linguistica e di traduzione¶

Funzioni di endpoint per report basate su motore supportano attualmente solo lang=en. Questo è intenzionale per preservare la sfumatura editoriale deterministica in produzione, mentre l'affidabilità della traduzione viene curata separatamente. Lo strato di assistenza di traduzione del gateway (lang=en|es|de|fr|pt) fornisce output tradotti al limite dell'API per tutti gli endpoint di report non relativi all'oroscopo.

Pipeline dei contenuti: Pacchetti di contenuti V2¶

I contenuti editoriali provengono dai pacchetti di contenuti strutturati V2 nel repository dei contenuti del motore.

Durante l'esecuzione, il repository dei contenuti seleziona le varianti in modo deterministico tramite selezione stabile dell'hash con una catena di fallback a quattro livelli:

1. Corrispondenza esatta (tipo_fattore + valore_fattore + intensità)
2. Qualsiasi valore per tipo_fattore (tipo_fattore + intensità)
3. Qualsiasi fattore nella sezione (sezione + intensità)
4. Modello di fallback della sezione

Questa struttura garantisce la varietà editoriale in base all'intensità, preservando al contempo la riproducibilità per lo stesso seed.

Modello di fiducia: Core chiuso + Open Source Lite¶

Il nostro motore principale in produzione è a codice sorgente e ottimizzato per l'affidabilità, la profondità e le operazioni gestite dell'azienda. Include:

• Reportistica personalizzata completa (tutti i periodi)
• Rapporti sul ciclo di nascita con fattori di ritorno solare
• Suite di rapporti su pianeti, aspetti, transiti, case e relazioni tra pianeti e case
• Tema natale con rendering SVG configurabile
• Caching Redis, metriche, controlli di salute e scalabilità orizzontale

Per supportare gli astrologi indipendenti e la valutazione da parte degli sviluppatori, forniamo anche il motore open-source lite:

• Sito OpAstro
• GitHub OpAstro
• PyPI OpAstro

Utilizza OpAstro per valutare la qualità del motore, esplorare la logica di calcolo dei fattori e verificare l'integrazione con Swiss Ephemeris. Scala verso le rotte enterprise di NumerologyAPI per livelli di report più ricchi, copertura più ampia degli endpoint e operazioni di produzione gestite.

Percorso di Integrazione¶

1. Iniziare con report di livello pubblico — giornaliero/settimanale/mensile/annuale utilizzando solo sign. Non sono richiesti dati di nascita. Ottimizzare la cache.
2. Aggiungere campi di nascita personalizzati — fornire birth_time + coordinate per sbloccare editoriali differenziati con fattori consapevoli della casa.
3. Strato di famiglie di report specializzate — punti finali planetari, aspetti, transiti e case per superfici di prodotto più approfondite.
4. Aggiungere punti finali di nascita — JSON completo del grafico natale + ruota SVG per la visualizzazione e flussi di lavoro astrologici avanzati.
5. Ottimizzare con sezioni — richiedere solo sections di cui ha bisogno l'interfaccia utente (ad esempio, ["general", "career"]) per ridurre la dimensione del payload.
6. Utilizzare tenant_id per l'isolamento della cache — livelli o varianti A/B gratuiti/premium separati senza inquinamento della cache.

Strategia di caching¶

Ulteriori letture¶

• Panoramica dell'API dei Report di Oroscopi
• Oroscopo di Oggi
• Oroscopo Settimanale
• Oroscopo Mensile
• Oroscopo Annuale
• Oroscopo di Compleanno
• Carta Natale