feat: follow llm.txt

backend/app/requests/label.go

@@ -1,8 +1,11 @@
 package requests
 
+// KV is a generic key-value response item, commonly used for label/value enums.
 type KV struct {
-	Key   string `json:"key,omitempty"`
-	Value any    `json:"value,omitempty"`
+	// Key is a machine-readable value, usually an enum string.
+	Key string `json:"key,omitempty"`
+	// Value is the label payload, often a human-readable string.
+	Value any `json:"value,omitempty"`
 }
 
 func NewKV(k string, v any) KV {

backend/app/requests/pagination.go

@@ -2,14 +2,21 @@ package requests
 
 import "github.com/samber/lo"
 
+// Pager is a common paginated API response envelope.
 type Pager struct {
+	// Pagination contains paging inputs (page/limit) echoed back in the response.
 	Pagination `      json:",inline"`
-	Total      int64 `json:"total"`
-	Items      any   `json:"items"`
+	// Total is the total number of items matching current filter (before paging).
+	Total int64 `json:"total"`
+	// Items is the paged result list; concrete type depends on endpoint.
+	Items any `json:"items"`
 }
 
+// Pagination defines common paging query parameters used by list endpoints.
 type Pagination struct {
-	Page  int64 `json:"page"  form:"page"  query:"page"`
+	// Page is 1-based page index; values <= 0 are normalized to 1.
+	Page int64 `json:"page"  form:"page"  query:"page"`
+	// Limit is page size; only values in {10,20,50,100} are accepted (otherwise defaults to 10).
 	Limit int64 `json:"limit" form:"limit" query:"limit"`
 }
 

backend/app/requests/sort.go

@@ -6,8 +6,11 @@ import (
 	"github.com/samber/lo"
 )
 
+// SortQueryFilter defines common query sorting parameters used by list endpoints.
 type SortQueryFilter struct {
-	Asc  *string `json:"asc" form:"asc"`
+	// Asc specifies comma-separated field names to sort ascending by.
+	Asc *string `json:"asc" form:"asc"`
+	// Desc specifies comma-separated field names to sort descending by.
 	Desc *string `json:"desc" form:"desc"`
 }