[AZ-189] Update coding and testing rules for clarity and consistency

- Revised coding standards to emphasize readability, meaningful comments, and test verification.
- Adjusted test coverage thresholds to 75% for business logic and clarified expectations for test scenarios.
- Enhanced guidelines for handling skipped tests, emphasizing the need for investigation and resolution.
- Updated commit message format and length requirements for better adherence to Git conventions.

Made-with: Cursor

_docs/02_tasks/todo/AZ-196_register_device_endpoint.md

@@ -0,0 +1,95 @@
+# Register Device Endpoint
+
+**Task**: AZ-196_register_device_endpoint
+**Name**: POST /devices endpoint for auto device registration
+**Description**: Add POST /devices endpoint to admin API that auto-generates device serial, email, and password for CompanionPC users
+**Complexity**: 2 points
+**Dependencies**: None
+**Component**: Admin API
+**Tracker**: AZ-196
+**Epic**: AZ-181
+
+## Problem
+
+During Jetson manufacturing, each device needs a unique CompanionPC identity (serial, email, password). Currently the provisioning script generates the email client-side and calls POST /users. The serial/email format should be server-controlled so the admin API is the single source of truth for device numbering.
+
+## Outcome
+
+- Single POST /devices endpoint that requires no request body
+- Server auto-assigns the next sequential serial (azj-0000, azj-0001, ...)
+- Returns plaintext credentials so the provisioning script can embed them in device.conf
+
+## Scope
+
+### Included
+
+- `RegisterDeviceResponse` DTO in `Azaion.Common/Requests/` with `Serial`, `Email`, `Password` fields
+- `RegisterDevice` method on `IUserService` / `UserService`
+- `POST /devices` endpoint in `Program.cs` with `RequireAuthorization(apiAdminPolicy)`
+- Sequential serial assignment based on most recent CompanionPC user
+
+### Excluded
+
+- Changes to the provisioning shell script (handled in loader repo)
+- Removing old POST /users endpoint (still used for non-device users)
+
+## Implementation Details
+
+### Serial number logic
+
+Email format: `azj-NNNN@azaion.com` where NNNN is zero-padded to 4 digits.
+
+Constants at the top of `UserService`:
+
+```csharp
+private const int SerialNumberStart = 4;
+private const int SerialNumberLength = 4;
+```
+
+`RegisterDevice` implementation:
+
+1. Query the single most recent CompanionPC user: `WHERE role = 'CompanionPC' ORDER BY created_at DESC LIMIT 1`
+2. If none found, next number is 0000; otherwise extract via `Substring(SerialNumberStart, SerialNumberLength)`, parse, increment
+3. Generate email `azj-{number:D4}@azaion.com`
+4. Generate random 32-char hex password: `Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLower()`
+5. Insert User with `Role = CompanionPC`, `IsEnabled = true`, password hashed via `ToHash()`
+6. Return `RegisterDeviceResponse { Serial, Email, Password (plaintext) }`
+
+### Endpoint
+
+```csharp
+app.MapPost("/devices",
+    async (IUserService userService, CancellationToken cancellationToken)
+        => await userService.RegisterDevice(cancellationToken))
+    .RequireAuthorization(apiAdminPolicy)
+    .WithSummary("Creates a new device");
+```
+
+No request body required.
+
+## Acceptance Criteria
+
+**AC-1: First device gets serial azj-0000**
+Given no CompanionPC users exist in the database
+When POST /devices is called with a valid ApiAdmin JWT
+Then the response contains `serial: "azj-0000"`, `email: "azj-0000@azaion.com"`, and a 32-char hex password
+
+**AC-2: Sequential numbering**
+Given azj-0000 already exists
+When POST /devices is called again
+Then the response contains `serial: "azj-0001"`
+
+**AC-3: User persisted with correct role**
+Given POST /devices returned successfully
+When the users table is queried
+Then a user exists with the returned email, Role=CompanionPC, IsEnabled=true
+
+**AC-4: Password is hashed in DB**
+Given POST /devices returned a plaintext password
+When the users table is inspected
+Then PasswordHash contains the SHA-384 hash of the plaintext password, not the plaintext itself
+
+**AC-5: Requires ApiAdmin authorization**
+Given a request without a JWT or with a non-ApiAdmin JWT
+When POST /devices is called
+Then 401 or 403 is returned