refactor: привести кодовую базу в соответствие с канонами bible

- 400 → 422 для всех ошибок валидации входных данных (handlers: export, quote, sync, vendor_spec, partnumber_books, pricelist)
- SQL-запросы вынесены из handlers в localdb (partnumber_books, pricelist, support_bundle); ValidateMariaDBConnection перенесён в internal/db/validate.go
- List-ответы унифицированы: ключ items, поля total_count/page/per_page/total_pages (component, pricelist, partnumber_books); шаблоны обновлены
- Молчаливые ошибки заменены на slog.Warn/Error (support_bundle, vendor_spec, component, configuration, local_configuration, localdb)
- N+1 запросы устранены: batch-запросы в export.go и vendor_workspace_import.go
- fmt.Println → slog в cmd/ (qfs, migrate, migrate_ops_projects, migrate_project_updated_at)
- Заголовки recovery/verify добавлены во все 28 SQL-миграций
- Добавлены bible-local/runtime-flows.md и bible-local/decisions/
- Обновлён субмодуль bible до v0.2.0-13

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

internal/handlers/component.go

@@ -64,11 +64,16 @@ func (h *ComponentHandler) List(c *gin.Context) {
 		}
 	}
 
+	totalPages := int((total + int64(perPage) - 1) / int64(perPage))
+	if totalPages < 1 {
+		totalPages = 1
+	}
 	c.JSON(http.StatusOK, &services.ComponentListResult{
-		Components: components,
-		Total:      total,
+		Items:      components,
+		TotalCount: total,
 		Page:       page,
 		PerPage:    perPage,
+		TotalPages: totalPages,
 	})
 }
 

internal/handlers/export.go

@@ -60,7 +60,7 @@ type ProjectExportOptionsRequest struct {
 func (h *ExportHandler) ExportCSV(c *gin.Context) {
 	var req ExportRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -68,7 +68,7 @@ func (h *ExportHandler) ExportCSV(c *gin.Context) {
 
 	// Validate before streaming (can return JSON error)
 	if len(data.Configs) == 0 || len(data.Configs[0].Items) == 0 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "no items to export"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "no items to export"})
 		return
 	}
 
@@ -160,7 +160,7 @@ func (h *ExportHandler) ExportConfigCSV(c *gin.Context) {
 
 	// Validate before streaming (can return JSON error)
 	if len(data.Configs) == 0 || len(data.Configs[0].Items) == 0 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "no items to export"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "no items to export"})
 		return
 	}
 
@@ -206,7 +206,7 @@ func (h *ExportHandler) ExportProjectCSV(c *gin.Context) {
 	}
 
 	if len(result.Configs) == 0 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "no configurations to export"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "no configurations to export"})
 		return
 	}
 
@@ -228,7 +228,7 @@ func (h *ExportHandler) ExportConfigPricingCSV(c *gin.Context) {
 
 	var req ProjectExportOptionsRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -285,7 +285,7 @@ func (h *ExportHandler) ExportProjectPricingCSV(c *gin.Context) {
 
 	var req ProjectExportOptionsRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -301,7 +301,7 @@ func (h *ExportHandler) ExportProjectPricingCSV(c *gin.Context) {
 		return
 	}
 	if len(result.Configs) == 0 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "no configurations to export"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "no configurations to export"})
 		return
 	}
 

internal/handlers/export_test.go

