{ "swagger": "2.0", "info": { "description": "积分服务，提供积分获取、消费、规则管理、统计等功能", "title": "Point Service API", "contact": {}, "version": "1.0.0" }, "basePath": "/api/v1", "paths": { "/admin/point-rules": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，查询租户下的积分规则列表。默认仅返回启用的规则，设置 include_disabled=true 可同时返回已禁用的规则。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "获取积分规则列表", "parameters": [ { "type": "boolean", "default": false, "description": "包含已禁用规则", "name": "include_disabled", "in": "query" } ], "responses": { "200": { "description": "积分规则列表", "schema": { "$ref": "#/definitions/dto.PointRuleListResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，为租户创建新的积分规则。规则匹配事件类型后自动触发积分发放。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "创建积分规则", "parameters": [ { "description": "创建规则请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreatePointRuleRequest" } } ], "responses": { "201": { "description": "规则创建成功", "schema": { "$ref": "#/definitions/dto.PointRuleDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "409": { "description": "规则名称已存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/point-rules/test": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，dry-run 试算给定事件类型匹配的规则参数和预期积分。不实际发放积分，不修改任何数据。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "规则试算", "parameters": [ { "description": "试算请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TestRuleRequest" } } ], "responses": { "200": { "description": "试算结果（points/effective_rate/daily_remaining）", "schema": { "$ref": "#/definitions/dto.RuleTestResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "无匹配的积分规则", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/point-rules/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，根据规则ID获取规则详情。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "获取单个积分规则详情", "parameters": [ { "type": "string", "description": "规则ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "规则详情", "schema": { "$ref": "#/definitions/dto.PointRuleDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "规则不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，部分更新积分规则字段，仅更新请求中提供的字段（name、event_type、points、multiplier、daily_limit、total_limit、enabled）。", "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.UpdatePointRuleRequest" } } ], "responses": { "200": { "description": "规则更新成功", "schema": { "$ref": "#/definitions/dto.PointRuleDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "规则不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，软删除积分规则（设置 enabled=false），不物理删除记录。已禁用的规则再次调用返回404。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "删除积分规则", "parameters": [ { "type": "string", "description": "规则ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "规则不存在或已禁用", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询租户下所有积分账户，可按状态筛选。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "查询积分账户列表", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" }, { "enum": [ "active", "suspended", "closed" ], "type": "string", "description": "状态筛选", "name": "status", "in": "query" } ], "responses": { "200": { "description": "积分账户分页列表", "schema": { "$ref": "#/definitions/dto.PointAccountListResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "资源不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "为用户在当前租户下创建积分账户。同一用户在同一租户下只能有一个积分账户。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "创建积分账户", "parameters": [ { "description": "创建积分账户请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreatePointAccountRequest" } } ], "responses": { "201": { "description": "积分账户创建成功", "schema": { "$ref": "#/definitions/dto.PointAccountDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "资源不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "409": { "description": "账户已存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/apply-rule": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，根据事件类型匹配租户下已启用的积分规则并自动发放积分。计算逻辑：基础积分 × multiplier，若配置 daily_limit 则检查当日已获得量。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "应用积分规则", "parameters": [ { "description": "应用规则请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ApplyPointRuleRequest" } } ], "responses": { "200": { "description": "规则应用成功，积分已发放", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "无匹配的积分规则", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/batch-earn": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，一次请求向多个用户发放积分。逐条处理，每条记录独立处理，某条失败不影响其他记录。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "批量发放积分", "parameters": [ { "description": "批量发放请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.BatchEarnRequest" } } ], "responses": { "200": { "description": "批量发放完成，返回成功和失败的统计", "schema": { "$ref": "#/definitions/dto.BatchEarnResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/config": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，查询当前租户的积分配置，包含积分类型、兑换比率、过期策略、功能开关等。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "获取租户积分配置", "responses": { "200": { "description": "租户积分配置", "schema": { "$ref": "#/definitions/dto.TenantConfigDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "配置不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，更新当前租户的积分配置参数（积分类型、兑换比率、过期策略、功能开关等）。仅更新请求中提供的字段。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "更新租户积分配置", "parameters": [ { "description": "更新配置请求（所有字段可选）", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateTenantConfigRequest" } } ], "responses": { "200": { "description": "配置更新成功", "schema": { "$ref": "#/definitions/dto.TenantConfigDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "配置不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，删除当前租户的积分配置。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "删除租户积分配置", "responses": { "200": { "description": "配置删除成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "配置不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/{user_id}": { "delete": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，删除指定用户的积分账户（物理删除）。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "删除积分账户", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "账户删除成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/{user_id}/adjust": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，对用户积分进行调整。正数增加积分，负数扣减积分。建议填写明确的 reason 以便审计追溯。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "调整积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "调整积分请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.AdjustPointsRequest" } } ], "responses": { "200": { "description": "积分调整成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/{user_id}/expire": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，手动触发积分过期，将指定积分从可用余额扣除并标记为已过期。请求的 amount 超过当前可用余额时按比例结算。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "处理积分过期", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "积分过期请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ExpirePointsRequest" } } ], "responses": { "200": { "description": "积分过期处理完成", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/{user_id}/freeze": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，冻结用户可用积分，将指定数额从可用余额转入冻结余额。冻结期间积分不可消费。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "冻结积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "冻结积分请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.FreezePointsRequest" } } ], "responses": { "200": { "description": "积分冻结成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或可用余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/{user_id}/status": { "put": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，修改积分账户状态。suspended 状态不可进行 earn/spend 操作，closed 状态不可逆。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "更新积分账户状态", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "状态更新请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateAccountStatusRequest" } } ], "responses": { "200": { "description": "状态更新成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/points/{user_id}/unfreeze": { "post": { "security": [ { "bearerAuth": [] } ], "description": "管理员操作，将之前冻结的积分解冻，恢复为可用余额。解冻数额不能超过当前冻结余额。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "解冻积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "解冻积分请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UnfreezePointsRequest" } } ], "responses": { "200": { "description": "积分解冻成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或冻结余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "无权限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/point/accounts/{user_id}": { "get": { "description": "服务间内部调用，供其他微服务查询积分账户信息。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务 - 内部接口" ], "summary": "内部获取积分账户", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "积分账户信息", "schema": { "$ref": "#/definitions/dto.PointAccountDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/point/delete-user-data": { "post": { "description": "服务间内部调用，匿名化指定用户的所有积分数据，用于 GDPR 擦除合规场景。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务 - 内部接口" ], "summary": "GDPR 删除用户数据", "parameters": [ { "description": "删除用户数据请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.DeleteUserDataRequest" } } ], "responses": { "200": { "description": "用户数据删除成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/point/export-user-data": { "post": { "description": "服务间内部调用，导出指定用户的积分账户和统计数据，用于 GDPR 数据导出等合规场景。", "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.DataResponse-dto_ExportUserDataResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/runtime": { "get": { "description": "获取积分服务的运行时状态信息。", "produces": [ "application/json" ], "tags": [ "积分服务 - 内部接口" ], "summary": "服务运行时信息", "responses": { "200": { "description": "运行时状态", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "服务不可用", "schema": { "type": "object", "additionalProperties": true } } } } }, "/points/{user_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据用户ID获取积分账户信息，包含可用余额、冻结余额、总获得、总消费、过期积分、积分类型、兑换比率等。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "获取积分账户详情", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "积分账户详情", "schema": { "$ref": "#/definitions/dto.PointAccountDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/confirm-deduction": { "post": { "security": [ { "bearerAuth": [] } ], "description": "从冻结余额中确认扣除积分。适用于订单确认后实际扣减冻结积分的场景。工作流：Freeze → ConfirmDeduction 或 Unfreeze。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "确认扣除冻结积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "确认扣除请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ConfirmDeductionRequest" } } ], "responses": { "200": { "description": "扣除确认成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或冻结余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/earn": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为用户账户添加积分。如果账户不存在则自动创建。通过 X-Idempotency-Key 请求头实现幂等。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "获得积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "description": "幂等键，推荐UUID", "name": "X-Idempotency-Key", "in": "header" }, { "description": "获得积分请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EarnPointsRequest" } } ], "responses": { "200": { "description": "积分发放成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "409": { "description": "并发冲突，请重试", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/exchange": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将积分兑换为指定类型的物品（如优惠券、折扣等）。需要租户开启 ExchangeEnabled 配置。兑换后积分即扣除，不可逆。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "积分兑换", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "description": "幂等键，推荐UUID", "name": "X-Idempotency-Key", "in": "header" }, { "description": "兑换请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ExchangePointsRequest" } } ], "responses": { "200": { "description": "积分兑换成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/expiring": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询用户账户中在未来N天内即将过期的积分明细，包含每笔的来源、数额、到期日、剩余天数。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "查询即将过期积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "default": 30, "description": "查询天数范围", "name": "days", "in": "query" } ], "responses": { "200": { "description": "即将过期积分详情", "schema": { "$ref": "#/definitions/dto.ExpiringPointDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "用户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/refund": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将已消费的积分退还给用户，用于订单退款、交易撤销等场景。建议传入 related_tx_id 以建立退款链路。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "退回积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "description": "退回积分请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.RefundPointsRequest" } } ], "responses": { "200": { "description": "积分退回成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/risk-score": { "get": { "security": [ { "bearerAuth": [] } ], "description": "基于多维度因子（冻结次数、消费比率、近期获取频率、负余额、交易活跃度）对积分账户进行反作弊/套利风险评估。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "积分账户风险评分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "风险评分（score\u003e=70高风险，40-69中风险，\u003c40低风险）", "schema": { "$ref": "#/definitions/dto.PointRiskScoreDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "用户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/spend": { "post": { "security": [ { "bearerAuth": [] } ], "description": "从用户账户扣除可用积分。账户必须存在且余额充足，冻结积分不可用于消费。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "消费积分", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "description": "幂等键，推荐UUID", "name": "X-Idempotency-Key", "in": "header" }, { "description": "消费积分请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SpendPointsRequest" } } ], "responses": { "200": { "description": "积分消费成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/stats": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取用户积分账户的综合统计数据：当前余额、总获得/消费/过期、本月数据、30天内即将过期积分。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "积分统计", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "积分统计数据", "schema": { "$ref": "#/definitions/dto.PointStatsDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "用户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/transactions": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询用户的积分交易历史，支持按类型筛选，按创建时间倒序排列。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "查询交易记录", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" }, { "enum": [ "earn", "spend", "expire", "freeze", "unfreeze", "refund", "adjust" ], "type": "string", "description": "交易类型", "name": "type", "in": "query" } ], "responses": { "200": { "description": "交易记录分页列表", "schema": { "$ref": "#/definitions/dto.PointTransactionListResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "用户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/transactions/{tx_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据交易ID查询交易详情，包括余额快照（balance_before / balance_after）。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "获取单笔交易详情", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "description": "交易ID", "name": "tx_id", "in": "path", "required": true } ], "responses": { "200": { "description": "交易详情", "schema": { "$ref": "#/definitions/dto.PointTransactionDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "交易不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/transfer": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将积分从当前用户账户转给同租户下另一用户。需要租户开启 TransferEnabled 配置。通过 X-Idempotency-Key 请求头防幂等重复转账。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "积分转账", "parameters": [ { "type": "string", "description": "发送方用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "description": "幂等键，推荐UUID", "name": "X-Idempotency-Key", "in": "header" }, { "description": "转账请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TransferPointsRequest" } } ], "responses": { "200": { "description": "积分转账成功，返回账户和交易记录", "schema": { "$ref": "#/definitions/dto.PointOperationResponse" } }, "400": { "description": "请求参数错误或余额不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "账户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/points/{user_id}/value": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据积分类型和兑换比率计算当前余额对应的现金价值。cash_value = balance / exchange_rate。仅 cash_equivalent 类型可兑换。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "积分服务" ], "summary": "积分现金价值", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "积分现金价值", "schema": { "$ref": "#/definitions/dto.PointValueResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "用户不存在", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } } }, "definitions": { "dto.AdjustPointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "description": "正数增加，负数减少", "type": "integer" }, "reason": { "type": "string" } } }, "dto.ApplyPointRuleRequest": { "type": "object", "required": [ "event_type", "user_id" ], "properties": { "event_type": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "user_id": { "type": "string" } } }, "dto.BatchEarnItem": { "type": "object", "properties": { "amount": { "type": "integer", "example": 100 }, "error": { "type": "string" }, "new_balance": { "type": "integer", "example": 1100 }, "success": { "type": "boolean", "example": true }, "user_id": { "type": "string", "example": "user-001" } } }, "dto.BatchEarnRequest": { "type": "object", "required": [ "users" ], "properties": { "description": { "type": "string" }, "source": { "type": "string" }, "users": { "type": "array", "items": { "$ref": "#/definitions/dto.BatchEarnUser" } } } }, "dto.BatchEarnResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.BatchEarnResult" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.BatchEarnResult": { "type": "object", "properties": { "failed_count": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/definitions/dto.BatchEarnItem" } }, "success_count": { "type": "integer", "example": 3 } } }, "dto.BatchEarnUser": { "type": "object", "required": [ "amount", "user_id" ], "properties": { "amount": { "type": "integer" }, "user_id": { "type": "string" } } }, "dto.ConfirmDeductionRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "reason": { "type": "string" } } }, "dto.CreatePointAccountRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } }, "dto.CreatePointRuleRequest": { "type": "object", "required": [ "event_type", "name", "points" ], "properties": { "daily_limit": { "type": "integer" }, "event_type": { "type": "string" }, "multiplier": { "type": "number" }, "name": { "type": "string" }, "points": { "type": "integer" }, "total_limit": { "type": "integer" } } }, "dto.DataResponse-dto_ExportUserDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ExportUserDataResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.DeleteUserDataRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } }, "dto.EarnPointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "description": { "type": "string" }, "expires_at": { "type": "string" }, "source": { "type": "string" } } }, "dto.ExchangePointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "description": { "type": "string" }, "exchange_type": { "type": "string" }, "source": { "type": "string" } } }, "dto.ExpirePointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "description": { "type": "string" } } }, "dto.ExpiringPointDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ExpiringPointsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ExpiringPointResponse": { "type": "object", "properties": { "amount": { "type": "integer", "example": 500 }, "days_left": { "type": "integer", "example": 7 }, "expires_at": { "type": "string", "example": "2026-06-15T00:00:00Z" }, "source": { "type": "string", "example": "signup_bonus" }, "transaction_id": { "type": "string", "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV" } } }, "dto.ExpiringPointsResponse": { "type": "object", "properties": { "days_threshold": { "type": "integer", "example": 30 }, "expiring_points": { "type": "array", "items": { "$ref": "#/definitions/dto.ExpiringPointResponse" } }, "total_expiring": { "type": "integer", "example": 1500 }, "user_id": { "type": "string", "example": "usr_example_001" } } }, "dto.ExportUserDataRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } }, "dto.ExportUserDataResponse": { "type": "object", "properties": { "account": { "$ref": "#/definitions/dto.PointAccountResponse" }, "stats": { "$ref": "#/definitions/dto.PointStatsResponse" } } }, "dto.FreezePointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "reason": { "type": "string" } } }, "dto.PointAccountDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointAccountResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointAccountListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.PointAccountResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.PointAccountResponse": { "type": "object", "properties": { "balance": { "type": "integer", "example": 1500 }, "created_at": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "exchange_rate": { "type": "integer", "example": 100 }, "expired_points": { "type": "integer", "example": 100 }, "frozen_balance": { "type": "integer", "example": 200 }, "id": { "type": "string", "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }, "points_type": { "type": "string", "example": "cash_equivalent" }, "status": { "type": "string", "example": "active" }, "tenant_id": { "type": "string", "example": "tnt_example_001" }, "total_earned": { "type": "integer", "example": 5000 }, "total_spent": { "type": "integer", "example": 3500 }, "updated_at": { "type": "string", "example": "2026-04-10T14:20:00Z" }, "user_id": { "type": "string", "example": "usr_example_001" }, "version": { "type": "integer", "example": 3 } } }, "dto.PointOperationData": { "type": "object", "properties": { "account": { "$ref": "#/definitions/dto.PointAccountResponse" }, "points_earned": { "type": "integer", "example": 100 }, "transaction": { "$ref": "#/definitions/dto.PointTransactionResponse" } } }, "dto.PointOperationResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointOperationData" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointRiskScoreDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointRiskScoreResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointRiskScoreResponse": { "type": "object", "properties": { "factors": { "type": "array", "items": { "type": "string" }, "example": [ "[\"normal_behavior\"", "\"trusted_device\"]" ] }, "risk_level": { "type": "string", "example": "low" }, "risk_score": { "type": "integer", "example": 10 }, "user_id": { "type": "string", "example": "usr_example_001" } } }, "dto.PointRuleDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointRuleResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointRuleListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/dto.PointRuleResponse" } }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointRuleResponse": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "daily_limit": { "type": "integer", "example": 3 }, "enabled": { "type": "boolean", "example": true }, "event_type": { "type": "string", "example": "daily_checkin" }, "expiry_days": { "type": "integer", "example": 365 }, "id": { "type": "string", "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }, "multiplier": { "type": "number", "example": 1.5 }, "name": { "type": "string", "example": "每日签到" }, "points": { "type": "integer", "example": 10 }, "priority": { "type": "integer", "example": 1 }, "tenant_id": { "type": "string", "example": "tnt_example_001" }, "total_limit": { "type": "integer", "example": 100 }, "updated_at": { "type": "string", "example": "2026-04-10T14:20:00Z" } } }, "dto.PointStatsDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointStatsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointStatsResponse": { "type": "object", "properties": { "current_balance": { "type": "integer", "example": 1500 }, "earned_this_month": { "type": "integer", "example": 200 }, "expiring_soon": { "type": "integer", "example": 500 }, "spent_this_month": { "type": "integer", "example": 150 }, "total_earned": { "type": "integer", "example": 5000 }, "total_expired": { "type": "integer", "example": 100 }, "total_spent": { "type": "integer", "example": 3500 }, "user_id": { "type": "string", "example": "usr_example_001" } } }, "dto.PointTransactionDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointTransactionResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointTransactionListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.PointTransactionResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.PointTransactionResponse": { "type": "object", "properties": { "account_id": { "type": "string", "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }, "amount": { "type": "integer", "example": 100 }, "balance_after": { "type": "integer", "example": 1500 }, "balance_before": { "type": "integer", "example": 1400 }, "created_at": { "type": "string", "example": "2026-04-15T10:30:00Z" }, "description": { "type": "string", "example": "每日签到奖励" }, "expires_at": { "type": "string", "example": "2027-01-15T10:30:00Z" }, "id": { "type": "string", "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }, "idempotency_key": { "type": "string", "example": "ik_abc123" }, "reason": { "type": "string", "example": "签到奖励" }, "related_id": { "type": "string", "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }, "source": { "type": "string", "example": "daily_checkin" }, "status": { "type": "string", "example": "completed" }, "type": { "type": "string", "example": "earn" }, "updated_at": { "type": "string", "example": "2026-04-15T10:30:00Z" }, "user_id": { "type": "string", "example": "usr_example_001" } } }, "dto.PointValueResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PointValueResult" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PointValueResult": { "type": "object", "properties": { "balance": { "type": "integer", "example": 5000 }, "cash_value": { "type": "string", "example": "50" }, "exchange_rate": { "type": "integer", "example": 100 }, "points_type": { "type": "string", "example": "cash_equivalent" }, "user_id": { "type": "string", "example": "user-001" } } }, "dto.RefundPointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "description": { "type": "string" }, "related_tx_id": { "type": "string" } } }, "dto.RuleTestResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "$ref": "#/definitions/dto.RuleTestResult" }, "message": { "type": "string", "example": "success" } } }, "dto.RuleTestResult": { "type": "object", "properties": { "daily_remaining": { "type": "integer", "example": 3 }, "effective_rate": { "type": "number", "example": 2 }, "points": { "type": "integer", "example": 100 } } }, "dto.SpendPointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "description": { "type": "string" }, "source": { "type": "string" } } }, "dto.TenantConfigDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TenantConfigResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TenantConfigResponse": { "type": "object", "properties": { "default_expiry_days": { "type": "integer", "example": 365 }, "earn_enabled": { "type": "boolean", "example": true }, "exchange_enabled": { "type": "boolean", "example": true }, "exchange_rate": { "type": "integer", "example": 100 }, "expire_enabled": { "type": "boolean", "example": true }, "expiry_mode": { "type": "string", "example": "rolling" }, "max_balance": { "type": "integer", "example": 100000 }, "min_spend_points": { "type": "integer", "example": 10 }, "points_type": { "type": "string", "example": "cash_equivalent" }, "spend_enabled": { "type": "boolean", "example": true }, "tenant_id": { "type": "string", "example": "tnt_example_001" }, "transfer_enabled": { "type": "boolean", "example": true } } }, "dto.TestRuleRequest": { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string" } } }, "dto.TransferPointsRequest": { "type": "object", "required": [ "amount", "to_user_id" ], "properties": { "amount": { "type": "integer" }, "description": { "type": "string" }, "reason": { "type": "string", "maxLength": 200 }, "source": { "type": "string" }, "to_user_id": { "type": "string" } } }, "dto.UnfreezePointsRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer" }, "reason": { "type": "string" } } }, "dto.UpdateAccountStatusRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "dto.UpdatePointRuleRequest": { "type": "object", "properties": { "daily_limit": { "type": "integer" }, "enabled": { "type": "boolean" }, "event_type": { "type": "string" }, "multiplier": { "type": "number" }, "name": { "type": "string" }, "points": { "type": "integer" }, "total_limit": { "type": "integer" } } }, "dto.UpdateTenantConfigRequest": { "type": "object", "properties": { "default_expiry_days": { "type": "integer" }, "earn_enabled": { "type": "boolean" }, "exchange_enabled": { "type": "boolean" }, "exchange_rate": { "type": "integer" }, "expire_enabled": { "type": "boolean" }, "expiry_mode": { "type": "string" }, "max_balance": { "type": "integer" }, "min_spend_points": { "type": "integer" }, "points_type": { "type": "string" }, "spend_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" } } }, "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" } } }, "gitee_com_linmes_authms_base_dto.SimpleResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } } }, "securityDefinitions": { "bearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "description": "积分账户管理：创建、查询、冻结", "name": "积分账户" }, { "description": "积分操作：获取、消费、转让、过期", "name": "积分操作" }, { "description": "积分查询：余额、明细、统计", "name": "积分查询" }, { "description": "积分规则管理：创建、编辑、生效", "name": "积分规则" }, { "description": "积分管理后台：全局配置、审计", "name": "积分管理" } ] }