Files
Anubis/docs/SVILUPPO.md
T
Alby96andClaude Opus 5.5 32b95b8d68 docs: add Anubis specification, design screens and development plan
Load the full project specification renamed from the provisional "Giano"
to "Anubis" (ADR 0001), the nine reference screens with the new name,
the Unraid template draft pointing at the Gitea container registry, and
the working documents the development phases rely on: CLAUDE.md,
ROADMAP (linked to the 84 Gitea issues and 12 milestones), STATE,
development rules (SVILUPPO), ADR 0002 on Gitea issues, packages and
installer, and Gitea issue/PR templates. No application code yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 12:02:52 +01:00

6.1 KiB

Come si sviluppa Anubis

Regole di lavoro per chi scrive il codice, persona o agente. Riassumono le sezioni 2, 3, 16 e 19 della specifica e aggiungono il flusso su Gitea. Se qualcosa qui contraddice docs/SPEC.md, vale la specifica; se una decisione cambia, si scrive un ADR.

Dove sta cosa

Cosa Dove
Specifica completa, fonte di verità docs/SPEC.md (non si modifica)
Schermate di riferimento docs/design/01…09-*.jpg (tabella in SPEC 13.1)
Piano e criteri di accettazione docs/ROADMAP.md e le issue su Gitea, una milestone per fase
Stato della sessione docs/STATE.md
Decisioni docs/adr/NNNN-titolo.md (formato in SPEC appendice B)
Fatti verificati sulle API docs/API-NOTES.md (nasce nella Fase 0)
Template Unraid deploy/unraid/anubis.xml
Lavori, milestone, pacchetti, release https://gitea.encke-hake.ts.net/BalboSoft/Anubis

Il giro di una fase

  1. Leggi CLAUDE.md, docs/STATE.md, poi le sezioni della specifica che la tabella di SPEC 17 indica per la fase, più 2, 3, 16 e 19.
  2. Apri la milestone della fase su Gitea e scegli le issue in ordine di numero: sono già in ordine di dipendenza.
  3. Branch fase-N partendo da main (per esempio fase-0).
  4. Prima di scrivere codice elenca file, interfacce e test che dimostreranno che funziona; scrivilo come commento nella issue.
  5. Implementa a piccoli passi, con i test accanto al codice. Spunta i passi della issue man mano che sono veri.
  6. Commit piccoli, in inglese, stile Conventional Commits, con il riferimento alla issue: feat(oms): deterministic client order id (refs #27).
  7. Chiudi la issue quando tutti i suoi passi sono fatti e provati: commento con la prova (comando e risultato), poi chiusura.
  8. Chiusura della fase: la issue "Chiusura della fase N" elenca tutti i criteri di accettazione. Ognuno si spunta solo con la prova mostrata. Poi revisione indipendente con un subagent a contesto pulito (messaggio dell'appendice A), correzione dei difetti reali, aggiornamento di ROADMAP.md e STATE.md, pull request fase-N → main con Closes #…, merge, tag fase-N su main, riepilogo di fine fase (appendice B) come commento alla issue di chiusura.
  9. Fermati: una fase per sessione. La successiva riparte con il messaggio di ripresa dell'appendice A.

Il lavoro non resta mai solo sul disco: ogni sessione si chiude con un commit. Il push su Gitea si fa quando l'utente lo chiede o lo ha già indicato per questo repository.

Criteri "in attesa dell'utente"

Un criterio che dipende solo da qualcosa che deve dare l'utente (chiavi dei conti di prova, prove su Unraid) non tiene aperta la fase: si segna così in ROADMAP.md, si mette l'etichetta Status/In attesa utente sulla issue che lo contiene e si scrive in STATE.md cosa serve. Si chiude appena l'utente lo fornisce (messaggio dell'appendice A).

Regole che non si discutono

Sicurezza durante lo sviluppo (SPEC 2.2)

  • Mai ordini su conti reali: solo simulatore interno, paper di Alpaca, demo di OKX.
  • Mai chiavi con permesso di prelievo.
  • Mai ANUBIS_ALLOW_LIVE=1 né allow_live = true: i test falliscono se li trovano.
  • Nessun segreto nel repository, nei registri, nei commit, negli screenshot. Solo .env.example con valori finti.
  • Non scavalcare limiti di frequenza, condizioni d'uso o blocchi geografici.

Autonomia (SPEC 2.1)

  • Non chiedere conferme e non proporre alternative: scegli l'opzione più prudente e più semplice, scrivila in un ADR, prosegui.
  • Fermati solo per ciò che solo l'utente può dare (credenziali, secondo fattore, soldi veri), dopo aver fatto tutto il resto.
  • Un fatto su un'API non verificabile non si inventa: flag, nota "non verificato" in API-NOTES.md, avanti.

Prove (SPEC 2.3)

  • Una fase si chiude con make check passato, immagine Docker costruita e, per le schermate, screenshot Playwright confrontati con i mockup. "Dovrebbe funzionare" non è una prova.

Codice (SPEC 3, 16, 19)

  • Denaro, prezzi e quantità sempre Decimal, mai float; sul database il tipo decimale personalizzato di 5.4.
  • Tutto il tempo passa dall'orologio iniettabile; nessun test dipende dall'ora reale o dalla rete.
  • Tutto in UTC nel database; orari di borsa sempre dal calendario del broker.
  • Lo stesso schema e gli stessi test su PostgreSQL e su SQLite; niente funzioni proprie di un solo motore.
  • Nessuna strategia parla con un broker: ogni ordine passa per correttivi, rischio e OMS.
  • Calcoli pesanti nel process pool, mai nell'event loop.
  • Nessuna libreria di analisi tecnica: gli indicatori si scrivono in casa e si testano contro valori calcolati a mano.
  • Le trenta trappole di SPEC 19 si rileggono a ogni fase.

Lingua (SPEC 2.6, 13.3)

  • Codice, identificatori, commenti e commit in inglese; valori interni in inglese (observation, simulation, reduced_live, live).
  • Documenti del progetto e tutto ciò che l'utente legge in italiano semplice, senza gergo; il bot parla in prima persona.
  • Numeri all'italiana, segno meno tipografico, valuta dopo il numero, tutto da frontend/src/lib/format.ts.

Dipendenze (SPEC 2.7)

  • Ultime versioni stabili, fissate con lockfile; prima di aggiungere una libreria controlla ultimo rilascio e licenza.
  • Vietate: pandas-ta, backtrader, ib_insync, mlfinlab, timeseriescv.

Schermate

Per ogni schermata: implementa, apri con Playwright sui dati dimostrativi (make seed-demo) a 1440 e 390 pixel, fotografa, confronta zona per zona con lo screen di docs/design/, correggi, ripeti finché restano differenze trascurabili. I testi fissi si leggono dalle immagini, i dati dall'appendice F, colori e misure dall'appendice C. Guarda uno screen per volta e ritaglia la zona che ti serve: le immagini sono a doppia densità.

Pacchetti e consegne

  • Docker: immagine gitea.encke-hake.ts.net/balbosoft/anubis, pubblicata dalla CI sui tag v* nella sezione Packages del repository (ADR 0002). I tag fase-N non pubblicano nulla.
  • Windows: installatore costruito con make desktop-win su Windows e allegato alla release v*.
  • Unraid: deploy/unraid/anubis.xml, da copiare in /boot/config/plugins/dockerMan/templates-user/.