@@ -128,8 +128,8 @@ func TestExportCSV_InvalidRequest(t *testing.T) {
 	handler.ExportCSV(c)
 
 	// Should return 400 Bad Request
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("Expected status 400, got %d", w.Code)
+	if w.Code != http.StatusUnprocessableEntity {
+		t.Errorf("Expected status 422, got %d", w.Code)
 	}
 
 	// Should return JSON error
@@ -162,8 +162,8 @@ func TestExportCSV_EmptyItems(t *testing.T) {
 	handler.ExportCSV(c)
 
 	// Should return 400 Bad Request (validation error from gin binding)
-	if w.Code != http.StatusBadRequest {
-		t.Logf("Status code: %d (expected 400 for empty items)", w.Code)
+	if w.Code != http.StatusUnprocessableEntity {
+		t.Logf("Status code: %d (expected 422 for empty items)", w.Code)
 	}
 }
 
@@ -294,8 +294,8 @@ func TestExportConfigCSV_EmptyItems(t *testing.T) {
 	handler.ExportConfigCSV(c)
 
 	// Should return 400 Bad Request
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("Expected status 400, got %d", w.Code)
+	if w.Code != http.StatusUnprocessableEntity {
+		t.Errorf("Expected status 422, got %d", w.Code)
 	}
 
 	// Should return JSON error

internal/handlers/partnumber_books.go

@@ -51,8 +51,11 @@ func (h *PartnumberBooksHandler) List(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{
-		"books": summaries,
-		"total": len(summaries),
+		"items":       summaries,
+		"total_count": len(summaries),
+		"page":        1,
+		"per_page":    len(summaries),
+		"total_pages": 1,
 	})
 }
 
@@ -62,7 +65,7 @@ func (h *PartnumberBooksHandler) GetItems(c *gin.Context) {
 	idStr := c.Param("id")
 	id, err := strconv.ParseUint(idStr, 10, 64)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid book ID"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "invalid book ID"})
 		return
 	}
 
@@ -77,9 +80,8 @@ func (h *PartnumberBooksHandler) GetItems(c *gin.Context) {
 		perPage = 100
 	}
 
-	// Find local book by server_id
-	var book localdb.LocalPartnumberBook
-	if err := h.localDB.DB().Where("server_id = ?", id).First(&book).Error; err != nil {
+	book, err := h.localDB.GetLocalPartnumberBookByServerID(uint(id))
+	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "partnumber book not found"})
 		return
 	}
@@ -90,15 +92,20 @@ func (h *PartnumberBooksHandler) GetItems(c *gin.Context) {
 		return
 	}
 
+	totalPages := int((total + int64(perPage) - 1) / int64(perPage))
+	if totalPages < 1 {
+		totalPages = 1
+	}
 	c.JSON(http.StatusOK, gin.H{
 		"book_id":     book.ServerID,
 		"version":     book.Version,
 		"is_active":   book.IsActive,
 		"partnumbers": book.PartnumbersJSON,
 		"items":       items,
-		"total":       total,
+		"total_count": total,
 		"page":        page,
 		"per_page":    perPage,
+		"total_pages": totalPages,
 		"search":      search,
 		"book_total":  bookRepo.CountBookItems(book.ID),
 		"lot_count":   bookRepo.CountDistinctLots(book.ID),

internal/handlers/pricelist.go

@@ -106,11 +106,16 @@ func (h *PricelistHandler) List(c *gin.Context) {
 		})
 	}
 
+	totalPages := (total + perPage - 1) / perPage
+	if totalPages < 1 {
+		totalPages = 1
+	}
 	c.JSON(http.StatusOK, gin.H{
-		"pricelists": summaries,
-		"total":      total,
-		"page":       page,
-		"per_page":   perPage,
+		"items":       summaries,
+		"total_count": total,
+		"page":        page,
+		"per_page":    perPage,
+		"total_pages": totalPages,
 	})
 }
 
@@ -119,7 +124,7 @@ func (h *PricelistHandler) Get(c *gin.Context) {
 	idStr := c.Param("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid pricelist ID"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "invalid pricelist ID"})
 		return
 	}
 
@@ -146,7 +151,7 @@ func (h *PricelistHandler) GetItems(c *gin.Context) {
 	idStr := c.Param("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid pricelist ID"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "invalid pricelist ID"})
 		return
 	}
 
