init

enriched-qwen3-coder-next/DataPRO/CanFDApiProxy/Requests.md

@@ -0,0 +1,84 @@
+---
+source_files:
+  - DataPRO/CanFDApiProxy/Requests/SerialRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/CanPostRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/FileRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/ClocksRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/NetworkRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/LEDsRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/CANConfigRequest.cs
+  - DataPRO/CanFDApiProxy/Requests/CanConfigItem.cs
+generated_at: "2026-04-16T04:02:28.102963+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "b4b7d8b4fcb0bb80"
+---
+
+# Requests
+
+## Documentation: `CANFDApiProxy.Requests` Module
+
+---
+
+### 1. **Purpose**
+
+This module defines a set of request classes used to serialize configuration and control commands for a CAN FD device API proxy layer. Each class corresponds to a specific type of operation (e.g., network configuration, LED control, CAN bus configuration, file operations, clock synchronization), and is intended for use in constructing JSON payloads sent to a backend service or embedded device. The module serves as a data contract layer—encapsulating structured input for remote API endpoints—without implementing business logic or I/O operations itself.
+
+---
+
+### 2. **Public Interface**
+
+All classes and enums are declared in the `CANFDApiProxy.Requests` namespace.
+
+| Name | Type | Signature & Description |
+|------|------|-------------------------|
+| `SerialRequest` | class | `public class SerialRequest { public string serial { get; set; } }`<br>• Represents a request to perform an operation using a device serial number. |
+| `NetworkRequest` | class | `public class NetworkRequest { public bool dhcp { get; set; } public string set_address { get; set; } }`<br>• Configures network settings: `dhcp` enables/disables DHCP; `set_address` specifies a static IP address (format unspecified). |
+| `LEDsRequest` | class | `public class LEDsRequest { public string led { get; set; } public string cmd { get; set; } public string color { get; set; } }`<br>• Controls an LED: `led` identifies the LED (via `LedName`), `cmd` is `"on"`/`"off"`, `color` is `"red"`, `"green"`, or `"blue"` (via `LedColor`). |
+| `LedColor` | enum | `public enum LedColor { red, green, blue }`<br>• Valid LED colors. |
+| `LedCmd` | enum | `public enum LedCmd { on, off }`<br>• Valid LED commands. |
+| `LedName` | enum | `public enum LedName { can1, can2, can3, can4, pwr, sts, status }`<br>• Valid LED identifiers. |
+| `CANConfigRequest` | class | `public class CANConfigRequest { public config config { get; set; } public string Status { get; set; } }`<br>• Top-level request for CAN bus configuration. Contains a `config` object and an optional `Status` string (e.g., `"success"`). |
+| `config` | class | `public class config { public CanConfigItem can1 { get; set; } public CanConfigItem can2 { get; set; } public CanConfigItem can3 { get; set; } public CanConfigItem can4 { get; set; } }`<br>• Holds per-CAN-channel configuration (up to 4 channels). |
+| `CanConfigItem` | class | `public class CanConfigItem(int base_or_arb_bitrate, int base_or_arb_sjw, int data_bitrate, int data_sjw, string filetype, bool included, bool is_fd)`<br>• Constructor initializes all properties.<br>• Properties:<br>  - `base_or_arb_bitrate`: int — Bitrate for arbitration/base phase (e.g., 500000).<br>  - `base_or_arb_sjw`: int — Synchronization jump width for arbitration/base phase.<br>  - `data_bitrate`: int — Bitrate for data phase (used only if `is_fd == true`).<br>  - `data_sjw`: int — SJW for data phase.<br>  - `filetype`: string — File type identifier (e.g., `"bin"`, `"hex"`).<br>  - `included`: bool — Whether this channel’s config is active.<br>  - `is_fd`: bool — Whether CAN FD mode is enabled.<br>• Includes `ToString()` overrides for debugging. |
+
+> **Note**: `CanConfigItem` has no parameterless constructor. All instances must be created via the explicit constructor.
+
+---
+
+### 3. **Invariants**
+
+- `SerialRequest.serial` and `NetworkRequest.set_address` are expected to be non-null and non-empty when used, though not enforced in the class itself.
+- `LEDsRequest.led`, `cmd`, and `color` are expected to match values from `LedName`, `LedCmd`, and `LedColor` respectively—**but no runtime validation is performed**; mismatches may cause downstream errors.
+- `CanConfigItem` instances must be constructed with all 7 parameters; partial initialization is impossible due to lack of a parameterless constructor.
+- `config` object expects exactly 4 `CanConfigItem` properties (`can1`–`can4`), but they may be `null` unless explicitly set.
+- `CANConfigRequest.Status` is a string field with no defined format or allowed values in this module.
+
+---
+
+### 4. **Dependencies**
+
+- **Internal usage**: `CANConfigRequest` references `config`, which is defined in the same namespace (`CANFDApiProxy.Requests`).
+- **External usage**: `CANConfigRequest` imports `using CANFDApiProxy.Messages;`, indicating a dependency on the `CANFDApiProxy.Messages` namespace (not provided in source). This suggests `config` or related types may be shared or extended there.
+- **Consumers**: These request classes are likely used by higher-level API client classes (e.g., in `CANFDApiProxy.Client` or similar) to serialize requests to JSON for HTTP or serial transport.
+- **No external libraries** are imported beyond the standard `System` (implied by C# syntax).
+
+---
+
+### 5. **Gotchas**
+
+- **No validation**: None of the request classes perform input validation (e.g., checking `serial` is non-empty, `set_address` is a valid IP, or `led`/`cmd`/`color` match expected enums). Validation must be handled externally.
+- **Enum mismatch risk**: `LEDsRequest` uses `string` properties (`led`, `cmd`, `color`) instead of the strongly-typed `LedName`, `LedCmd`, and `LedColor` enums. This invites typos (e.g., `"Red"` vs `"red"`) and runtime errors.
+- **`CanConfigItem` constructor is mandatory**: Since there is no parameterless constructor, deserialization frameworks (e.g., `System.Text.Json`) may fail unless custom converters or `JsonConstructor` attributes are applied.
+- **Ambiguous field semantics**:
+  - `NetworkRequest.set_address`’s format (e.g., CIDR notation, `"192.168.1.10"`) is unspecified.
+  - `FileRequest.path` and `ClocksRequest.time` are defined but no usage context is provided in this module.
+  - `CANConfigRequest.Status` is present in the request type, suggesting it may be used for client-to-server feedback—unusual for a request object.
+- **Inconsistent visibility**: `SerialRequest` and `NetworkRequest` are `public`, while `CanPostRequest`, `FileRequest`, and `ClocksRequest` are `internal`. This implies only a subset of request types are part of the public API surface.
+- **No documentation on `filetype`**: Its purpose (e.g., firmware image type, config file format) is unclear from the source.
+
+> **None identified from source alone** for `CanPostRequest`, `FileRequest`, and `ClocksRequest` beyond visibility and field names—behavior is entirely inferred from field names and naming conventions.
+
+--- 
+
+*End of documentation.*