deploy: 0105f798e0

auriondocs/Code/src/EchoHub.Core/DTOs/ModerationDtos.cs.md

@@ -27,14 +27,14 @@ public record AssignRoleRequest(string Username, ServerRole Role)
 | `Role` | [`ServerRole`](../Models/ServerRole.cs.md) | — |
 
 
-AssignRoleRequest is a lightweight, immutable data transfer object that carries the intent to assign a specific server role to a user. It encapsulates just two pieces of information—the target Username and the desired Role—and is intended to be serialized and sent to moderation or authorization services that perform the actual role assignment.
+AssignRoleRequest is a lightweight, immutable data container (a positional `record`) that carries the target `Username` and the `Role` to be assigned. It serves as the payload for moderation workflows when granting a [`ServerRole`](../Models/ServerRole.cs.md) to a user, enabling consistent transport of this intent across API boundaries without embedding behavior. As a `record`, it uses value-based equality and can be copied with a `with` expression to create variations.
 
 ## Remarks
-The record type provides value-based equality and immutability, making it a reliable payload for messaging boundaries between UI, services, and backend handlers. By expressing the action as data rather than behavior, it supports clean separation of concerns and straightforward routing in moderation workflows.
+This symbol acts purely as a data carrier for the moderation flow, separating payload shape from the enforcement logic. It relies on the `Username` and `Role` values to identify the target user and the desired permission, enabling services to validate and enact the change consistently.
 
 ## Notes
-- Ensure Username conforms to identity rules at the boundary before processing the request.
-- Because this is an immutable record, callers should create a new instance for every distinct request; do not modify an existing instance.
+- Ensure `Username` is a valid existing member; the DTO does not enforce existence.
+- The `Role` must be a valid [`ServerRole`](../Models/ServerRole.cs.md) value; rely on server-side validation to handle invalid roles.
 
 ---
 
@@ -53,13 +53,7 @@ public record BanRequest(string? Reason = null)
 | `Reason` | `string?` | `null` |
 
 
-BanRequest is a lightweight, immutable data container used when issuing moderation bans. It carries an optional Reason and is designed to be passed as a single object through the moderation pipeline instead of a group of disparate parameters. This structure makes future extension straightforward (e.g., adding additional ban metadata) without changing call sites.
-
-## Remarks
-BanRequest acts as a boundary between the transport/presentation layer and the moderation domain. Using a record provides value-based equality and predictable serialization, which aids testing, logging, and caching. The optional Reason supports both silent bans and bans accompanied by rationale, with policy decisions about requiring a reason typically enforced at higher layers.
-
-## Notes
-- Reason is nullable; handle nulls gracefully when displaying or persisting data, and apply any policy about requiring a reason at the appropriate layer.
+BanRequest is a simple data carrier used to submit a moderation ban action, optionally including a rationale. Its only member, `Reason`, is nullable and defaults to null, so callers may omit a reason when none is provided.
 
 ---
 
@@ -78,15 +72,19 @@ public record KickRequest(string? Reason = null)
 | `Reason` | `string?` | `null` |
 
 
-KickRequest is a lightweight, immutable payload used when performing a moderation kick. It carries an optional Reason describing why the kick occurred. Callers construct this record when issuing a kick action and attach the reason if one is known; if no reason is provided, Reason remains null. The record shape ensures value-based equality and easy serialization across boundaries, making it a convenient transport object for moderation workflows.
+KickRequest is a minimal, immutable data carrier used to convey a moderation kick action. It carries an optional `Reason` explaining why the kick is issued. Callers instantiate a `KickRequest` when initiating a kick, providing a `Reason` if available; if no reason is supplied, the `Reason` property is `null`.
 
 ## Remarks
-KickRequest isolates the transport of a kick action from its core moderation logic. This abstraction makes it easy to extend later with additional fields (for example, moderatorId, timestamp, or kick ban duration) without changing the public contract. It also supports consistent logging and audit trails by treating the kick reason as optional metadata.
+KickRequest being a `record` makes it a value object with structural equality and immutability, which is helpful when routing kick intents through handlers or messaging layers. It encapsulates the kick payload so that higher-level services can work with a single, consistent input type rather than ad-hoc parameters.
+
+## Example
+```csharp
+var req = new KickRequest("Spamming in chat");
+```
 
 ## Notes
-- Reason is optional; validate as needed at the API boundary if your scenario requires a non-null reason.
-- When serializing, null Reason might be omitted depending on serializer configuration; be explicit if you need to communicate 'no reason'.
-- This is a simple DTO; do not conflate it with the domain entity for a kick; use it to transport data.
+- `Reason` is nullable; downstream code should handle `null` and decide whether a reason is required.
+- Records provide value-based equality; two `KickRequest` instances with the same `Reason` compare equal.
 
 ---
 
@@ -106,22 +104,6 @@ public record MuteRequest(string? Reason = null, int? DurationMinutes = null)
 | `DurationMinutes` | `int?` | `null` |
 
 
-MuteRequest is a compact, immutable data transfer object used to initiate a moderation mute. It carries two optional fields: Reason and DurationMinutes, allowing you to specify a rationale and a duration when issuing a mute; omitting either field leaves that detail to the receiver's policy.
-
-## Remarks
-By grouping the fields into a single record, this abstraction reduces API surface area and provides a consistent payload for mute-related actions across the moderation layer. The record semantics also enable value-based equality and straightforward testing and transport.
-
-## Example
-```csharp
-// Mute for 30 minutes with a reason
-var request = new MuteRequest("Spamming in chat", 30);
-
-// Mute without specifying details
-var request2 = new MuteRequest();
-```
-
-## Notes
-- Reason may contain user-provided content; avoid including it in logs or telemetry unless explicitly permitted.
-- Because the type is a record with nullable fields, ensure boundary validation and handle nulls gracefully at the call site or in the receiving layer.
+MuteRequest is a lightweight data transfer object used to specify the parameters of a mute action in moderation flows. It includes two optional values: `Reason`, a `string?` describing why the mute is issued, and `DurationMinutes`, an `int?` indicating how long the mute should last; both default to `null` if not provided. This allows callers to mute with a default duration or provide additional context for auditing and user experience.
 
 ---