@@ -165,40 +170,21 @@ func (h *PricelistHandler) GetItems(c *gin.Context) {
 	if perPage < 1 {
 		perPage = 50
 	}
-	var items []localdb.LocalPricelistItem
-	dbq := h.localDB.DB().Model(&localdb.LocalPricelistItem{}).Where("pricelist_id = ?", localPL.ID)
-	if strings.TrimSpace(search) != "" {
-		dbq = dbq.Where("lot_name LIKE ?", "%"+strings.TrimSpace(search)+"%")
-	}
-	var total int64
-	if err := dbq.Count(&total).Error; err != nil {
-		RespondError(c, http.StatusInternalServerError, "internal server error", err)
-		return
-	}
-	offset := (page - 1) * perPage
 
-	if err := dbq.Order("lot_name").Offset(offset).Limit(perPage).Find(&items).Error; err != nil {
+	items, total, err := h.localDB.GetLocalPricelistItemsPage(localPL.ID, strings.TrimSpace(search), page, perPage)
+	if err != nil {
 		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
+
 	lotNames := make([]string, len(items))
 	for i, item := range items {
 		lotNames[i] = item.LotName
 	}
-	type compRow struct {
-		LotName        string
-		LotDescription string
-	}
-	var comps []compRow
-	if len(lotNames) > 0 {
-		h.localDB.DB().Table("local_components").
-			Select("lot_name, lot_description").
-			Where("lot_name IN ?", lotNames).
-			Scan(&comps)
-	}
-	descMap := make(map[string]string, len(comps))
-	for _, c := range comps {
-		descMap[c.LotName] = c.LotDescription
+	descMap, err := h.localDB.GetLocalComponentDescriptionsByLotNames(lotNames)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
+		return
 	}
 
 	resultItems := make([]gin.H, 0, len(items))
@@ -217,12 +203,14 @@ func (h *PricelistHandler) GetItems(c *gin.Context) {
 		})
 	}
 
+	totalPages := int((total + int64(perPage) - 1) / int64(perPage))
 	c.JSON(http.StatusOK, gin.H{
-		"source":   localPL.Source,
-		"items":    resultItems,
-		"total":    total,
-		"page":     page,
-		"per_page": perPage,
+		"source":      localPL.Source,
+		"items":       resultItems,
+		"total_count": total,
+		"page":        page,
+		"per_page":    perPage,
+		"total_pages": totalPages,
 	})
 }
 
@@ -230,7 +218,7 @@ func (h *PricelistHandler) GetLotNames(c *gin.Context) {
 	idStr := c.Param("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid pricelist ID"})
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "invalid pricelist ID"})
 		return
 	}
 

internal/handlers/pricelist_test.go

@@ -141,21 +141,21 @@ func TestPricelistList_ActiveOnlyExcludesPricelistsWithoutItems(t *testing.T) {
 	}
 
 	var resp struct {
-		Pricelists []struct {
+		Items []struct {
 			ID uint `json:"id"`
-		} `json:"pricelists"`
-		Total int `json:"total"`
+		} `json:"items"`
+		TotalCount int `json:"total_count"`
 	}
 	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
 		t.Fatalf("unmarshal response: %v", err)
 	}
