{ "swagger": "2.0", "info": { "description": "通信服务，提供短信、邮件、推送等多种通信渠道的集成和管理功能", "title": "Communication Service API", "contact": {}, "version": "1.0.0" }, "basePath": "/api/v1", "paths": { "/admin/communication/logs": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理员可按用户ID查询任意用户的通信日志，支持分页和渠道、状态筛选。与普通用户GetLogs接口不同，此接口不受用户隔离限制。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "管理员查询任意用户的通信日志", "parameters": [ { "type": "string", "description": "目标用户ID（不传返回全部用户的日志）", "name": "user_id", "in": "query" }, { "type": "string", "description": "发送渠道筛选：sms/email/push", "name": "channel", "in": "query" }, { "type": "string", "description": "发送状态筛选：pending/sent/failed/delivered", "name": "status", "in": "query" }, { "type": "integer", "description": "页码，从1开始（默认1）", "name": "page", "in": "query" }, { "type": "integer", "description": "每页条数（默认20）", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回完整通信日志列表", "schema": { "$ref": "#/definitions/dto.CommunicationLogListResponse" } }, "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/communication/platform-stats": { "get": { "security": [ { "bearerAuth": [] } ], "description": "返回跨所有租户的通信服务汇总统计，包括总发送量、投递成功率、按渠道和状态的分布。仅限超级管理员访问。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "获取平台级通信仪表盘（跨租户）", "responses": { "200": { "description": "查询成功，返回平台级汇总仪表盘数据", "schema": { "$ref": "#/definitions/dto.CommunicationDashboardDataResponse" } }, "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/communication/providers": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为当前租户创建短信/邮件/推送服务商的连接配置。支持阿里云、腾讯云、AWS SNS/SES、SendGrid、FCM等主流服务商。配置内容（API密钥等）以加密方式存储，响应中自动脱敏。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "创建服务商配置", "parameters": [ { "description": "创建服务商配置请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateProviderConfigRequest" } } ], "responses": { "201": { "description": "创建成功，返回配置详情（凭据已脱敏）", "schema": { "$ref": "#/definitions/dto.ProviderConfigDataResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "409": { "description": "同渠道同服务商的配置已存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/providers/{id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "更新指定服务商配置的凭据、激活状态和优先级。支持部分更新（仅传需要修改的字段）。配置凭据以加密方式存储。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.UpdateProviderConfigRequest" } } ], "responses": { "200": { "description": "更新成功，返回更新后的配置详情（凭据已脱敏）", "schema": { "$ref": "#/definitions/dto.ProviderConfigDataResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "配置不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除指定的服务商配置记录。删除后该渠道将回退使用默认服务商或提示未配置。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "配置不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/rate-limits": { "get": { "security": [ { "bearerAuth": [] } ], "description": "返回当前系统中各渠道（sms/email/push）的速率限制配置，包括每分钟/每小时最大发送量和当前服务商。管理员可查看系统默认值和租户级别覆盖。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "管理员查看限流配置", "parameters": [ { "type": "string", "description": "渠道筛选：sms/email/push（不传返回全部）", "name": "channel", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回各渠道速率限制配置", "schema": { "$ref": "#/definitions/dto.RateLimitsDetailResponse" } }, "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/communication/resend/{id}": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将处于failed或cancelled状态的消息重新加入发送队列进行重试。仅支持sms和email渠道（推送不支持重发）。重发后会创建新的发送记录并通过对应服务商重新投递。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源（仅管理员）", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "消息不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "409": { "description": "消息状态不允许重发（仅failed/cancelled可重发）", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/templates": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为当前租户创建消息发送模板。支持短信、邮件、推送三种渠道，模板内容可使用 {{变量}} 或 Go template 语法定义变量占位符（如 {{code}}），后续发送时由传入的变量值替换。模板支持多语言（locale）。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "创建消息模板", "parameters": [ { "description": "创建模板请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateTemplateRequest" } } ], "responses": { "201": { "description": "模板创建成功，返回模板详情", "schema": { "$ref": "#/definitions/dto.CreateTemplateResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "资源不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/templates/{id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "更新指定模板的名称、内容、变量列表等字段。更新后自动递增模板版本号，旧版本保留在版本历史中。支持修改模板的激活状态。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.UpdateTemplateRequest" } } ], "responses": { "200": { "description": "更新成功，返回更新后的模板详情", "schema": { "$ref": "#/definitions/dto.MessageTemplateDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "模板不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "软删除消息模板（将is_active设置为false）。如存在待发送消息（pending状态）引用该模板，则拒绝删除以保证投递可追踪。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "模板不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "409": { "description": "存在待发送消息引用该模板，无法删除", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/templates/{id}/clone-to-locale": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将源模板的所有字段（名称、内容、变量等）复制一份到目标语言区域（locale），保持相同的模板编码（code）。用于快速创建多语言模板。如果目标locale已存在同名模板，返回409冲突。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.CloneTemplateToLocaleRequest" } } ], "responses": { "200": { "description": "复制成功，返回新模板详情", "schema": { "$ref": "#/definitions/dto.MessageTemplateDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "源模板不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "409": { "description": "目标语言环境已存在同名模板", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/templates/{id}/preview": { "post": { "security": [ { "bearerAuth": [] } ], "description": "使用提供的变量值渲染指定模板，返回渲染后的主题、内容和纯文本版本，用于发送前预览确认。支持 simple 和 go-template 两种模板格式。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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": { "type": "object" } } ], "responses": { "200": { "description": "渲染成功，返回包含subject/content/text_content的渲染结果", "schema": { "type": "object" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "模板不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/communication/templates/{id}/versions": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据模板ID获取该模板的所有历史版本记录。每次更新模板会递增版本号并保存快照，用于变更追溯和版本回退参考。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.TemplateVersionListResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "模板不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/bulk": { "post": { "security": [ { "bearerAuth": [] } ], "description": "向多个接收方批量发送短信或邮件。支持模板变量替换，逐条记录发送状态，适用于营销通知、系统公告等批量通信场景。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "批量发送消息", "parameters": [ { "description": "批量发送请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.BulkSendRequest" } } ], "responses": { "200": { "description": "批量发送成功，返回各条日志列表", "schema": { "$ref": "#/definitions/dto.CommunicationLogListResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "资源不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/callback/{provider}": { "post": { "description": "接收并处理各短信、邮件、推送服务商（阿里云、腾讯云、AWS SNS/SES、SendGrid、Mailgun、FCM、APNs、JPush等）的投递状态回调通知，自动更新对应消息的发送状态。回调为公开端点，由各服务商直接调用。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "处理短信/邮件/推送服务商回调", "parameters": [ { "type": "string", "description": "服务商名称：aliyun/tencentcloud/aws/sendgrid/ses/mailgun/fcm/apns/jpush", "name": "provider", "in": "path", "required": true }, { "description": "回调数据（各服务商格式不同，支持JSON和Form表单）", "name": "request", "in": "body", "schema": { "type": "object" } } ], "responses": { "200": { "description": "回调已接收确认", "schema": { "$ref": "#/definitions/dto.CallbackResultDetailResponse" } }, "400": { "description": "请求数据格式错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "回调处理内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/dashboard": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取当前租户的通信服务各渠道投递统计数据，包括总发送量、成功投递数、失败数、投递成功率，以及按渠道和状态的分布统计。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "获取通信投递仪表盘", "parameters": [ { "type": "integer", "description": "统计天数范围（默认30天）", "name": "days", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回租户通信投递仪表盘数据", "schema": { "$ref": "#/definitions/dto.CommunicationDashboardDataResponse" } }, "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" } } } } }, "/communication/email": { "post": { "security": [ { "bearerAuth": [] } ], "description": "向指定邮箱地址发送邮件。支持模板（需预定义模板）或直接发送HTML/纯文本内容，支持CC抄送和BCC密送，自动记录到发送日志。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "发送邮件", "parameters": [ { "description": "邮件发送请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EmailRequest" } } ], "responses": { "200": { "description": "发送成功，返回发送日志详情", "schema": { "$ref": "#/definitions/dto.CommunicationLogDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "资源不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/health/{channel}": { "get": { "description": "检查指定通信渠道（sms/email/push）的服务商配置和连通性状态。用于运维监控，验证服务商API端点是否可达、配置是否有效。公开端点，无需认证。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "渠道连通性检查", "parameters": [ { "type": "string", "description": "通信渠道：sms/email/push", "name": "channel", "in": "path", "required": true } ], "responses": { "200": { "description": "检查成功，返回渠道健康状态（healthy/unhealthy/not_configured）", "schema": { "$ref": "#/definitions/dto.ChannelHealthDataResponse" } }, "400": { "description": "渠道参数无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "健康检查内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/logs": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询当前租户的消息发送记录。按当前登录用户隔离数据（仅返回本人的发送记录），支持按渠道（sms/email/push）和发送状态（pending/sent/failed/delivered）筛选。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "分页查询发送日志", "parameters": [ { "type": "string", "description": "用户ID（按当前登录用户自动过滤）", "name": "user_id", "in": "query" }, { "type": "string", "description": "发送渠道筛选：sms/email/push", "name": "channel", "in": "query" }, { "type": "string", "description": "发送状态筛选：pending/sent/failed/delivered", "name": "status", "in": "query" }, { "type": "integer", "description": "页码，从1开始（默认1）", "name": "page", "in": "query" }, { "type": "integer", "description": "每页条数（默认20，最大100）", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "分页查询成功，返回发送日志摘要列表", "schema": { "$ref": "#/definitions/dto.CommunicationLogListResponse" } }, "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" } } } } }, "/communication/providers": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询当前租户的服务商配置列表。支持按渠道（sms/email/push）和激活状态筛选。配置凭据在响应中自动脱敏（显示为***REDACTED***）。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "查询服务商配置列表", "parameters": [ { "type": "string", "description": "渠道筛选：sms/email/push", "name": "channel", "in": "query" }, { "type": "boolean", "description": "激活状态筛选：true/false", "name": "is_active", "in": "query" }, { "type": "integer", "description": "页码，从1开始（默认1）", "name": "page", "in": "query" }, { "type": "integer", "description": "每页条数（默认20）", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回配置列表（凭据已脱敏）", "schema": { "$ref": "#/definitions/dto.ListResponse-dto_ProviderConfigResponse" } }, "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" } } } } }, "/communication/providers/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据配置ID获取单个服务商配置的详细信息。配置凭据在响应中自动脱敏。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.ProviderConfigDataResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "配置不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/push": { "post": { "security": [ { "bearerAuth": [] } ], "description": "向指定用户的所有激活设备发送推送通知。支持按平台（iOS/Android/Web/Desktop）筛选目标设备，自动记录每个Token的发送成功/失败情况。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "发送推送通知", "parameters": [ { "description": "推送通知发送请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PushRequest" } } ], "responses": { "200": { "description": "发送完成，返回成功和失败的Token数量", "schema": { "$ref": "#/definitions/dto.PushResultDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "用户或设备不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/push-tokens": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询当前租户下当前登录用户的设备推送令牌。支持按平台类型（ios/android/web/desktop）筛选，返回令牌ID、平台、设备ID、激活状态和创建时间。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "查询推送令牌列表", "parameters": [ { "type": "string", "description": "用户ID（自动从JWT获取当前用户）", "name": "user_id", "in": "query" }, { "type": "string", "description": "平台筛选：ios/android/web/desktop", "name": "platform", "in": "query" }, { "type": "integer", "description": "页码，从1开始（默认1）", "name": "page", "in": "query" }, { "type": "integer", "description": "每页条数（默认20）", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回令牌列表", "schema": { "$ref": "#/definitions/dto.PushTokenListResponse" } }, "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" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "为当前租户下的指定用户注册设备推送令牌（iOS APNs / Android FCM / Web Push / Desktop），用于后续推送通知发送。相同Token重复注册会自动停用旧记录，确保每个Token在库中唯一且最新。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "注册设备推送令牌", "parameters": [ { "description": "注册推送令牌请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreatePushTokenRequest" } } ], "responses": { "201": { "description": "注册成功，返回令牌详情", "schema": { "$ref": "#/definitions/dto.PushTokenDataResponse" } }, "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" } } } } }, "/communication/push-tokens/{id}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "更新指定推送令牌的激活状态（is_active）。停用后该令牌不再接收推送，重新激活后恢复。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.UpdatePushTokenRequest" } } ], "responses": { "200": { "description": "更新成功", "schema": { "$ref": "#/definitions/dto.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "令牌不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "停用指定的设备推送令牌（将is_active设置为false）。注销后该令牌不再接收推送通知，用户下次打开应用需重新注册。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "令牌不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/rate-limits": { "get": { "security": [ { "bearerAuth": [] } ], "description": "基于当前配置的服务商返回短信、邮件、推送等渠道的速率限制配置（每分钟/每小时最大发送量），用于客户端发送前的流量控制参考。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "查询各渠道速率限制", "parameters": [ { "type": "string", "description": "渠道筛选：sms/email/push（不传返回全部）", "name": "channel", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回各渠道速率限制配置", "schema": { "$ref": "#/definitions/dto.RateLimitsDetailResponse" } }, "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" } } } } }, "/communication/scheduled/{id}": { "delete": { "security": [ { "bearerAuth": [] } ], "description": "取消指定ID且处于scheduled状态的消息定时发送任务。已发送或已失败的消息无法取消。取消后消息状态变更为cancelled。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "取消定时发送消息", "parameters": [ { "type": "string", "description": "消息ID", "name": "id", "in": "path", "required": true }, { "description": "取消请求（可传cancel_key用于幂等匹配）", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/dto.CancelScheduledRequest" } } ], "responses": { "200": { "description": "取消成功", "schema": { "$ref": "#/definitions/dto.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "消息不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "409": { "description": "消息非scheduled状态，无法取消", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/sms": { "post": { "security": [ { "bearerAuth": [] } ], "description": "向指定手机号码发送短信。支持模板发送（需预定义模板）或直接发送内容，自动记录到发送日志。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "发送短信", "parameters": [ { "description": "短信发送请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SMSRequest" } } ], "responses": { "200": { "description": "发送成功，返回发送日志详情", "schema": { "$ref": "#/definitions/dto.CommunicationLogDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "资源不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/communication/template-stats": { "get": { "security": [ { "bearerAuth": [] } ], "description": "返回当前租户各模板在最近30天内的发送量、成功投递数和失败数统计，用于模板效果分析。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "获取模板使用统计（近30天）", "parameters": [ { "type": "string", "description": "渠道筛选：sms/email/push", "name": "channel", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回各模板统计数据", "schema": { "$ref": "#/definitions/dto.TemplateStatsListResponse" } }, "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" } } } } }, "/communication/templates": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询当前租户的消息模板列表。支持按发送渠道（sms/email/push）、激活状态、关键词（模板名称/编码）进行筛选。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "获取模板列表", "parameters": [ { "type": "string", "description": "渠道筛选：sms/email/push", "name": "channel", "in": "query" }, { "type": "boolean", "description": "是否激活筛选：true/false", "name": "is_active", "in": "query" }, { "type": "string", "description": "关键词搜索（匹配模板名称或编码）", "name": "keyword", "in": "query" }, { "type": "integer", "description": "页码，从1开始（默认1）", "name": "page", "in": "query" }, { "type": "integer", "description": "每页条数（默认20）", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回模板列表", "schema": { "$ref": "#/definitions/dto.TemplateListResponse" } }, "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" } } } } }, "/communication/templates/available": { "get": { "security": [ { "bearerAuth": [] } ], "description": "返回平台默认模板和租户自定义模板的聚合列表，每个模板标注来源（platform/tenant）和是否被租户自定义覆盖。用于前端模板选择器展示。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "获取可用模板列表（含平台默认模板）", "parameters": [ { "type": "string", "description": "语言区域：zh-CN/en-US（默认zh-CN）", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "查询成功，返回可用模板列表（含来源标注）", "schema": { "$ref": "#/definitions/dto.AvailableTemplateListResponse" } }, "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" } } } } }, "/communication/templates/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据模板ID获取消息模板的完整信息，包含渲染示例（使用示例变量值展示模板渲染后的实际效果）。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "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.TemplateDetailDataResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "无权访问该资源", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "404": { "description": "模板不存在", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/internal/communication/erase-user-data": { "post": { "description": "根据用户ID和租户ID擦除用户的通信数据：软删除通信日志（保留审计追踪），硬删除推送令牌（数据最小化）。用于GDPR第17条（被遗忘权）的合规执行。内部接口，使用InternalAPIKeyAuth认证。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "擦除用户通信数据（GDPR合规）", "parameters": [ { "description": "擦除用户数据请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EraseUserDataRequest" } } ], "responses": { "200": { "description": "擦除成功", "schema": { "$ref": "#/definitions/dto.OKResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/internal/communication/export-user-data": { "post": { "description": "根据用户ID和租户ID导出该用户的所有通信日志和推送令牌数据。用于GDPR第15条（数据主体访问权）和第20条（数据可携权）的合规响应。内部接口，使用InternalAPIKeyAuth认证。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "导出用户通信数据（GDPR合规）", "parameters": [ { "description": "导出用户数据请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ExportUserDataRequest" } } ], "responses": { "200": { "description": "导出成功，返回通信日志和推送令牌数据", "schema": { "$ref": "#/definitions/dto.ExportUserDataDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/internal/communication/send": { "post": { "description": "提供给内部微服务调用的统一消息发送接口。支持短信、邮件、推送三种渠道，支持模板发送和内容直发两种模式。创建真实发送记录到数据库并异步尝试发送。使用 InternalAPIKeyAuth 认证。参考：ePrivacy Directive 2002/58/EC、CAN-SPAM Act。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "通信服务" ], "summary": "内部服务统一发送消息", "parameters": [ { "description": "内部发送请求参数", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.InternalSendRequest" } } ], "responses": { "200": { "description": "消息已入队/发送，返回消息ID和状态", "schema": { "$ref": "#/definitions/dto.InternalSendDetailResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "500": { "description": "服务内部错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } } }, "definitions": { "domain.ChannelRateLimitData": { "type": "object", "properties": { "max_per_hour": { "type": "integer" }, "max_per_min": { "type": "integer" }, "provider": { "type": "string" }, "tenant_id": { "type": "string" } } }, "dto.AvailableTemplateListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.AvailableTemplateResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.AvailableTemplateResponse": { "type": "object", "properties": { "channel": { "type": "string", "example": "email" }, "code": { "type": "string", "example": "welcome" }, "is_active": { "type": "boolean", "example": true }, "is_customized": { "type": "boolean", "example": false }, "locale": { "type": "string", "example": "zh-CN" }, "name": { "type": "string", "example": "欢迎邮件" }, "source": { "description": "platform | tenant", "type": "string", "example": "platform" }, "subject": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } } } }, "dto.BulkSendRequest": { "description": "批量发送消息的请求参数", "type": "object", "required": [ "channel", "content", "recipients" ], "properties": { "channel": { "type": "string", "enum": [ "sms", "email" ], "example": "sms" }, "content": { "type": "string", "example": "您的验证码是123456" }, "recipients": { "type": "array", "items": { "type": "string" }, "example": [ "[\"13800138000\"", "\"13900139000\"]" ] }, "subject": { "type": "string", "example": "通知" }, "template": { "type": "string", "example": "verify_code" }, "user_id": { "type": "string", "example": "usr_abc123" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "dto.CallbackResultDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.CallbackResultResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.CallbackResultResponse": { "description": "提供商回调结果", "type": "object", "properties": { "provider": { "type": "string", "example": "aliyun" }, "received": { "type": "boolean", "example": true } } }, "dto.CancelScheduledRequest": { "type": "object", "properties": { "cancel_key": { "type": "string" } } }, "dto.ChannelHealthDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ChannelHealthResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ChannelHealthResponse": { "description": "渠道连通性检查结果", "type": "object", "properties": { "channel": { "type": "string", "example": "sms" }, "message": { "type": "string", "example": "SMS provider is reachable" }, "provider": { "type": "string", "example": "aliyun" }, "status": { "type": "string", "example": "healthy" } } }, "dto.CloneTemplateToLocaleRequest": { "type": "object", "required": [ "target_locale" ], "properties": { "content": { "type": "string" }, "subject": { "type": "string" }, "target_locale": { "type": "string", "example": "en-US" } } }, "dto.CommunicationDashboardDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.CommunicationDashboardResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.CommunicationDashboardResponse": { "description": "通信服务各渠道投递统计数据", "type": "object", "properties": { "by_channel": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "delivered": { "type": "integer", "example": 980 }, "delivery_rate": { "type": "number", "example": 0.98 }, "failed": { "type": "integer", "example": 20 }, "total_sent": { "type": "integer", "example": 1000 } } }, "dto.CommunicationLogDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.CommunicationLogResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.CommunicationLogListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.CommunicationLogResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.CommunicationLogResponse": { "description": "消息发送日志记录", "type": "object", "properties": { "channel": { "type": "string", "example": "sms" }, "content": { "type": "string", "example": "您的验证码是123456" }, "created_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "error": { "type": "string", "example": "发送超时" }, "id": { "type": "string", "example": "log_abc123" }, "provider": { "type": "string", "example": "aliyun" }, "recipient": { "type": "string", "example": "138****8000" }, "response": { "type": "string" }, "sent_at": { "type": "string", "example": "2026-04-15T10:01:00Z" }, "status": { "type": "string", "example": "delivered" }, "template_id": { "type": "string", "example": "tpl_abc123" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "updated_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.CreateProviderConfigRequest": { "type": "object", "required": [ "channel", "config", "provider" ], "properties": { "channel": { "type": "string", "enum": [ "sms", "email", "push" ], "example": "sms" }, "config": { "type": "string", "example": "{\"access_key\":\"...\"}" }, "priority": { "type": "integer", "example": 10 }, "provider": { "type": "string", "example": "aliyun" } } }, "dto.CreatePushTokenRequest": { "description": "注册设备推送令牌的请求参数", "type": "object", "required": [ "platform", "token", "user_id" ], "properties": { "device_id": { "type": "string", "example": "iPhone15-001" }, "platform": { "type": "string", "enum": [ "ios", "android", "web", "desktop" ], "example": "ios" }, "token": { "type": "string", "example": "device_token_xxx" }, "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.CreateTemplateRequest": { "description": "创建消息模板的请求参数", "type": "object", "required": [ "channel", "code", "content", "name" ], "properties": { "channel": { "type": "string", "enum": [ "sms", "email", "push" ], "example": "sms" }, "code": { "type": "string", "example": "verify_code" }, "content": { "type": "string", "example": "您的验证码是{code}，5分钟内有效" }, "content_type": { "type": "string", "example": "text" }, "description": { "type": "string", "example": "用于发送登录验证码" }, "format": { "type": "string", "example": "simple" }, "name": { "type": "string", "example": "验证码模板" }, "subject": { "type": "string", "example": "验证码通知" }, "text_content": { "type": "string", "example": "Your code is {code}" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "[\"code\"]" ] } } }, "dto.CreateTemplateResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "$ref": "#/definitions/dto.MessageTemplateResponse" }, "message": { "type": "string", "example": "success" } } }, "dto.EmailRequest": { "description": "发送邮件请求参数", "type": "object", "required": [ "subject", "to" ], "properties": { "bcc": { "description": "密送", "type": "array", "items": { "type": "string" }, "example": [ "manager@example.com" ] }, "cancel_key": { "type": "string", "example": "order-123" }, "cc": { "description": "抄送", "type": "array", "items": { "type": "string" }, "example": [ "admin@example.com" ] }, "content": { "description": "内容", "type": "string", "example": "\u003ch1\u003e欢迎！\u003c/h1\u003e" }, "is_html": { "description": "HTML格式", "type": "boolean", "example": false }, "send_at": { "type": "string", "example": "2026-06-07T10:00:00Z" }, "subject": { "description": "主题", "type": "string", "example": "账户激活邮件" }, "template": { "description": "模板", "type": "string", "example": "welcome_email" }, "to": { "description": "收件人", "type": "array", "minItems": 1, "items": { "type": "string" }, "example": [ "user@example.com" ] }, "user_id": { "description": "用户ID", "type": "string", "example": "usr_abc123" }, "variables": { "description": "变量", "type": "object", "additionalProperties": { "type": "string" } } } }, "dto.EraseUserDataRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.ExportUserDataDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ExportUserDataResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ExportUserDataRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.ExportUserDataResponse": { "type": "object", "properties": { "logs": {}, "tokens": {} } }, "dto.InternalSendDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.InternalSendResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.InternalSendRequest": { "description": "内部服务间统一发送消息的请求参数", "type": "object", "required": [ "channel", "to" ], "properties": { "channel": { "type": "string", "example": "email" }, "content": { "type": "string", "example": "您的验证码是123456" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "subject": { "type": "string", "example": "账户激活" }, "template": { "type": "string", "example": "welcome" }, "to": { "type": "string", "example": "user@example.com" }, "user_id": { "type": "string", "example": "usr_abc123" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "dto.InternalSendResponse": { "description": "内部统一发送接口的响应信息", "type": "object", "properties": { "channel": { "type": "string", "example": "email" }, "message_id": { "type": "string", "example": "internal-1234567890" }, "status": { "type": "string", "example": "queued" }, "to": { "type": "string", "example": "user@example.com" } } }, "dto.ListResponse-dto_ProviderConfigResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.ProviderConfigResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.MessageTemplateDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.MessageTemplateResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.MessageTemplateResponse": { "description": "消息模板数据", "type": "object", "properties": { "channel": { "type": "string", "example": "sms" }, "code": { "type": "string", "example": "verify_code" }, "content": { "type": "string", "example": "您的验证码是{code}，5分钟内有效" }, "content_type": { "type": "string", "example": "text" }, "created_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "description": { "type": "string", "example": "用于发送登录验证码" }, "id": { "type": "string", "example": "tpl_abc123" }, "is_active": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "验证码模板" }, "subject": { "type": "string", "example": "验证码通知" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "updated_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "[\"code\"]" ] }, "version": { "type": "integer", "example": 1 } } }, "dto.OKResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "message": { "type": "string", "example": "success" } } }, "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" } } }, "dto.ProviderConfigDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ProviderConfigResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ProviderConfigResponse": { "type": "object", "properties": { "app_id": { "type": "string" }, "channel": { "type": "string" }, "config": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "priority": { "type": "integer" }, "provider": { "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "dto.PushRequest": { "description": "发送推送通知请求参数", "type": "object", "required": [ "body", "title", "user_id" ], "properties": { "body": { "description": "内容", "type": "string", "example": "您有一条新消息" }, "channel": { "description": "渠道", "type": "string", "example": "ios" }, "data": { "description": "数据", "type": "object", "additionalProperties": true }, "device_token": { "description": "设备Token", "type": "string", "example": "device_token_xxx" }, "platform": { "description": "平台", "type": "string", "enum": [ "all", "ios", "android", "web", "desktop" ], "example": "all" }, "title": { "description": "标题", "type": "string", "example": "新消息通知" }, "user_id": { "description": "用户ID", "type": "string", "example": "usr_abc123" } } }, "dto.PushResultDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PushResultResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PushResultResponse": { "description": "推送发送结果", "type": "object", "properties": { "sent": { "type": "boolean", "example": true }, "tokens_failed": { "type": "integer", "example": 0 }, "tokens_sent": { "type": "integer", "example": 2 } } }, "dto.PushTokenDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PushTokenResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PushTokenListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.PushTokenResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.PushTokenResponse": { "description": "推送令牌信息", "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "device_id": { "type": "string", "example": "iPhone15-001" }, "id": { "type": "string", "example": "pt_abc123" }, "is_active": { "type": "boolean", "example": true }, "platform": { "type": "string", "example": "ios" }, "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.RateLimitsDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.RateLimitsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.RateLimitsResponse": { "description": "通信服务各发送渠道的速率限制配置", "type": "object", "properties": { "email": { "$ref": "#/definitions/domain.ChannelRateLimitData" }, "push": { "$ref": "#/definitions/domain.ChannelRateLimitData" }, "sms": { "$ref": "#/definitions/domain.ChannelRateLimitData" } } }, "dto.SMSRequest": { "description": "发送短信请求参数", "type": "object", "required": [ "phone" ], "properties": { "cancel_key": { "type": "string", "example": "order-123" }, "content": { "description": "内容", "type": "string", "example": "您的验证码是123456" }, "phone": { "description": "手机号", "type": "string", "example": "13800138000" }, "send_at": { "type": "string", "example": "2026-06-07T10:00:00Z" }, "template": { "description": "模板", "type": "string", "example": "verify_code" }, "user_id": { "description": "用户ID", "type": "string", "example": "usr_abc123" }, "variables": { "description": "变量", "type": "object", "additionalProperties": { "type": "string" } } } }, "dto.SimpleResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TemplateDetailDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TemplateDetailResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TemplateDetailResponse": { "description": "模板详情数据（包含渲染示例）", "type": "object", "properties": { "channel": { "type": "string", "example": "sms" }, "code": { "type": "string", "example": "verify_code" }, "content": { "type": "string", "example": "您的验证码是{code}，5分钟内有效" }, "content_type": { "type": "string", "example": "text" }, "created_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "description": { "type": "string", "example": "用于发送登录验证码" }, "id": { "type": "string", "example": "tpl_abc123" }, "is_active": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "验证码模板" }, "render_example": { "type": "string", "example": "您的验证码是[code]，5分钟内有效" }, "subject": { "type": "string", "example": "验证码通知" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "updated_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "[\"code\"]" ] }, "version": { "type": "integer", "example": 1 } } }, "dto.TemplateListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.TemplateResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.TemplateResponse": { "description": "模板数据", "type": "object", "properties": { "channel": { "type": "string", "example": "sms" }, "code": { "type": "string", "example": "verify_code" }, "content": { "type": "string", "example": "您的验证码是{code}，5分钟内有效" }, "content_type": { "type": "string", "example": "text" }, "created_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "description": { "type": "string", "example": "用于发送登录验证码" }, "id": { "type": "string", "example": "tpl_abc123" }, "is_active": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "验证码模板" }, "subject": { "type": "string", "example": "验证码通知" }, "tenant_id": { "type": "string", "example": "tnt_xyz789" }, "updated_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "[\"code\"]" ] }, "version": { "type": "integer", "example": 1 } } }, "dto.TemplateStatsListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.TemplateStatsResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.TemplateStatsResponse": { "type": "object", "properties": { "channel": { "type": "string", "example": "sms" }, "delivered": { "type": "integer", "example": 480 }, "failed": { "type": "integer", "example": 20 }, "template_code": { "type": "string", "example": "verify_code" }, "total_sent": { "type": "integer", "example": 500 } } }, "dto.TemplateVersionListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.TemplateVersionResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.TemplateVersionResponse": { "type": "object", "properties": { "changed_by": { "type": "string", "example": "usr_abc123" }, "channel": { "type": "string", "example": "sms" }, "code": { "type": "string", "example": "verify_code" }, "content": { "type": "string", "example": "您的验证码是{code}，5分钟内有效" }, "content_type": { "type": "string", "example": "text" }, "created_at": { "type": "string", "example": "2026-04-15T10:00:00Z" }, "id": { "type": "string", "example": "tv_abc123" }, "name": { "type": "string", "example": "验证码模板" }, "subject": { "type": "string", "example": "验证码通知" }, "template_id": { "type": "string", "example": "tpl_abc123" }, "text_content": { "type": "string" }, "variables": { "type": "string", "example": "[\"code\"]" }, "version": { "type": "integer", "example": 3 } } }, "dto.UpdateProviderConfigRequest": { "type": "object", "properties": { "config": { "type": "string" }, "is_active": { "type": "boolean" }, "priority": { "type": "integer" } } }, "dto.UpdatePushTokenRequest": { "type": "object", "required": [ "user_id" ], "properties": { "is_active": { "type": "boolean", "example": true }, "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.UpdateTemplateRequest": { "description": "更新消息模板的请求参数", "type": "object", "properties": { "content": { "type": "string", "example": "您的验证码是{code}，10分钟内有效" }, "content_type": { "type": "string", "example": "text" }, "description": { "type": "string", "example": "更新版验证码模板" }, "format": { "type": "string", "example": "go-template" }, "is_active": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "验证码模板v2" }, "subject": { "type": "string", "example": "验证码通知v2" }, "text_content": { "type": "string", "example": "Your code is {code}, valid for 10 min" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "[\"code\"]" ] } } } }, "securityDefinitions": { "bearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "description": "通信接口：邮件、短信、Webhook", "name": "通信服务" } ] }