[AZ-513] [AZ-196] [AZ-183] Add /classes CRUD, /devices, fleet OTA

AZ-513: POST/PATCH/DELETE /classes for detection-class CRUD; new
DetectionClass entity, schema, DTOs, IDetectionClassService. Unblocks
ui/AZ-512.

AZ-196: POST /devices auto-assigns sequential azj-NNNN serial+email
+password and inserts a CompanionPC user. Returns plaintext credentials
for the provisioning script.

AZ-183: Resources table + POST /get-update + POST /resources/publish
for fleet OTA. Per-resource encryption_key column AES-256-CBC encrypted
at rest with ResourcesConfig.EncryptionMasterKey; ICache wraps the
per-(arch,stage) latest-versions lookup and is invalidated on publish.

Adds IDbFactory.RunAdmin<T> overload for write-and-return.

Backfills _docs/02_document/module-layout.md to satisfy the implement
skill's File Ownership prerequisite (the _docs/ artifact set predates
the Step 1.5 module-layout addition).

Code review: PASS_WITH_WARNINGS — see
_docs/03_implementation/reviews/batch_05_review.md.

Co-authored-by: Cursor <cursoragent@cursor.com>

Azaion.Common/Configs/ResourcesConfig.cs

@@ -5,4 +5,11 @@ public class ResourcesConfig
     public string ResourcesFolder { get; set; } = null!;
     public string SuiteInstallerFolder { get; set; } = null!;
     public string SuiteStageInstallerFolder { get; set; } = null!;
+
+    /// <summary>
+    /// Master key used to AES-encrypt the per-resource <c>encryption_key</c> column at rest.
+    /// Required by AZ-183 constraint "encryption_key must be stored securely (... or via
+    /// application-level encryption)". Configure via <c>ResourcesConfig__EncryptionMasterKey</c>.
+    /// </summary>
+    public string EncryptionMasterKey { get; set; } = null!;
 }

Azaion.Common/Database/AzaionDb.cs

@@ -6,5 +6,7 @@ namespace Azaion.Common.Database;
 
 public class AzaionDb(DataOptions dataOptions) : DataConnection(dataOptions)
 {
-    public ITable<User> Users => this.GetTable<User>();
+    public ITable<User>            Users             => this.GetTable<User>();
+    public ITable<DetectionClass>  DetectionClasses  => this.GetTable<DetectionClass>();
+    public ITable<Resource>        Resources         => this.GetTable<Resource>();
 }

Azaion.Common/Database/AzaionDbShemaHolder.cs

@@ -36,6 +36,17 @@ public static class AzaionDbSchemaHolder
                     p => string.IsNullOrEmpty(p) ? new UserConfig() : JsonConvert.DeserializeObject<UserConfig>(p))
                 .IsNullable();
 
+        builder.Entity<DetectionClass>()
+            .HasTableName("detection_classes")
+            .Property(x => x.Id)
+                .IsPrimaryKey()
+                .IsIdentity();
+
+        builder.Entity<Resource>()
+            .HasTableName("resources")
+            .Property(x => x.Id)
+                .IsPrimaryKey()
+                .HasDataType(DataType.Guid);
 
         builder.Build();
     }

Azaion.Common/Database/DbFactory.cs

@@ -10,6 +10,7 @@ public interface IDbFactory
     Task<T> Run<T>(Func<AzaionDb, Task<T>> func);
     Task Run(Func<AzaionDb, Task> func);
     Task RunAdmin(Func<AzaionDb, Task> func);
+    Task<T> RunAdmin<T>(Func<AzaionDb, Task<T>> func);
 }
 
 public class DbFactory : IDbFactory
@@ -54,4 +55,10 @@ public class DbFactory : IDbFactory
         await using var db = new AzaionDb(_dataOptionsAdmin);
         await func(db);
     }
+
+    public async Task<T> RunAdmin<T>(Func<AzaionDb, Task<T>> func)
+    {
+        await using var db = new AzaionDb(_dataOptionsAdmin);
+        return await func(db);
+    }
 }

Azaion.Common/Entities/DetectionClass.cs

@@ -0,0 +1,12 @@
+namespace Azaion.Common.Entities;
+
+public class DetectionClass
+{
+    public int      Id        { get; set; }
+    public string   Name      { get; set; } = null!;
+    public string   ShortName { get; set; } = null!;
+    public string   Color     { get; set; } = null!;
+    public double   MaxSizeM  { get; set; }
+    public string?  PhotoMode { get; set; }
+    public DateTime CreatedAt { get; set; }
+}

Azaion.Common/Entities/Resource.cs

@@ -0,0 +1,15 @@
+namespace Azaion.Common.Entities;
+
+public class Resource
+{
+    public Guid     Id            { get; set; }
+    public string   ResourceName  { get; set; } = null!;
+    public string   DevStage      { get; set; } = null!;
+    public string   Architecture  { get; set; } = null!;
+    public string   Version       { get; set; } = null!;
+    public string   CdnUrl        { get; set; } = null!;
+    public string   Sha256        { get; set; } = null!;
+    public string   EncryptionKey { get; set; } = null!;
+    public long     SizeBytes     { get; set; }
+    public DateTime CreatedAt     { get; set; }
+}

Azaion.Common/Requests/CreateDetectionClassRequest.cs

