From d7f252e1bdbd54ae4bdb9f7b9c8deff44d16e5e5 Mon Sep 17 00:00:00 2001 From: ysyneu <9045284+ysyneu@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:11:55 +0000 Subject: [PATCH] chore: sync OpenAPI spec from flashduty-docs + regenerate --- models_gen.go | 37 +++++- openapi/openapi.en.json | 262 ++++++++++++++++++++++++++++++++++++++- openapi/openapi.zh.json | 268 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 553 insertions(+), 14 deletions(-) diff --git a/models_gen.go b/models_gen.go index ddc7c30..49c5b32 100644 --- a/models_gen.go +++ b/models_gen.go @@ -29,7 +29,7 @@ func (e CSVFileResponse) String() string { return string(e) } // DataSourceListResponse is a list response payload. type DataSourceListResponse []DataSourceItem -// ErrorCode Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational. +// ErrorCode Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value. type ErrorCode string const ( @@ -7174,6 +7174,41 @@ type RUMFieldListResponse struct { Items []RUMFieldItem `json:"items" toon:"items"` } +// RUMIssueExportRequest is generated from the Flashduty OpenAPI schema. +type RUMIssueExportRequest struct { + ListOptions + // Filter by application IDs. Get IDs via `POST /rum/application/list`. + ApplicationIDs []string `json:"application_ids,omitempty" toon:"application_ids,omitempty"` + // Sort ascending when `true`; descending by default. + Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` + // When `true`, match by time-range overlap: export issues still active within the window (`last_seen_timestamp` >= `start_time`) even if created before it. Default `false` exports only issues created inside the window. + ByIntersection bool `json:"by_intersection,omitempty" toon:"by_intersection,omitempty"` + // Console origin used to build the `issue_url` column, e.g. `https://console.flashcat.cloud`. The service cannot infer it (SaaS, on-premises and dev releases answer on different origins). + ConsoleOrigin string `json:"console_origin,omitempty" toon:"console_origin,omitempty"` + // DQL query for advanced filtering. Cannot be used with `sql`. + Dql string `json:"dql,omitempty" toon:"dql,omitempty"` + // End of time range, millisecond timestamp. Maximum range: 183 days. + EndTime int64 `json:"end_time" toon:"end_time"` + // If `true`, only export issues with at least one associated error event. + ErrorRequired bool `json:"error_required,omitempty" toon:"error_required,omitempty"` + // CSV columns to export, in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set. + ExportFields []string `json:"export_fields,omitempty" toon:"export_fields,omitempty"` + // Sort field; defaults to `updated_at` when omitted. + Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` + // SQL-style query for advanced filtering. Cannot be used with `dql`. + Sql string `json:"sql,omitempty" toon:"sql,omitempty"` + // Start of the time range, Unix epoch milliseconds. + StartTime int64 `json:"start_time" toon:"start_time"` + // Filter by status; only the enum values are accepted — any other value is rejected with a parameter error. + Statuses []string `json:"statuses,omitempty" toon:"statuses,omitempty"` + // Filter by suspected cause; see the enum for valid values. + SuspectedCauses []string `json:"suspected_causes,omitempty" toon:"suspected_causes,omitempty"` + // Filter by team IDs. Get team IDs via `POST /team/list`. + TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` + // IANA time zone used to render timestamps in the CSV, e.g. `Asia/Shanghai` or `UTC`. Default: `Asia/Shanghai`. + TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` +} + // RUMIssueIDRequest is generated from the Flashduty OpenAPI schema. type RUMIssueIDRequest struct { // Issue ID. Get issue IDs via `POST /rum/issue/list`. diff --git a/openapi/openapi.en.json b/openapi/openapi.en.json index 4edc9eb..9e4a04d 100644 --- a/openapi/openapi.en.json +++ b/openapi/openapi.en.json @@ -16342,7 +16342,7 @@ "RUM/Issues" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are millisecond timestamps. Maximum range: 183 days.\n- `statuses` filters by issue status. Valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `orderby` accepts: `created_at`, `updated_at`, `session_count`, `error_count`.\n- Use `dql` or `sql` for advanced filtering. Cannot provide both.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are millisecond timestamps. Maximum range: 183 days.\n- `statuses` filters by issue status. Valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `orderby` accepts: `created_at`, `updated_at`, `session_count`, `error_count`, `severity`.\n- Use `dql` or `sql` for advanced filtering. Cannot provide both.", "href": "/en/api-reference/rum/issues/rum-issue-read-list", "metadata": { "sidebarTitle": "List issues" @@ -16494,6 +16494,96 @@ } } }, + "/rum/issue/export": { + "post": { + "operationId": "rum-issue-read-export", + "summary": "Export issues as CSV", + "description": "Export the filtered RUM error tracking issues as a CSV file. The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope; non-console callers can read the `X-Export-Total` and `X-Export-Truncated` response headers.", + "tags": [ + "RUM/Issues" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/day**; **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not wrapped in the standard envelope. The filename is `rum-issues-.csv`, stamped in the requested `time_zone`. Read `X-Export-Total` and `X-Export-Truncated` response headers instead of a body field.\n- The export reads the first 100 matching rows (`ExportMaxRows`); `X-Export-Truncated` is `true` when more issues match. `p` and `limit` are ignored.\n- The request filters are exactly those of `POST /rum/issue/list` — an export is \"what I am looking at, as a file\".\n- `export_fields` names the CSV columns in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set.\n- `time_zone` must be a valid IANA zone name (e.g. `Asia/Shanghai`, `UTC`); timestamps are rendered in that zone and time columns carry the zone in their header. Invalid names are rejected.\n- `console_origin` is used to build the `issue_url` column; the service cannot infer it (SaaS, on-premises and dev releases answer on different origins).\n- Every call is recorded in the account's audit log with the caller's member ID, request payload, and resulting error (if any). Do not put secrets in request fields.", + "href": "/en/api-reference/rum/issues/rum-issue-read-export", + "metadata": { + "sidebarTitle": "Export issues as CSV" + } + }, + "responses": { + "200": { + "description": "Success. CSV attachment, not a JSON envelope.", + "headers": { + "X-Export-Total": { + "description": "Total number of issues matching the filters, before the row cap.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + "X-Export-Truncated": { + "description": "`true` when more issues matched than the 100-row cap and the file was truncated.", + "schema": { + "type": "boolean" + } + } + }, + "content": { + "text/csv": { + "schema": { + "type": "string", + "description": "CSV file content. The header row matches the exported columns in order; values are sanitized against spreadsheet formula injection." + }, + "example": "Issue ID,Error type,Error message,Status,Error count,Affected sessions,Last seen (Asia/Shanghai)\nNHEacQHi2DhXqobr9qPQz9,Error,Script error.,for_review,752,381,2026-04-12 10:43:59\nH8kZSmxiE7EgdyD4fCyyNa,Error,\"API ERROR: We encountered an internal error | POST /api/access/logout\",for_review,3,1,2026-04-03 12:41:24" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RumIssueExportRequest" + }, + "example": { + "start_time": 1772611200000, + "end_time": 1775961914595, + "application_ids": [ + "eWbr4xk3ZRnLabRa6unqwD" + ], + "statuses": [ + "for_review" + ], + "orderby": "updated_at", + "export_fields": [ + "issue_id", + "error_type", + "error_message", + "status", + "error_count", + "session_count", + "last_seen_at" + ], + "console_origin": "https://console.flashcat.cloud", + "time_zone": "Asia/Shanghai" + } + } + } + } + } + }, "/rum/issue/update": { "post": { "operationId": "rum-issue-write-update", @@ -31173,7 +31263,7 @@ }, "ErrorCode": { "type": "string", - "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", + "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |", "enum": [ "OK", "InvalidParameter", @@ -31195,7 +31285,30 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ] + ], + "x-enumDescriptions": { + "OK": "Reserved — not returned on real errors.", + "InvalidParameter": "A required parameter is missing or failed validation.", + "BadRequest": "Generic 400 used when no more specific code fits.", + "InvalidContentType": "The `Content-Type` header is not `application/json`.", + "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).", + "NoLicense": "The feature is license-gated and no active license was found.", + "ReferenceExist": "Deletion blocked — other entities still reference this resource.", + "Unauthorized": "`app_key` is missing, invalid, or expired.", + "BalanceNotEnough": "Billing-gated operation with insufficient account balance.", + "AccessDenied": "Authenticated but lacking the permission required for this operation.", + "RouteNotFound": "The request URL path is not a known route.", + "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.", + "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.", + "RequestLocked": "Operation temporarily locked due to repeated failures.", + "EntityTooLarge": "Request body exceeds the configured max size.", + "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.", + "RequestVerifyRequired": "Second-factor verification required but not supplied.", + "DangerousOperation": "High-risk operation requires MFA verification.", + "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.", + "ServiceUnavailable": "A backend dependency is unavailable. Try again later." + }, + "example": "InvalidParameter" }, "DutyError": { "type": "object", @@ -31206,7 +31319,8 @@ }, "message": { "type": "string", - "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." + "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.", + "example": "The specified parameter template_id is not valid." } }, "required": [ @@ -45458,6 +45572,143 @@ } } }, + "RumIssueExportRequest": { + "type": "object", + "required": [ + "start_time", + "end_time" + ], + "description": "Filters for exporting RUM error tracking issues to CSV.", + "properties": { + "start_time": { + "type": "integer", + "format": "int64", + "description": "Start of the time range, Unix epoch milliseconds." + }, + "end_time": { + "type": "integer", + "format": "int64", + "description": "End of time range, millisecond timestamp. Maximum range: 183 days." + }, + "application_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Filter by application IDs. Get IDs via `POST /rum/application/list`." + }, + "dql": { + "type": "string", + "description": "DQL query for advanced filtering. Cannot be used with `sql`." + }, + "sql": { + "type": "string", + "description": "SQL-style query for advanced filtering. Cannot be used with `dql`." + }, + "statuses": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "for_review", + "reviewed", + "ignored", + "resolved" + ] + }, + "description": "Filter by status; only the enum values are accepted — any other value is rejected with a parameter error." + }, + "suspected_causes": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "api.failed_request", + "network.error", + "code.exception", + "code.invalid_object_access", + "code.invalid_argument", + "unknown" + ] + }, + "description": "Filter by suspected cause; see the enum for valid values." + }, + "team_ids": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + }, + "description": "Filter by team IDs. Get team IDs via `POST /team/list`." + }, + "p": { + "type": "integer", + "description": "Page number (1-based). Ignored by the export — the first 100 matching rows are always read." + }, + "limit": { + "type": "integer", + "description": "Page size (1–100). Ignored by the export — the row cap is fixed at 100." + }, + "orderby": { + "type": "string", + "enum": [ + "created_at", + "updated_at", + "session_count", + "error_count", + "severity" + ], + "description": "Sort field; defaults to `updated_at` when omitted." + }, + "asc": { + "type": "boolean", + "description": "Sort ascending when `true`; descending by default." + }, + "error_required": { + "type": "boolean", + "description": "If `true`, only export issues with at least one associated error event." + }, + "by_intersection": { + "type": "boolean", + "description": "When `true`, match by time-range overlap: export issues still active within the window (`last_seen_timestamp` >= `start_time`) even if created before it. Default `false` exports only issues created inside the window." + }, + "export_fields": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "issue_id", + "issue_url", + "application_name", + "service", + "error_type", + "error_message", + "status", + "severity", + "is_crash", + "error_count", + "session_count", + "first_seen_at", + "first_seen_version", + "last_seen_at", + "last_seen_version", + "versions", + "suspected_cause", + "resolved_at" + ] + }, + "description": "CSV columns to export, in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set." + }, + "console_origin": { + "type": "string", + "description": "Console origin used to build the `issue_url` column, e.g. `https://console.flashcat.cloud`. The service cannot infer it (SaaS, on-premises and dev releases answer on different origins)." + }, + "time_zone": { + "type": "string", + "description": "IANA time zone used to render timestamps in the CSV, e.g. `Asia/Shanghai` or `UTC`. Default: `Asia/Shanghai`." + } + } + }, "RumIssueItem": { "type": "object", "description": "A RUM error tracking issue.", @@ -45727,7 +45978,8 @@ "created_at", "updated_at", "session_count", - "error_count" + "error_count", + "severity" ], "description": "Sort field; defaults to `updated_at` when omitted." }, diff --git a/openapi/openapi.zh.json b/openapi/openapi.zh.json index 3948a5e..3b107d0 100644 --- a/openapi/openapi.zh.json +++ b/openapi/openapi.zh.json @@ -16486,6 +16486,96 @@ } } }, + "/rum/issue/export": { + "post": { + "operationId": "rum-issue-read-export", + "summary": "导出 Issue 列表", + "description": "将符合过滤条件的 RUM 异常追踪 Issue 导出为 CSV 文件。响应为 `text/csv` 流，通过 `Content-Disposition: attachment` 交付——不是 JSON 信封；非控制台调用方可通过 `X-Export-Total` 与 `X-Export-Truncated` 响应头获知匹配总数与截断情况。", + "tags": [ + "RUM/RUM 问题跟踪" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/天**；**100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应为 `text/csv` 流，通过 `Content-Disposition: attachment` 交付——不使用标准信封。文件名为 `rum-issues-<时间戳>.csv`，按请求的 `time_zone` 打时间戳。请通过 `X-Export-Total` 与 `X-Export-Truncated` 响应头获取总数与截断情况。\n- 导出读取前 100 条匹配记录（`ExportMaxRows`）；匹配数超过上限时 `X-Export-Truncated` 为 `true`。`p` 和 `limit` 被忽略。\n- 请求过滤条件与 `POST /rum/issue/list` 完全一致——导出就是“我正在看的列表，输出成文件”。\n- `export_fields` 按顺序指定 CSV 列；未知键会被拒绝；空数组使用默认列集。\n- `time_zone` 必须是合法的 IANA 时区名（如 `Asia/Shanghai`、`UTC`）；时间戳按该时区渲染，时间列表头携带时区。非法时区名会被拒绝。\n- `console_origin` 用于拼接 `issue_url` 列；服务无法自行推断（SaaS、私有化与 dev 环境地址不同）。\n- 每次调用都会记录到账户审计日志，包含调用者成员 ID、请求负载与最终错误（如有）。请勿在请求字段中放置敏感信息。", + "href": "/zh/api-reference/rum/issues/rum-issue-read-export", + "metadata": { + "sidebarTitle": "导出 Issue 列表" + } + }, + "responses": { + "200": { + "description": "Success. CSV attachment, not a JSON envelope.", + "headers": { + "X-Export-Total": { + "description": "Total number of issues matching the filters, before the row cap.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + "X-Export-Truncated": { + "description": "`true` when more issues matched than the 100-row cap and the file was truncated.", + "schema": { + "type": "boolean" + } + } + }, + "content": { + "text/csv": { + "schema": { + "type": "string", + "description": "CSV file content. The header row matches the exported columns in order; values are sanitized against spreadsheet formula injection." + }, + "example": "Issue ID,Error type,Error message,Status,Error count,Affected sessions,Last seen (Asia/Shanghai)\nNHEacQHi2DhXqobr9qPQz9,Error,Script error.,for_review,752,381,2026-04-12 10:43:59\nH8kZSmxiE7EgdyD4fCyyNa,Error,\"API ERROR: We encountered an internal error | POST /api/access/logout\",for_review,3,1,2026-04-03 12:41:24" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RumIssueExportRequest" + }, + "example": { + "start_time": 1772611200000, + "end_time": 1775961914595, + "application_ids": [ + "eWbr4xk3ZRnLabRa6unqwD" + ], + "statuses": [ + "for_review" + ], + "orderby": "updated_at", + "export_fields": [ + "issue_id", + "error_type", + "error_message", + "status", + "error_count", + "session_count", + "last_seen_at" + ], + "console_origin": "https://console.flashcat.cloud", + "time_zone": "Asia/Shanghai" + } + } + } + } + } + }, "/rum/issue/update": { "post": { "operationId": "rum-issue-write-update", @@ -31165,7 +31255,7 @@ }, "ErrorCode": { "type": "string", - "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", + "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |", "enum": [ "OK", "InvalidParameter", @@ -31187,18 +31277,42 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ] + ], + "x-enumDescriptions": { + "OK": "保留值，正常错误响应不会返回。", + "InvalidParameter": "必填参数缺失或未通过校验。", + "BadRequest": "通用的 400 错误，通常是请求本身不合法。", + "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。", + "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。", + "NoLicense": "功能需要有效授权，但未找到可用的 license。", + "ReferenceExist": "该资源仍被其他实体引用，无法删除。", + "Unauthorized": "`app_key` 缺失、无效或已过期。", + "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。", + "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。", + "RouteNotFound": "请求的 URL 路径不是已知路由。", + "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。", + "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。", + "RequestLocked": "因连续失败被临时锁定。", + "EntityTooLarge": "请求体超过允许的最大长度。", + "RequestTooFrequently": "命中限流（全局、账户级或集成级）。", + "RequestVerifyRequired": "操作需要二次验证码，但未提供。", + "DangerousOperation": "危险操作，需要进行 MFA 验证。", + "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。", + "ServiceUnavailable": "后端依赖不可用，请稍后重试。" + }, + "example": "InvalidParameter" }, "DutyError": { "type": "object", - "description": "Error payload inside the response envelope. Present only on non-2xx responses.", + "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", - "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." + "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", + "example": "The specified parameter template_id is not valid." } }, "required": [ @@ -31226,7 +31340,7 @@ }, "ErrorResponse": { "type": "object", - "description": "Response envelope for errors. `error` is required; `data` is absent.", + "description": "错误响应结构。`error` 必填，`data` 不存在。", "properties": { "request_id": { "type": "string", @@ -45449,6 +45563,143 @@ } } }, + "RumIssueExportRequest": { + "type": "object", + "required": [ + "start_time", + "end_time" + ], + "description": "导出 RUM 异常追踪 Issue 的过滤参数。", + "properties": { + "start_time": { + "type": "integer", + "format": "int64", + "description": "时间范围起始，Unix 毫秒时间戳。" + }, + "end_time": { + "type": "integer", + "format": "int64", + "description": "时间范围结束，毫秒时间戳，最大范围 183 天。" + }, + "application_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "按应用 ID 过滤；应用 ID 可通过 `POST /rum/application/list` 获取。" + }, + "dql": { + "type": "string", + "description": "DQL 高级过滤查询，不能与 `sql` 同时使用。" + }, + "sql": { + "type": "string", + "description": "SQL 式高级过滤查询，不能与 `dql` 同时使用。" + }, + "statuses": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "for_review", + "reviewed", + "ignored", + "resolved" + ] + }, + "description": "按状态过滤，取值见枚举；传入其他值会报参数错误。" + }, + "suspected_causes": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "api.failed_request", + "network.error", + "code.exception", + "code.invalid_object_access", + "code.invalid_argument", + "unknown" + ] + }, + "description": "按疑似原因过滤，取值见枚举。" + }, + "team_ids": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + }, + "description": "按团队 ID 过滤；团队 ID 可通过 `POST /team/list` 获取。" + }, + "p": { + "type": "integer", + "description": "页码（从 1 开始）。导出时忽略——始终读取前 100 条匹配记录。" + }, + "limit": { + "type": "integer", + "description": "每页条数（1–100）。导出时忽略——行数上限固定为 100。" + }, + "orderby": { + "type": "string", + "enum": [ + "created_at", + "updated_at", + "session_count", + "error_count", + "severity" + ], + "description": "排序字段；缺省时按 `updated_at` 排序。" + }, + "asc": { + "type": "boolean", + "description": "为 `true` 时升序排列；默认降序。" + }, + "error_required": { + "type": "boolean", + "description": "为 `true` 时仅导出有关联错误事件的 Issue。" + }, + "by_intersection": { + "type": "boolean", + "description": "为 `true` 时按时间交集匹配：导出在时间窗口内仍有活动的 Issue（`last_seen_timestamp` 不早于 `start_time`），即使其创建于窗口之前；默认 `false` 仅导出创建于窗口内的 Issue。" + }, + "export_fields": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "issue_id", + "issue_url", + "application_name", + "service", + "error_type", + "error_message", + "status", + "severity", + "is_crash", + "error_count", + "session_count", + "first_seen_at", + "first_seen_version", + "last_seen_at", + "last_seen_version", + "versions", + "suspected_cause", + "resolved_at" + ] + }, + "description": "按顺序指定导出的 CSV 列；未知键会被拒绝；空数组使用默认列集。" + }, + "console_origin": { + "type": "string", + "description": "用于拼接 `issue_url` 列的控制台地址，如 `https://console.flashcat.cloud`；服务无法自行推断（SaaS、私有化与 dev 环境地址不同）。" + }, + "time_zone": { + "type": "string", + "description": "渲染 CSV 时间戳所用的 IANA 时区名，如 `Asia/Shanghai`、`UTC`；默认 `Asia/Shanghai`。" + } + } + }, "RumIssueItem": { "type": "object", "description": "单个 RUM 异常追踪 Issue。", @@ -45718,7 +45969,8 @@ "created_at", "updated_at", "session_count", - "error_count" + "error_count", + "severity" ], "description": "排序字段；缺省时按 `updated_at` 排序。" }, @@ -48920,14 +49172,14 @@ "properties": { "request_id": { "type": "string", - "description": "Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.", + "description": "本次请求的唯一 ID，与 Flashcat-Request-Id 响应头一致。反馈问题时请携带该 ID。", "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" }, "error": { "$ref": "#/components/schemas/DutyError" }, "data": { - "description": "Endpoint-specific payload. See each operation's 200 response schema." + "description": "端点专属数据负载，具体结构见各操作 200 响应中的 schema。" } }, "required": [