update godoc

server/handler/encryptData.go

@@ -14,8 +14,8 @@ import (
 // @Accept json
 // @Produce json
 // @Param payload body map[string]string true "Plaintext payload"
-// @Success 200 {object} map[string]string "Ciphertext response"
+// @Success 200 {object} models.StatusMessageResponse "Ciphertext response"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/encrypt [post]
 func (h *Handler) EncryptData(w http.ResponseWriter, r *http.Request) {
 	//ctx := context.Background()

server/handler/reportDownload.go

@@ -14,7 +14,7 @@ import (
 // @Tags reports
 // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 // @Success 200 {file} file "Inventory XLSX report"
-// @Failure 500 {object} map[string]string "Report generation failed"
+// @Failure 500 {object} models.ErrorResponse "Report generation failed"
 // @Router /api/report/inventory [get]
 func (h *Handler) InventoryReportDownload(w http.ResponseWriter, r *http.Request) {
 
@@ -48,7 +48,7 @@ func (h *Handler) InventoryReportDownload(w http.ResponseWriter, r *http.Request
 // @Tags reports
 // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 // @Success 200 {file} file "Updates XLSX report"
-// @Failure 500 {object} map[string]string "Report generation failed"
+// @Failure 500 {object} models.ErrorResponse "Report generation failed"
 // @Router /api/report/updates [get]
 func (h *Handler) UpdateReportDownload(w http.ResponseWriter, r *http.Request) {
 

server/handler/snapshotAggregate.go

@@ -8,6 +8,7 @@ import (
 	"time"
 	"vctp/internal/settings"
 	"vctp/internal/tasks"
+	"vctp/server/models"
 )
 
 // SnapshotAggregateForce forces regeneration of a daily or monthly summary table.
@@ -18,9 +19,9 @@ import (
 // @Param type query string true "Aggregation type: daily or monthly"
 // @Param date query string true "Daily date (YYYY-MM-DD) or monthly date (YYYY-MM)"
 // @Param granularity query string false "Monthly aggregation granularity: hourly or daily"
-// @Success 200 {object} map[string]string "Aggregation complete"
+// @Success 200 {object} models.StatusResponse "Aggregation complete"
-// @Failure 400 {object} map[string]string "Invalid request"
+// @Failure 400 {object} models.ErrorResponse "Invalid request"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/snapshots/aggregate [post]
 func (h *Handler) SnapshotAggregateForce(w http.ResponseWriter, r *http.Request) {
 	snapshotType := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("type")))
@@ -112,8 +113,8 @@ func (h *Handler) SnapshotAggregateForce(w http.ResponseWriter, r *http.Request)
 func writeJSONError(w http.ResponseWriter, status int, message string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
-	json.NewEncoder(w).Encode(map[string]string{
+	json.NewEncoder(w).Encode(models.ErrorResponse{
-		"status":  "ERROR",
+		Status:  "ERROR",
-		"message": message,
+		Message: message,
 	})
 }

server/handler/snapshotForceHourly.go

@@ -16,9 +16,9 @@ import (
 // @Accept json
 // @Produce json
 // @Param confirm query string true "Confirmation text; must be 'FORCE'"
-// @Success 200 {object} map[string]string "Snapshot started"
+// @Success 200 {object} models.StatusResponse "Snapshot started"
-// @Failure 400 {object} map[string]string "Invalid request"
+// @Failure 400 {object} models.ErrorResponse "Invalid request"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/snapshots/hourly/force [post]
 func (h *Handler) SnapshotForceHourly(w http.ResponseWriter, r *http.Request) {
 	confirm := strings.TrimSpace(r.URL.Query().Get("confirm"))

server/handler/snapshotMigrate.go

@@ -12,8 +12,8 @@ import (
 // @Description Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.
 // @Tags snapshots
 // @Produce json
-// @Success 200 {object} map[string]interface{} "Migration results"
+// @Success 200 {object} models.SnapshotMigrationResponse "Migration results"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.SnapshotMigrationResponse "Server error"
 // @Router /api/snapshots/migrate [post]
 func (h *Handler) SnapshotMigrate(w http.ResponseWriter, r *http.Request) {
 	ctx := context.Background()

server/handler/snapshotRegenerateHourly.go

@@ -15,8 +15,8 @@ import (
 // @Description Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.
 // @Tags snapshots
 // @Produce json
-// @Success 200 {object} map[string]interface{} "Regeneration summary"
+// @Success 200 {object} models.SnapshotRegenerateReportsResponse "Regeneration summary"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/snapshots/regenerate-hourly-reports [post]
 func (h *Handler) SnapshotRegenerateHourlyReports(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()

server/handler/snapshotRepair.go

@@ -17,7 +17,7 @@ import (
 // @Description Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.
 // @Tags snapshots
 // @Produce json
-// @Success 200 {object} map[string]string
+// @Success 200 {object} models.SnapshotRepairResponse
 // @Router /api/snapshots/repair [post]
 func (h *Handler) SnapshotRepair(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
@@ -102,7 +102,7 @@ func (h *Handler) repairDailySummaries(ctx context.Context, now time.Time) (repa
 // @Description Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.
 // @Tags snapshots
 // @Produce json
-// @Success 200 {object} map[string]string
+// @Success 200 {object} models.SnapshotRepairSuiteResponse
 // @Router /api/snapshots/repair/all [post]
 func (h *Handler) SnapshotRepairSuite(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/snapshots.go

@@ -55,8 +55,8 @@ func (h *Handler) SnapshotMonthlyList(w http.ResponseWriter, r *http.Request) {
 // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 // @Param table query string true "Snapshot table name"
 // @Success 200 {file} file "Snapshot XLSX report"
-// @Failure 400 {object} map[string]string "Invalid request"
+// @Failure 400 {object} models.ErrorResponse "Invalid request"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/report/snapshot [get]
 func (h *Handler) SnapshotReportDownload(w http.ResponseWriter, r *http.Request) {
 	ctx := context.Background()

server/handler/vcCleanup.go

@@ -16,8 +16,8 @@ import (
 // @Deprecated
 // @Produce json
 // @Param vc_url query string true "vCenter URL"
-// @Success 200 {object} map[string]string "Cleanup completed"
+// @Success 200 {object} models.StatusMessageResponse "Cleanup completed"
-// @Failure 400 {object} map[string]string "Invalid request"
+// @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Router /api/cleanup/vcenter [delete]
 func (h *Handler) VcCleanup(w http.ResponseWriter, r *http.Request) {
 	ctx := context.Background()

server/handler/vmCleanup.go

@@ -17,8 +17,8 @@ import (
 // @Produce json
 // @Param vm_id query string true "VM ID"
 // @Param datacenter_name query string true "Datacenter name"
-// @Success 200 {object} map[string]string "Cleanup completed"
+// @Success 200 {object} models.StatusMessageResponse "Cleanup completed"
-// @Failure 400 {object} map[string]string "Invalid request"
+// @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Router /api/inventory/vm/delete [delete]
 func (h *Handler) VmCleanup(w http.ResponseWriter, r *http.Request) {
 	ctx := context.Background()

server/handler/vmImport.go

@@ -21,8 +21,8 @@ import (
 // @Accept json
 // @Produce json
 // @Param import body models.ImportReceived true "Bulk import payload"
-// @Success 200 {object} map[string]string "Import processed"
+// @Success 200 {object} models.StatusMessageResponse "Import processed"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/import/vm [post]
 func (h *Handler) VmImport(w http.ResponseWriter, r *http.Request) {
 	// Read request body

server/handler/vmModifyEvent.go

@@ -27,9 +27,9 @@ import (
 // @Accept json
 // @Produce json
 // @Param event body models.CloudEventReceived true "CloudEvent payload"
-// @Success 200 {object} map[string]string "Modify event processed"
+// @Success 200 {object} models.StatusMessageResponse "Modify event processed"
-// @Success 202 {object} map[string]string "No relevant changes"
+// @Success 202 {object} models.StatusMessageResponse "No relevant changes"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/event/vm/modify [post]
 func (h *Handler) VmModifyEvent(w http.ResponseWriter, r *http.Request) {
 	var configChanges []map[string]string

server/handler/vmMoveEvent.go

@@ -22,9 +22,9 @@ import (
 // @Accept json
 // @Produce json
 // @Param event body models.CloudEventReceived true "CloudEvent payload"
-// @Success 200 {object} map[string]string "Move event processed"
+// @Success 200 {object} models.StatusMessageResponse "Move event processed"
-// @Failure 400 {object} map[string]string "Invalid request"
+// @Failure 400 {object} models.ErrorResponse "Invalid request"
-// @Failure 500 {object} map[string]string "Server error"
+// @Failure 500 {object} models.ErrorResponse "Server error"
 // @Router /api/event/vm/move [post]
 func (h *Handler) VmMoveEvent(w http.ResponseWriter, r *http.Request) {
 	params := queries.CreateUpdateParams{}

server/models/api_responses.go

@@ -0,0 +1,61 @@
+package models
+
+// StatusResponse represents a simple status-only JSON response.
+type StatusResponse struct {
+	Status string `json:"status"`
+}
+
+// StatusMessageResponse represents a status + message JSON response.
+type StatusMessageResponse struct {
+	Status  string `json:"status"`
+	Message string `json:"message"`
+}
+
+// ErrorResponse represents a standard error JSON response.
+type ErrorResponse struct {
+	Status  string `json:"status"`
+	Message string `json:"message"`
+}
+
+// SnapshotMigrationStats mirrors the snapshot registry migration stats payload.
+type SnapshotMigrationStats struct {
+	HourlyRenamed     int `json:"HourlyRenamed"`
+	HourlyRegistered  int `json:"HourlyRegistered"`
+	DailyRegistered   int `json:"DailyRegistered"`
+	MonthlyRegistered int `json:"MonthlyRegistered"`
+	Errors            int `json:"Errors"`
+}
+
+// SnapshotMigrationResponse captures snapshot registry migration results.
+type SnapshotMigrationResponse struct {
+	Status string                 `json:"status"`
+	Error  string                 `json:"error,omitempty"`
+	Stats  SnapshotMigrationStats `json:"stats"`
+}
+
+// SnapshotRegenerateReportsResponse describes the hourly report regeneration response.
+type SnapshotRegenerateReportsResponse struct {
+	Status       string `json:"status"`
+	Total        int    `json:"total"`
+	Regenerated  int    `json:"regenerated"`
+	Skipped      int    `json:"skipped"`
+	Errors       int    `json:"errors"`
+	ReportsDir   string `json:"reports_dir"`
+	SnapshotType string `json:"snapshotType"`
+}
+
+// SnapshotRepairResponse describes the daily snapshot repair response.
+type SnapshotRepairResponse struct {
+	Status   string `json:"status"`
+	Repaired string `json:"repaired"`
+	Failed   string `json:"failed"`
+}
+
+// SnapshotRepairSuiteResponse describes the full repair suite response.
+type SnapshotRepairSuiteResponse struct {
+	Status         string `json:"status"`
+	DailyRepaired  string `json:"daily_repaired"`
+	DailyFailed    string `json:"daily_failed"`
+	MonthlyRefined string `json:"monthly_refined"`
+	MonthlyFailed  string `json:"monthly_failed"`
+}