Ossatura del progetto: soluzione, contratti, specifica, mockup, carattere e icone

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mzbb6zeFTjT6Rp8b92AVkA
This commit is contained in:
Claude committed 2026-10-13 14:47:06 +00:00
1 parent 10a9ed3ec3
commit db3d9f1aa4
123 files changed
+3763 -1

No files matched your search

+48
View File
@@ -0,0 +1,48 @@
using System.Text.Json;
namespace Febe.Core.Abstractions;
/// <summary>Options for starting the browser that visits the site.</summary>
/// <param name="ProfileDirectory">Browser profile folder (Dati/browser): holds the Instagram session.</param>
/// <param name="WindowWidth">Fixed window width, always the same.</param>
/// <param name="WindowHeight">Fixed window height, always the same.</param>
/// <param name="DebugPort">Fixed remote-debugging port, bound to 127.0.0.1 only (Docker). Never 0.</param>
/// <param name="ExecutablePath">Browser executable (Docker: the distribution's Chromium). Null means autodetect.</param>
/// <param name="Display">X display for Xvfb (Docker), e.g. ":99". Null means the current display.</param>
public sealed record BrowserOptions(
string ProfileDirectory,
int WindowWidth = 1280,
int WindowHeight = 900,
int DebugPort = 9222,
string? ExecutablePath = null,
string? Display = null);
/// <summary>
/// The browser host (spec §5): Chromium on Xvfb in Docker, WebView2 on Windows.
/// Everything above this interface is identical on both platforms.
/// </summary>
public interface IBrowserHost : IAsyncDisposable
{
Task StartAsync(BrowserOptions options, CancellationToken ct);
ICdpSession Cdp { get; }
/// <summary>Windows: brings the browser window to the foreground.</summary>
Task ShowToUserAsync();
Task HideFromUserAsync();
/// <summary>True while Alberto uses the browser: the engine does not act.</summary>
bool UserIsDriving { get; }
}
/// <summary>
/// A Chrome DevTools Protocol session on the page target. Only the commands listed in spec §6.1 may be sent;
/// implementations log command and event names only, never parameters or results.
/// </summary>
public interface ICdpSession
{
Task<JsonElement> SendAsync(string method, object? parameters = null, CancellationToken ct = default);
IDisposable On(string eventName, Action<JsonElement> handler);
}
+116
View File
@@ -0,0 +1,116 @@
namespace Febe.Core.Abstractions;
/// <summary>
/// Categories of counted actions toward the site (spec §7.4). Each has an hourly and a daily budget,
/// except <see cref="DataDownload"/>, which has a daily byte budget.
/// </summary>
public enum ActionKind
{
/// <summary>Opening the home page (Giro dei seguiti).</summary>
Home,
/// <summary>Opening a profile page.</summary>
ProfileOpen,
/// <summary>One story shown in the viewer (stories and highlight items).</summary>
StoryView,
/// <summary>One page of history loaded by scrolling (Storico, Taggati, Reel).</summary>
BackfillPage,
/// <summary>Opening a single post page.</summary>
SinglePost,
/// <summary>One page of the list of profiles Alberto follows.</summary>
FollowingListPage,
/// <summary>Bytes downloaded from the CDN (daily byte budget).</summary>
DataDownload,
}
/// <summary>Why the Governor refused an action. Shown in the interface.</summary>
public enum DenialReason
{
None,
BreakerOpen,
OutsideActiveWindow,
NoSession,
HourlyBudgetReached,
DailyBudgetReached,
MinimumSpacing,
AccountLimitReached,
UserIsDriving,
Paused,
}
/// <summary>
/// The Governor's answer to a request: either a permission or a motivated refusal (spec §7.4).
/// </summary>
public sealed record Permit(bool Granted, ActionKind Kind, long? AccountId, DenialReason Reason, string? Message, DateTimeOffset? RetryAfter)
{
public static Permit Grant(ActionKind kind, long? accountId) =>
new(true, kind, accountId, DenialReason.None, null, null);
public static Permit Deny(ActionKind kind, long? accountId, DenialReason reason, string message, DateTimeOffset? retryAfter = null) =>
new(false, kind, accountId, reason, message, retryAfter);
}
/// <summary>
/// The single point through which every engine action toward the site passes (spec §2 rule 7, §7.4).
/// No code path may load an Instagram page or perform a gesture on it without a granted permit.
/// </summary>
public interface IGovernor
{
Task<Permit> RequestAsync(ActionKind kind, long? accountId, CancellationToken ct);
}
/// <summary>Severity levels of stop signals (spec §7.6).</summary>
public enum SignalLevel
{
/// <summary>Rallentamento: timed stop (1h, 6h, 24h), then halved budgets for 48 hours.</summary>
Throttle,
/// <summary>Verifica: stops everything until Alberto resumes by hand.</summary>
Challenge,
/// <summary>Disconnessione: as Challenge; never tries to log back in.</summary>
Disconnect,
}
/// <summary>A stop signal reported by recipes or by the response capture.</summary>
/// <param name="Level">Severity.</param>
/// <param name="Code">Stable identifier of the signal, e.g. "http-429" or "challenge-url" (from segnali.json).</param>
/// <param name="Url">Address where it was seen, without query string (never secrets).</param>
/// <param name="At">When it was seen.</param>
public sealed record Signal(SignalLevel Level, string Code, string? Url, DateTimeOffset At);
/// <summary>State of the circuit breaker (Interruttore).</summary>
public enum BreakerStatus
{
/// <summary>Normal operation.</summary>
Closed,
/// <summary>Timed stop after a throttle signal; reopens by itself at <see cref="BreakerState.Until"/>.</summary>
Throttled,
/// <summary>Stopped after a challenge: needs Alberto and «Riprendi».</summary>
Challenge,
/// <summary>Stopped after a disconnection: needs Alberto and «Riprendi».</summary>
Disconnected,
}
public sealed record BreakerState(BreakerStatus Status, DateTimeOffset? Until, Signal? LastSignal, DateTimeOffset? HalvedBudgetsUntil)
{
public static readonly BreakerState Normal = new(BreakerStatus.Closed, null, null, null);
public bool AllowsSiteActions => Status == BreakerStatus.Closed;
}
/// <summary>The circuit breaker (spec §7.6). Every stop is persisted as an incident.</summary>
public interface ICircuitBreaker
{
BreakerState State { get; }
void Report(Signal signal);
}
+54
View File
@@ -0,0 +1,54 @@
namespace Febe.Core.Abstractions;
/// <summary>
/// The only source of time for the engine (spec §5). Engine code never uses
/// DateTime.Now, DateTimeOffset.Now or Task.Delay directly, so it can run under a virtual clock.
/// </summary>
public interface IClock
{
DateTimeOffset Now { get; }
/// <summary>The user's time zone (Alberto's): daily budgets and file names use it.</summary>
TimeZoneInfo LocalZone { get; }
Task Delay(TimeSpan time, CancellationToken ct);
}
/// <summary>The only source of randomness for the engine (spec §5).</summary>
public interface IRandomSource
{
/// <summary>Uniform value in [0, 1).</summary>
double NextDouble();
}
/// <summary>Real wall clock, used outside tests and simulation.</summary>
public sealed class SystemClock(TimeZoneInfo? zone = null) : IClock
{
public DateTimeOffset Now => DateTimeOffset.UtcNow;
public TimeZoneInfo LocalZone { get; } = zone ?? TimeZoneInfo.Local;
public Task Delay(TimeSpan time, CancellationToken ct) =>
time <= TimeSpan.Zero ? Task.CompletedTask : Task.Delay(time, ct);
}
/// <summary>Process-wide random source for production use.</summary>
public sealed class SystemRandom : IRandomSource
{
public double NextDouble() => Random.Shared.NextDouble();
}
/// <summary>Deterministic random source for tests and simulation (fixed seed).</summary>
public sealed class SeededRandom(int seed) : IRandomSource
{
private readonly Random _random = new(seed);
private readonly Lock _gate = new();
public double NextDouble()
{
lock (_gate)
{
return _random.NextDouble();
}
}
}
+143
View File
@@ -0,0 +1,143 @@
using Febe.Core.Abstractions;
namespace Febe.Core.Domain;
/// <summary>An hourly and daily budget for one action category.</summary>
public sealed record Budget(int PerHour, int PerDay);
/// <summary>
/// Values of a caution profile (spec §7.5). These are cautious starting estimates, not official limits
/// and not measurements: the interface must say so.
/// </summary>
public sealed record CautionProfile
{
public required CautionProfileKind Kind { get; init; }
/// <summary>Start of the daily active window (local time).</summary>
public required TimeOnly WindowStart { get; init; }
/// <summary>End of the daily active window (local time); may be after midnight (e.g. 00:30).</summary>
public required TimeOnly WindowEnd { get; init; }
/// <summary>Random daily shift applied to start and end, ± this amount.</summary>
public required TimeSpan WindowJitter { get; init; }
public required TimeSpan SessionMin { get; init; }
public required TimeSpan SessionMax { get; init; }
public required TimeSpan PauseMin { get; init; }
public required TimeSpan PauseMax { get; init; }
/// <summary>Budgets per category, excluding <see cref="ActionKind.DataDownload"/>.</summary>
public required IReadOnlyDictionary<ActionKind, Budget> Budgets { get; init; }
/// <summary>Daily download budget in bytes.</summary>
public required long DataPerDayBytes { get; init; }
/// <summary>Default per-account backfill limit (posts per day).</summary>
public required int BackfillPostsPerAccountPerDay { get; init; }
/// <summary>Gradual start: days to go from half to full budgets.</summary>
public required int RampUpDays { get; init; }
/// <summary>Active weekdays (all by default).</summary>
public IReadOnlySet<DayOfWeek> ActiveDays { get; init; } = new HashSet<DayOfWeek>(Enum.GetValues<DayOfWeek>());
public bool GradualStart { get; init; } = true;
public GesturePace Pace { get; init; } = GesturePace.Natural;
private const long GB = 1024L * 1024 * 1024;
public static CautionProfile Prudent { get; } = new()
{
Kind = CautionProfileKind.Prudent,
WindowStart = new TimeOnly(7, 30),
WindowEnd = new TimeOnly(23, 30),
WindowJitter = TimeSpan.FromMinutes(40),
SessionMin = TimeSpan.FromMinutes(2),
SessionMax = TimeSpan.FromMinutes(10),
PauseMin = TimeSpan.FromMinutes(20),
PauseMax = TimeSpan.FromMinutes(90),
Budgets = new Dictionary<ActionKind, Budget>
{
[ActionKind.Home] = new(4, 30),
[ActionKind.ProfileOpen] = new(12, 100),
[ActionKind.StoryView] = new(50, 300),
[ActionKind.BackfillPage] = new(20, 100),
[ActionKind.SinglePost] = new(10, 60),
[ActionKind.FollowingListPage] = new(15, 60),
},
DataPerDayBytes = 4 * GB,
BackfillPostsPerAccountPerDay = 300,
RampUpDays = 7,
};
public static CautionProfile Balanced { get; } = new()
{
Kind = CautionProfileKind.Balanced,
WindowStart = new TimeOnly(7, 0),
WindowEnd = new TimeOnly(0, 0),
WindowJitter = TimeSpan.FromMinutes(30),
SessionMin = TimeSpan.FromMinutes(3),
SessionMax = TimeSpan.FromMinutes(14),
PauseMin = TimeSpan.FromMinutes(12),
PauseMax = TimeSpan.FromMinutes(60),
Budgets = new Dictionary<ActionKind, Budget>
{
[ActionKind.Home] = new(5, 45),
[ActionKind.ProfileOpen] = new(20, 180),
[ActionKind.StoryView] = new(80, 500),
[ActionKind.BackfillPage] = new(30, 180),
[ActionKind.SinglePost] = new(15, 100),
[ActionKind.FollowingListPage] = new(20, 90),
},
DataPerDayBytes = 8 * GB,
BackfillPostsPerAccountPerDay = 500,
RampUpDays = 5,
};
public static CautionProfile Fast { get; } = new()
{
Kind = CautionProfileKind.Fast,
WindowStart = new TimeOnly(6, 30),
WindowEnd = new TimeOnly(0, 30),
WindowJitter = TimeSpan.FromMinutes(30),
SessionMin = TimeSpan.FromMinutes(4),
SessionMax = TimeSpan.FromMinutes(18),
PauseMin = TimeSpan.FromMinutes(8),
PauseMax = TimeSpan.FromMinutes(40),
Budgets = new Dictionary<ActionKind, Budget>
{
[ActionKind.Home] = new(6, 60),
[ActionKind.ProfileOpen] = new(30, 300),
[ActionKind.StoryView] = new(120, 800),
[ActionKind.BackfillPage] = new(45, 300),
[ActionKind.SinglePost] = new(20, 160),
[ActionKind.FollowingListPage] = new(30, 150),
},
DataPerDayBytes = 16 * GB,
BackfillPostsPerAccountPerDay = 800,
RampUpDays = 3,
};
public static CautionProfile For(CautionProfileKind kind) => kind switch
{
CautionProfileKind.Prudent => Prudent,
CautionProfileKind.Balanced => Balanced,
CautionProfileKind.Fast => Fast,
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "Custom profiles are stored values, not presets."),
};
/// <summary>Limits enforced by the interface (spec §7.5): minimum pause 5 min, session ≤ 30 min, window ≤ 20 h, no budget above twice «Rapido».</summary>
public static class Limits
{
public static readonly TimeSpan MinPause = TimeSpan.FromMinutes(5);
public static readonly TimeSpan MaxSession = TimeSpan.FromMinutes(30);
public static readonly TimeSpan MaxWindow = TimeSpan.FromHours(20);
public static Budget MaxBudget(ActionKind kind) =>
new(Fast.Budgets[kind].PerHour * 2, Fast.Budgets[kind].PerDay * 2);
public static long MaxDataPerDayBytes => Fast.DataPerDayBytes * 2;
}
}
+186
View File
@@ -0,0 +1,186 @@
namespace Febe.Core.Domain;
/// <summary>
/// Kind of an entry (spec §4.3). The folder name and the {tipo} placeholder are the Italian names
/// returned by <see cref="EntryKindNames.Folder"/>.
/// </summary>
public enum EntryKind
{
/// <summary>Grid post, reels included («post»).</summary>
Post,
/// <summary>Active story («storie»).</summary>
Story,
/// <summary>Item of a highlight collection («evidenza»).</summary>
Highlight,
/// <summary>Someone else's post where the account appears («taggati»).</summary>
Tagged,
/// <summary>Profile picture, one copy per change («profilo»).</summary>
ProfilePicture,
}
public static class EntryKindNames
{
/// <summary>Folder name and value of the {tipo} placeholder.</summary>
public static string Folder(EntryKind kind) => kind switch
{
EntryKind.Post => "post",
EntryKind.Story => "storie",
EntryKind.Highlight => "evidenza",
EntryKind.Tagged => "taggati",
EntryKind.ProfilePicture => "profilo",
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null),
};
public static EntryKind? FromFolder(string folder) => folder.ToLowerInvariant() switch
{
"post" => EntryKind.Post,
"storie" => EntryKind.Story,
"evidenza" => EntryKind.Highlight,
"taggati" => EntryKind.Tagged,
"profilo" => EntryKind.ProfilePicture,
_ => null,
};
}
/// <summary>State of an entry (spec §8.3).</summary>
public enum EntryState
{
/// <summary>da scaricare</summary>
ToDownload,
/// <summary>scaricato</summary>
Downloaded,
/// <summary>parziale: some files missing</summary>
Partial,
/// <summary>fallito</summary>
Failed,
/// <summary>saltato: excluded by a limit (e.g. video too large)</summary>
Skipped,
/// <summary>importato</summary>
Imported,
/// <summary>eliminato: kept in the database without files so it is not downloaded again</summary>
Deleted,
}
/// <summary>State of a single file.</summary>
public enum MediaState
{
ToDownload,
Downloaded,
Failed,
Skipped,
Imported,
Deleted,
/// <summary>The signed address expired: needs the Post singolo recipe (not possible for stories).</summary>
Expired,
}
public enum MediaKind
{
Photo,
Video,
}
/// <summary>Where an entry came from.</summary>
public enum Provenance
{
Downloaded,
Imported,
}
/// <summary>State of a followed account (spec §4.2).</summary>
public enum AccountState
{
/// <summary>Aggiornato</summary>
UpToDate,
/// <summary>Storico in corso</summary>
Backfilling,
/// <summary>In pausa</summary>
Paused,
/// <summary>Solo archivio: never contacted</summary>
ArchiveOnly,
/// <summary>Non raggiungibile: private and not followed, missing, blocked, renamed</summary>
Unreachable,
}
/// <summary>Check frequency of an account (spec §7.3).</summary>
public enum Frequency
{
Low,
Normal,
High,
/// <summary>Su misura: explicit hours for posts and maximum interval for stories.</summary>
Custom,
}
/// <summary>The six per-account switches of «Cosa scaricare» (spec §4.3, §4.4).</summary>
[Flags]
public enum ContentTypes
{
None = 0,
/// <summary>Foto dei post</summary>
PostPhotos = 1,
/// <summary>Video e reel</summary>
PostVideos = 2,
/// <summary>Storie</summary>
Stories = 4,
/// <summary>Storie in evidenza</summary>
Highlights = 8,
/// <summary>Post in cui è taggato</summary>
Tagged = 16,
/// <summary>Foto del profilo</summary>
ProfilePicture = 32,
All = PostPhotos | PostVideos | Stories | Highlights | Tagged | ProfilePicture,
}
/// <summary>Starting points when adding accounts (spec §4.2).</summary>
public enum StartingPoint
{
/// <summary>Scarica tutto e tieni aggiornato</summary>
EverythingAndKeepUpdated,
/// <summary>Solo le novità da oggi</summary>
OnlyNewFromToday,
/// <summary>Solo le storie</summary>
OnlyStories,
}
/// <summary>Caution profiles (spec §7.5). Prudent is the default.</summary>
public enum CautionProfileKind
{
Prudent,
Balanced,
Fast,
Custom,
}
/// <summary>«Ritmo dei gesti» slider (spec §7.7).</summary>
public enum GesturePace
{
Slow,
Natural,
Brisk,
}
+10
View File
@@ -0,0 +1,10 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Dominio e logica: motore, Governatore, interruttore, ricette, lettori, libreria, importazione.
Nessun riferimento a interfaccia o piattaforma: Data e Browser implementano le interfacce definite qui. -->
<ItemGroup>
<PackageReference Include="SkiaSharp" />
</ItemGroup>
<ItemGroup>
<InternalsVisibleTo Include="Febe.Tests" />
</ItemGroup>
</Project>