junhong_cmp_fiber/internal/routes/device.go

package routes

import (
	"github.com/gofiber/fiber/v2"

	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
	"github.com/break/junhong_cmp_fiber/internal/model/dto"
	"github.com/break/junhong_cmp_fiber/pkg/openapi"
)

func registerDeviceRoutes(router fiber.Router, handler *admin.DeviceHandler, importHandler *admin.DeviceImportHandler, doc *openapi.Generator, basePath string) {
	devices := router.Group("/devices")
	groupPath := basePath + "/devices"

	Register(devices, doc, groupPath, "GET", "", handler.List, RouteSpec{
		Summary: "设备列表",
		Tags:    []string{"设备管理"},
		Input:   new(dto.ListDeviceRequest),
		Output:  new(dto.ListDeviceResponse),
		Auth:    true,
	})

	Register(devices, doc, groupPath, "GET", "/:id", handler.GetByID, RouteSpec{
		Summary: "设备详情",
		Tags:    []string{"设备管理"},
		Input:   new(dto.GetDeviceRequest),
		Output:  new(dto.DeviceResponse),
		Auth:    true,
	})

	Register(devices, doc, groupPath, "GET", "/by-imei/:imei", handler.GetByIMEI, RouteSpec{
		Summary: "通过设备号查询设备详情",
		Tags:    []string{"设备管理"},
		Input:   new(dto.GetDeviceByIMEIRequest),
		Output:  new(dto.DeviceResponse),
		Auth:    true,
	})

	Register(devices, doc, groupPath, "DELETE", "/:id", handler.Delete, RouteSpec{
		Summary:     "删除设备",
		Description: "仅平台用户可操作。删除设备时自动解绑所有卡（卡不会被删除）。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.DeleteDeviceRequest),
		Output:      nil,
		Auth:        true,
	})

	Register(devices, doc, groupPath, "GET", "/:id/cards", handler.ListCards, RouteSpec{
		Summary: "获取设备绑定的卡列表",
		Tags:    []string{"设备管理"},
		Input:   new(dto.ListDeviceCardsRequest),
		Output:  new(dto.ListDeviceCardsResponse),
		Auth:    true,
	})

	Register(devices, doc, groupPath, "POST", "/:id/cards", handler.BindCard, RouteSpec{
		Summary:     "绑定卡到设备",
		Description: "仅平台用户可操作。用于导入后调整卡绑定关系（补卡、换卡）。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.BindCardToDeviceRequest),
		Output:      new(dto.BindCardToDeviceResponse),
		Auth:        true,
	})

	Register(devices, doc, groupPath, "DELETE", "/:id/cards/:cardId", handler.UnbindCard, RouteSpec{
		Summary:     "解绑设备上的卡",
		Description: "仅平台用户可操作。解绑不改变卡的 shop_id。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.UnbindCardFromDeviceRequest),
		Output:      new(dto.UnbindCardFromDeviceResponse),
		Auth:        true,
	})

	Register(devices, doc, groupPath, "POST", "/allocate", handler.Allocate, RouteSpec{
		Summary:     "批量分配设备",
		Description: "分配设备给直属下级店铺。分配时自动同步绑定的所有卡的 shop_id。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.AllocateDevicesRequest),
		Output:      new(dto.AllocateDevicesResponse),
		Auth:        true,
	})

	Register(devices, doc, groupPath, "POST", "/recall", handler.Recall, RouteSpec{
		Summary:     "批量回收设备",
		Description: "从直属下级店铺回收设备。回收时自动同步绑定的所有卡的 shop_id。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.RecallDevicesRequest),
		Output:      new(dto.RecallDevicesResponse),
		Auth:        true,
	})

	Register(devices, doc, groupPath, "POST", "/import", importHandler.Import, RouteSpec{
		Summary: "批量导入设备",
		Description: `仅平台用户可操作。文件格式已从 CSV 升级为 Excel (.xlsx)。

### 完整导入流程

1. **获取上传 URL**: 调用 ` + "`POST /api/admin/storage/upload-url`" + `
2. **上传 Excel 文件**: 使用预签名 URL 上传文件到对象存储
3. **调用本接口**: 使用返回的 ` + "`file_key`" + ` 提交导入任务

### Excel 文件格式

- 文件格式：仅支持 .xlsx (Excel 2007+)
- 必须包含列（首行为表头）:
  - ` + "`device_no`" + `: 设备号（必填，唯一）
  - ` + "`device_name`" + `: 设备名称
  - ` + "`device_model`" + `: 设备型号
  - ` + "`device_type`" + `: 设备类型
  - ` + "`max_sim_slots`" + `: 最大插槽数（默认4）
  - ` + "`manufacturer`" + `: 制造商
  - ` + "`iccid_1`" + ` ~ ` + "`iccid_4`" + `: 绑定的卡 ICCID（卡必须已存在且未绑定）
- 列格式：设置为文本格式(避免长数字被转为科学记数法)`,
		Tags:   []string{"设备管理"},
		Input:  new(dto.ImportDeviceRequest),
		Output: new(dto.ImportDeviceResponse),
		Auth:   true,
	})

	Register(devices, doc, groupPath, "GET", "/import/tasks", importHandler.List, RouteSpec{
		Summary:     "导入任务列表",
		Description: "仅平台用户可操作。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.ListDeviceImportTaskRequest),
		Output:      new(dto.ListDeviceImportTaskResponse),
		Auth:        true,
	})

	Register(devices, doc, groupPath, "GET", "/import/tasks/:id", importHandler.GetByID, RouteSpec{
		Summary:     "导入任务详情",
		Description: "仅平台用户可操作。包含跳过和失败记录的详细信息。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.GetDeviceImportTaskRequest),
		Output:      new(dto.DeviceImportTaskDetailResponse),
		Auth:        true,
	})

	Register(devices, doc, groupPath, "PATCH", "/series-binding", handler.BatchSetSeriesBinding, RouteSpec{
		Summary:     "批量设置设备的套餐系列绑定",
		Description: "批量设置或清除设备与套餐系列分配的关联关系。series_allocation_id 为 0 时表示清除关联。",
		Tags:        []string{"设备管理"},
		Input:       new(dto.BatchSetDeviceSeriesBindngRequest),
		Output:      new(dto.BatchSetDeviceSeriesBindngResponse),
		Auth:        true,
	})
}