feat: swag.

controllers/gateway.go

@@ -36,9 +36,17 @@ func NewGatewayAdminController() *GatewayAdminController {
 	return &GatewayAdminController{DB: config.DB}
 }
 
-// List 获取网关列表
-// GET /api/v1/gateways?keyword=&isSold=&projectType=&regionId=
-// 超级管理员可查询全部；操作员/区域管理员仅能查询所属 regionIDs 的网关
+// @Summary 获取网关列表
+// @Description 查询网关列表，支持关键词/售出状态/项目类型/区域筛选。超级管理员可查全部，操作员只能查所属区域
+// @Tags 网关管理
+// @Produce json
+// @Param keyword query string false "关键词(名称/MAC模糊搜索)"
+// @Param isSold query bool false "售出状态"
+// @Param projectType query string false "项目类型"
+// @Param regionId query int false "区域ID"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Router /admin/gateways [get]
 func (gc *GatewayAdminController) List(c *gin.Context) {
 	var items []models.Gateway
 	query := gc.DB.Model(&models.Gateway{}).Order("region_id ASC, created_at DESC")
@@ -91,8 +99,16 @@ func (gc *GatewayAdminController) List(c *gin.Context) {
 	writeSuccess(c, http.StatusOK, "查询成功", items)
 }
 
-// GetByMACForUser 按 MAC 查询网关信息
-// GET /api/v1/gateways/by-mac?mac=
+// @Summary 按MAC查询网关
+// @Description 根据MAC地址查询网关信息（支持格式兼容：带冒号/横线/纯数字）
+// @Tags 网关管理
+// @Produce json
+// @Param mac query string true "MAC地址"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Failure 400 {object} SwagAPIResponse "MAC参数为空"
+// @Failure 404 {object} SwagAPIResponse "未找到该网关"
+// @Router /gateways/by-mac [get]
 func (gc *GatewayAdminController) GetByMACForUser(c *gin.Context) {
 	macInput := strings.ToUpper(strings.TrimSpace(c.Query("mac")))
 	if macInput == "" {
@@ -132,8 +148,17 @@ func (gc *GatewayAdminController) GetByMACForUser(c *gin.Context) {
 	writeSuccess(c, http.StatusOK, "查询成功", item)
 }
 
-// Create 创建新网关
-// POST /api/gateways
+// @Summary 创建网关
+// @Description 创建新的网关记录，自动同步到产品库存
+// @Tags 网关管理
+// @Accept json
+// @Produce json
+// @Param gateway body gatewayPayload true "网关信息"
+// @Security BearerAuth
+// @Success 201 {object} SwagAPIResponse "创建成功"
+// @Failure 400 {object} SwagAPIResponse "请求参数错误"
+// @Failure 409 {object} SwagAPIResponse "MAC地址已存在"
+// @Router /admin/gateways [post]
 func (gc *GatewayAdminController) Create(c *gin.Context) {
 	var payload gatewayPayload
 	if err := c.ShouldBindJSON(&payload); err != nil {
@@ -188,8 +213,18 @@ func (gc *GatewayAdminController) Create(c *gin.Context) {
 	writeSuccess(c, http.StatusCreated, "创建成功", record)
 }
 
-// Update 更新网关信息
-// PUT /api/gateways/:id
+// @Summary 更新网关信息
+// @Description 更新指定网关的详细信息，自动同步到产品库存
+// @Tags 网关管理
+// @Accept json
+// @Produce json
+// @Param id path int true "网关ID"
+// @Param gateway body gatewayPayload true "更新信息"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "更新成功"
+// @Failure 400 {object} SwagAPIResponse "请求参数错误"
+// @Failure 404 {object} SwagAPIResponse "网关不存在"
+// @Router /admin/gateways/{id} [put]
 func (gc *GatewayAdminController) Update(c *gin.Context) {
 	record, err := gc.findByID(c.Param("id"))
 	if err != nil {
@@ -246,8 +281,16 @@ func (gc *GatewayAdminController) Update(c *gin.Context) {
 	writeSuccess(c, http.StatusOK, "更新成功", record)
 }
 
-// Delete 删除网关
-// DELETE /api/gateways/:id
+// @Summary 删除网关
+// @Description 删除指定网关（已售出的网关禁止删除），自动同步删除产品库存
+// @Tags 网关管理
+// @Produce json
+// @Param id path int true "网关ID"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "删除成功"
+// @Failure 403 {object} SwagAPIResponse "已售出无法删除"
+// @Failure 404 {object} SwagAPIResponse "网关不存在"
+// @Router /admin/gateways/{id} [delete]
 func (gc *GatewayAdminController) Delete(c *gin.Context) {
 	record, err := gc.findByID(c.Param("id"))
 	if err != nil {