// Package v1 defines the public common API contracts served at /api/common/v1.
//
// These endpoints are open to any frontend client (mini/h5/app) and require
// no authentication. Implementations live in internal/controller/common and
// reuse the common/tools Go packages as their backend.
package v1

import "github.com/gogf/gf/v2/frame/g"

// UUIDReq generates a unique ID.
type UUIDReq struct {
	g.Meta `path:"/tools/uuid" method:"get" tags:"Common/Tools" summary:"Generate a unique ID"`
	Short  bool `json:"short"` // true: 8-char short code; false: 32-char ID
}

// UUIDRes is the response of UUIDReq.
type UUIDRes struct {
	UUID string `json:"uuid"`
}

// MD5Req computes an MD5 digest.
type MD5Req struct {
	g.Meta `path:"/tools/md5" method:"post" tags:"Common/Tools" summary:"Compute MD5 digest"`
	Text   string `json:"text" v:"required#text required"`
}

// MD5Res is the response of MD5Req.
type MD5Res struct {
	MD5 string `json:"md5"`
}

// RandomReq generates a random string.
type RandomReq struct {
	g.Meta `path:"/tools/random" method:"get" tags:"Common/Tools" summary:"Generate a random string"`
	Length int    `json:"length" d:"16" v:"min:1|max:128#length must be 1-128"`
	Type   string `json:"type" d:"alnum" v:"in:alnum,digits,letters#unsupported type"`
}

// RandomRes is the response of RandomReq.
type RandomRes struct {
	Value string `json:"value"`
}

// TimeReq returns the current server time.
type TimeReq struct {
	g.Meta `path:"/tools/time" method:"get" tags:"Common/Tools" summary:"Current server time"`
}

// TimeRes is the response of TimeReq.
type TimeRes struct {
	Timestamp int64  `json:"timestamp"` // unix seconds
	DateTime  string `json:"dateTime"`  // 2006-01-02 15:04:05
	Date      string `json:"date"`      // 2006-01-02
}

// IPReq returns the caller's IP information.
type IPReq struct {
	g.Meta `path:"/tools/ip" method:"get" tags:"Common/Tools" summary:"Client IP info"`
}

// IPRes is the response of IPReq.
type IPRes struct {
	IP       string `json:"ip"`
	Internal bool   `json:"internal"` // whether the IP is a private/internal address
}