小程序一些功能更新

api/admin/v1/order.go

@@ -0,0 +1,79 @@
+package v1
+
+import "github.com/gogf/gf/v2/frame/g"
+
+// ============================================================================
+// 管理端「订单管理 + 退款」契约
+//
+// 铁律 S1：请求体 camelCase / 响应 snake_case。
+// 订单来源：member_orders（同一张表承载两类商品，order_type 1=会员套餐 2=次数包）。
+//
+// 退款是可逆性资金动作：POST /order/refund 允许在退款的同时**可选**回收所购服务
+// （revokeService=true 回收权益；false 仅改状态、权益保留）。
+// ============================================================================
+
+// OrderItem 订单列表项。
+type OrderItem struct {
+	Id         int64  `json:"id"`
+	OutTradeNo string `json:"out_trade_no"`
+	// ===== 归属用户信息 =====
+	UserId    int64  `json:"user_id"`
+	Nickname  string `json:"nickname"`
+	Username  string `json:"username"`
+	AvatarUrl string `json:"avatar_url"`
+	// ===== 商品 =====
+	OrderType int    `json:"order_type"` // 1 会员套餐 / 2 次数包
+	Title     string `json:"title"`      // 商品名（会员=套餐名；次数包=工具名·档位名）
+	PlanKey   string `json:"plan_key"`
+	PackKey   string `json:"pack_key"`
+	ToolKey   string `json:"tool_key"`
+	Times     int    `json:"times"` // 次数包次数
+	// ===== 金额（分）=====
+	OriginPriceCents int64 `json:"origin_price_cents"`
+	DiscountCents    int64 `json:"discount_cents"`
+	PaidPriceCents   int64 `json:"paid_price_cents"`
+	PromoKind        int   `json:"promo_kind"` // 0无 1优惠码 2免单券
+	// ===== 状态 =====
+	Status         int    `json:"status"` // 0待支付 1已发货 2已退款 3已关闭
+	StatusText     string `json:"status_text"`
+	ServiceRevoked int    `json:"service_revoked"` // 退款时是否已回收所购服务：0未回收 1已回收
+	// ===== 时间 =====
+	CreatedAt  string `json:"created_at"`  // 创建时间
+	PaidAt     string `json:"paid_at"`     // 支付时间（发货时写入）
+	RefundedAt string `json:"refunded_at"` // 退款时间
+}
+
+// OrderListReq 订单列表（分页 + 关键字 + 状态筛选）。
+type OrderListReq struct {
+	g.Meta   `path:"/order/list" method:"get" tags:"admin" summary:"订单列表"`
+	Page     int `json:"page"`
+	PageSize int `json:"pageSize"`
+	// Keyword 关键字：匹配 订单号 / 用户昵称 / 用户名（模糊）
+	Keyword string `json:"keyword"`
+	// Status 状态筛选：nil=全部（0待支付 1已发货 2已退款 3已关闭）
+	Status *int `json:"status"`
+}
+type OrderListRes struct {
+	List  []OrderItem `json:"list"`
+	Total int         `json:"total"`
+}
+
+// OrderRefundReq 订单退款。
+//
+// RevokeService=true → 退款同时回收所购服务（会员套餐回收有效期；次数包扣回付费次数）；
+// false → 仅改状态为「已退款」，用户权益保留。
+// 仅「已发货(1)」订单可退款；已是「已退款(2)」的订单幂等返回成功但不重复回收权益。
+type OrderRefundReq struct {
+	g.Meta        `path:"/order/refund" method:"post" tags:"admin" summary:"订单退款（可选回收所购服务）"`
+	OutTradeNo    string `v:"required#订单号不能为空" json:"outTradeNo"`
+	RevokeService bool   `json:"revokeService"`
+}
+type OrderRefundRes struct {
+	OutTradeNo      string `json:"out_trade_no"`
+	Status          int    `json:"status"`
+	StatusText      string `json:"status_text"`
+	ServiceRevoked  bool   `json:"service_revoked"`  // 该订单当前是否已回收所购服务
+	Revoked         bool   `json:"revoked"`          // 本次调用是否实际执行了退款动作
+	AlreadyRefunded bool   `json:"already_refunded"` // 幂等命中：调用前已是已退款
+	Message         string `json:"message"`
+}