Files
Anubis/docs/SVILUPPO.md
Alby96andClaude Opus 5.5 e561245d4e
ci / test (sqlite) (pull_request) Successful in 3m37s
ci / test (sqlite) (push) Successful in 4m1s
ci / test (postgres) (pull_request) Successful in 6m4s
ci / test (postgres) (push) Successful in 6m27s
ci / image (pull_request) Successful in 1m3s
ci / image (push) Successful in 1m5s
Keep the 48-hour run going after Docker stopped with the Claude app (refs #53 #55)
On 12 November at 23:37 Docker Desktop stopped for 15 minutes. It had
been started from the Claude app's shell after the PC switched off, so it
lived in the app's process job and died when the app updated itself. The
bot resumed alone and recorded the absence.

The run is not restarted from zero: a fresh start would no longer span
two US sessions before the weekend. Instead two reports are read: the 48
uninterrupted hours from 23:57, which must be regular, and the whole run
from 21:02, whose only allowed failure is that 15-minute stop. Docker is
now started through WMI, outside the app, and SVILUPPO.md says how.

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

111 lines
9.6 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.
- Docker Desktop non si avvia dalla shell dell'app Claude (`Start-Process`, `docker desktop start`): il processo resta legato all'app e si chiude con lei quando si aggiorna o si chiude. Il 12 novembre 2026 è successo durante la prova di durata. Se va avviato da lì, si passa da WMI, che lo fa partire da un servizio di Windows:
`Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{CommandLine='"C:\Program Files\Docker\Docker\Docker Desktop.exe"'}`
- 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/`.