tenant: admin batch topup

2025-12-19 13:55:20 +08:00
parent 86a1a0a2cc
commit 17d51d5ed2
11 changed files with 771 additions and 3 deletions
--- a/backend/docs/docs.go
+++ b/backend/docs/docs.go
@@ -1437,6 +1437,46 @@ const docTemplate = `{
                }
            }
        },
+        "/t/{tenantCode}/v1/admin/users/topup/batch": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Tenant"
+                ],
+                "summary": "批量为租户成员充值（租户管理）",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Tenant Code",
+                        "name": "tenantCode",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Form",
+                        "name": "form",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.AdminBatchTopupForm"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.AdminBatchTopupResponse"
+                        }
+                    }
+                }
+            }
+        },
        "/t/{tenantCode}/v1/admin/users/{userID}": {
            "delete": {
                "consumes": [
@@ -2389,6 +2429,100 @@ const docTemplate = `{
                "UserStatusBanned"
            ]
        },
+        "dto.AdminBatchTopupForm": {
+            "type": "object",
+            "properties": {
+                "batch_idempotency_key": {
+                    "description": "BatchIdempotencyKey 批次幂等键：必须填写；用于重试同一批次时保证不会重复入账。",
+                    "type": "string"
+                },
+                "items": {
+                    "description": "Items 充值明细列表：至少 1 条；单批次条数在业务侧限制（避免拖垮系统）。",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/dto.AdminBatchTopupItem"
+                    }
+                }
+            }
+        },
+        "dto.AdminBatchTopupItem": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "description": "Amount 充值金额：单位分；必须 \u003e 0。",
+                    "type": "integer"
+                },
+                "idempotency_key": {
+                    "description": "IdempotencyKey 幂等键（可选）：为空时后端会用 batch_idempotency_key 派生生成；\n建议前端/调用方提供稳定值，便于重试时保持结果一致。",
+                    "type": "string"
+                },
+                "reason": {
+                    "description": "Reason 充值原因（可选）：用于审计与追溯。",
+                    "type": "string"
+                },
+                "user_id": {
+                    "description": "UserID 目标用户ID：必须属于当前租户，否则该条充值失败。",
+                    "type": "integer"
+                }
+            }
+        },
+        "dto.AdminBatchTopupResponse": {
+            "type": "object",
+            "properties": {
+                "failed": {
+                    "description": "Failed 失败条数。",
+                    "type": "integer"
+                },
+                "items": {
+                    "description": "Items 明细结果列表：与请求 items 顺序一致，便于前端逐条展示。",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/dto.AdminBatchTopupResultItem"
+                    }
+                },
+                "success": {
+                    "description": "Success 成功条数。",
+                    "type": "integer"
+                },
+                "total": {
+                    "description": "Total 总条数：等于 items 长度。",
+                    "type": "integer"
+                }
+            }
+        },
+        "dto.AdminBatchTopupResultItem": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "description": "Amount 充值金额（单位分）。",
+                    "type": "integer"
+                },
+                "error_code": {
+                    "description": "ErrorCode 错误码：失败时返回；成功时为 0。",
+                    "type": "integer"
+                },
+                "error_message": {
+                    "description": "ErrorMessage 错误信息：失败时返回；成功时为空。",
+                    "type": "string"
+                },
+                "idempotency_key": {
+                    "description": "IdempotencyKey 实际使用的幂等键：可能为客户端传入，也可能为后端派生生成。",
+                    "type": "string"
+                },
+                "ok": {
+                    "description": "OK 是否成功：true 表示该条充值已成功入账或命中幂等成功结果。",
+                    "type": "boolean"
+                },
+                "order_id": {
+                    "description": "OrderID 生成的订单ID：成功时返回；失败时为 0。",
+                    "type": "integer"
+                },
+                "user_id": {
+                    "description": "UserID 目标用户ID。",
+                    "type": "integer"
+                }
+            }
+        },
        "dto.AdminOrderDetail": {
            "type": "object",
            "properties": {