@@ -0,0 +1,24 @@
+using FluentValidation;
+
+namespace Azaion.Common.Requests;
+
+public class CreateDetectionClassRequest
+{
+    public string  Name      { get; set; } = null!;
+    public string  ShortName { get; set; } = null!;
+    public string  Color     { get; set; } = null!;
+    public double  MaxSizeM  { get; set; }
+    public string? PhotoMode { get; set; }
+}
+
+public class CreateDetectionClassValidator : AbstractValidator<CreateDetectionClassRequest>
+{
+    public CreateDetectionClassValidator()
+    {
+        RuleFor(r => r.Name).NotEmpty().MaximumLength(120);
+        RuleFor(r => r.ShortName).NotEmpty().MaximumLength(20);
+        RuleFor(r => r.Color).NotEmpty().MaximumLength(20);
+        RuleFor(r => r.MaxSizeM).GreaterThan(0);
+        RuleFor(r => r.PhotoMode!).MaximumLength(20).When(r => r.PhotoMode != null);
+    }
+}

Azaion.Common/Requests/GetUpdateRequest.cs

@@ -0,0 +1,35 @@
+using FluentValidation;
+
+namespace Azaion.Common.Requests;
+
+public class GetUpdateRequest
+{
+    public string Architecture { get; set; } = null!;
+    public string DevStage     { get; set; } = null!;
+
+    /// <summary>
+    /// Map of <c>resource_name → currently-installed-version</c>. Resources missing
+    /// from the map are treated as "device has no version of this resource yet" and
+    /// will be returned in the response if any version exists server-side.
+    /// </summary>
+    public Dictionary<string, string> CurrentVersions { get; set; } = new();
+}
+
+public class GetUpdateValidator : AbstractValidator<GetUpdateRequest>
+{
+    public GetUpdateValidator()
+    {
+        RuleFor(r => r.Architecture).NotEmpty().MaximumLength(40);
+        RuleFor(r => r.DevStage).NotEmpty().MaximumLength(40);
+    }
+}
+
+public class ResourceUpdateItem
+{
+    public string ResourceName  { get; set; } = null!;
+    public string Version       { get; set; } = null!;
+    public string CdnUrl        { get; set; } = null!;
+    public string Sha256        { get; set; } = null!;
+    public string EncryptionKey { get; set; } = null!;
+    public long   SizeBytes     { get; set; }
+}

Azaion.Common/Requests/PublishResourceRequest.cs

@@ -0,0 +1,30 @@
+using FluentValidation;
+
+namespace Azaion.Common.Requests;
+
+public class PublishResourceRequest
+{
+    public string ResourceName  { get; set; } = null!;
+    public string DevStage      { get; set; } = null!;
+    public string Architecture  { get; set; } = null!;
+    public string Version       { get; set; } = null!;
+    public string CdnUrl        { get; set; } = null!;
+    public string Sha256        { get; set; } = null!;
+    public string EncryptionKey { get; set; } = null!;
+    public long   SizeBytes     { get; set; }
+}
+
+public class PublishResourceValidator : AbstractValidator<PublishResourceRequest>
+{
+    public PublishResourceValidator()
+    {
+        RuleFor(r => r.ResourceName).NotEmpty().MaximumLength(120);
+        RuleFor(r => r.DevStage).NotEmpty().MaximumLength(40);
+        RuleFor(r => r.Architecture).NotEmpty().MaximumLength(40);
+        RuleFor(r => r.Version).NotEmpty().MaximumLength(40);
+        RuleFor(r => r.CdnUrl).NotEmpty().MaximumLength(500);
+        RuleFor(r => r.Sha256).NotEmpty().MaximumLength(128);
+        RuleFor(r => r.EncryptionKey).NotEmpty();
+        RuleFor(r => r.SizeBytes).GreaterThan(0);
+    }
+}

Azaion.Common/Requests/RegisterDeviceResponse.cs

@@ -0,0 +1,8 @@
+namespace Azaion.Common.Requests;
+
+public class RegisterDeviceResponse
+{
+    public string Serial   { get; set; } = null!;
+    public string Email    { get; set; } = null!;
+    public string Password { get; set; } = null!;
+}

Azaion.Common/Requests/UpdateDetectionClassRequest.cs

@@ -0,0 +1,24 @@
+using FluentValidation;
+
+namespace Azaion.Common.Requests;
+
+public class UpdateDetectionClassRequest
+{
+    public string?  Name      { get; set; }
+    public string?  ShortName { get; set; }
+    public string?  Color     { get; set; }
+    public double?  MaxSizeM  { get; set; }
+    public string?  PhotoMode { get; set; }
+}
+
+public class UpdateDetectionClassValidator : AbstractValidator<UpdateDetectionClassRequest>
+{
+    public UpdateDetectionClassValidator()
+    {
+        RuleFor(r => r.Name!).NotEmpty().MaximumLength(120).When(r => r.Name != null);
+        RuleFor(r => r.ShortName!).NotEmpty().MaximumLength(20).When(r => r.ShortName != null);
+        RuleFor(r => r.Color!).NotEmpty().MaximumLength(20).When(r => r.Color != null);
+        RuleFor(r => r.MaxSizeM!.Value).GreaterThan(0).When(r => r.MaxSizeM != null);
+        RuleFor(r => r.PhotoMode!).MaximumLength(20).When(r => r.PhotoMode != null);
+    }
+}