小程序一些功能更新

api/user/v1/promo.go

@@ -0,0 +1,107 @@
+package v1
+
+import "github.com/gogf/gf/v2/frame/g"
+
+// ============================================================================
+// 用户端优惠凭证域契约（优惠码校验 / 我的券 / 券可用性校验 / 当前订单可选用券）
+//
+// 约定（铁律 S1）：请求 camelCase / 响应 **snake_case**。
+// （架构文档 §4.4.3 此处曾把若干出参写成驼峰，已按 S1 纠正。）
+// ============================================================================
+
+// ===== P1 优惠码校验（服务端为准，前端只展示）=====
+
+// PromoValidateReq 校验优惠码
+type PromoValidateReq struct {
+	g.Meta    `path:"/promo/validate" method:"post" tags:"promo" summary:"校验优惠码"`
+	Code      string `v:"required#请输入优惠码" json:"code"`
+	OrderType int    `v:"required|in:1,2#订单类型非法" json:"orderType"` // 1会员套餐 2次数包
+	TargetKey string `json:"targetKey"`                            // plan_key 或 pack_key
+}
+type PromoValidateRes struct {
+	Valid            bool   `json:"valid"`
+	OriginPriceCents int64  `json:"origin_price_cents"`
+	PaidPriceCents   int64  `json:"paid_price_cents"`
+	DiscountCents    int64  `json:"discount_cents"`
+	ProductId        string `json:"product_id"`
+	Message          string `json:"message"`
+}
+
+// ===== P5 我的优惠券 =====
+
+// CouponMyReq 我的优惠券
+type CouponMyReq struct {
+	g.Meta `path:"/coupon/my" method:"get" tags:"coupon" summary:"我的优惠券"`
+	Status *int `json:"status"` // 可空：0可用 1已用 2已过期
+}
+type CouponMySummary struct {
+	Usable       int `json:"usable"`
+	Freebie      int `json:"freebie"`       // 可抵扣券（仅免单券）
+	ExpiringSoon int `json:"expiring_soon"` // 本月将过期
+	Used         int `json:"used"`
+	Expired      int `json:"expired"`
+}
+type UserCouponItem struct {
+	Id             int64  `json:"id"`
+	CouponId       int64  `json:"coupon_id"`
+	Title          string `json:"title"`
+	SubTitle       string `json:"sub_title"`
+	CouponType     int    `json:"coupon_type"` // 1免单券 2展示券
+	Kind           int    `json:"kind"`
+	Value          int    `json:"value"`
+	ThresholdCents int    `json:"threshold_cents"`
+	Status         int    `json:"status"` // 0未使用 1已使用 2已过期 3已作废
+	ExpireAt       string `json:"expire_at"`
+	GrantedAt      string `json:"granted_at"`
+	UsedAt         string `json:"used_at"`
+}
+type CouponMyRes struct {
+	Summary CouponMySummary  `json:"summary"`
+	List    []UserCouponItem `json:"list"`
+}
+
+// ===== P6 下单前可用性校验（只读，不占用）=====
+
+// CouponValidateReq 校验免单券可用性
+type CouponValidateReq struct {
+	g.Meta       `path:"/coupon/validate" method:"post" tags:"coupon" summary:"校验免单券可用性"`
+	UserCouponId int64  `v:"required" json:"userCouponId"`
+	OrderType    int    `v:"required|in:1,2" json:"orderType"`
+	TargetKey    string `json:"targetKey"`
+}
+type CouponValidateRes struct {
+	Valid            bool   `json:"valid"`
+	CouponType       int    `json:"coupon_type"`
+	IsFreebie        bool   `json:"is_freebie"`
+	ProductId        string `json:"product_id"`
+	PriceCents       int64  `json:"price_cents"`
+	OriginPriceCents int64  `json:"origin_price_cents"`
+	PaidPriceCents   int64  `json:"paid_price_cents"`
+	Message          string `json:"message"`
+}
+
+// ===== P7 当前订单可选用的券（只返免单券）=====
+
+// CouponUsableReq 当前订单可选用的券
+type CouponUsableReq struct {
+	g.Meta    `path:"/coupon/usable" method:"get" tags:"coupon" summary:"当前订单可选用券"`
+	OrderType int    `v:"required|in:1,2" json:"orderType"`
+	TargetKey string `json:"targetKey"`
+	// OutTradeNo 可选（向后兼容）：传入本人订单号时，响应会**保底**返回该订单当前
+	// 已选中的那张免单券并标记 applied=true。原因：下单占用后该券 status 变 1，
+	// 会被「仅返未使用券」的过滤排除，导致用户只有一张券时列表变空、既看不到也换不了。
+	OutTradeNo string `json:"outTradeNo"`
+}
+type UsableCouponItem struct {
+	UserCouponId            int64  `json:"user_coupon_id"`
+	Title                   string `json:"title"`
+	CouponType              int    `json:"coupon_type"`
+	IsFreebie               bool   `json:"is_freebie"`
+	ExpireAt                string `json:"expire_at"`
+	EstimatedPaidPriceCents int64  `json:"estimated_paid_price_cents"`
+	// Applied 是否为「当前订单已选中」的券（默认 false；仅当请求带 outTradeNo 时可能为 true）。
+	Applied bool `json:"applied"`
+}
+type CouponUsableRes struct {
+	List []UsableCouponItem `json:"list"`
+}