observer/server/biz/model/dto/admin.go

package dto

import (
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
	"github.com/gogf/gf/v2/os/gtime"
)

// 后台管理端接口聚合（组前缀 /api/v1/admin，path 相对组）。
// service 按表归入各表文件（订单→order、授权→license），controller 聚合 admin。

// ---------- 订单管理 ----------

// AdminOrderListReq 订单列表查询
type AdminOrderListReq struct {
	g.Meta   `path:"/orders" method:"get" summary:"订单列表" tags:"管理端"`
	PhoneNum string      `json:"phoneNum" v:"length:0,20"        dc:"手机号精确匹配"`
	Status   string      `json:"status"   v:"in:created,paid,closed" dc:"订单状态"`
	StartAt  *gtime.Time `json:"startAt"  dc:"下单时间起(含)"`
	EndAt    *gtime.Time `json:"endAt"    dc:"下单时间止(含)"`
	Page     int         `json:"page"     v:"integer|min:1"      dc:"页码,默认 1"`
	Size     int         `json:"size"     v:"integer|min:1|max:100" dc:"每页条数,默认 20"`
}

// AdminOrderItem 订单条目（金额整数分，前端展示 ÷100）
type AdminOrderItem struct {
	OrderId     string      `json:"orderId"`
	PhoneNum    string      `json:"phoneNum"`
	PlanId      string      `json:"planId"`
	Channel     string      `json:"channel"`
	AmountCents int64       `json:"amountCents"`
	Status      string      `json:"status"`
	CreatedAt   *gtime.Time `json:"createdAt"`
	PaidAt      *gtime.Time `json:"paidAt"`
}

type AdminOrderListRes struct {
	Total int64             `json:"total"`
	List  []*AdminOrderItem `json:"list"`
}

// ---------- 授权管理 ----------

// AdminLicenseListReq 账号/授权列表查询
type AdminLicenseListReq struct {
	g.Meta   `path:"/licenses" method:"get" summary:"账号列表" tags:"管理端"`
	PhoneNum string `json:"phoneNum" v:"length:0,20"   dc:"手机号模糊匹配"`
	Page     int    `json:"page"     v:"integer|min:1" dc:"页码,默认 1"`
	Size     int    `json:"size"     v:"integer|min:1|max:100" dc:"每页条数,默认 20"`
}

// AdminLicenseItem 账号条目（未充值时 expiresAt 为 null；remark 为管理端备注）
type AdminLicenseItem struct {
	PhoneNum  string      `json:"phoneNum"`
	ExpiresAt *gtime.Time `json:"expiresAt"`
	Remark    string      `json:"remark"`
	CreatedAt *gtime.Time `json:"createdAt"`
	UpdatedAt *gtime.Time `json:"updatedAt"`
}

type AdminLicenseListRes struct {
	Total int64               `json:"total"`
	List  []*AdminLicenseItem `json:"list"`
}

// AdminGrantReq 手动授权（免费发卡，与支付回调同自然日叠加语义；未注册账号自动建占位行）
type AdminGrantReq struct {
	g.Meta   `path:"/licenses/grant" method:"post" summary:"手动授权" tags:"管理端"`
	PhoneNum string `json:"phoneNum" v:"required|length:6,20" dc:"手机号"`
	PlanId   string `json:"planId"   v:"required"             dc:"套餐标识（需在 config.yml plans 存在）"`
}

type AdminGrantRes struct {
	ExpiresAt *gtime.Time `json:"expiresAt"`
}

// AdminRevokeReq 撤销授权（清授权保留账号）
type AdminRevokeReq struct {
	g.Meta   `path:"/licenses/revoke" method:"post" summary:"撤销授权" tags:"管理端"`
	PhoneNum string `json:"phoneNum" v:"required|length:6,20" dc:"手机号"`
}

type AdminRevokeRes struct{}

// AdminRemarkReq 写账号备注（空串即清空；仅管理端可见，客户端接口不含该字段）
type AdminRemarkReq struct {
	g.Meta   `path:"/licenses/remark" method:"post" summary:"写账号备注" tags:"管理端"`
	PhoneNum string `json:"phoneNum" v:"required|length:6,20" dc:"手机号"`
	Remark   string `json:"remark"   v:"length:0,200"         dc:"备注内容,空串清空"`
}

type AdminRemarkRes struct{}

// ---------- App 版本管理 ----------

// AdminAppVersionListReq 版本记录列表（按下发时间倒序）
type AdminAppVersionListReq struct {
	g.Meta `path:"/app-versions" method:"get" summary:"版本记录列表" tags:"管理端"`
	Page   int `json:"page" v:"integer|min:1" dc:"页码,默认 1"`
	Size   int `json:"size" v:"integer|min:1|max:100" dc:"每页条数,默认 20"`
}

// AdminAppVersionItem 版本记录条目
type AdminAppVersionItem struct {
	Id        int64       `json:"id"`
	Version   string      `json:"version"`
	Notes     string      `json:"notes"`
	CreatedAt *gtime.Time `json:"createdAt"`
}

type AdminAppVersionListRes struct {
	Total int64                  `json:"total"`
	List  []*AdminAppVersionItem `json:"list"`
}

// AdminAppVersionAddReq 下发新版本（multipart/form-data：notes + APK 文件；
// 版本号从文件名识别，文件须命名为 observer-x.y.z.apk；version UNIQUE 防重复下发；
// APK 覆盖保存固定文件，目录永远只有一个文件；检测到新版本即强制更新，无普通/强制之分）
type AdminAppVersionAddReq struct {
	g.Meta `path:"/app-versions" method:"post" summary:"下发新版本" tags:"管理端" mime:"multipart/form-data"`
	Notes  string            `json:"notes" v:"length:0,500" dc:"更新说明"`
	File   *ghttp.UploadFile `json:"file"  dc:"APK 文件（文件名须为 observer-x.y.z.apk）"`
}

type AdminAppVersionAddRes struct{}

// AdminAppVersionDeleteReq 删除版本记录（删最新版本联动删除 APK 文件，删历史版本仅删记录）
type AdminAppVersionDeleteReq struct {
	g.Meta `path:"/app-versions/delete" method:"post" summary:"删除版本" tags:"管理端"`
	Id     int64 `json:"id" v:"required|min:1" dc:"版本记录 id"`
}

type AdminAppVersionDeleteRes struct{}