{ "swagger": "2.0", "info": { "description": "计费服务 API，提供订阅管理、账单生成、支付处理等功能", "title": "Billing Service API", "contact": {}, "version": "1.0.0" }, "basePath": "/api/v1", "paths": { "/admin/billing/credit-note/{number}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据红字发票编号查询详情，含金额、原因、关联发票和状态", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取红字发票详情", "parameters": [ { "type": "string", "description": "红字发票编号", "name": "number", "in": "path", "required": true } ], "responses": { "200": { "description": "红字发票查询成功", "schema": { "$ref": "#/definitions/dto.CreditNoteDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "红字发票不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "作废一张红字发票，使其不再生效。参考：GAAP/IFRS (Double-Entry Accounting Principles)。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "作废红字发票", "parameters": [ { "type": "string", "description": "红字发票编号", "name": "number", "in": "path", "required": true } ], "responses": { "200": { "description": "作废成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "物理删除一张红字发票记录", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除红字发票", "parameters": [ { "type": "string", "description": "红字发票编号", "name": "number", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/dunning-settings/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取租户的失败支付催缴策略配置，包括重试排程、宽限期天数、自动取消天数和邮件模板", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取催缴配置", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "催缴配置查询成功", "schema": { "$ref": "#/definitions/dto.DunningSettingsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "创建或更新租户的失败支付催缴策略，包括：重试排程、宽限期天数、自动取消天数和邮件模板。支持 upsert——已有配置时更新，无配置时创建。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "配置催缴策略", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "description": "催缴配置请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.DunningSettingsRequest" } } ], "responses": { "200": { "description": "催缴配置更新成功", "schema": { "$ref": "#/definitions/dto.DunningSettingsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除指定租户的失败支付催缴策略配置，恢复默认行为", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除催缴配置", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/feature-gates": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据当前租户订阅的套餐返回已启用的 FeatureGates（功能开关）列表，用于前端根据功能开关渲染 UI。两层判定：套餐权益 + 租户覆盖。", "produces": [ "application/json" ], "tags": [ "计费服务 - 特性开关" ], "summary": "获取功能开关列表", "responses": { "200": { "description": "功能开关列表查询成功", "schema": { "$ref": "#/definitions/handler.featureGateResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/billing/feature-gates/overrides": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取当前租户的所有 FeatureGate 覆盖配置。覆盖允许按租户级别开启/关闭功能开关，优先级高于套餐默认权益。", "produces": [ "application/json" ], "tags": [ "计费服务 - 特性开关" ], "summary": "查询租户功能开关覆盖", "responses": { "200": { "description": "功能开关覆盖查询成功", "schema": { "$ref": "#/definitions/handler.overrideResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "按租户级别创建或更新功能开关覆盖（upsert）。覆盖优先于套餐默认权益，可用于按需开启/关闭特定功能。请求体含 gate_key 和 enabled 布尔值。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 特性开关" ], "summary": "创建或更新功能开关覆盖", "parameters": [ { "description": "功能开关覆盖请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.overrideRequest" } } ], "responses": { "200": { "description": "功能开关覆盖保存成功，返回当前所有覆盖", "schema": { "$ref": "#/definitions/handler.overrideResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/billing/invoice/{invoice_number}/credit-note": { "post": { "security": [ { "bearerAuth": [] } ], "description": "对已有发票开具红字冲销发票，用于退款、折扣等负向金额调整。参考：GAAP/IFRS (Double-Entry Accounting Principles)。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "创建红字发票", "parameters": [ { "type": "string", "description": "原发票编号", "name": "invoice_number", "in": "path", "required": true }, { "description": "红字发票请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreditNoteRequest" } } ], "responses": { "200": { "description": "红字发票创建成功", "schema": { "$ref": "#/definitions/dto.CreditNoteDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/metered-usage/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询指定租户的计量计费使用记录，包含各资源类型的包含量、超额量和超额费用。支持按应用和时间范围过滤。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "计量计费记录", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" }, { "type": "string", "description": "开始日期 (YYYY-MM-DD)", "name": "start", "in": "query" }, { "type": "string", "description": "结束日期 (YYYY-MM-DD)", "name": "end", "in": "query" } ], "responses": { "200": { "description": "计量计费记录查询成功", "schema": { "$ref": "#/definitions/dto.MeteredBillingListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/payment-gateways": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询支付网关列表，支持按名称或代码模糊搜索", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "支付网关列表", "parameters": [ { "type": "string", "description": "名称或代码模糊搜索", "name": "name_or_code", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "支付网关列表查询成功", "schema": { "$ref": "#/definitions/dto.PaymentGatewayListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "配置一个新的支付渠道（支付宝、微信支付、Stripe 等），包含网关名称、代码和 JSON 配置", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "创建支付网关", "parameters": [ { "description": "创建支付网关请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreatePaymentGatewayRequest" } } ], "responses": { "201": { "description": "支付网关创建成功", "schema": { "$ref": "#/definitions/dto.PaymentGatewayDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/payment-gateways/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据ID查询支付网关的配置详情，含名称、代码、状态和 JSON 配置", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取支付网关详情", "parameters": [ { "type": "string", "description": "支付网关ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "支付网关查询成功", "schema": { "$ref": "#/definitions/dto.PaymentGatewayDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "支付网关不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "修改支付网关的名称、JSON 配置或激活状态。支持部分更新。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "更新支付网关", "parameters": [ { "type": "string", "description": "支付网关ID", "name": "id", "in": "path", "required": true }, { "description": "更新支付网关请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdatePaymentGatewayRequest" } } ], "responses": { "200": { "description": "支付网关更新成功", "schema": { "$ref": "#/definitions/dto.PaymentGatewayDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "支付网关不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除一个支付网关配置", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除支付网关", "parameters": [ { "type": "string", "description": "支付网关ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "支付网关不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/plans": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询所有套餐定价方案的详情，包括名称、价格、计费周期和包含的功能特性", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取套餐定价列表", "responses": { "200": { "description": "套餐定价列表查询成功", "schema": { "$ref": "#/definitions/dto.PlanPricingDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "新建一个套餐定价方案（free/basic/pro/enterprise/platform），定义名称、描述、月/年价格、币种和功能特性（最大用户数、存储、带宽、API调用、MFA/SSO、审计日志保留天数、支持级别）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "创建套餐定价", "parameters": [ { "description": "创建套餐请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreatePlanRequest" } } ], "responses": { "201": { "description": "套餐创建成功", "schema": { "$ref": "#/definitions/dto.PlanPricingDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/plans/{id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "更新已有套餐定价方案的名称、描述、月/年价格、状态。支持部分更新，未传递的字段保持原值。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "更新套餐定价", "parameters": [ { "type": "string", "description": "套餐定价ID", "name": "id", "in": "path", "required": true }, { "description": "更新套餐请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdatePlanRequest" } } ], "responses": { "200": { "description": "套餐更新成功", "schema": { "$ref": "#/definitions/dto.PlanPricingModelDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "套餐不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "移除一个不再使用的套餐定价方案。已有租户订阅该套餐时不阻止删除，仅移除套餐定义。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除套餐定价", "parameters": [ { "type": "string", "description": "套餐定价ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/plans/{id}/feature-gates": { "patch": { "security": [ { "bearerAuth": [] } ], "description": "更新指定套餐的 FeatureGates（功能开关）列表，支持按 key 开启/关闭功能。自动同步 MFA 和 SSO 布尔字段到套餐特性中。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "更新套餐功能开关", "parameters": [ { "type": "string", "description": "套餐ID (free/basic/pro/enterprise/platform)", "name": "id", "in": "path", "required": true }, { "description": "功能开关请求体 {feature_gates:[{key,enabled}]}", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "功能开关更新成功", "schema": { "$ref": "#/definitions/dto.PlanPricingModelDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "套餐不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/records/{id}": { "delete": { "security": [ { "bearerAuth": [] } ], "description": "作废一条计费记录，标记为 void 状态。参考：GAAP/IFRS (Double-Entry Accounting Principles)。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "作废计费记录", "parameters": [ { "type": "string", "description": "计费记录ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "作废成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/refund-approval": { "post": { "security": [ { "bearerAuth": [] } ], "description": "发起退款审批流程，记录退款金额、原因和关联交易。审批通过后由管理员执行实际退款操作。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "提交退款审批", "parameters": [ { "description": "退款审批请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.RefundApprovalRequest" } } ], "responses": { "200": { "description": "退款审批提交成功", "schema": { "$ref": "#/definitions/dto.RefundApprovalDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/refund-approval/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询退款审批的当前处理状态和审批进度（pending/approved/rejected/executed/completed）", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取退款审批状态", "parameters": [ { "type": "string", "description": "退款审批ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "退款审批状态查询成功", "schema": { "$ref": "#/definitions/dto.RefundApprovalDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除一条退款审批记录。已完成或已拒绝的审批不可删除。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除退款审批", "parameters": [ { "type": "string", "description": "退款审批ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "状态冲突（已完成/已拒绝不可删除）", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/refund-approval/{id}/approve": { "post": { "security": [ { "bearerAuth": [] } ], "description": "审批通过退款申请，将状态从 pending 变更为 approved。只有 approved 状态的退款才能执行。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "审批通过退款", "parameters": [ { "type": "string", "description": "退款审批ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "审批成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "状态冲突（非pending状态不可审批）", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/refund-approval/{id}/execute": { "post": { "security": [ { "bearerAuth": [] } ], "description": "对已批准的退款审批执行实际退款操作，调用 wallet-service 完成扣款/退款交易", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "执行退款审批", "parameters": [ { "type": "string", "description": "退款审批ID", "name": "id", "in": "path", "required": true }, { "description": "执行退款请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ExecuteRefundRequest" } } ], "responses": { "200": { "description": "退款执行成功", "schema": { "$ref": "#/definitions/dto.ExecuteRefundDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "状态冲突（退款未审批或已执行）", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/refund-approval/{id}/reject": { "post": { "security": [ { "bearerAuth": [] } ], "description": "拒绝退款申请，将状态从 pending 变更为 rejected。rejected 状态的退款不可再次审批或执行。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "拒绝退款审批", "parameters": [ { "type": "string", "description": "退款审批ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "拒绝成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "状态冲突（非pending状态不可拒绝）", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/refund-approvals": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询退款审批记录列表，支持按状态过滤（pending/approved/rejected/executed/completed）", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "查询退款审批列表", "parameters": [ { "type": "string", "description": "审批状态 (pending/approved/rejected/executed/completed)", "name": "status", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "退款审批列表查询成功", "schema": { "$ref": "#/definitions/dto.RefundApprovalListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/revenue-amortization": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询收入的递延情况和按时间分摊的报表（Revenue Amortization）。遵循 GAAP/IFRS 收入确认原则，按会计期间分摊已递延收入。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "收入递延报表", "parameters": [ { "type": "string", "description": "开始日期 (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "结束日期 (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "收入递延查询成功", "schema": { "$ref": "#/definitions/dto.RevenueAmortizationDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "修改指定租户的订阅配置，支持变更套餐（plan）和自动续费（auto_renew）设置。套餐变更时按比例计算费用。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "更新订阅配置", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "description": "更新订阅请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateSubscriptionRequestDTO" } } ], "responses": { "200": { "description": "订阅更新成功", "schema": { "$ref": "#/definitions/dto.SubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "取消指定租户的当前订阅，状态变更为 cancelled。取消后租户在订阅周期结束后失去套餐功能。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "取消订阅", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "取消成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}/apps": { "get": { "security": [ { "bearerAuth": [] } ], "description": "列出租户下所有应用的独立定价配置，每个应用可具有不同的资源定价策略", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "列出应用定价列表", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "应用定价列表查询成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}/apps/{app_id}/pricing": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询租户指定应用的资源定价配置详情，包含各资源类型的定价策略", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取应用定价", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true } ], "responses": { "200": { "description": "应用定价查询成功", "schema": { "$ref": "#/definitions/dto.AppSubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "应用定价配置不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "为租户的某个应用单独配置资源定价方案（每个资源类型独立定价），覆盖默认套餐定价。支持设置包含单位数、单价和超额单价。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "配置应用定价", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true }, { "description": "应用定价配置请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ConfigureAppPricingRequest" } } ], "responses": { "200": { "description": "应用定价配置成功", "schema": { "$ref": "#/definitions/dto.AppSubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除指定租户应用的独立资源定价配置，删除后该应用恢复使用租户默认套餐定价", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除应用定价", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}/cancel-trial": { "post": { "security": [ { "bearerAuth": [] } ], "description": "立即终止指定租户当前订阅的免费试用期，状态变更为 active（转为正式计费）", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "取消试用期", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "试用期取消成功", "schema": { "$ref": "#/definitions/dto.TrialActionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}/change-plan": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将指定租户当前订阅切换到另一个套餐（升级或降级），自动计算按比例（proration）费用。差额为正时产生应收账单，为负时计入信用余额。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "变更套餐", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "description": "套餐变更请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PlanChangeRequest" } } ], "responses": { "200": { "description": "套餐变更成功，含按比例费用", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}/extend-trial": { "post": { "security": [ { "bearerAuth": [] } ], "description": "延长指定租户当前订阅的免费试用期限（以天为单位），成功后发送试用到期提醒通知", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "延长试用期", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "description": "延长试用请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ExtendTrialRequest" } } ], "responses": { "200": { "description": "试用期延长成功", "schema": { "$ref": "#/definitions/dto.TrialActionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/subscription/{tenant_id}/rollback-plan": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将变更套餐操作回滚到原来的套餐。退还因套餐变更收取的按比例（proration）费用至信用余额。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "回滚套餐", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "套餐回滚成功", "schema": { "$ref": "#/definitions/dto.SubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/tax-export": { "get": { "security": [ { "bearerAuth": [] } ], "description": "导出指定时间段内的税务相关数据，用于税务申报和审计。支持按 tax_period 或 start_date/end_date 指定范围，默认导出 CSV 格式。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "税务导出", "parameters": [ { "type": "string", "description": "税务周期", "name": "tax_period", "in": "query" }, { "type": "string", "description": "开始日期 (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "结束日期 (YYYY-MM-DD)", "name": "end_date", "in": "query" }, { "type": "string", "default": "csv", "description": "导出格式 (csv/json)", "name": "format", "in": "query" } ], "responses": { "200": { "description": "税务导出成功", "schema": { "$ref": "#/definitions/dto.TaxExportDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/tax-exports": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询已生成的税务导出记录列表，支持按税务周期过滤", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "税务导出列表", "parameters": [ { "type": "string", "description": "税务周期", "name": "period", "in": "query" } ], "responses": { "200": { "description": "税务导出列表查询成功", "schema": { "$ref": "#/definitions/dto.TaxExportListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/admin/billing/usage-stats/{tenant_id}/{id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "管理员手动修正指定租户的使用统计数据（用于异常数据修正）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "更新使用统计", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "使用统计记录ID", "name": "id", "in": "path", "required": true }, { "description": "更新参数（key-value 键值对）", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "additionalProperties": true } } ], "responses": { "200": { "description": "使用统计更新成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "无权限", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/alerts": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询已配置的用量告警规则列表，支持按应用ID、资源类型和状态过滤", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "列出用量告警", "parameters": [ { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" }, { "type": "string", "description": "资源类型（可选）", "name": "resource_type", "in": "query" }, { "type": "string", "description": "告警状态（active/silenced/triggered）", "name": "status", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "用量告警列表查询成功", "schema": { "$ref": "#/definitions/dto.UsageAlertListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "创建一条用量告警规则（如：当月API调用量超过 80% 时通过指定渠道发送通知）。支持按资源类型设定阈值百分比和多渠道通知。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "创建用量告警", "parameters": [ { "description": "创建用量告警请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateUsageAlertRequest" } } ], "responses": { "201": { "description": "用量告警创建成功", "schema": { "$ref": "#/definitions/dto.UsageAlertDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/alerts/{id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "修改已有用量告警规则的阈值、通知渠道或状态。支持部分更新，未传递的字段保持原值。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "更新用量告警", "parameters": [ { "type": "string", "description": "告警ID", "name": "id", "in": "path", "required": true }, { "description": "更新用量告警请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateUsageAlertRequest" } } ], "responses": { "200": { "description": "用量告警更新成功", "schema": { "$ref": "#/definitions/dto.UsageAlertDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "告警不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "移除一条不再需要的用量告警规则，返回 204 无内容表示删除成功", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "删除用量告警", "parameters": [ { "type": "string", "description": "告警ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "删除成功" }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "告警不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/balance": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询当前用户的钱包余额信息（通过 wallet-service），含可用余额、币种和冻结金额", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "查询钱包余额", "responses": { "200": { "description": "余额查询成功", "schema": { "$ref": "#/definitions/dto.BalanceDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/credit-balance/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取租户的信用余额，来源于退款、按比例降价、促销额度等。信用余额可用于抵扣后续账单。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "查询租户信用余额", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "信用余额查询成功", "schema": { "$ref": "#/definitions/dto.CreditBalanceDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/credit-transactions/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询租户的信用交易明细（复式记账，仅 INSERT，不可修改删除）。支持按交易来源过滤。参考：GAAP/IFRS (Double-Entry Accounting Principles)。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "查询信用交易记录", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" }, { "type": "string", "description": "交易来源 (proration/refund/promo/manual_adjust)", "name": "source", "in": "query" } ], "responses": { "200": { "description": "信用交易记录查询成功", "schema": { "$ref": "#/definitions/dto.CreditTransactionListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/feature-gates": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取当前认证用户的租户功能开关列表，合并套餐权益与租户级别覆盖", "produces": [ "application/json" ], "tags": [ "计费服务 - 特性开关" ], "summary": "获取当前租户功能开关", "responses": { "200": { "description": "功能开关列表查询成功", "schema": { "$ref": "#/definitions/handler.featureGateResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/billing/invoice/{invoice_number}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据发票编号查询发票的详细信息，包括金额、币种、行项目、税额、支付状态等", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取发票详情", "parameters": [ { "type": "string", "description": "发票编号", "name": "invoice_number", "in": "path", "required": true } ], "responses": { "200": { "description": "发票详情查询成功", "schema": { "$ref": "#/definitions/dto.InvoiceDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "发票不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/invoice/{invoice_number}/export": { "get": { "security": [ { "bearerAuth": [] } ], "description": "导出指定发票的详细信息，支持 JSON/CSV 两种格式", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "导出发票", "parameters": [ { "type": "string", "description": "发票编号", "name": "invoice_number", "in": "path", "required": true }, { "type": "string", "default": "json", "description": "导出格式 (json/csv)", "name": "format", "in": "query" } ], "responses": { "200": { "description": "发票导出成功", "schema": { "$ref": "#/definitions/dto.InvoiceDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "发票不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/invoice/{invoice_number}/pdf": { "get": { "security": [ { "bearerAuth": [] } ], "description": "生成并下载指定发票的PDF文件，包含公司信息、发票号、日期、租户ID、行项目明细和金额汇总", "produces": [ "application/pdf" ], "tags": [ "计费服务" ], "summary": "下载发票PDF", "parameters": [ { "type": "string", "description": "发票编号", "name": "invoice_number", "in": "path", "required": true } ], "responses": { "200": { "description": "PDF发票文件", "schema": { "type": "file" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "发票不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/plans": { "get": { "description": "公开接口（无需认证）：获取所有已发布的套餐定价列表，用于 Developer Portal 定价页。含套餐名称、描述、月/年价格、功能特性和配额。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取公开套餐列表", "responses": { "200": { "description": "公开套餐列表查询成功", "schema": { "$ref": "#/definitions/dto.PublicPlansDetailResponse" } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/prorations/calculate/{tenant_id}": { "post": { "security": [ { "bearerAuth": [] } ], "description": "在正式变更套餐前预览将产生的按比例（proration）金额，返回预估费用和剩余计费天数，不执行实际变更", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "预览套餐变更按比例费用", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "description": "按比例计算请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ProrationCalculateRequest" } } ], "responses": { "200": { "description": "按比例费用计算成功", "schema": { "$ref": "#/definitions/dto.ProrationCalculateDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/records/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "按租户维度分页查询计费记录，可选 app_id 过滤。默认按时间倒序排列，含发票编号、金额、币种、状态等字段。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取计费记录", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "计费记录查询成功", "schema": { "$ref": "#/definitions/dto.BillingRecordListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/records/{tenant_id}/apps/{app_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "按应用维度分页查询指定租户的计费记录，适用于多应用租户的独立计费查询", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "按应用获取计费记录", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "计费记录查询成功", "schema": { "$ref": "#/definitions/dto.BillingRecordListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/records/{tenant_id}/search": { "get": { "security": [ { "bearerAuth": [] } ], "description": "支持多条件组合搜索计费记录，筛选条件包括：状态、日期范围、金额范围、关键词搜索。结果分页返回。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "高级搜索计费记录", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" }, { "type": "string", "description": "计费状态 (paid/failed/refunded/pending)", "name": "status", "in": "query" }, { "type": "string", "description": "开始日期 (YYYY-MM-DD)", "name": "date_from", "in": "query" }, { "type": "string", "description": "结束日期 (YYYY-MM-DD)", "name": "date_to", "in": "query" }, { "type": "number", "description": "最低金额", "name": "min_amount", "in": "query" }, { "type": "number", "description": "最高金额", "name": "max_amount", "in": "query" }, { "type": "string", "description": "关键词搜索", "name": "search", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "计费记录搜索成功", "schema": { "$ref": "#/definitions/dto.BillingRecordListResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/statistics/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询租户的综合计费统计，包括活跃用户数、资源使用量等汇总指标。可选按 app_id 过滤。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取租户统计", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" } ], "responses": { "200": { "description": "租户统计查询成功", "schema": { "$ref": "#/definitions/dto.TenantStatisticsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/statistics/{tenant_id}/apps/{app_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "按应用维度查询租户的计费和用量综合统计，含活跃用户数和资源使用概览", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "按应用获取租户统计", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true } ], "responses": { "200": { "description": "租户统计查询成功", "schema": { "$ref": "#/definitions/dto.TenantStatisticsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/subscribe": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为当前租户创建订阅，绑定套餐（free/basic/pro/enterprise/platform）和计费周期（monthly/yearly）。支持设定自动续费和试用天数。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "订阅服务", "parameters": [ { "description": "订阅请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SubscribeRequestDTO" } } ], "responses": { "201": { "description": "订阅创建成功", "schema": { "$ref": "#/definitions/dto.SubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "租户已有有效订阅", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/subscription/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询租户当前的订阅详情，包括套餐、状态、计费周期、有效期和试用结束日期", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取订阅信息", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "订阅信息查询成功", "schema": { "$ref": "#/definitions/dto.SubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/usage/{tenant_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询指定租户的资源使用量统计数据（用户数、存储量、API调用次数）。默认查询近 30 天数据，可通过 start_date/end_date 指定范围。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取使用统计", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" }, { "type": "string", "default": "30天前", "description": "开始日期 (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "default": "今天", "description": "结束日期 (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "使用统计查询成功", "schema": { "$ref": "#/definitions/dto.UsageStatsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/usage/{tenant_id}/apps/{app_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "按应用维度查询资源使用量统计（用户数、存储量、API调用次数）。默认查询近 30 天数据。", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "按应用获取使用统计", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true }, { "type": "string", "default": "30天前", "description": "开始日期 (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "default": "今天", "description": "结束日期 (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "使用统计查询成功", "schema": { "$ref": "#/definitions/dto.UsageStatsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/usage/{tenant_id}/apps/{app_id}/current": { "get": { "security": [ { "bearerAuth": [] } ], "description": "按应用维度查询当前计费周期内的资源使用量，用于多应用租户的独立用量监控", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "按应用获取当前使用量", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true } ], "responses": { "200": { "description": "当前使用量查询成功", "schema": { "$ref": "#/definitions/dto.CurrentUsageDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/usage/{tenant_id}/current": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询当前计费周期内的已使用资源量（用户数、存储、API调用），用于实时用量监控", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取当前使用量", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" } ], "responses": { "200": { "description": "当前使用量查询成功", "schema": { "$ref": "#/definitions/dto.CurrentUsageDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/usage/{tenant_id}/endpoints": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询API端点调用次数TopN排行，含请求数、错误数和平均延迟，用于分析热点接口", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取端点用量TopN排行", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" }, { "type": "integer", "default": 20, "description": "返回条数", "name": "limit", "in": "query" }, { "type": "integer", "default": 7, "description": "统计天数", "name": "days", "in": "query" } ], "responses": { "200": { "description": "端点用量排行查询成功", "schema": { "$ref": "#/definitions/dto.EndpointUsageDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/billing/usage/{tenant_id}/timeline": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询指定天数内的用量变化时间序列数据，按日返回用户数、API调用量、存储和带宽使用量，用于趋势分析图表", "produces": [ "application/json" ], "tags": [ "计费服务" ], "summary": "获取用量时间序列", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID（可选）", "name": "app_id", "in": "query" }, { "type": "integer", "default": 30, "description": "统计天数", "name": "days", "in": "query" } ], "responses": { "200": { "description": "用量时间序列查询成功", "schema": { "$ref": "#/definitions/dto.UsageTimelineDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/apps/{tenant_id}/{app_id}/billing-event": { "post": { "description": "服务间内部调用：处理应用维度的计费事件（suspend 暂停计费/resume 恢复计费/delete 删除计费），由 tenant-service 在应用生命周期变更时调用", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 处理应用计费事件", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true }, { "description": "应用计费事件请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.AppBillingEventRequest" } } ], "responses": { "200": { "description": "计费事件处理成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/endpoint-stats/import": { "post": { "description": "服务间内部调用：从审计日志等来源批量导入各 API 端点的调用次数、错误数和平均延迟，用于计费和用量分析", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 批量导入端点用量统计", "parameters": [ { "description": "端点用量导入请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EndpointStatsImportRequest" } } ], "responses": { "200": { "description": "端点用量导入成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/erase-user": { "post": { "description": "服务间内部调用：擦除指定用户在计费服务中的所有PII数据", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] GDPR擦除用户账单", "parameters": [ { "description": "{\\", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/export-user-data": { "post": { "description": "服务间内部调用（compliance-service）：导出指定用户在计费服务中的所有关联数据，含订阅、计费记录、信用余额、使用统计、用量告警和计量记录", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 导出用户数据", "parameters": [ { "description": "导出用户数据请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ExportUserDataRequest" } } ], "responses": { "200": { "description": "用户数据导出成功", "schema": { "$ref": "#/definitions/dto.ExportUserDataResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/feature-gates/check": { "post": { "description": "服务间内部调用：查询两层 FeatureGate 判定结果（Plan Entitlement 套餐权益 + Tenant Override 租户覆盖），返回最终有效值", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 特性开关" ], "summary": "[内部] 检查功能开关", "parameters": [ { "description": "功能开关检查请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.featureGateCheckRequest" } } ], "responses": { "200": { "description": "功能开关检查结果", "schema": { "$ref": "#/definitions/handler.featureGateCheckResult" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/metering/report": { "post": { "description": "服务间内部调用：接收并记录各微服务上报的资源使用量（计量计费），用于生成账单和配额检查", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 上报使用量", "parameters": [ { "description": "使用量上报请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.MeteringReportRequest" } } ], "responses": { "200": { "description": "使用量上报成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/plans": { "get": { "description": "服务间内部调用：获取所有可用套餐定价列表，供其他微服务（如 tenant-service）查询套餐信息", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 获取套餐列表", "responses": { "200": { "description": "套餐列表查询成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/plans/admin": { "get": { "description": "服务间内部调用：获取所有套餐定价列表（含非活跃套餐），供管理后台使用。include_inactive=true 时返回停用的套餐。", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 列出套餐定价（含非活跃）", "parameters": [ { "type": "string", "default": "false", "description": "是否包含非活跃套餐", "name": "include_inactive", "in": "query" } ], "responses": { "200": { "description": "套餐定价列表查询成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/plans/{plan}/quotas": { "get": { "description": "服务间内部调用：根据套餐名称（free/basic/pro/enterprise/platform）获取配额限制，包含最大用户数、存储、带宽、API调用数、短信/邮件日限额等", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 获取套餐配额", "parameters": [ { "type": "string", "description": "套餐名称 (free/basic/pro/enterprise/platform)", "name": "plan", "in": "path", "required": true } ], "responses": { "200": { "description": "套餐配额查询成功", "schema": { "$ref": "#/definitions/dto.PlanQuotasDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "套餐不存在", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/quota/check": { "post": { "description": "服务间内部调用：检查租户资源配额是否超出限制（如用户数、存储、API调用），供其他微服务在资源操作前进行配额校验", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 检查资源配额", "parameters": [ { "description": "配额检查请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.QuotaCheckInternalRequest" } } ], "responses": { "200": { "description": "配额检查成功", "schema": { "$ref": "#/definitions/dto.QuotaCheckDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/records": { "post": { "description": "服务间内部调用：创建一条计费记录（由 pay-service 等支付相关微服务调用），含金额、币种、发票编号、支付方式、计费周期等字段", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 创建计费记录", "parameters": [ { "description": "计费记录请求体", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateBillingRecordInternalRequest" } } ], "responses": { "201": { "description": "计费记录创建成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/renewals/process": { "post": { "description": "服务间内部调用：批量处理到期订阅的自动续费流程（由 scheduler 定时触发），返回续费成功和失败数量", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 处理自动续费", "responses": { "200": { "description": "自动续费处理完成", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/subscription/{tenant_id}": { "get": { "description": "服务间内部调用：通过 X-Tenant-ID 和 InternalAPIKey 获取指定租户的订阅详情，供其他微服务查询套餐和功能权限。", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 获取订阅信息", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "订阅信息查询成功", "schema": { "$ref": "#/definitions/dto.SubscriptionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/usage/{tenant_id}": { "get": { "description": "服务间内部调用：查询指定租户的当前资源使用量统计数据，供其他微服务进行配额校验", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 获取使用量", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "使用量查询成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } }, "/internal/billing/usage/{tenant_id}/{app_id}": { "get": { "description": "服务间内部调用：按应用维度获取资源使用量统计数据，供其他微服务进行应用级配额校验", "produces": [ "application/json" ], "tags": [ "计费服务 - 内部接口" ], "summary": "[内部] 按应用获取使用量", "parameters": [ { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "应用ID", "name": "app_id", "in": "path", "required": true } ], "responses": { "200": { "description": "使用量查询成功", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "请求参数错误", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "未授权", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务器内部错误", "schema": { "type": "object", "additionalProperties": true } } } } } }, "definitions": { "billing.FeatureGate": { "type": "object", "properties": { "description": { "description": "功能描述", "type": "string" }, "enabled": { "description": "当前租户是否启用", "type": "boolean" }, "key": { "description": "\"nhi\", \"mfa\", \"sso\", \"audit_export\"", "type": "string" }, "name": { "description": "\"Non-Human Identities\" (展示名)", "type": "string" } } }, "domain.TenantFeatureGateOverride": { "type": "object", "properties": { "created_at": { "type": "string" }, "enabled": { "type": "boolean" }, "gate_key": { "type": "string" }, "id": { "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } } }, "dto.AppBillingEventRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "description": "suspend/resume/delete", "type": "string", "example": "suspend" } } }, "dto.AppResourcePricingInputDTO": { "type": "object", "required": [ "resource_type" ], "properties": { "included_units": { "type": "integer", "example": 10000 }, "overage_unit_price": { "type": "number", "example": 0.05 }, "resource_type": { "type": "string", "example": "api_calls" }, "unit_label": { "type": "string", "example": "次" }, "unit_price": { "type": "number", "example": 0.01 } } }, "dto.AppResourcePricingResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "arp_001" }, "included_units": { "type": "integer", "example": 10000 }, "overage_unit_price": { "type": "number", "example": 0.05 }, "resource_type": { "type": "string", "example": "api_calls" }, "subscription_app_id": { "type": "string", "example": "sa_001" }, "unit_label": { "type": "string", "example": "次" }, "unit_price": { "type": "number", "example": 0.01 } } }, "dto.AppSubscriptionDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.SubscriptionAppResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.BalanceDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.BalanceResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.BalanceResponse": { "type": "object", "properties": { "balance": { "type": "number", "example": 500 }, "currency": { "type": "string", "example": "CNY" }, "frozen_amount": { "type": "number", "example": 0 }, "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.BillingRecordListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.BillingRecordResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.BillingRecordResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 99 }, "app_id": { "type": "string", "example": "app_001" }, "created_at": { "type": "string", "example": "2026-04-01T00:00:00Z" }, "currency": { "type": "string", "example": "CNY" }, "description": { "type": "string", "example": "专业版月度订阅" }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "line_items": { "type": "array", "items": { "$ref": "#/definitions/dto.InvoiceLineItemResponse" } }, "record_id": { "type": "string", "example": "rec_001" }, "status": { "type": "string", "example": "paid" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "type": { "type": "string", "example": "subscription" } } }, "dto.ConfigureAppPricingRequest": { "type": "object", "required": [ "pricings" ], "properties": { "pricings": { "type": "array", "items": { "$ref": "#/definitions/dto.AppResourcePricingInputDTO" } } } }, "dto.CreateBillingRecordInternalRequest": { "type": "object", "required": [ "amount", "period_end", "period_start", "status", "subscription_id" ], "properties": { "amount": { "type": "number", "example": 99 }, "app_id": { "type": "string", "example": "app_001" }, "currency": { "type": "string", "example": "CNY" }, "description": { "type": "string", "example": "月度订阅" }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "payment_method": { "type": "string", "example": "alipay" }, "period_end": { "type": "string", "example": "2026-06-01T00:00:00Z" }, "period_start": { "type": "string", "example": "2026-05-01T00:00:00Z" }, "status": { "type": "string", "example": "paid" }, "subscription_id": { "type": "string", "example": "sub_001" } } }, "dto.CreatePaymentGatewayRequest": { "type": "object", "required": [ "code", "config", "name" ], "properties": { "code": { "type": "string", "example": "alipay" }, "config": { "type": "string", "example": "{\"app_id\":\"123456\"}" }, "name": { "type": "string", "example": "支付宝" } } }, "dto.CreatePlanRequest": { "type": "object", "required": [ "monthly_price", "name", "plan", "yearly_price" ], "properties": { "audit_log_days": { "type": "integer", "example": 90 }, "currency": { "type": "string", "example": "CNY" }, "description": { "type": "string", "example": "适用于大型团队" }, "max_api_requests": { "type": "integer", "example": 100000 }, "max_bandwidth_gb": { "type": "integer", "example": 1024 }, "max_storage_gb": { "type": "integer", "example": 100 }, "max_users": { "type": "integer", "example": 100 }, "mfa_enabled": { "type": "boolean", "example": true }, "monthly_price": { "type": "number", "example": 499 }, "name": { "type": "string", "example": "专业版" }, "plan": { "type": "string", "example": "pro" }, "sso_enabled": { "type": "boolean", "example": true }, "support_level": { "type": "string", "example": "priority" }, "yearly_price": { "type": "number", "example": 4999 } } }, "dto.CreateUsageAlertRequest": { "type": "object", "required": [ "name", "notification_channels", "resource_type", "threshold_percent" ], "properties": { "app_id": { "type": "string", "example": "app_001" }, "name": { "type": "string", "example": "API调用量告警" }, "notification_channels": { "type": "string", "example": "email,in_app" }, "resource_type": { "type": "string", "example": "api_calls" }, "threshold_percent": { "type": "integer", "example": 80 } } }, "dto.CreditBalanceDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.CreditBalanceResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.CreditBalanceResponse": { "type": "object", "properties": { "balance": { "type": "number", "example": 150 }, "currency": { "type": "string", "example": "CNY" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "updated_at": { "type": "string", "example": "2026-05-12T10:00:00Z" } } }, "dto.CreditNoteDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.CreditNoteResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.CreditNoteRequest": { "type": "object", "required": [ "amount", "invoice_number", "reason" ], "properties": { "amount": { "type": "number", "example": 99 }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "reason": { "type": "string", "example": "服务取消" } } }, "dto.CreditNoteResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 99 }, "applied_at": { "type": "string", "example": "2026-04-15T12:00:00Z" }, "credit_note_number": { "type": "string", "example": "CN-2026-001" }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "issued_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "reason": { "type": "string", "example": "服务取消" }, "status": { "type": "string", "example": "issued" }, "tenant_id": { "type": "string", "example": "tnt_abc123" } } }, "dto.CreditTransactionListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.CreditTransactionResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.CreditTransactionResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 50 }, "balance": { "type": "number", "example": 150 }, "created_at": { "type": "string", "example": "2026-05-12T10:00:00Z" }, "id": { "type": "string", "example": "ctr_001" }, "remark": { "type": "string", "example": "套餐降级按比例信用" }, "source": { "type": "string", "example": "proration" }, "source_id": { "type": "string", "example": "sub_xyz789" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "type": { "type": "string", "example": "credit" } } }, "dto.CurrentUsageDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.CurrentUsageResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.CurrentUsageResponse": { "type": "object", "properties": { "api_calls_today": { "type": "integer", "example": 150 }, "storage_gb": { "type": "number", "example": 2.5 }, "users": { "type": "integer", "example": 8 } } }, "dto.DunningSettingsDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.DunningSettingsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.DunningSettingsRequest": { "type": "object", "properties": { "auto_cancel_days": { "type": "integer", "example": 30 }, "email_templates": { "type": "string" }, "grace_period_days": { "type": "integer", "example": 7 }, "retry_schedule": { "type": "string", "example": "[1,3,7,14]" } } }, "dto.DunningSettingsResponse": { "type": "object", "properties": { "auto_cancel_days": { "type": "integer", "example": 30 }, "created_at": { "type": "string", "example": "2026-05-12T10:00:00Z" }, "email_templates": { "type": "string" }, "grace_period_days": { "type": "integer", "example": 7 }, "retry_schedule": { "type": "string", "example": "[1,3,7,14]" }, "status": { "type": "string", "example": "active" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "updated_at": { "type": "string", "example": "2026-05-12T10:00:00Z" } } }, "dto.EndpointStatsImportRecord": { "type": "object", "required": [ "date", "endpoint" ], "properties": { "app_id": { "type": "string", "example": "app_001" }, "avg_latency_ms": { "type": "number", "example": 12.5 }, "date": { "type": "string", "example": "2026-05-10" }, "endpoint": { "type": "string" }, "error_count": { "type": "integer", "example": 50 }, "request_count": { "type": "integer", "example": 15000 } } }, "dto.EndpointStatsImportRequest": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/definitions/dto.EndpointStatsImportRecord" } } } }, "dto.EndpointUsageDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.EndpointUsageListResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.EndpointUsageItem": { "type": "object", "properties": { "avg_latency_ms": { "type": "number", "example": 12.5 }, "endpoint": { "type": "string" }, "error_count": { "type": "integer", "example": 50 }, "request_count": { "type": "integer", "example": 15000 } } }, "dto.EndpointUsageListResponse": { "type": "object", "properties": { "app_id": { "type": "string", "example": "app_001" }, "days": { "type": "integer", "example": 7 }, "endpoints": { "type": "array", "items": { "$ref": "#/definitions/dto.EndpointUsageItem" } }, "tenant_id": { "type": "string", "example": "tnt_xyz789" } } }, "dto.ExecuteRefundDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ExecuteRefundResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ExecuteRefundRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.ExecuteRefundResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 99 }, "refund_id": { "type": "string", "example": "ref_001" }, "status": { "type": "string", "example": "completed" }, "wallet_transaction_id": { "type": "string", "example": "txn_def456" } } }, "dto.ExportUserDataRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.ExportUserDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ExportUserDataResult" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ExportUserDataResult": { "type": "object", "properties": { "billing_records": { "type": "array", "items": { "$ref": "#/definitions/dto.BillingRecordResponse" } }, "credit_balance": { "$ref": "#/definitions/dto.CreditBalanceResponse" }, "credit_transactions": { "type": "array", "items": { "$ref": "#/definitions/dto.CreditTransactionResponse" } }, "exported_at": { "type": "string" }, "metered_billing_records": { "type": "array", "items": { "$ref": "#/definitions/dto.MeteredBillingExportItem" } }, "note": { "type": "string" }, "subscription": { "$ref": "#/definitions/dto.SubscriptionResponse" }, "tenant_id": { "type": "string" }, "usage_alerts": { "type": "array", "items": { "$ref": "#/definitions/dto.UsageAlertResponse" } }, "usage_stats": { "type": "array", "items": { "$ref": "#/definitions/dto.UsageStatsExportItem" } }, "user_id": { "type": "string" } } }, "dto.ExtendTrialRequest": { "type": "object", "required": [ "extend_days" ], "properties": { "extend_days": { "type": "integer", "example": 14 } } }, "dto.InvoiceDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.InvoiceResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.InvoiceLineItemResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 99 }, "description": { "type": "string", "example": "专业版月度订阅" }, "quantity": { "type": "integer", "example": 1 }, "resource_type": { "type": "string", "example": "subscription" }, "tax_amount": { "type": "number", "example": 5.94 }, "tax_rate": { "type": "number", "example": 0.06 }, "unit_price": { "type": "number", "example": 99 } } }, "dto.InvoiceResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 104.94 }, "app_id": { "type": "string", "example": "app_001" }, "currency": { "type": "string", "example": "CNY" }, "due_date": { "type": "string", "example": "2026-04-15T00:00:00Z" }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "issued_at": { "type": "string", "example": "2026-04-01T00:00:00Z" }, "line_items": { "type": "array", "items": { "$ref": "#/definitions/dto.InvoiceLineItemResponse" } }, "paid_at": { "type": "string", "example": "2026-04-10T15:00:00Z" }, "status": { "type": "string", "example": "issued" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" } } }, "dto.MeteredBillingExportItem": { "type": "object", "properties": { "included_units": { "type": "integer" }, "overage_amount": { "type": "string" }, "overage_units": { "type": "integer" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "total_usage": { "type": "integer" } } }, "dto.MeteredBillingListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/dto.MeteredBillingResponse" } }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.MeteredBillingResponse": { "type": "object", "properties": { "app_id": { "type": "string" }, "id": { "type": "string" }, "overage_amount": { "type": "string" }, "overage_units": { "type": "integer" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "tenant_id": { "type": "string" }, "total_usage": { "type": "integer" } } }, "dto.MeteringReportRequest": { "type": "object", "required": [ "amount", "resource_type" ], "properties": { "amount": { "type": "integer", "example": 1000 }, "app_id": { "type": "string", "example": "app_001" }, "resource_type": { "type": "string", "example": "api_calls" } } }, "dto.PaymentGatewayDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PaymentGatewayResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PaymentGatewayListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.PaymentGatewayResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.PaymentGatewayResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "alipay" }, "config": { "type": "string" }, "created_at": { "type": "string", "example": "2026-01-01T00:00:00Z" }, "id": { "type": "string", "example": "pg_001" }, "name": { "type": "string", "example": "支付宝" }, "status": { "type": "string", "example": "active" }, "updated_at": { "type": "string", "example": "2026-04-10T14:20:00Z" } } }, "dto.PlanChangeRequest": { "type": "object", "required": [ "new_plan" ], "properties": { "billing_cycle": { "type": "string", "example": "monthly" }, "new_plan": { "type": "string", "example": "enterprise" } } }, "dto.PlanDetail": { "type": "object", "properties": { "currency": { "type": "string", "example": "CNY" }, "description": { "type": "string", "example": "适用于大型团队" }, "features": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "example": "专业版" }, "plan_id": { "type": "string", "example": "pro" }, "price_monthly": { "type": "number", "example": 499 }, "price_yearly": { "type": "number", "example": 4999 }, "quotas": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "dto.PlanPricingDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PlanPricingResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PlanPricingModelDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PlanPricingModelResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PlanPricingModelResponse": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-01-01T00:00:00Z" }, "currency": { "type": "string", "example": "CNY" }, "description": { "type": "string", "example": "适用于大型团队" }, "feature_gates": { "type": "array", "items": { "$ref": "#/definitions/billing.FeatureGate" } }, "id": { "type": "string", "example": "ppm_001" }, "monthly_price": { "type": "number", "example": 499 }, "name": { "type": "string", "example": "专业版" }, "plan": { "type": "string", "example": "pro" }, "status": { "type": "string", "example": "active" }, "updated_at": { "type": "string", "example": "2026-04-10T14:20:00Z" }, "yearly_price": { "type": "number", "example": 4999 } } }, "dto.PlanPricingResponse": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/definitions/dto.PlanDetail" } } } }, "dto.PlanQuotasDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PlanQuotasResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PlanQuotasResponse": { "type": "object", "properties": { "max_api_requests": { "type": "integer", "example": 100000 }, "max_bandwidth_bytes": { "type": "integer", "example": 107374182400 }, "max_email_daily": { "type": "integer", "example": 5000 }, "max_sms_daily": { "type": "integer", "example": 1000 }, "max_storage_bytes": { "type": "integer", "example": 10737418240 }, "max_users": { "type": "integer", "example": 500 }, "name": { "type": "string", "example": "Professional" }, "plan": { "type": "string", "example": "pro" } } }, "dto.ProrationCalculateDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ProrationCalculateResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ProrationCalculateRequest": { "type": "object", "required": [ "new_plan" ], "properties": { "billing_cycle": { "type": "string", "example": "monthly" }, "new_plan": { "type": "string", "example": "enterprise" } } }, "dto.ProrationCalculateResponse": { "type": "object", "properties": { "currency": { "type": "string", "example": "CNY" }, "current_billing_end": { "type": "string", "example": "2026-06-01T00:00:00Z" }, "current_plan": { "type": "string", "example": "pro" }, "message": { "type": "string", "example": "升级将产生按比例费用 ¥249.50（剩余15天）" }, "proration_amount": { "type": "number", "example": 249.5 }, "remaining_days": { "type": "integer", "example": 15 }, "target_plan": { "type": "string", "example": "enterprise" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" } } }, "dto.PublicPlanResponse": { "type": "object", "properties": { "currency": { "type": "string", "example": "CNY" }, "description": { "type": "string", "example": "适用于个人开发者和小型项目" }, "features": { "type": "array", "items": { "type": "string" } }, "is_popular": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "免费版" }, "plan_id": { "type": "string", "example": "free" }, "price_monthly": { "type": "number", "example": 0 }, "price_yearly": { "type": "number", "example": 0 }, "quotas": { "type": "object", "additionalProperties": true } } }, "dto.PublicPlansDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PublicPlansResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PublicPlansResponse": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/definitions/dto.PublicPlanResponse" } } } }, "dto.QuotaCheckDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.QuotaCheckResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.QuotaCheckInternalRequest": { "type": "object", "required": [ "requested_amount", "resource_type" ], "properties": { "app_id": { "type": "string", "example": "app_001" }, "requested_amount": { "type": "integer", "minimum": 1, "example": 100 }, "resource_type": { "type": "string", "example": "api_calls" } } }, "dto.QuotaCheckResponse": { "type": "object", "properties": { "allowed": { "type": "boolean", "example": true }, "current": { "type": "integer", "example": 5000 }, "limit": { "type": "integer", "example": 10000 }, "message": { "type": "string" }, "remaining": { "type": "integer", "example": 5000 }, "resource_type": { "type": "string", "example": "api_calls" } } }, "dto.RefundApprovalDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.RefundApprovalResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.RefundApprovalListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.RefundApprovalResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.RefundApprovalRequest": { "type": "object", "required": [ "amount", "invoice_number", "reason", "transaction_id" ], "properties": { "amount": { "type": "number", "example": 99 }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "reason": { "type": "string", "example": "服务不满意" }, "reviewer_comments": { "type": "string", "example": "审批通过" }, "transaction_id": { "type": "string", "example": "txn_abc123" } } }, "dto.RefundApprovalResponse": { "type": "object", "properties": { "amount": { "type": "number", "example": 99 }, "approved_at": { "type": "string", "example": "2026-04-15T14:00:00Z" }, "approved_by": { "type": "string", "example": "admin@example.com" }, "invoice_number": { "type": "string", "example": "INV-2026-001" }, "refund_id": { "type": "string", "example": "ref_001" }, "status": { "type": "string", "example": "approved" }, "transaction_id": { "type": "string", "example": "txn_abc123" } } }, "dto.RevenueAmortizationDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.RevenueAmortizationResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.RevenueAmortizationItem": { "type": "object", "properties": { "amount": { "type": "number", "example": 99 }, "period": { "type": "string", "example": "2026-04" }, "status": { "type": "string", "example": "recognized" } } }, "dto.RevenueAmortizationResponse": { "type": "object", "properties": { "amortized_amount": { "type": "number", "example": 396 }, "end_date": { "type": "string", "example": "2026-12-31T00:00:00Z" }, "items": { "type": "array", "items": { "$ref": "#/definitions/dto.RevenueAmortizationItem" } }, "pending_amount": { "type": "number", "example": 792 }, "start_date": { "type": "string", "example": "2026-01-01T00:00:00Z" }, "subscription_id": { "type": "string", "example": "sub_001" }, "total_amount": { "type": "number", "example": 1188 } } }, "dto.SimpleResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.SubscribeRequestDTO": { "type": "object", "required": [ "billing_cycle", "plan" ], "properties": { "auto_renew": { "type": "boolean", "example": true }, "billing_cycle": { "type": "string", "example": "monthly" }, "plan": { "type": "string", "example": "pro" }, "trial_days": { "type": "integer", "example": 14 } } }, "dto.SubscriptionAppResponse": { "type": "object", "properties": { "app_id": { "type": "string", "example": "app_001" }, "created_at": { "type": "string", "example": "2026-04-01T00:00:00Z" }, "id": { "type": "string", "example": "sa_001" }, "pricings": { "type": "array", "items": { "$ref": "#/definitions/dto.AppResourcePricingResponse" } }, "status": { "type": "string", "example": "active" }, "subscription_id": { "type": "string", "example": "sub_001" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" } } }, "dto.SubscriptionDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.SubscriptionResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.SubscriptionResponse": { "type": "object", "properties": { "admin_user_id": { "type": "string", "example": "usr_abc123" }, "amount": { "type": "number", "example": 499 }, "auto_renew": { "type": "boolean", "example": true }, "billing_cycle": { "type": "string", "example": "monthly" }, "cancel_at_period_end": { "type": "boolean", "example": false }, "currency": { "type": "string", "example": "CNY" }, "current_period_end": { "type": "string", "example": "2026-02-01T00:00:00Z" }, "current_period_start": { "type": "string", "example": "2026-01-01T00:00:00Z" }, "grace_period_days": { "type": "integer", "example": 7 }, "plan_id": { "type": "string", "example": "pro" }, "status": { "type": "string", "example": "active" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "trial_end_date": { "type": "string", "example": "2026-01-15T00:00:00Z" } } }, "dto.TaxExportDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TaxExportResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TaxExportListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.TaxExportResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.TaxExportResponse": { "type": "object", "properties": { "download_url": { "type": "string", "example": "https://storage.example.com/..." }, "expires_at": { "type": "string", "example": "2026-04-16T10:00:00Z" }, "format": { "type": "string", "example": "pdf" }, "period": { "type": "string", "example": "2026-Q1" }, "tax_report_id": { "type": "string", "example": "tax_2026q1" } } }, "dto.TenantStatisticsDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TenantStatisticsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TenantStatisticsResponse": { "type": "object", "properties": { "active_users": { "type": "integer", "example": 45 }, "app_id": { "type": "string", "example": "app_001" }, "mrr": { "type": "number", "example": 99 }, "retention_rate": { "type": "number", "example": 0.95 }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "total_spend": { "type": "number", "example": 1188 } } }, "dto.TrialActionDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TrialActionResult" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TrialActionResult": { "type": "object", "properties": { "message": { "type": "string", "example": "试用期已延长14天" }, "plan": { "type": "string", "example": "pro" }, "status": { "type": "string", "example": "active" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "trial_end_date": { "type": "string", "example": "2026-06-01T00:00:00Z" } } }, "dto.UpdatePaymentGatewayRequest": { "type": "object", "properties": { "config": { "type": "string", "example": "{\"app_id\":\"654321\"}" }, "name": { "type": "string", "example": "支付宝国际版" }, "status": { "type": "string", "example": "active" } } }, "dto.UpdatePlanRequest": { "type": "object", "properties": { "audit_log_days": { "type": "integer", "example": 90 }, "description": { "type": "string", "example": "适用于大型团队" }, "max_api_requests": { "type": "integer", "example": 100000 }, "max_bandwidth_gb": { "type": "integer", "example": 1024 }, "max_storage_gb": { "type": "integer", "example": 100 }, "max_users": { "type": "integer", "example": 100 }, "mfa_enabled": { "type": "boolean", "example": true }, "monthly_price": { "type": "number", "example": 499 }, "name": { "type": "string", "example": "专业版" }, "sso_enabled": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "active" }, "support_level": { "type": "string", "example": "priority" }, "yearly_price": { "type": "number", "example": 4999 } } }, "dto.UpdateSubscriptionRequestDTO": { "type": "object", "properties": { "auto_renew": { "type": "boolean", "example": false }, "billing_cycle": { "type": "string", "example": "yearly" }, "plan": { "type": "string", "example": "enterprise" } } }, "dto.UpdateUsageAlertRequest": { "type": "object", "properties": { "name": { "type": "string" }, "notification_channels": { "type": "string" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "threshold_percent": { "type": "integer" } } }, "dto.UsageAlertDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.UsageAlertResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.UsageAlertListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.UsageAlertResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.UsageAlertResponse": { "type": "object", "properties": { "app_id": { "type": "string", "example": "app_001" }, "created_at": { "type": "string", "example": "2026-05-01T00:00:00Z" }, "id": { "type": "string", "example": "ua_001" }, "last_triggered_at": { "type": "string", "example": "2026-05-10T08:00:00Z" }, "name": { "type": "string", "example": "API调用量告警" }, "notification_channels": { "type": "string", "example": "email,in_app" }, "resource_type": { "type": "string", "example": "api_calls" }, "status": { "type": "string", "example": "active" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "threshold_percent": { "type": "integer", "example": 80 }, "updated_at": { "type": "string", "example": "2026-05-05T10:00:00Z" } } }, "dto.UsageStatItem": { "type": "object", "properties": { "limit": { "type": "integer", "example": 100 }, "unit": { "type": "string", "example": "个" }, "used": { "type": "integer", "example": 8 } } }, "dto.UsageStatsDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.UsageStatsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.UsageStatsExportItem": { "type": "object", "properties": { "api_requests": { "type": "integer" }, "bandwidth_used": { "type": "integer" }, "date": { "type": "string" }, "failed_logins": { "type": "integer" }, "login_attempts": { "type": "integer" }, "mfa_verifications": { "type": "integer" }, "storage_used": { "type": "integer" }, "user_count": { "type": "integer" } } }, "dto.UsageStatsResponse": { "type": "object", "properties": { "api_calls": { "$ref": "#/definitions/dto.UsageStatItem" }, "app_id": { "type": "string", "example": "app_001" }, "period_end": { "type": "string", "example": "2026-04-01" }, "period_start": { "type": "string", "example": "2026-03-01" }, "storage": { "$ref": "#/definitions/dto.UsageStatItem" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "users": { "$ref": "#/definitions/dto.UsageStatItem" } } }, "dto.UsageTimelineDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.UsageTimelineResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.UsageTimelinePoint": { "type": "object", "properties": { "api_requests": { "type": "integer", "example": 15000 }, "bandwidth_gb": { "type": "number", "example": 15 }, "date": { "type": "string", "example": "2026-05-01" }, "storage_gb": { "type": "number", "example": 2.5 }, "users": { "type": "integer", "example": 120 } } }, "dto.UsageTimelineResponse": { "type": "object", "properties": { "app_id": { "type": "string", "example": "app_001" }, "days": { "type": "integer", "example": 30 }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "timeline": { "type": "array", "items": { "$ref": "#/definitions/dto.UsageTimelinePoint" } } } }, "gitee_com_linmes_authms_base_dto.PageInfo": { "type": "object", "properties": { "has_next": { "description": "HasNext indicates whether there is a next page", "type": "boolean" }, "has_prev": { "description": "HasPrev indicates whether there is a previous page", "type": "boolean" }, "page": { "description": "Page is the current page number (1-based)", "type": "integer" }, "page_size": { "description": "PageSize is the number of items per page", "type": "integer" }, "total": { "description": "Total is the total number of items across all pages", "type": "integer" }, "total_pages": { "description": "TotalPages is the total number of pages", "type": "integer" } } }, "handler.featureGateCheckRequest": { "type": "object", "properties": { "gate_key": { "type": "string" } } }, "handler.featureGateCheckResult": { "type": "object", "properties": { "effective": { "type": "boolean" }, "gate_key": { "type": "string" }, "plan_entitled": { "type": "boolean" }, "tenant_override": { "type": "boolean" } } }, "handler.featureGateResponse": { "type": "object", "properties": { "feature_gates": { "type": "array", "items": { "$ref": "#/definitions/billing.FeatureGate" } } } }, "handler.overrideRequest": { "type": "object", "required": [ "gate_key" ], "properties": { "enabled": { "type": "boolean" }, "gate_key": { "type": "string" } } }, "handler.overrideResponse": { "type": "object", "properties": { "overrides": { "type": "array", "items": { "$ref": "#/definitions/domain.TenantFeatureGateOverride" } } } } }, "securityDefinitions": { "bearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "description": "计费服务对外接口：订阅管理、账单生成、支付处理、税务管理", "name": "计费服务" }, { "description": "计费服务内部接口：供其他微服务调用的内部端点", "name": "计费服务 - 内部接口" } ] }