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, }) }