Files
Anubis/docs/SVILUPPO.md
T
Alby96andClaude Opus 5.5 9a4e31aa48
ci / test (postgres) (push) Successful in 9m13s
ci / test (sqlite) (push) Successful in 4m46s
ci / image (push) Successful in 1m50s
ci / test (sqlite) (pull_request) Successful in 4m57s
ci / test (postgres) (pull_request) Successful in 11m4s
ci / image (pull_request) Successful in 1m2s
Record the start of the 48-hour run and how to read its report (refs #53)
The run started on 11 November 2026 at 21:44 Italian time in the
anubis-prova container, from the image of this branch. STATE says when
and how to make the report so that it spans both US sessions; its check
is the first step of Phase 7 (#55).

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

109 lines
9.2 KiB
Markdown

# Come si sviluppa Anubis
Regole di lavoro per chi scrive il codice, persona o agente. Riassumono le sezioni 2, 16 e 19 della specifica e gli ADR 0003 (stack C#) e 0004 (componenti esterni), 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) |
| Stack e struttura del repository | `docs/adr/0003-csharp-dotnet.md` (sostituisce SPEC 3, 5.1 e appendice D) |
| Pacchetti ammessi | `docs/adr/0004-componenti-esterni.md` |
| Logo | `docs/design/logo/` (ADR 0005) |
| 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, 16 e 19, e l'ADR 0003.
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. Unica eccezione: i componenti esterni (sotto, "Dipendenze").
- 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 `tasks check` passato, immagine Docker costruita e, per le schermate, fotografie di Edge senza finestra confrontate con i mockup. "Dovrebbe funzionare" non è una prova.
**Codice (ADR 0003, SPEC 16, 19)**
- Denaro, prezzi e quantità sempre `decimal`, mai `double`; sul database `NUMERIC(38,18)` su PostgreSQL e testo su SQLite (5.4), arrotondati a 18 decimali.
- `Nullable` attivo e avvisi degli analizzatori trattati come errori in tutti i progetti.
- 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 in thread dedicati a bassa priorità; un solo scrittore sul database.
- 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 `src/Anubis/Core/Format.cs`.
**Dipendenze (ADR 0004, SPEC 2.7)**
- Nessun SDK né componente esterno senza il permesso dell'utente. Ammessi solo .NET 10 con i suoi framework e i pacchetti elencati nell'ADR 0004, con versioni fissate in `Directory.Packages.props` e file di blocco.
- Per tutto il resto si scrive codice in casa: client dei broker, Telegram, TOTP, lettura RSS, grafici, migrazioni, installatore.
- Se un componente nuovo sembra indispensabile: fermati, chiedi all'utente spiegando cos'è, a cosa serve, perché non conviene scriverlo e cosa si porta dietro; solo con il sì lo aggiungi, con un ADR.
- Niente librerie di analisi tecnica né di backtest (SPEC 2.7): indicatori e motore si scrivono in casa.
## Schermate
Per ogni schermata: implementa, apri sui dati dimostrativi (`tasks seed-demo`), fotografa con Edge senza finestra (`msedge --headless --screenshot`) a 1440 e 390 pixel, 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à.
## Debug con Visual Studio Code
Apri la radice del repository in VS Code con l'estensione C# (`ms-dotnettools.csharp`, suggerita da `.vscode/extensions.json`), poi Esegui e debug (F5). Ogni voce compila il server in Debug (attività `build-server` di `.vscode/tasks.json`) e apre il browser quando il server ascolta:
- **Anubis: server, dati di prova**: una cartella dati a parte, `artifacts/debug-data`, ignorata da git. Al primo avvio chiede la configurazione iniziale; per ripartire da zero basta cancellare la cartella.
- **Anubis: modalità dimostrativa**: i dati dell'appendice F, come `tasks seed-demo`.
- **Anubis: server, dati dell'utente**: la cartella vera, `%APPDATA%\Anubis`, come `tasks dev`.
- **Anubis: aggancia a un processo**: per un server già avviato, per esempio con `tasks dev`.
Le attività `check`, `test` e `dev` sono anche in Terminale → Esegui attività. L'estensione è dell'editor, non del progetto: non entra nell'elenco dell'ADR 0004.
## Guardia e prova di durata
- In Docker il processo principale è la guardia (`Anubis.Guard.dll`), che avvia il server come processo figlio (ADR 0012). Fuori da Docker, con `tasks dev` o da VS Code, il server gira da solo, senza guardia.
- La prova della guardia blocca davvero il motore con una vendita a metà e controlla che tutto torni a posto:
- `dotnet run --project src/Anubis.Guard -- drill` sul computer;
- `docker run --rm <immagine> drill` dentro l'immagine.
La fanno anche `tasks ci` e la CI.
- Il rapporto di una prova di durata si legge mentre il bot lavora: `docker exec -u 99:100 -e HOME=/tmp <container> dotnet /app/Anubis.Server.dll soak --hours 48 --platform docker`, con l'utente del bot (`PUID:PGID`) perché i file del database restino suoi. Esce con 0 se tutto è regolare e con 4 se qualcosa va guardato. Senza `--from` la finestra sono le ultime `--hours` ore; con `--from` comincia lì e dura `--hours` ore, che sono anche la durata minima richiesta.
- Gli appigli per le prove (`ANUBIS_FAULT`, `ANUBIS_DRILL_OKX_URL`) non si usano mai su un'installazione vera.
## 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 `Anubis.Setup` (scritto in casa, ADR 0003) costruito con `tasks desktop-win` su Windows e allegato alla release `v*`.
- **Unraid**: `deploy/unraid/anubis.xml`, da copiare in `/boot/config/plugins/dockerMan/templates-user/`.