小程序一些功能更新

2026-09-29 10:57:01 +08:00
parent 0cb70a7618
commit 3bb7fa8db3
96 changed files with 13890 additions and 213 deletions
--- a/api/admin/v1/coupon.go
+++ b/api/admin/v1/coupon.go
@@ -0,0 +1,128 @@
+package v1
+
+import "github.com/gogf/gf/v2/frame/g"
+
+// ============================================================================
+// 管理端优惠券契约：券模板（A6–A8）+ 发放/记录/核销（A9–A11）
+// ============================================================================
+
+// CouponTemplateItem 券模板列表项
+type CouponTemplateItem struct {
+	Id             int64    `json:"id"`
+	Title          string   `json:"title"`
+	SubTitle       string   `json:"sub_title"`
+	CouponType     int      `json:"coupon_type"`
+	Kind           int      `json:"kind"`
+	Value          int      `json:"value"`
+	ThresholdCents int      `json:"threshold_cents"`
+	Scope          int      `json:"scope"`
+	ScopeKeys      []string `json:"scope_keys"`
+	TotalLimit     int      `json:"total_limit"`
+	PerUserLimit   int      `json:"per_user_limit"`
+	ValidFrom      string   `json:"valid_from"`
+	ValidTo        string   `json:"valid_to"`
+	Status         int      `json:"status"`
+	GrantedCount   int64    `json:"granted_count"` // 已发
+	UsedCount      int64    `json:"used_count"`    // 已用
+}
+
+// CouponTemplateListReq 券模板列表（A6）
+type CouponTemplateListReq struct {
+	g.Meta     `path:"/coupon/template/list" method:"get" tags:"coupon" summary:"券模板列表"`
+	Keyword    string `json:"keyword"`
+	Status     *int   `json:"status"`
+	CouponType *int   `json:"couponType"`
+	Page       int    `json:"page"`
+	PageSize   int    `json:"pageSize"`
+}
+type CouponTemplateListRes struct {
+	List  []CouponTemplateItem `json:"list"`
+	Total int                  `json:"total"`
+}
+
+// CouponTemplateSaveReq 新增/编辑券模板（A7）。
+//
+// CouponType 1 免单券 / 2 展示券；**前端未显式传时后端按 2 兜底（fail-closed）**。
+type CouponTemplateSaveReq struct {
+	g.Meta         `path:"/coupon/template/save" method:"post" tags:"coupon" summary:"保存券模板"`
+	Id             int64    `json:"id"`
+	Title          string   `v:"required#券名不能为空" json:"title"`
+	SubTitle       string   `json:"subTitle"`
+	CouponType     int      `json:"couponType"`
+	Kind           int      `json:"kind"`
+	Value          int      `v:"min:0#面额不能为负" json:"value"`
+	ThresholdCents int      `v:"min:0#门槛不能为负" json:"thresholdCents"`
+	Scope          int      `json:"scope"`
+	ScopeKeys      []string `json:"scopeKeys"`
+	TotalLimit     int      `v:"min:0#总发行上限不能为负" json:"totalLimit"`
+	PerUserLimit   int      `v:"min:0#单人限领不能为负" json:"perUserLimit"`
+	ValidFrom      string   `json:"validFrom"`
+	ValidTo        string   `json:"validTo"`
+	Status         int      `json:"status"`
+	Remark         string   `json:"remark"`
+}
+type CouponTemplateSaveRes struct {
+	Id int64 `json:"id"`
+}
+
+// CouponTemplateToggleReq 启停券模板（A8）
+type CouponTemplateToggleReq struct {
+	g.Meta `path:"/coupon/template/toggle" method:"post" tags:"coupon" summary:"启停券模板"`
+	Id     int64 `v:"required" json:"id"`
+	Status int   `json:"status"`
+}
+type CouponTemplateToggleRes struct{}
+
+// CouponGrantReq 发放优惠券（A9）：单用户 / 批量共用，靠 userIds 数量区分。
+type CouponGrantReq struct {
+	g.Meta   `path:"/coupon/grant" method:"post" tags:"coupon" summary:"发放优惠券"`
+	CouponId int64   `v:"required#请选择券模板" json:"couponId"`
+	UserIds  []int64 `v:"required|min-length:1#请选择要发放的用户" json:"userIds"`
+	Remark   string  `json:"remark"`
+}
+type CouponGrantRes struct {
+	Success  int            `json:"success"`
+	Failed   int            `json:"failed"`
+	Failures []BatchFailure `json:"failures"`
+}
+
+// CouponRecordItem 发放记录项（券面快照 + 占用/核销轨迹）
+type CouponRecordItem struct {
+	Id          int64  `json:"id"`
+	UserId      int64  `json:"user_id"`
+	CouponId    int64  `json:"coupon_id"`
+	Title       string `json:"title"`
+	CouponType  int    `json:"coupon_type"`
+	Kind        int    `json:"kind"`
+	Value       int    `json:"value"`
+	Status      int    `json:"status"`
+	Source      int    `json:"source"`
+	GrantedAt   string `json:"granted_at"`
+	UsedAt      string `json:"used_at"`
+	ExpireAt    string `json:"expire_at"`
+	UsedBy      string `json:"used_by"`
+	UsedOrderNo string `json:"used_order_no"`
+}
+
+// CouponRecordListReq 发放记录列表（A10）
+type CouponRecordListReq struct {
+	g.Meta     `path:"/coupon/record/list" method:"get" tags:"coupon" summary:"优惠券发放记录"`
+	UserId     *int64 `json:"userId"`
+	CouponId   *int64 `json:"couponId"`
+	CouponType *int   `json:"couponType"`
+	Status     *int   `json:"status"`
+	Page       int    `json:"page"`
+	PageSize   int    `json:"pageSize"`
+}
+type CouponRecordListRes struct {
+	List  []CouponRecordItem `json:"list"`
+	Total int                `json:"total"`
+}
+
+// CouponRedeemReq 人工核销（A11）：**仅展示券**；对免单券且 status != 0 返回 4011。
+type CouponRedeemReq struct {
+	g.Meta       `path:"/coupon/redeem" method:"post" tags:"coupon" summary:"人工核销优惠券"`
+	UserCouponId int64  `v:"required" json:"userCouponId"`
+	Remark       string `json:"remark"`
+}
+type CouponRedeemRes struct{}