-	if resp.Total != 1 {
-		t.Fatalf("expected total=1, got %d", resp.Total)
+	if resp.TotalCount != 1 {
+		t.Fatalf("expected total=1, got %d", resp.TotalCount)
 	}
-	if len(resp.Pricelists) != 1 {
-		t.Fatalf("expected 1 pricelist, got %d", len(resp.Pricelists))
+	if len(resp.Items) != 1 {
+		t.Fatalf("expected 1 pricelist, got %d", len(resp.Items))
 	}
-	if resp.Pricelists[0].ID != 10 {
-		t.Fatalf("expected pricelist id=10, got %d", resp.Pricelists[0].ID)
+	if resp.Items[0].ID != 10 {
+		t.Fatalf("expected pricelist id=10, got %d", resp.Items[0].ID)
 	}
 }

internal/handlers/quote.go

@@ -18,13 +18,13 @@ func NewQuoteHandler(quoteService *services.QuoteService) *QuoteHandler {
 func (h *QuoteHandler) Validate(c *gin.Context) {
 	var req services.QuoteRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
 	result, err := h.quoteService.ValidateAndCalculate(&req)
 	if err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -34,13 +34,13 @@ func (h *QuoteHandler) Validate(c *gin.Context) {
 func (h *QuoteHandler) Calculate(c *gin.Context) {
 	var req services.QuoteRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
 	result, err := h.quoteService.ValidateAndCalculate(&req)
 	if err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -53,13 +53,13 @@ func (h *QuoteHandler) Calculate(c *gin.Context) {
 func (h *QuoteHandler) PriceLevels(c *gin.Context) {
 	var req services.PriceLevelsRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
 	result, err := h.quoteService.CalculatePriceLevels(&req)
 	if err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 

internal/handlers/setup.go

@@ -1,7 +1,6 @@
 package handlers
 
 import (
-	"errors"
 	"fmt"
 	"html/template"
 	"log/slog"
@@ -15,9 +14,6 @@ import (
 	"git.mchus.pro/mchus/quoteforge/internal/localdb"
 	"github.com/gin-gonic/gin"
 	mysqlDriver "github.com/go-sql-driver/mysql"
-	gormmysql "gorm.io/driver/mysql"
-	"gorm.io/gorm"
-	"gorm.io/gorm/logger"
 )
 
 type SetupHandler struct {
@@ -27,8 +23,6 @@ type SetupHandler struct {
 	restartSig chan struct{}
 }
 
-var errPermissionProbeRollback = errors.New("permission probe rollback")
-
 func NewSetupHandler(localDB *localdb.LocalDB, connMgr *db.ConnectionManager, _ string, restartSig chan struct{}) (*SetupHandler, error) {
 	funcMap := template.FuncMap{
 		"sub": func(a, b int) int { return a - b },
@@ -93,7 +87,7 @@ func (h *SetupHandler) TestConnection(c *gin.Context) {
 	}
 
 	dsn := buildMySQLDSN(host, port, database, user, password, 5*time.Second)
-	lotCount, canWrite, err := validateMariaDBConnection(dsn)
+	lotCount, canWrite, err := db.ValidateMariaDBConnection(dsn)
 	if err != nil {
 		_ = c.Error(err)
 		c.JSON(http.StatusOK, gin.H{
@@ -135,7 +129,7 @@ func (h *SetupHandler) SaveConnection(c *gin.Context) {
 
 	// Test connection first
 	dsn := buildMySQLDSN(host, port, database, user, password, 5*time.Second)
-	if _, _, err := validateMariaDBConnection(dsn); err != nil {
+	if _, _, err := db.ValidateMariaDBConnection(dsn); err != nil {
 		_ = c.Error(err)
 		c.JSON(http.StatusBadRequest, gin.H{
 			"success": false,
@@ -214,46 +208,3 @@ func buildMySQLDSN(host string, port int, database, user, password string, timeo
 	return cfg.FormatDSN()
 }
 
-func validateMariaDBConnection(dsn string) (int64, bool, error) {
-	db, err := gorm.Open(gormmysql.Open(dsn), &gorm.Config{
-		Logger: logger.Default.LogMode(logger.Silent),
-	})
-	if err != nil {
-		return 0, false, fmt.Errorf("open MariaDB connection: %w", err)
-	}
-
-	sqlDB, err := db.DB()
-	if err != nil {
-		return 0, false, fmt.Errorf("get database handle: %w", err)
-	}
-	defer sqlDB.Close()
-
-	if err := sqlDB.Ping(); err != nil {
-		return 0, false, fmt.Errorf("ping MariaDB: %w", err)
-	}
-
-	var lotCount int64
-	if err := db.Table("lot").Count(&lotCount).Error; err != nil {
-		return 0, false, fmt.Errorf("check required table lot: %w", err)
-	}
-
-	return lotCount, testSyncWritePermission(db), nil
-}
-
-func testSyncWritePermission(db *gorm.DB) bool {
-	sentinel := fmt.Sprintf("quoteforge-permission-check-%d", time.Now().UnixNano())
-	err := db.Transaction(func(tx *gorm.DB) error {
-		if err := tx.Exec(`
-			INSERT INTO qt_client_schema_state (username, hostname, last_checked_at, updated_at)
-			VALUES (?, ?, NOW(), NOW())
-			ON DUPLICATE KEY UPDATE
-				last_checked_at = VALUES(last_checked_at),
-				updated_at = VALUES(updated_at)
-		`, sentinel, "setup-check").Error; err != nil {
-			return err
-		}
-		return errPermissionProbeRollback
-	})
-
-	return errors.Is(err, errPermissionProbeRollback)
-}

internal/handlers/support_bundle.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"log/slog"
 	"net"
 	"net/http"
 	"os"
@@ -39,7 +40,10 @@ func NewSupportBundleHandler(local *localdb.LocalDB, connMgr *db.ConnectionManag
 // GET /api/support-bundle
 func (h *SupportBundleHandler) DownloadBundle(c *gin.Context) {
 	now := time.Now().UTC()
-	hostname, _ := os.Hostname()
+	hostname, err := os.Hostname()
+	if err != nil {
+		slog.Warn("support bundle: could not get hostname", "err", err)
+	}
 
 	c.Header("Content-Type", "application/zip")
 	c.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="qfs-bundle-%s.zip"`, now.Format("20060102-150405")))
@@ -153,8 +157,10 @@ func (h *SupportBundleHandler) DownloadBundle(c *gin.Context) {
 	}
 
 	// schema_migrations.json
-	var migrations []localdb.LocalSchemaMigration
-	_ = h.localDB.DB().Order("applied_at ASC").Find(&migrations).Error
+	migrations, err := h.localDB.GetSchemaMigrations()
+	if err != nil {
+		slog.Warn("support bundle: could not load schema migrations", "err", err)
+	}
 	writeJSON("schema_migrations.json", migrations)
 
 	// app.log (tail 5 MiB)
@@ -169,7 +175,9 @@ func (h *SupportBundleHandler) DownloadBundle(c *gin.Context) {
 				}
 				if _, err := f.Seek(offset, io.SeekStart); err == nil {
 					if w, err := zw.Create("app.log"); err == nil {
-						_, _ = io.Copy(w, f)
+						if _, err := io.Copy(w, f); err != nil {
+							slog.Warn("support bundle: error copying log file", "err", err)
+						}
 					}
 				}
 			}

internal/handlers/sync.go

@@ -739,7 +739,7 @@ func (h *SyncHandler) ReportPartnumberSeen(c *gin.Context) {
 		} `json:"items"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 

internal/handlers/vendor_spec.go

@@ -2,6 +2,7 @@ package handlers
 
 import (
 	"errors"
+	"log/slog"
 	"net/http"
 	"strings"
 
@@ -65,7 +66,7 @@ func (h *VendorSpecHandler) PutVendorSpec(c *gin.Context) {
 		VendorSpec []localdb.VendorSpecItem `json:"vendor_spec"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -136,7 +137,7 @@ func (h *VendorSpecHandler) ResolveVendorSpec(c *gin.Context) {
 		VendorSpec []localdb.VendorSpecItem `json:"vendor_spec"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}
 
@@ -149,7 +150,11 @@ func (h *VendorSpecHandler) ResolveVendorSpec(c *gin.Context) {
 		return
 	}
 
-	book, _ := bookRepo.GetActiveBook()
+	book, err := bookRepo.GetActiveBook()
+	if err != nil {
+		slog.Warn("vendor spec resolve: no active partnumber book", "err", err)
+		book = nil
+	}
 	aggregated, err := services.AggregateLOTs(resolved, book, bookRepo)
 	if err != nil {
 		RespondError(c, http.StatusInternalServerError, "internal server error", err)
@@ -179,7 +184,7 @@ func (h *VendorSpecHandler) ApplyVendorSpec(c *gin.Context) {
 		} `json:"items"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		RespondError(c, http.StatusBadRequest, "invalid request", err)
+		RespondError(c, http.StatusUnprocessableEntity, "invalid request", err)
 		return
 	}